Language - Max/MSP: Difference between revisions

From Phidgets Support
No edit summary
 
(112 intermediate revisions by 11 users not shown)
Line 1: Line 1:
<metadesc>Communicate over USB with sensors, controllers and relays with Phidgets! Our Max/MSP library supports Windows and MacOS.</metadesc>
[[Category:Language]]
[[Category:Language]]
[[File:icon-MaxMSP.png|link=|alt=MaxMSP|64x64px]] Max/MSP, developed by [http://cycling74.com Cycling74] is a visual programming language for creating music and media applications.
__NOTOC__
We provide support for Max/MSP in '''macOS''' and '''Windows'''. We also provide instructions on how to get your project started. Select your operating system below, and follow the instructions to get your project running with Phidgets.


__TOC__
Once you have set up your development environment to run with Phidgets, we recommend you follow our guide on [[Phidget Programming Basics]]. The guide will showcase the fundamentals of programming with Phidgets.


==Introduction==
==Setup Guide==


{{LanguageSupport|Max/MSP|the complete Phidget API, including events|all Phidget devices.| Windows and Mac OS X.|}}
<div class="phd-deck-sequence">
{{PT3_MAX_CHOOSE}}{{PT3_MAX_WIN}}{{PT3_MAX_MAC}}
</div>


Only Max/MSP 4.5 or higher are supported.


==Quick Downloads==
== Quick Downloads ==
If you already know what you're doing and just need the files, you can find them all below.


Just need the Max/MSP drivers, libraries, and examples?  Here they are:
=== Documentation ===


===Library and Example Code===
*{{Phidget22API}} (Select Max/MSP from drop-down menu)
*[http://www.phidgets.com/downloads/examples/WinMaxMSP_2.1.8.20120123.zip Windows]
*[http://www.phidgets.com/downloads/examples/WinMaxMSP_2.1.8.20120123.zip Mac OS X]


===Libraries and Drivers===
=== Phidgets Max Libraries ===
*[http://www.phidgets.com/downloads/libraries/Phidget-x86_2.1.8.20111220.exe 32-bit Windows Drivers Installer]
*[http://www.phidgets.com/downloads/libraries/Phidget-x64_2.1.8.20111220.exe 64-bit Windows Drivers Installer]
*[http://www.phidgets.com/downloads/libraries/Phidget_2.1.8.20111103.dmg Mac OS X Drivers Installer]


==Getting started with Max/MSP==
* [https://cdn.phidgets.com/downloads/phidget22/libraries/windows/Phidget22MaxMSP.zip Windows Max Libraries for Phidgets]
* [https://cdn.phidgets.com/downloads/phidget22/libraries/macos/Phidget22MaxMSP.zip MacOS Max Libraries for Phidgets]


If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:
=== Max Example Code ===
{{ExampleCodeReasons}}


Instructions are divided up by operating system. Choose:
*{{SampleCode|MaxMSP|Max/MSP Example}}
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#Mac OS X |Mac OS X]]


==Windows(2000/XP/Vista/7)==
===Phidgets Core Libraries===


===Description of Library Files===
{{AllQuickDownloads}}
Max/MSP programs on Windows depend on the following files, which the installers above put onto your system:
* <b><code>phidget21.dll</code></b> contains the actual Phidgets library, which is used at run-time.  By default, it is placed in <code>C:\Windows\System32</code>.
* <b><code>PhidgetXXX.mxe</code></b> is the Phidgets library for your specific device. XXX denotes the name of your device, Please make sure the <code>.mxe</code> file corresponds with the device you are using. For example, if you are using the PhidgetInterfaceKit, you will need the {{Code|PhidgetInterfaceKit.mxe}} It is to be placed in the same directory as your {{Code|.help}} file or anywhere in the Max/MSP class path.
 
If you do not want to use our installer, you can download the [http://www.phidgets.com/downloads/libraries/phidget21-x86_2.1.8.20110615.zip {{Code|phidget21.dll}}] and manually install it where you want; refer to our [[Manual Installation instructions]].
 
===Use Our Examples===
 
Please start by downloading the [http://www.phidgets.com/downloads/examples/WinMaxMSP_2.1.8.20120123.zip  Max/MSP Examples and Library].  These examples were written in Max/MSP 4.6, but are also supported on other versions.
 
To run the examples, you first download them [[#Quick Downloads|from above]] and unpack them into a folder. Here, you will find example programs, in {{code | .help}} format for all the devices. If you aren't sure what the software example for your device is called, check the software object listed in the [[Device List | Getting Started guide for your device]].
 
The only thing left to do is to run the examples! Open the {{code| .help}} file in the Max environment.
 
Once you have the Max/MSP examples running, we have a [[#Follow The Examples|teaching section]] below to help you follow them.
 
===Write Your Own Code===
 
When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure the Max/MSP environment to properly link the Phidget libraries. To begin:
 
Place the {{Code|.mxe}} in the same directory as the patcher, or anywhere in the Max/MSP class path. You can verify the class path locations by navigating to Options | File Preferences.
 
[[File:MaxMSP Path.PNG|link=|alt=Class Path]]
 
The best way to start writing your patch is to modify the examples, and saving it as a {{Code|.pat}} file.
 
If you wish to start a new patch. All you need to do is create an object named PhidgetXXX where XXX is the name of your device. For example, the [[Product - 1023 1 - PhidgetRFID | PhidgetRFID device]] will have the {{Code|PhidgetRFID}} object name.
The project now has access to the Phidget21 function calls and you are ready to begin coding.
 
The same [[#Follow The Examples|teaching]] section which describes the examples also has further resources for programming your Phidget.
 
==Mac OS X==
 
Max/MSP has excellent support on Mac OS X.
 
The first step in using C# on Mac is to install the Phidget libraries.  Compile and install them as explained on the [[Device List|getting started guide for your device]].  Then, the [[OS - Mac OS X]] page also describes the different Phidget files, their installed locations, and their roles....
 
==Follow The Examples==
 
By following the instructions for your operating system, you probably now have a working example and want to understand it better so you can change it to do what you want.  This teaching section has resources for you to learn from the examples and write your own.
 
Now, it is time to explain how to operate the example.
 
[[File:MaxMSP Example.PNG|link=|alt=Example]]
 
The above screenshot is what shows up when you open the example for the PhidgetInterfaceKit. If you are using a different device, your example patch will be different, but the idea is the same.
 
The Max object is called {{Code|PhidgetInterfaceKit}}, which is located in the center of the screen. Other objects are connected to the inputs and outputs of the PhidgetInterfaceKit object. The input objects will either cause the a property of the device to change or request for a property to be retrieved. The output objects return the retrieved information. All the supported features of the device are shown in the {{Code|.help}} file.
 
Try it for yourself! Click on the {{Code | getSerial}} message box to send a message to the your Phidget. You should see the last output object of {{Code|route}} changed to the serial number of your device. All devices support the {{Code|getSerial}} object, and is the easiest way to determine if the Phidget libraries are correctly set up, and whether the Max/MSP application is connected to your device.
 
[[File:MaxMSP getSerial.PNG|link=|alt=getSerial]]
 
If your example contains the {{Code|read}} message box, click on it. This will return all the device specific values to the screen.
 
[[File:MaxMSP read.PNG|link=|alt=Read Data]]
 
If your example contains the {{Code|start}} message box, you can continuously poll for events. Set the sample rate input for the {{Code|setSampleRate}} object. Then, press the {{Code|start}} message box. Upon events triggering, certain values will be continuously returned to the screen. Press the {{Code|stop}} message box to stop sampling.
 
For the PhidgetInterfaceKit example, there is also a {{Code|setoutput}} message box. Clicking on the check boxes will cause the digital outputs of the PhidgetInterfaceKit device to change. Your example may contain device specific message boxes/objects to click on. See for yourself what they do!
 
Next, comes our API information.  These resources outline the Max/MSP Phidget objects:
 
* [[Device List | Device Specific APIs]] (more general help on functions specific to your Phidget)
 
==Code Snippets==
 
==Common Problems and Solutions/Workarounds==
 
Here you can put various frequent problems and our recommended solutions.

Latest revision as of 18:18, 20 February 2024


We provide support for Max/MSP in macOS and Windows. We also provide instructions on how to get your project started. Select your operating system below, and follow the instructions to get your project running with Phidgets.

Once you have set up your development environment to run with Phidgets, we recommend you follow our guide on Phidget Programming Basics. The guide will showcase the fundamentals of programming with Phidgets.

Setup Guide

Max/MSP - Select Development Environment

Select your Development Environment:

Windows

macOS

Language - Max/MSP

Windows with Max/MSP

Welcome to using Phidgets with Max/MSP! By using Max/MSP, you will have access to the complete Phidget22 API, including events.

Phidget22 supports Max/MSP versions 6 and up.

Requirements

First, make sure you have the following installed:

● Phidgets Drivers for Windows (see Part 1 of this user guide)

Max/MSP

Use Our Examples

Next, download and unpack the Phidgets Max/MSP library:

Phidget Max/MSP library

Use Our Examples

After unpacking the download, navigate to the externals folder. Copy the following folder to your clipboard:

  • For 32-bit Max/MSP, copy the x86 folder
  • For 64-bit Max/MSP, copy the x64 folder

Use Our Examples

The folder you copied needs to be placed in a specific location for Max/MSP to reference it. Open Max/MSP and navigate to Options -> File Preferences.

Use Our Examples

The folder that you copied earlier needs to be placed in any of the locations listed in File Preferences. Navigate to one of the locations and paste the folder:

Use Our Examples

The Phidget Max/MSP library is now being referenced. Next, navigate to the examples folder located within the Phidget22MaxMSP folder you previously unpacked:

Use Our Examples

From here, select an example that will work with your Phidget and open it in Max/MSP. You can run the example by simply pressing the start button:

The example is now running. Play around with the device and experiment with some of the functionality. When you are ready, the next step is configuring your project and writing your own code!

Write Code

You should now have working examples and a project that is configured. This teaching section will help you understand how the examples were written so you can start writing your own code.

Remember: your main reference for writing Max/MSP code will be:

● The Phidget22 API Manual

● The Max/MSP examples

Write Code

First, let's explain how to operate the examples. We will take a look at the PhidgetVoltageInput example:

For this particular example, the Max object is called PhidgetVoltageInput. Objects/message boxes are connected to the inputs and outputs of this object. Input objects will either cause a property of the device to change or request for a property to be retrieved. Output objects return the retrieved information.

All supported functions for Max/MSP can be found in the Phidget22 API.

Write Code

Try it for yourself! Click on the getDeviceSerialNumber message box to request the Phidget to retrieve the serial number of the device. You should see the a message in the Max window denoting the serial number of your device. All devices support the getDeviceSerialNumber message, making it an easy way to determine if the Phidget libraries are correctly set up, and whether the Max/MSP application is connected to your device.

If your example contains a get[DataType] message box (e.g. getVoltage), click on it to cause the associated data to be output with a relevant prefix. [DataType] can be data member the object has. A list of available messages and their associated outputs is outlined in the Phidget22 API for your device.

Write Code

If your example contains the start message box, you can continuously poll for events. Just press the start message box to start sampling. When an event occurs on a Phidget (i.e. when a sensor detects a change in the measured data), associated data will be output with related prefixes. Press the stop message box to stop sampling.

For the PhidgetDigitalOutput example, there are setDutyCycle and setState message boxes. Changing the numbers will cause the digital output to change. Your example may contain device specific message boxes to click on. Click them to see what they do!

Write Code

Your best resource to program in MaxMSP will be our examples. If you aren't familiar with concepts in Phidget programming, you may find our Phidget Programming Basics page helpful. It provides a very generic overview of what traditional languages follow when using Phidgets. For Max users, conceptual details about particular actions (e.g. opening a Phidget) are explained there.

Keep in mind when reading these general resources that the Max/MSP libraries may not implement the full Phidgets API - some function calls and Phidget classes may not be supported.

In general, Phidget objects can be placed inside the patcher, and functions can be called on them using appropriately connected messages. We'll go over a basic setup next.

Write Code

Step One: Initialize and Open

Initializing and opening the device is be done by placing a new object. Other objects handle different Phidgets - a Spatial, a Light Sensor, a Motor Controller, etc. Only the name of the object changes. You can find the name for the object in the device's .maxhelp file (e.g. VoltageInput.maxhelp). If you are unsure what the software object for your device is, go to the API tab on its product page on our website.

In the case of a Voltage Input, we name it PhidgetVoltageInput:

Important: a local connection will reserve the device until closed. This prevents any other instances from retrieving data from the Phidget, including other programs. Every Phidget object in Max will automatically try to connect to and reserve a Phidget for itself. As long as a MaxMSP Phidget object is running, it will continuously try to connect to a Phidget, even trying to reconnect if it gets disconnected.

Write Code

Specifying a Phidget

When the instance is created as with the Voltage Input above, normally it will make a connection to the first device of its type it can find. The Phidget object can also be declared with a number of specifiers to open a specific Phidget instead.

Specifiers can be added to the object in the format: PhidgetExternal {Specifiers}. These will be written in the form: specifier=value

The full list of specifiers that can be used to identify a Phidget in Max/MSP are as follows:

  • serialnumber - The serial number of the device
  • channel - The channel of the device to open
  • hubport - The hub port the device is plugged into (where applicable)
  • ishubport - Specifies whether this channel should be opened on a hub port directly, or on a VINT device attached to a hub port.
  • remote - Forces connection to a remote device over a network, ignoring devices on the local machine
  • local - Forces connection to a device plugged into the local machine, ignoring network devices

Write Code

Specifying a Phidget

For instance, to open a VoltageInput with serial number 349428, you would use:

Some other examples:

Open a Digital Input:

PhidgetDigitalInput

Open channel 1 of a Digital Input Phidget connected to port 2 of a hub with serial number 35569

PhidgetDigitalInput serialnumber=35569 channel=1 hubport=2

Open open hub port 2 as a DigitalInput for a hub with serial number 35569

PhidgetDigitalInput serialnumber=35569 hubport=2 ishubport=1

Write Code

Using a Phidget Over a Network

To use the Network Server, first the Phidget needs to be plugged in to a computer that has the Network Server turned on within your local network. (For information on how to do this, see the Phidget Network Server page in the section on how to use the Network Server for your operating system).

Next, in your patch you need a PhidgetNet object. To automatically find local networks, send it a message saying enableServerDiscovery.

Then, to connect a Phidget over the network, change the object text to specify it is to connect to a Phidget on a remote server, as per the following example.

Write Code

Step Two: Wait for Attachment (plugging in) of the Phidget

Although this is a required step in many of our other languages (and therefore you may be expecting this if coming from another Phidget language), in MaxMSP you do not have to add a specific waitForAttachment block.

Keep in mind, however, that if your Phidget is not responding within your MaxMSP program, it may simply not be plugged in! Send a getAttached message to a Phidget object at any time to see if it's attached.

Write Code

Step Three: Do Things with the Phidget

Phidget data is accessed either by one-time polling or at a fixed rate via on-board timers for some devices.

Getting or setting values directly via polling on the Phidget is done through messages linked to the inlet. The object’s inlet can be wired to send commands to the device, and the outlet used to retrieve the results. You can set values on the Phidget by using the set messages, and some properties can be read with get messages:

To sample at a fixed rate, use the start and stop messages to start and stop the data flow, respectively.

Write Code

Step Three: Do Things with the Phidget

Outlet data is always given a prefix to allow for routing. For instance, the digital input state state change event data is given the prefix stateChange, and the voltage input voltage change event similarly use voltageChange. The specific prefixes for each set of outlet data is listed on the API page for that class.

The rightmost outlet on the Phidget object outputs error event data. This will send information on error events such as saturation events. To see which error events may apply to your device, check its API page.

Write Code

Step Four: Close and Delete

Although this is a required step in many of our other languages (and therefore you may be expecting this if coming from another Phidget language), in MaxMSP you do not have to add a specific close and delete block.

Special Case: Multiple Phidgets

Multiple Phidgets of the same type can easily be used inside a single program, it only requires another Phidget object placed. If two of the same type of Phidget object are placed, the serial number and channel arguments should always be specified (as well as hub port, if applicable) to ensure that the correct Phidget gets associated with the correct object.

What's Next?

Now that you've set up Phidgets in your programming environment, you should read our guide on Phidget Programming Basics to learn the fundamentals of programming with Phidgets.

Continue reading below for advanced information and troubleshooting for your device.

«
»

Language - Max/MSP

MacOS with Max/MSP

Welcome to using Phidgets with Max/MSP! By using Max/MSP, you will have access to the complete Phidget22 API, including events.

Phidget22 supports Max/MSP versions 6 and up.

Requirements

First, make sure you have the following installed:

● Phidgets Drivers for MacOS (see Part 1 of this user guide)

Max/MSP

Use Our Examples

Next, download and unpack the Phidgets Max/MSP library:

Phidget Max/MSP library

Use Our Examples

After unpacking the download, navigate to the externals folder and copy it to your clipboard:

Use Our Examples

The folder you copied needs to be placed in a specific location for Max/MSP to reference it. Open Max/MSP and navigate to Options -> File Preferences.

You will see something similar to this:

Use Our Examples

The folder that you copied earlier needs to be placed in any of the locations listed in File Preferences. Navigate to one of the locations and paste the folder:

Use Our Examples

The Phidget Max/MSP library is now being referenced. Next, navigate to the examples folder located within the Phidget22MaxMSP folder you previously unpacked:

Use Our Examples

From here, select an example that will work with your Phidget and open it in Max/MSP. You can run the example by simply pressing the start button:

The example is now running. Play around with the device and experiment with some of the functionality. When you are ready, the next step is configuring your project and writing your own code!

Write Code

You should now have working examples and a project that is configured. This teaching section will help you understand how the examples were written so you can start writing your own code.

Remember: your main reference for writing Max/MSP code will be:

● The Phidget22 API Manual

● The Max/MSP examples

Write Code

First, let's explain how to operate the examples. We will take a look at the PhidgetVoltageInput example:

For this particular example, the Max object is called PhidgetVoltageInput. Objects/message boxes are connected to the inputs and outputs of this object. Input objects will either cause a property of the device to change or request for a property to be retrieved. Output objects return the retrieved information.

All supported functions for Max/MSP can be found in the Phidget22 API.

Write Code

Try it for yourself! Click on the getDeviceSerialNumber message box to request the Phidget to retrieve the serial number of the device. You should see the a message in the Max window denoting the serial number of your device. All devices support the getDeviceSerialNumber message, making it an easy way to determine if the Phidget libraries are correctly set up, and whether the Max/MSP application is connected to your device.

If your example contains a get[DataType] message box (e.g. getVoltage), click on it to cause the associated data to be output with a relevant prefix. [DataType] can be data member the object has. A list of available messages and their associated outputs is outlined in the Phidget22 API for your device.

Write Code

If your example contains the start message box, you can continuously poll for events. Just press the start message box to start sampling. When an event occurs on a Phidget (i.e. when a sensor detects a change in the measured data), associated data will be output with related prefixes. Press the stop message box to stop sampling.

For the PhidgetDigitalOutput example, there are setDutyCycle and setState message boxes. Changing the numbers will cause the digital output to change. Your example may contain device specific message boxes to click on. Click them to see what they do!

Write Code

Your best resource to program in MaxMSP will be our examples. If you aren't familiar with concepts in Phidget programming, you may find our Phidget Programming Basics page helpful. It provides a very generic overview of what traditional languages follow when using Phidgets. For Max users, conceptual details about particular actions (e.g. opening a Phidget) are explained there.

Keep in mind when reading these general resources that the Max/MSP libraries may not implement the full Phidgets API - some function calls and Phidget classes may not be supported.

In general, Phidget objects can be placed inside the patcher, and functions can be called on them using appropriately connected messages. We'll go over a basic setup next.

Write Code

Step One: Initialize and Open

Initializing and opening the device is be done by placing a new object. Other objects handle different Phidgets - a Spatial, a Light Sensor, a Motor Controller, etc. Only the name of the object changes. You can find the name for the object in the device's .maxhelp file (e.g. VoltageInput.maxhelp). If you are unsure what the software object for your device is, go to the API tab on its product page on our website.

In the case of a Voltage Input, we name it PhidgetVoltageInput:

Important: a local connection will reserve the device until closed. This prevents any other instances from retrieving data from the Phidget, including other programs. Every Phidget object in Max will automatically try to connect to and reserve a Phidget for itself. As long as a MaxMSP Phidget object is running, it will continuously try to connect to a Phidget, even trying to reconnect if it gets disconnected.

Write Code

Specifying a Phidget

When the instance is created as with the Voltage Input above, normally it will make a connection to the first device of its type it can find. The Phidget object can also be declared with a number of specifiers to open a specific Phidget instead.

Specifiers can be added to the object in the format: PhidgetExternal {Specifiers}. These will be written in the form: specifier=value

The full list of specifiers that can be used to identify a Phidget in Max/MSP are as follows:

  • serialnumber - The serial number of the device
  • channel - The channel of the device to open
  • hubport - The hub port the device is plugged into (where applicable)
  • ishubport - Specifies whether this channel should be opened on a hub port directly, or on a VINT device attached to a hub port.
  • remote - Forces connection to a remote device over a network, ignoring devices on the local machine
  • local - Forces connection to a device plugged into the local machine, ignoring network devices

Write Code

Specifying a Phidget

For instance, to open a VoltageInput with serial number 349428, you would use:

Some other examples:

Open a Digital Input:

PhidgetDigitalInput

Open channel 1 of a Digital Input Phidget connected to port 2 of a hub with serial number 35569

PhidgetDigitalInput serialnumber=35569 channel=1 hubport=2

Open open hub port 2 as a DigitalInput for a hub with serial number 35569

PhidgetDigitalInput serialnumber=35569 hubport=2 ishubport=1

Write Code

Using a Phidget Over a Network

To use the Network Server, first the Phidget needs to be plugged in to a computer that has the Network Server turned on within your local network. (For information on how to do this, see the Phidget Network Server page in the section on how to use the Network Server for your operating system).

Next, in your patch you need a PhidgetNet object. To automatically find local networks, send it a message saying enableServerDiscovery.

Then, to connect a Phidget over the network, change the object text to specify it is to connect to a Phidget on a remote server, as per the following example.

Write Code

Step Two: Wait for Attachment (plugging in) of the Phidget

Although this is a required step in many of our other languages (and therefore you may be expecting this if coming from another Phidget language), in MaxMSP you do not have to add a specific waitForAttachment block.

Keep in mind, however, that if your Phidget is not responding within your MaxMSP program, it may simply not be plugged in! Send a getAttached message to a Phidget object at any time to see if it's attached.

Write Code

Step Three: Do Things with the Phidget

Phidget data is accessed either by one-time polling or at a fixed rate via on-board timers for some devices.

Getting or setting values directly via polling on the Phidget is done through messages linked to the inlet. The object’s inlet can be wired to send commands to the device, and the outlet used to retrieve the results. You can set values on the Phidget by using the set messages, and some properties can be read with get messages:

To sample at a fixed rate, use the start and stop messages to start and stop the data flow, respectively.

Write Code

Step Three: Do Things with the Phidget

Outlet data is always given a prefix to allow for routing. For instance, the digital input state state change event data is given the prefix stateChange, and the voltage input voltage change event similarly use voltageChange. The specific prefixes for each set of outlet data is listed on the API page for that class.

The rightmost outlet on the Phidget object outputs error event data. This will send information on error events such as saturation events. To see which error events may apply to your device, check its API page.

Write Code

Step Four: Close and Delete

Although this is a required step in many of our other languages (and therefore you may be expecting this if coming from another Phidget language), in MaxMSP you do not have to add a specific close and delete block.

Special Case: Multiple Phidgets

Multiple Phidgets of the same type can easily be used inside a single program, it only requires another Phidget object placed. If two of the same type of Phidget object are placed, the serial number and channel arguments should always be specified (as well as hub port, if applicable) to ensure that the correct Phidget gets associated with the correct object.

What's Next?

Now that you've set up Phidgets in your programming environment, you should read our guide on Phidget Programming Basics to learn the fundamentals of programming with Phidgets.

Continue reading below for advanced information and troubleshooting for your device.

«
»


Quick Downloads

If you already know what you're doing and just need the files, you can find them all below.

Documentation

Phidgets Max Libraries

Max Example Code

Phidgets Core Libraries