Language - Max/MSP: Difference between revisions

From Phidgets Support
No edit summary
No edit summary
Line 25: Line 25:
== Windows ==
== Windows ==
{{Windows_Languages}}
{{Windows_Languages}}
===Use Our Examples===
===Use our examples===
One of the best ways to start programming with Phidgets is to use our example code as a guide. In order to run the examples, you will need to download and install Max/MSP from [https://cycling74.com/downloads Cycling '74].
One of the best ways to start programming with Phidgets is to use our example code as a guide. In order to run the examples, you will need to download and install Max/MSP from [https://cycling74.com/downloads Cycling '74].


Line 52: Line 52:




The folder that you copied earlier needs to be placed in any of the locations listed in ''File Preferences''. Navigate to one of the folders and paste the folder:
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:
[[Image:Max_folder.PNG|link=|center]]
[[Image:Max_folder.PNG|link=|center]]




The Phidget Max/MSP library is now being referenced. Next, navigate to the ''examples'' folder located within the folder you previously unpacked:
The Phidget Max/MSP library is now being referenced. Next, navigate to the ''examples'' folder located within the Phidget22MaxMSP folder you previously unpacked:
[[Image:Max_examples.PNG|link=|center]]
[[Image:Max_examples.PNG|link=|center]]


Line 67: Line 67:


===Configure your project===
===Configure your project===
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 Max/MSP libraries. To begin:
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 Max/MSP library.
 
Place the .mxe in the same directory as the patcher, or anywhere in the Max/MSP search path. You can verify the search path locations by navigating to Options → File Preferences.
 
[[Image: MaxMSP_File_Preferences_PC.png|link=|500px]]
 
The best way to start writing your patch is to modify an example, and saving it as a .maxpat file.


If you wish to start a new patch. All you need to do is create an object named Phidget[Name] where [Name] is the name of your device. For example, the PhidgetRFID device will have the PhidgetRFID object name. The project now has access to the Phidget function calls and you are ready to begin coding.


The same [[#Edit the Examples|teaching section]] which describes the examples also has further resources for programming your Phidget.
Ensure the Phidget library files are moved to a location in the Max/MSP search path. This procedure is covered in detail above in the [[#Use our examples | use our examples]] section.  


==OS X==


The first step in using Max/MSP on Mac is to install the Phidget library. Compile and install as described on the OS - OS X page, which also describes the different Phidget files, their installed locations, and their roles.
After moving the library files into the correct location your project will have access to Phidgets. Next, view the [[#Write Code | write your own code]] section below.
 
===Use Our Examples===


==macOS==
{{macOS_Languages}}
===Use our examples===
Please start by downloading the Max/MSP Examples and Library and unpack them into a folder. These examples were written in Max/MSP 6, but any version above 6 is also supported.
Please start by downloading the Max/MSP Examples and Library and unpack them into a folder. These examples were written in Max/MSP 6, but any version above 6 is also supported.


Line 93: Line 86:
Once you have the Max/MSP examples running, we have a [[#Edit the Examples|teaching section]] below to help you follow them.
Once you have the Max/MSP examples running, we have a [[#Edit the Examples|teaching section]] below to help you follow them.


===Write Your Own Code===
===Configure your project===
 
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 Max/MSP libraries. To begin:
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 Max/MSP libraries. To begin:


Line 107: Line 99:
The same [[#Edit the Examples|teaching section]] which describes the examples also has further resources for programming your Phidget.
The same [[#Edit the Examples|teaching section]] which describes the examples also has further resources for programming your Phidget.


== Edit the Examples ==
== Write Code ==


By following the instructions for your operating system and compiler above, 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.
By following the instructions for your operating system and compiler above, 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.
Line 219: Line 211:


[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.
[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.
== Common Problems and Solutions/Workarounds ==
'''Crash: <span style="color:DarkRed">When a patch file is closed in the Max/MSP environment, the program crashes</span>'''
If in your Max/MSP environment, you have more patches(of the same Phidget object) than you have of the actual hardware device, the Max/MSP environment may crash. This is due to the fact that a single Phidget Max/MSP object only corresponds to a single Phidget device hardware. For example, your Max/MSP environment may experience unexpected behavior while you have one PhidgetInterfaceKit device connected to the computer, but you have a two seperate patches opened with a single PhidgetInterfaceKit Max object in each one.
Likely Fix: Please ensure that you do not use more patches(of the same Phidget object) than you have of the actual Phidget device.

Revision as of 16:30, 7 June 2017


Quick Downloads

Documentation

Example Code

Libraries

Getting Started 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. We also provide example code in Max/MSP for all Phidget devices.


If you are developing for Windows, keep reading. Otherwise, jump ahead to macOS.

Windows

If you haven't already, please visit the Windows page before you continue reading. There you will be instructed on how to properly set up your Windows machine so you can follow the guides below!

Use our examples

One of the best ways to start programming with Phidgets is to use our example code as a guide. In order to run the examples, you will need to download and install Max/MSP from Cycling '74.


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


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

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


Max externals.png


The folder you copied needs to be placed in a specific location for Max/MSP to reference it. We will find this location in in the next step.


Open Max/MSP and navigate to Options -> File Preferences.

Max filepreferences.png


You will see something similar to this:

Max filepreferences locations.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 folder.PNG


The Phidget Max/MSP library is now being referenced. Next, 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/MSP. You can run the example by simply pressing the start button:

Max run.png


You should now have the example up and running for your device. 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!

Configure your project

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 Max/MSP library.


Ensure the Phidget library files are moved to a location in the Max/MSP search path. This procedure is covered in detail above in the use our examples section.


After moving the library files into the correct location your project will have access to Phidgets. Next, view the write your own code section below.

macOS

If you haven't already, please visit the macOS page before you continue reading. There you will be instructed on how to properly set up your macOS machine so you can follow the guides below!

Use our examples

Please start by downloading the Max/MSP Examples and Library and unpack them into a folder. These examples were written in Max/MSP 6, but any version above 6 is also supported.

Here, you will find example programs, in .maxhelp format for all the devices. The source file will be named the same as the software object for your device. If you are not sure what the software object for your device is, find your Phidget on our webpage, and then check the Phidget22 API documentation for it.

The only thing left to do is to run the examples! Open the .maxhelp file in the Max environment.

Once you have the Max/MSP examples running, we have a teaching section below to help you follow them.

Configure your project

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 Max/MSP libraries. To begin:

Place the .mxe in the same directory as the patcher, or anywhere in the Max/MSP search path. You can verify the search path locations by navigating to Options → File Preferences.

MaxMSP File Preferences OSX.png

The best way to start writing your patch is to modify an example, and saving it as a .maxpat file.

If you wish to start a new patch. All you need to do is create an object named Phidget[Name] where [Name] is the name of your device. For example, the PhidgetRFID device will have the PhidgetRFID object name. The project now has access to the Phidget function calls and you are ready to begin coding.

The same teaching section which describes the examples also has further resources for programming your Phidget.

Write Code

By following the instructions for your operating system and compiler above, 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. Your main reference for writing Max/MSP code will be the Phidget22 API Manual:

Example Flow

First, let's explain how to operate the example.

MSP Example.png

The above screenshot is what shows up when you open the example for the PhidgetVoltageInput. If you are using a different device, your example patch will be different, but the idea is the same.

For this particular example, the Max object is called PhidgetVoltageInput, which is located near the bottom left of the screen. Objects/message boxes are connected to the inputs and outputs of the PhidgetVoltageInput object. The input objects will either cause 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 functions for Max/MSP will be documented in the Phidget22 API for your device.

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.

MaxMSP GetSerial.png

If your example contains a get[DataType] message box, click on it to cause the associated data to be output with a relevant prefix. [DataType] can denote any data the object may offer, such as Voltage for a voltage input. A list of available messages and their associated outputs is outlined in the Phidget22 API for your device.

MaxMSP GetVoltage.png

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!

For information regarding calls specific to your device, please see the Phidget22 API for your specific device, which can be found in its user guide.

Code Snippets

Your best resource to program code in MaxMSP will be our examples.

If you aren't familiar with concepts in Phidget programming, you may find our General Phidget Programming page helpful. It provides a very generic overview of what traditional languages follow when using Phidgets. For setup 'syntax', your main resource will of course be this MaxMSP page, the Phidget22 API, and the examples. But for conceptual details about particular actions - opening a Phidget, for example - the General Phidget Programming page is a more in-depth resource.

Keep in mind when reading these general resources that the Max/MSP libraries may not implement the full Phidget22 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 go over a basic setup for this below.

Step One: Initialize and Open

This tutorial uses a Phidget Voltage Input, and thus the object we use will be called PhidgetVoltageInput. Initializing and opening the device is be done by placing a new object. Other objects handle different Phidgets - a Spatial, a Temperature Sensor, a Motor Controller, etc. Only the name of the object changes. You can find the name for the object in the .maxhelp file for your device. The help file will be named the same as the software object for your device. If you are not sure what the software object for your device is, find your Phidget on our webpage, and then check the API documentation for it.

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

MaxMSP VoltageInput generic.png

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.

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 serial number, among other specifiers, to open a specific Phidget instead. To view a full list of available device specifiers and what they do, see the readme.txt included with the Phidget22 Max/MSP library.

MaxMSP VoltageInput specific.png

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.

MaxMSP Enable Server Discovery.png

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.

MaxMSP Remote.png

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.

Step Three: Do Things with the Phidget

There are two main approaches for retrieving data when working with Phidgets. 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. Setting values on the Phidget is achieved by using the set messages, and some properties can be read with get messages:

MaxMSP get and set.png

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

MaxMSP Start Stop.png

Data from the outlet of a Phidget object 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 used for each set of outlet data is listed under the API page for their class in the Phidget22 API.

MaxMSP Routing.png

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 in the Phidget22 API.

MaxMSP Error Event.png

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.

Further Reading

Phidget Programming Basics - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

Data Interval/Change Trigger - Learn about these two properties that control how much data comes in from your sensors.

Using Multiple Phidgets - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

Polling vs. Events - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

Logging, Exceptions, and Errors - Learn about all the tools you can use to debug your program.

Phidget Network Server - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.