Language - Max: Difference between revisions

From Phidgets Support
No edit summary
 
(183 intermediate revisions by 11 users not shown)
Line 1: Line 1:
[[File:icon-MaxMSP.png|64x64px]] Max/MSP, developed by [http://cycling74.com/.com Cycling74] is a visual programming language for creating music and media applications.
{{#seo:|description=Learn how to use Phidget USB devices with Max.}}
[[Category:Language]]


==Support==
==Get Started==
Max/MSP has a complete API and sample code for all Phidgets devices.
With the Phidgets Max library, it's easy to create Max patches that work with Phidget devices.


For a complete list of our supported languages and their support status, [[Levels of Support|click here]].
==Max Libraries==
To develop on Max with Phidgets, you'll need the [https://www.phidgets.com/downloads/phidget22/libraries/windows/Phidget22MaxMSP.zip Phidgets Max Library].  


* Our honest opinion on how well this language is suited to controlling Phidgets. If it is a poor choice, suggest and link similar (better) languages.
Unpack the zip file and copy the appropriate folder:
* In this section, list any restrictions or limitations that this particular language may impose. For example, incompatibility with certain operating systems.
* For 32-bit Max, copy the '''x86''' folder.
* For 64-bit Max, copy the '''x64''' folder.


==Development Environments and Compilers==
The folder you copied needs to be placed in a specific location for Max to reference it. Open Max and navigate to '''Options -> File Preferences'''.


Describe each major compiler and notable differences or important information. (eg. framework versions) If there are known issues/workarounds mention them and link to the corresponding issue at the bottom of the page.
[[Image:Max_filepreferences2.png|link=|center]]


==Quick Downloads==
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:
Before you can run your program, you need to set up the proper environment and get the necessary files off the Phidgets website.  
Visit the drivers section at www.phidgets.com and get the latest:
* [http://www.phidgets.com/drivers.php Phidget Framework]
You will need the Phidget Framework to use and to program with Phidgets. We also recommend that you download the following reference materials:
* API Manual (Link to API download)
* API Reference (Link to online API reference (if applicable))
* Max/MSP Sample Code:
** [http://www.phidgets.com/downloads/examples/WinMaxMSP_2.1.8.20110615.zip Windows]
** [http://www.phidgets.com/downloads/examples/MaxMSP_2.1.8.20110630.zip Mac OSX]
* You can find a high level discussion about programming with Phidgets in general on the [[General API]] page.
* The [[Device Functionality]] page explains the general operational information for your device.


You may want to have these pages open while working through these instructions.
[[Image:Max_folder2.PNG|link=|center]]


==Getting Started==
The Phidget Max library can now be referenced.


The Phidget libraries were written to support Max/MSP version 4.5 and greater.
==Development Environment Configuration==
This tutorial assumes the use of Max 5 but other versions can be set up and used in the same way.
===Using Our Examples===
To install the Phidgets to the Max environment, just add the Phidget Max/MSP examples folder to the Max search path.  
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
This can be done in Options | File Preferences, by adding the Phidget Max/MSP examples directory to the list.  
|+ '''Instructions'''
The project is now ready to use Phidgets and you can begin by creating a new Patcher (File | New Patcher).
|-
| Navigate to the '''examples''' folder located within the Phidget22MaxMSP folder you previously unpacked: ||[[Image:Max_examples.PNG|link=https://cdn.phidgets.com/docs/images/a/a0/Max_examples.PNG|350px]]
|-
|From here, select an example that will work with your Phidget and open it in Max. You can run the example by simply pressing the '''start''' button.<br/><br/>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! || [[Image:Max_run2.png|link=https://cdn.phidgets.com/docs/images/f/f8/Max_run2.png|350px]]
|-
|}


===Coding For Your Phidget===
=== Writing your own Code ===


Phidgets can be placed inside the patcher using Max objects, and functions can be called on them using appropriately connected messages.  
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
The Max/MSP libraries may not implement the full Phidget API - some function calls and Phidget classes may not be supported.  
|+ '''Instructions'''
The help files included with the Phidget externals show all the supported function calls for their type of Phidget.
|-
Data is accessed either by polling, or at a fixed rate via internal timers.  
|colspan="2"| 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.<br/>Your main reference for writing Max code will be:<br/><br/>
The Phidget webservice is supported.
* The [https://www.phidgets.com/?view=api Phidget22 API] Manual
This tutorial uses a PhidgetInterfaceKit and a new instance will be created.  
* The Max [https://www.phidgets.com/?view=code_samples&lang=MaxMSP examples]
It can be done by placing a new “object” object, and naming it PhidgetInterfaceKit.
|-
| First, let's explain how to operate the examples. We will take a look at the PhidgetVoltageInput example:<br/><br/>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.<br/><br/>All supported functions for Max can be found in the [https://www.phidgets.com/?view=api Phidget22 API].||[[File:MSP_Example2.png|link=https://cdn.phidgets.com/docs/images/f/f9/MSP_Example2.png|350px]]
|-
|You can click on the '''getDeviceSerialNumber''' message box to request the Phidget to retrieve the serial number of the device.||[[File:MaxMSP_GetSerial.png|link=]][[File:MaxMSP_GetVoltage.png|link=]]
|-
|colspan="2"|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.
|-
|colspan="2"|If your example contains '''start''' and '''stop''' message boxes, you can use them to turn on continuous polling for events. <br/><br/>For the PhidgetDigitalOutput example, there are '''setDutyCycle''' and '''setState''' message boxes that control the output.
|-
|colspan="2"|Your best resource to program in Max will be our examples. If you aren't familiar with concepts in Phidget programming, see the [https://www.phidgets.com/docs/Phidget_Programming_Basics Phidget Programming Basics].
|-
|colspan="2"|{{hiddenh4|Step One: Initialize and Open}}
|-
|Initializing and opening the device is 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'''.<br/><br/>'''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 Max Phidget object is running, it will continuously try to connect to a Phidget, even trying to reconnect if it gets disconnected.||[[File:MaxMSP_VoltageInput_generic.png|link=]][[File:MaxMSP_GetVoltage.png|link=]]
|-
|colspan="2"|{{hiddenh4|Specifying a Phidget}}
|-
|colspan="2"|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.


[[Image:MaxMSP1.jpg]]
Specifiers can be added to the object in the format: '''PhidgetExternal {Specifiers}'''


===Connecting to the Phidget===
These will be written in the form: '''specifier=value'''


One important thing to remember is that when working with Phidgets, a local connection will reserve the device until closed.
Available specifiers include:
This prevents any other instances from retrieving data from the Phidget, including other programs.
The one connection per device limit does not apply when using the Phidget Webservice. 
Be aware that every Phidget object in Max will automatically try to connect to and reserve the Phidget for itself.
It will also continuously try to connect to a Phidget, even trying to reconnect if it gets disconnected.
When the instance is created, 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 serial number to open a specific Phidget instead:  


[[Image:MaxMSP2.jpg]]
* '''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''' - Should this channel be opened on a hub port directly, or on a connected VINT device (default)
* '''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
|-
| '''Example:''' Opening a VoltageInput with serial number 349428. ||[[File:MaxMSP_VoltageInput_specific.png|link=]]
|-
|colspan="2"|Here are some other examples:
*Open a Digital Input:
<syntaxhighlight>PhidgetDigitalInput</syntaxhighlight>
*Open channel 1 of a Digital Input Phidget connected to port 2 of a hub with serial number 35569
<syntaxhighlight>PhidgetDigitalInput serialnumber=35569 channel=1 hubport=2</syntaxhighlight>
*Open open hub port 2 as a DigitalInput for a hub with serial number 35569
<syntaxhighlight>PhidgetDigitalInput serialnumber=35569 hubport=2 ishubport=1</syntaxhighlight>
|-
|colspan="2"|{{hiddenh4|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, see the [[Phidget Network Server]] page). Add a '''PhidgetNet''' object and send the message:'''enableServerDiscovery'''<br/>Then configure the object to connect to a remote server.||[[File:MaxMSP_Enable_Server_Discovery.png|link=]][[File:MaxMSP_Remote.png|link=]]
|-
|colspan="2"|{{hiddenh4|Step Two: Wait for Attachment}}
|-
|colspan="2"|In Max you do not need a specific '''waitForAttachment''' block. However, if your Phidget is not responding, ensure it is plugged in. Send a '''getAttached''' message to check.
|-
|colspan="2"|{{hiddenh4|Step Three: Do Things with the Phidget}}
|-
|Getting or setting values is done through messages linked to the inlet.<br/>Use '''set''' messages to change values and '''get''' messages to read them.</br>Use '''start''' and '''stop''' to control continuous sampling.||[[File:MaxMSP_get_and_set.png|link=]][[File:MaxMSP_Start_Stop.png|link=]]
|-
|colspan="2"|Phidget data is accessed either by one-time polling or at a fixed rate via on-board timers for some devices.<br/><br/>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.<br/><br/>To sample at a fixed rate, use the start and stop messages to start and stop the data flow, respectively.
|-
|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.<br/><br/>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.||[[File:MaxMSP_Routing.png|link=]][[File:MaxMSP_Error_Event.png|link=]]
|-
|colspan="2"|{{hiddenh4|Step Four: Close and Delete}}
|-
|colspan="2"|In Max you do not need a specific close/delete block.
|-
|colspan="2"|{{hiddenh4|Special Case: Multiple Phidgets}}
|-
|colspan="2"|Multiple Phidgets can be used in a single program by adding additional objects.<br/>If using multiple devices of the same type, specify the '''serial number''' and '''channel''' to ensure the correct device is used.
|-
|}


We can also open remote Phidgets over the Phidget Webservice, for example:
== Max Example Code ==
*{{SampleCode|MaxMSP|Max Examples}}


Open a remote interface kit using ServerID:
==Phidget Programming Basics==
<font size="3">
{{PhidgetProgrammingBasicsLink}}
PhidgetInterfaceKit remote “Some remote serverID”
</font>
Open a remote interface kit using IP address and port:
<font size="3">
PhidgetInterfaceKit remoteip 192.168.2.5 5001
</font>
Open a remote interface kit with serial number 35569 on serverID “Patrick’s PC”, with
password “pass”:
<font size="3">
PhidgetInterfaceKit 35569 remote “Patrick’s PC” pass
</font>
Open a remote interface kit with serial number 35569, on any remote server
<font size="3">
PhidgetInterfaceKit 35569 remote
</font>
Open the InterfaceKit on a PhidgetSBC:
<font size="3">
PhidgetInterfaceKit remote phidgetsbc
</font>
===Reading and Setting Data===
 
Getting or setting values directly on the Phidget can be 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.
Setting values on the Phidget is achieved by using the set messages, and some properties can be read with get messages.
 
[[Image:MaxMSP3.jpg]]
 
There are two main approaches for retrieving data when working with Phidgets.
One is to use the read message, and the other is to setSampleRate and use the start and stop message.
Read will read the data off the Phidget once, while using start will trigger data to be sent in periodic intervals.
If the sample rate is set to -1, then data output is only triggered on a change.
 
[[Image:MaxMSP4.jpg]]
 
Phidget specific data is always given a prefix in Max to allow for their routing.
For instance, the digital input states are given the prefix “di” and the analog inputs similarly use “ai”.
The specific prefixes used for each Phidget is listed in their respective help file.
Data common to all Phidgets, such as the serial number, is not prefixed.
The following picture would be an example of how to route and split some of the data for the PhidgetInterfaceKit.
 
[[Image:MaxMSP5.jpg]]
 
===Working with 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 argument should always be specified to ensure that the correct Phidget gets associated with the correct object.
 
===Other Phidgets===
 
The design given in this document can also be followed for almost all Phidgets.
For example, if you were using a PhidgetRFID instead of an Interfacekit, you would place a PhidgetRFID object instead of a PhidgetInterfaceKit.
The messages and data available would change but could be used in a similar manner.
 
==Building your Project==
Describe the different ways a project could be built using this language.
 
==Common Problems and Solutions/Workarounds==
Here you can put various frequent problems and our recommended solutions.

Latest revision as of 21:52, 16 March 2026


Get Started

With the Phidgets Max library, it's easy to create Max patches that work with Phidget devices.

Max Libraries

To develop on Max with Phidgets, you'll need the Phidgets Max Library.

Unpack the zip file and copy the appropriate folder:

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

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

Max filepreferences2.png

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:

Max folder2.PNG

The Phidget Max library can now be referenced.

Development Environment Configuration

Using Our Examples

Instructions
Navigate to the examples folder located within the Phidget22MaxMSP folder you previously unpacked: Max examples.PNG
From here, select an example that will work with your Phidget and open it in Max. 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!		 Max run2.png

Writing your own Code

Instructions
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.
Your main reference for writing Max code will be:

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 can be found in the Phidget22 API.		 MSP Example2.png
You can click on the getDeviceSerialNumber message box to request the Phidget to retrieve the serial number of the device. MaxMSP GetSerial.pngMaxMSP GetVoltage.png
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.
If your example contains start and stop message boxes, you can use them to turn on continuous polling for events.

For the PhidgetDigitalOutput example, there are setDutyCycle and setState message boxes that control the output.
Your best resource to program in Max will be our examples. If you aren't familiar with concepts in Phidget programming, see the Phidget Programming Basics.
Step One: Initialize and Open
Initializing and opening the device is 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 Max Phidget object is running, it will continuously try to connect to a Phidget, even trying to reconnect if it gets disconnected.		 MaxMSP VoltageInput generic.pngMaxMSP GetVoltage.png
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

Available specifiers include:

  • 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 - Should this channel be opened on a hub port directly, or on a connected VINT device (default)
  • 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
Example: Opening a VoltageInput with serial number 349428. MaxMSP VoltageInput specific.png
Here are 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
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, see the Phidget Network Server page). Add a PhidgetNet object and send the message:enableServerDiscovery
Then configure the object to connect to a remote server.		 MaxMSP Enable Server Discovery.pngMaxMSP Remote.png
Step Two: Wait for Attachment
In Max you do not need a specific waitForAttachment block. However, if your Phidget is not responding, ensure it is plugged in. Send a getAttached message to check.
Step Three: Do Things with the Phidget
Getting or setting values is done through messages linked to the inlet.
Use set messages to change values and get messages to read them.
Use start and stop to control continuous sampling.		 MaxMSP get and set.pngMaxMSP Start Stop.png
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.
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.		 MaxMSP Routing.pngMaxMSP Error Event.png
Step Four: Close and Delete
In Max you do not need a specific close/delete block.
Special Case: Multiple Phidgets
Multiple Phidgets can be used in a single program by adding additional objects.
If using multiple devices of the same type, specify the serial number and channel to ensure the correct device is used.

Max Example Code

Phidget Programming Basics

To learn more about the structure of the example code, visit our Phidget Programming Basics guide.

Retrieved from "https://www.phidgets.com/docs/index.php?title=Language_-_Max&oldid=35508"