Language - Max: Difference between revisions

From Phidgets Support
No edit summary
No edit summary
Line 1: Line 1:
[[File:icon-MaxMSP.png|64x64px]] Max/MSP, developed by [http://cycling74.com Cycling74] is a visual programming language for creating music and media applications.
[[File:icon-MaxMSP.png|64x64px]] Max/MSP, developed by [http://cycling74.com Cycling74] is a visual programming language for creating music and media applications.


==Support==
__TOC__
Max/MSP has a complete API and sample code for all Phidgets devices.


For a complete list of our supported languages and their support status, [[Levels of Support|click here]].
==Introduction==


* 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.
{{LanguageSupport|Max/MSP|the complete Phidget API, including events|all Phidget devices.| Windows and Mac OS X.}}
* In this section, list any restrictions or limitations that this particular language may impose. For example, incompatibility with certain operating systems.


==Development Environments and Compilers==
==Quick Downloads==
 
Just need the Max/MSP drivers, libraries, and examples?  Here they are:
 
API Documentation:
Should we include the next 2 links?
*[[General API]] (more help on functions common to all Phidgets)
*[[Device List | Device Specific APIs]] (more help on functions specific to your Phidget)
 
Max/MSP Library and Example Code:
 
*[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:
*[http://www.phidgets.com/downloads/libraries/Phidget-x86_2.1.8.20111220.exe 32 bit Windows (drivers, with libraries)]
*[http://www.phidgets.com/downloads/libraries/Phidget-x64_2.1.8.20111220.exe 64 bit Windows (drivers, with libraries)]
*[http://www.phidgets.com/downloads/libraries/libphidget_2.1.8.20111028.tar.gz General Linux Libraries] ([[OS - Linux | Linux Library Setup Instructions]])
*[http://www.phidgets.com/downloads/libraries/Phidget_2.1.8.20111103.dmg General Mac OSX Libraries] ([[OS - Mac OS X | Mac OS X Library Setup Instructions]])
 
==Getting started with Max/MSP==
 
If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:
{{ExampleCodeReasons}}
 
Instructions are divided up by operating system. Choose:
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#Mac OS X |Mac OS X]]
 
==Windows(2000/XP/Vista/7)==
 
===Libraries===
*[http://www.phidgets.com/downloads/examples/WinMaxMSP_2.1.8.20120123.zip Windows Library and Examples]
*[http://www.phidgets.com/downloads/examples/WinMaxMSP_2.1.8.20120123.zip Mac OS X Library and Examples]
 
===Description===
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.  If you used our installer, it's already correctly placed in <code>C:\Windows\System32</code>.  It can be manually installed - check our [[Manual Installation instructions]].
You will also need one of the following two files, depending on the .NET framework version you are targeting:
* <b><code>Phidget<Device Name>.mxe</code></b> is the Phidgets library for Max/MSP 4.5 or higher. It is to be placed in the same directory as your <code>.help</code> file
 
 
===Use Our Examples===


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.  
Please start by downloading the Max/MSP Examples.  These examples were written in Visual Studio 2005 and 2008, but Visual Studio 2010 will easily upgrade them.  
*[http://www.phidgets.com/downloads/examples/WinMaxMSP_2.1.8.20120123.zip Max/MSP Examples]


==Quick Downloads==
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.
To run the examples, you first download them [[#Quick Downloads|from above]] and unpack them into a folder.  To load all projects in Visual Studio, go to File | Open | Project, and open <code>AllExamples/AllExamples.sln</code> or <code>AllExamples/AllExamples_vs2008.sln</code> for Visual Studio 2005 and 2008, respectively.


==Getting Started==
If you are opening the Phidget examples in Visual Studio 2010, you will need to go through the Visual Studio Conversion Wizard to convert the 2005 or 2008 project.
<br/><br/>[[File:VS2005 Conversion Wizard.PNG]]<br/><br/>


The Phidget libraries were written to support Max/MSP version 4.5 and greater.
This will load all of the examples available for C#, and then you can set your main project to be the one that matches your device. 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]].
This tutorial assumes the use of Max 5 but other versions can be set up and used in the same way.
To install the Phidgets to the Max environment, just add the Phidget Max/MSP examples folder to the Max search path.
This can be done in Options | File Preferences, by adding the Phidget Max/MSP examples directory to the list.
The project is now ready to use Phidgets and you can begin by creating a new Patcher (File | New Patcher).


===Coding For Your Phidget===
The only thing left to do is to run the examples! Click on Debug -> Start Debugging. Please note that the projects, by default try to find the <code>Phidget21.NET.dll</code> in the <code>C:\Program Files\Phidgets</code>. If you have it installed in another location, please change the path accordingly. If you are receiving an error message regarding that the namespace Phidgets cannot be found, please re-add the reference to <code>Phidget21.NET.dll</code>. Please see the [[#Write Your Own Code | next section]] for details.
<br/><br/>
[[File:CSharp VS2005 Run.PNG ‎]]
<br/><br/>
Once you have the C# examples running, we have a [[#Follow The Examples|teaching section]] below to help you follow them.


Phidgets can be placed inside the patcher using Max objects, and functions can be called on them using appropriately connected messages.
=====Write Your Own Code=====
The Max/MSP libraries may not implement the full Phidget API - some function calls and Phidget classes may not be supported.
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.
The Phidget webservice is supported.
This tutorial uses a PhidgetInterfaceKit and a new instance will be created.
It can be done by placing a new “object” object, and naming it PhidgetInterfaceKit.


[[Image:MaxMSP1.jpg]]
When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your compiler / development environment to properly link the Phidget C# libraries. To begin:  


===Connecting to the Phidget===
* Generate a new Visual C# Windows Applications project with a descriptive name such as PhidgetTest.
<br/>[[File:CSharp VS2005 New Project.PNG ]]


One important thing to remember is that when working with Phidgets, a local connection will reserve the device until closed.
<br/>
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]]
* Add a reference to the .NET Phidgets library.
<br/>[[File:CSharp VS2005 Add Reference.PNG ]]<br/>
* Under the .NET tab, select <code>Phidget21.NET.dll</code>.
If you used our installer, these files are installed in <code>C:\Program Files\Phidgets</code>, by default. If it does not appear in this list, then you can browse to the Phidget Framework installation directory and add the file.
<br/>[[File:CSharp VS2005 Add Reference 2.PNG ]]<br/><br/>


We can also open remote Phidgets over the Phidget Webservice, for example:
Then, in your code, you will need to include the Phidget library:


Open a remote interface kit using ServerID:
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<font size="3">
PhidgetInterfaceKit remote “Some remote serverID”
<source lang=cpp>
  using Phidgets;
  using Phidgets.Events;
  </source>
</font>
</font>
Open a remote interface kit using IP address and port:
</div>
<font size="3">
 
PhidgetInterfaceKit remoteip 192.168.2.5 5001
The project now has access to the Phidget21 function calls and you are ready to begin coding.
</font>
 
Open a remote interface kit with serial number 35569 on serverID “Patrick’s PC”, with
The same [[#Follow The Examples|teaching section]] which describes the examples also has further resources for programming your Phidget.
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]]
==Mac OS X==


There are two main approaches for retrieving data when working with Phidgets.
Max/MSP has excellent support on Mac OS X.
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]]
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....


Phidget specific data is always given a prefix in Max to allow for their routing.
==Follow The Examples==
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]]
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.


===Working with multiple Phidgets===
Next, comes our API information.  These resources outline the Max/MSP Phidget functions:


Multiple Phidgets of the same type can easily be used inside a single program, it only requires another Phidget object placed.  
{{UsingAPhidgetInCodeGeneral|both of which are available in Max/MSP|[http://www.phidgets.com/documentation/Phidget21.NET.zip C# API]}}
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===
===Example Flow===


The design given in this document can also be followed for almost all Phidgets.  
{{ExamplePseudocode|In C#, you can name these '''event''' functions whatever you like.  You will then pass them as function pointers to the Phidget library below in the Main Code section.  This hooks them into the actual events when they occur. <br>
For example, if you were using a PhidgetRFID instead of an Interfacekit, you would place a PhidgetRFID object instead of a PhidgetInterfaceKit.  
In the example code, the event functions common to all Phidgets are called things like '''AttachHandler()''' and '''DetachHandler()''', etc.<br><br>
The messages and data available would change but could be used in a similar manner.  
Some event functions will be specific to each device, like when a tag is read on an RFID board, or when a sensor value changes on an Interface Kit.
Other functions are given in the examples to show you more detail on using your Phidget.  For example, '''DeviceInitialize()''' will show what needs to be set up for your Phidget before using it.
|Creating a Phidget software object in C# is specific to the Phidget.  For a Phidget Spatial, for example, this would involve creating a <code>Spatial</code> object. The examples show how to do this and other API functions.<br><br>
The object provides device specific methods and properties which are available from the API for your specific Phidget.|
[http://www.phidgets.com/documentation/Phidget21.NET.zip C# API]}}


==Building your Project==
==Code Snippets==
Describe the different ways a project could be built using this language.


==Common Problems and Solutions/Workarounds==
==Common Problems and Solutions/Workarounds==
Here you can put various frequent problems and our recommended solutions.
Here you can put various frequent problems and our recommended solutions.

Revision as of 20:40, 24 January 2012

Icon-MaxMSP.png Max/MSP, developed by Cycling74 is a visual programming language for creating music and media applications.

Introduction

Template:LanguageSupport

Quick Downloads

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

API Documentation:
Should we include the next 2 links?

Max/MSP Library and Example Code:

Libraries and Drivers:

Getting started with Max/MSP

If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:

  • Make sure your libraries are properly linked
  • Go from source code to a test application as quickly as possible
  • Ensure your Phidget is hooked up properly

Instructions are divided up by operating system. Choose:

Windows(2000/XP/Vista/7)

Libraries

Description

Max/MSP programs on Windows depend on the following files, which the installers above put onto your system:

  • phidget21.dll contains the actual Phidgets library, which is used at run-time. If you used our installer, it's already correctly placed in C:\Windows\System32. It can be manually installed - check our Manual Installation instructions.

You will also need one of the following two files, depending on the .NET framework version you are targeting:

  • Phidget<Device Name>.mxe is the Phidgets library for Max/MSP 4.5 or higher. It is to be placed in the same directory as your .help file


Use Our Examples

Please start by downloading the Max/MSP Examples. These examples were written in Visual Studio 2005 and 2008, but Visual Studio 2010 will easily upgrade them.


To run the examples, you first download them from above and unpack them into a folder. To load all projects in Visual Studio, go to File | Open | Project, and open AllExamples/AllExamples.sln or AllExamples/AllExamples_vs2008.sln for Visual Studio 2005 and 2008, respectively.

If you are opening the Phidget examples in Visual Studio 2010, you will need to go through the Visual Studio Conversion Wizard to convert the 2005 or 2008 project.

VS2005 Conversion Wizard.PNG

This will load all of the examples available for C#, and then you can set your main project to be the one that matches your device. If you aren't sure what the software example for your device is called, check the software object listed in the Getting Started guide for your device.

The only thing left to do is to run the examples! Click on Debug -> Start Debugging. Please note that the projects, by default try to find the Phidget21.NET.dll in the C:\Program Files\Phidgets. If you have it installed in another location, please change the path accordingly. If you are receiving an error message regarding that the namespace Phidgets cannot be found, please re-add the reference to Phidget21.NET.dll. Please see the next section for details.

CSharp VS2005 Run.PNG

Once you have the C# examples running, we have a 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 your compiler / development environment to properly link the Phidget C# libraries. To begin:

  • Generate a new Visual C# Windows Applications project with a descriptive name such as PhidgetTest.


CSharp VS2005 New Project.PNG


  • Add a reference to the .NET Phidgets library.


CSharp VS2005 Add Reference.PNG

  • Under the .NET tab, select Phidget21.NET.dll.

If you used our installer, these files are installed in C:\Program Files\Phidgets, by default. If it does not appear in this list, then you can browse to the Phidget Framework installation directory and add the file.
CSharp VS2005 Add Reference 2.PNG

Then, in your code, you will need to include the Phidget library: 

  using Phidgets;
  using Phidgets.Events;

The project now has access to the Phidget21 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.


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 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 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.

Next, comes our API information. These resources outline the Max/MSP Phidget functions:

Template:UsingAPhidgetInCodeGeneral

Example Flow

Template:ExamplePseudocode

Code Snippets

Common Problems and Solutions/Workarounds

Here you can put various frequent problems and our recommended solutions.

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