Language - MATLAB

MATLAB is a scientific and numerical analysis oriented language, with many graphical libraries and a wide user base.

Introduction

If this is your first time working with a Phidget, we suggest starting with the Getting Started page for your specific device. This can be found in the user guide for your device. That page will walk you through installing drivers and libraries for your operating system, and will then bring you back here to use MATLAB specifically.

MATLAB is capable of using the non-event driven part of the Phidget API. We also provide example code in MATLAB for AdvancedServo, Encoder, InterfaceKit, Servo and Stepper.

MATLAB can be developed with any operating system that can run MATLAB code.

You can compare MATLAB with our other supported languages.

If you want to use the events provided by the Phidget library (for, say, collecting sensor data as it changes) then consider using Python as a wrapper. Python has many libraries which can provide MATLAB-like functionality, such as:

• MatplotLib (plotting functions very similar to MATLAB)
• NumPy (array functions similar to MATLAB)
• SciPy (scientific functions similar to MATLAB libraries)

There is also Pytave, which interfaces with Octave, which can read .m files. Using the list of libraries above would mimic MATLAB abilities in Python. Using Pytave would allow you to open most MATLAB code directly, as long as it works on Octave. In both of these cases, you would use the Python Phidget libraries, and Python as your main Phidget programming language, not MATLAB. Python has excellent web documentation, and it is interpreted like MATLAB so there is no need to compile.

We do not support Octave. Phidgets in MATLAB depend on the calllib() function, which Octave does not have. For workarounds, see our common problems section. Also, the calllib library uses our C libraries, so programming in MATLAB for Phidgets uses the C API.

Quick Downloads

Just need the MATLAB documentation, drivers, libraries, and examples? Here they are:

Documentation

• API Manual

Example Code

• MATLAB Example Code

Libraries and Drivers

• MATLAB (Windows and Mac) Libraries
• 32-bit Windows Drivers Installer
• 64-bit Windows Drivers Installer
• Windows Driver and Library Files (Zipped)
• OS X Drivers Installer
• Linux Libraries (Source Code)

Quick Downloads

Just need the MATLAB drivers, libraries, and examples? Here they are.

• MATLAB Sample Code, including the phidget21Matlab.h library file, needed for any MATLAB project.

MATLAB depends on the C/C++ libraries, and all MATLAB calls essentially call functions in the C library. So. you need the C/C++ drivers and libraries, and you may also find the C/C++ API reference handy:

• C/C++ API Manual Download or (HTML online version)
• General API (more help on functions common to all Phidgets)
• Device Specific APIs (more help on functions specific to your Phidget)

Libraries and Drivers which MATLAB depends on:

• 32 bit Windows (drivers, with libraries)
• 64 bit Windows (drivers, with libraries)
• General Linux Libraries ( Linux Library Setup Instructions)
• General Mac OSX Libraries ( Mac OSX Library Setup Instructions)

Getting Started with MATLAB (Windows)

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

Use Our Examples

Start by using and modifying existing examples. You can find the MATLAB example code here:

• MATLAB Examples

If you are using a 64 bit version of Windows, a small modification to the phidget21Matlab.h will be required to use our examples or writing your own code. Please add the following lines to the beginning of the file:

  #ifndef WIN32 
  #define __stdcall
  #endif

To run the example code, you'll need to unpack the download and find the source code for your specific device within the example package. The file you need will be named something similar to your device name. Once you have found the file that runs your device, copy that .m source file and phidget21Matlab.h from the examples folder to your project directory. Then, run the code within MATLAB as you would any .m file. For example, from the MATLAB command line, to run the example that reads the analog input from a Phidget Interface Kit:

  run analogin.m

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

If you receive an error regarding that the selected compiler cannot be found.

You will have to to configure your compiler for MATLAB by entering the following command in the MATLAB command window:

  mex -setup

Next, select y to view all installed compilers.

Finally, select the compiler you wish MATLAB to use.

Write Your Own Code

You can write your MATLAB code the same way you usually do, whether within a text editor or within MATLAB itself. However, to use Phidget calls within your code, you must include a reference to the Phidget library in your main body of code, before any Phidget calls:

  function phidgettest(n)
     loadlibrary phidget21 phidget21Matlab.h;
      % More code goes here
  end

Also, before running your code, remember to copy phidget21Matlab.h to your project directory.

Getting Started with MATLAB (Mac OS)

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

Use Our Examples

Due to different library naming conventions, as well as different compiler support for the behind-the-scenes libraries, you will have to make two small modifications to our MATLAB examples to run them on Mac OSX or 32-bit Linux.

First, you need to make one change to phidget21Matlab.h, by adding the following to the top of the file:

  #ifndef WIN32 
  #define __stdcall
  #endif

Save the file and keep it in the same folder where you will run the example.

This change simply defines __stdcall to be nothing. The __stdcall function is not supported on a Mac or Linux because it is not supported by the library compiler gcc. Removing the __stdcall definition will simply call the Phidget functions in a raw manner rather than having the stack managed by the function itself.

The next change is to the example .m source code file you are using. In all of the example code .m files, there is a line near the very top (line 4 or so) that says:

loadlibrary phidget21 phidget21Matlab.h;

or:

loadlibrary ('phidget21', 'phidget21Matlab.h');

On Mac OSX, this needs to be changed to:

loadlibrary /Library/Phidget21.framework/Versions/Current/Phidget21 phidget21Matlab.h alias phidget21

On Linux, this needs to be changed to:

loadlibrary /usr/lib/libphidget21.so phidget21Matlab.h alias phidget21

For both systems, the location of Phidget21 (Mac) and libphidget21.so (Linux) should be the actual location of the Phidget libraries on your system. If you just did a default install, the locations as written above should be fine. Otherwise, find the libraries (use a search or locate function from the command line or operating system) and substitute their actual location.

These changes are needed because the Phidget libraries are named differently on Mac OSX and Linux than they are on Windows. On Windows, the loadlibrary function looks for a phidget21.dll file and links it to the phidget21 alias used throughout the MATLAB program. This alias linking happens automatically because the library and the alias have the same name, including capitalization.

On Mac OSX, however, the library to be linked is the executable Phidget21. Because it does not have exactly the same name as phidget21 (which is used as the alias in the rest of the .m code), you have to link it and alias it explicitly. The same goes for Linux, where the library to be linked is libphidget21.so

Without these changes, the errors that appear can be quite strange. They show up as file-not-found errors, ELF-header errors, or simply evalin() errors, depending on whether you've changed the phidget21Matlab.h file, the path, the file, or none of the above. The file-not-found error looks like this:

Error in ==> digitalout at 3
loadlibrary phidget21 phidget21Matlab.h;

Error in ==> run at 74
    evalin('caller',[script ';']);

Caused by:
    Error using ==> loaddefinedlibrary
    phidget21.so: cannot open shared object file: No such file or directory

In the case of both Linux and Mac OSX, the phidget21Matlab.h file should be either in the current project directory, or in a MATLAB path (type path in MATLAB to see the current setup). If you prefer to use parentheses and quotations for aliasing (to keep your formatting strict), you can read about the various syntax options for the loadlibrary function on the MathWorks website.

Once you have made the changes above to both the phidget21Matlab.h file and the *.m example file you want to run, running the example you want is easy. Just put the *.m example and the phidget21Matlab.h file into your current directory in Matlab, and type the example name.

For instance, to use the analogin.m example to read analog in data from a Phidget Interface Kit, you can just type it on the MATLAB command line:

< M A T L A B (R) >
Copyright 1984-2012 The MathWorks, Inc.
R2012a (7.14.0.739) 64-bit (glnxa64)
February 9, 2012
 
To get started, type one of these: helpwin, helpdesk, or demo.
For product information, visit www.mathworks.com.
 
>> analogin

Write Your Own Code

You can write your MATLAB code the same way you usually do, whether within a text editor or within MATLAB itself. However, to use Phidget calls within your code, you must include a reference to the Phidget library in your main body of code, before any Phidget calls.

On Mac OS:

  function phidgettest(n)
     loadlibrary /Library/Phidget21.framework/Versions/Current/Phidget21 phidget21Matlab.h alias phidget21
      % More code goes here
  end

Getting Started with MATLAB (Linux)

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

Use our Examples

Step 1: Compile the MATLAB Library

In the Phidget Linux libraries (not the MATLAB libraries) you have already have compiled the phidget21.h for running all Phidgets on Linux. There is another make target in those libraries to make the MATLAB library header file for your Linux system.

To make this MATLAB library:

1. Re-download the Phidget Linux libraries if you have deleted the Phidget Library source code
   • If you re-download, also make the main phidget21.h Phidget library as described on the OS - Linux page so the MATLAB library matches
2. Then, in the source code directory where you ran ./configure, make, and make install for the main libraries, also run:

   make phidget21matlab.h

This will generate a file called phidget21matlab.h which you can rename to phidget21Matlab.h so that it works with our examples:

mv phidget21matlab.h phidget21Matlab.h

Then, if you have an older library, you may have to add one line at the top of phidget21Matlab.h:

typedef long long __int64;

If you try running the examples as below, and something similar to this is not already in the phidget21Matlab.h file, MATLAB will give you a series of fairly descriptive errors involving __int64. So you can also try running the examples and adding this if needed.

And, on 64-bit Linux systems with older libraries, you will need to change the line that says typedef long CPhidgetHandle; to say either:

typedef long long CPhidgetHandle;

Or:

typedef void* CPhidgetHandle;

....depending on how you want to typecast your Phidget handle within your code (the first one should work fine).

This changes the pointer type for the Phidget software object to be 64 bits, which is what your 64 bit machine will naturally create.

Step 2: Modify the Examples

Download the and unzip the Phidget examples for MATLAB. Put the phidget21Matlab.h that you just compiled into the unzipped example directory, overwriting the existing Windows/Mac phidget21Matlab.h file that came with the examples.

The next change is to the example .m source code file you are using. In all of the example code .m files, there is a line near the very top (line 4 or so) that says:

loadlibrary phidget21 phidget21Matlab.h;

or:

loadlibrary ('phidget21', 'phidget21Matlab.h');

This needs to be changed to:

loadlibrary /usr/lib/libphidget21.so phidget21Matlab.h alias phidget21

The location of libphidget21.so should be the actual location of the Phidget libraries on your system. If you just did a default install, the location as written above should be fine. Otherwise, find the libraries (use a search or locate function from the command line or operating system) and substitute the actual location.

These changes are needed because the Phidget libraries are named differently on Linux than they are on Windows. On Windows, the loadlibrary function looks for a phidget21.dll file and links it to the phidget21 alias used throughout the MATLAB program. This alias linking happens automatically because the library and the alias have the same name, including capitalization.

On Linux, however, the library to be linked is the executable libphidget21.so. Because it does not have exactly the same name as phidget21 (which is used as the alias in the rest of the .m code), you have to link it and alias it explicitly.

Without these changes, the errors that appear can be quite strange. They show up as file-not-found errors, ELF-header errors, or simply evalin() errors, depending on whether you've changed the phidget21Matlab.h file, the path, the file, or none of the above. The file-not-found error looks like this:

Error in ==> digitalout at 3
loadlibrary phidget21 phidget21Matlab.h;

Error in ==> run at 74
    evalin('caller',[script ';']);

Caused by:
    Error using ==> loaddefinedlibrary
    phidget21.so: cannot open shared object file: No such file or directory

The phidget21Matlab.h file should be either in the current project directory, or in a MATLAB path (type path in MATLAB to see the current setup). If you prefer to use parentheses and quotations for aliasing (to keep your formatting strict), you can read about the various syntax options for the loadlibrary function on the MathWorks website.

On a 64-bit Linux system, you will need to change the Phidget handle within the example to be a 64 bit pointer, matching the phidget21Matlab.h file. For example, in the analogin.m example, the line that says {{{1}}} to say:

ptr = libpointer('int64Ptr',0);

loadlibrary /usr/lib/libphidget21.so phidget21Matlab.h alias phidget21

Step 3: Run the Examples

Once you have made the changes above to both the phidget21Matlab.h file and the *.m example file you want to run, running the example you want is easy. Just put the *.m example and the phidget21Matlab.h file into your current directory in Matlab, and type the example name.

For instance, to use the analogin.m example to read analog in data from a Phidget Interface Kit, you can just type it on the MATLAB command line:

< M A T L A B (R) >
Copyright 1984-2012 The MathWorks, Inc.
R2012a (7.14.0.739) 64-bit (glnxa64)
February 9, 2012
 
To get started, type one of these: helpwin, helpdesk, or demo.
For product information, visit www.mathworks.com.
 
>> analogin

Write Your Own Code

You can write your MATLAB code the same way you usually do, whether within a text editor or within MATLAB itself. However, to use Phidget calls within your code, you must include a reference to the Phidget library in your main body of code, before any Phidget calls.

And on Linux:

  function phidgettest(n)
     loadlibrary /usr/lib/libphidget21.so phidget21Matlab.h alias phidget21
      % More code goes here
  end

Also, before running your code, remember to copy phidget21Matlab.h to your project directory.

Follow The Examples

By following the instructions 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 section has resources for you to learn from the examples and write your own.

Programming with Phidgets in MATLAB makes extensive use of the calllib() function to the C/C++ library, so the C/C++ API reference will be helpful:

• C/C++ API (This is the complete set of functions you have available for all Phidgets)
• Device Specific APIs - The one for your Phidget can be found in its user guide.

To learn the details behind opening, configuring, using, and closing your Phidget, try the General Phidget Programming page. That page also describes using the Phidget in an event-driven manner and in a traditional manner, although you can only use the logic code type design in MATLAB.

If you find yourself wanting to use event functions in the API (which are not available in MATLAB), try using Python as described in the support section at the top of this page.

Code Snippets

Specific calls in MATLAB will differ in syntax from those on the General Phidget Programming page, but the concepts stay the same.

It may help to have the General Phidget Programming page and this section open at the same time, because they parallel each other and you can refer to the MATLAB syntax. However, many additional concepts are covered on the General Phidget Programming page on a high level, such as using multiple Phidgets, handling errors, and different styles of programming.

For example, if we were using a Phidget Interface Kit as our device, the general calls would look like this:

Step One: Initialize and Open

  devicePointer = libpointer('int32Ptr',0);
  calllib('phidget21', 'CPhidgetInterfaceKit_create', devicePointer);
  device = get(devicePointer, 'Value');

The devicePointer is converted to the handle device as a handle for the Phidget. This example is specific to the Interface Kit because the call CPhidgetInterfaceKit_create is used. For another device, use the correspondingly named call in the C/C++ API.

The handle device is then used for all the C function calls where CPhidgetHandle phid is used in the C/C++ API. Every type of Phidget also inherits functionality from the Phidget base class.

Note that open() opens the software object, but not hardware. So, it is not a guarantee you can use the Phidget immediately.

The different types of open can be used with parameters to try and get the first device it can find, open based on its serial number, or even open across the network. The API manual lists all of the available modes that open provides.

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

To use the Phidget, it must be plugged in (attached). We can handle this by calling waitForAttachment. This function works for any Phidget. WaitForAttachment will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded:

  calllib('phidget21', 'CPhidget_open', device, -1);
  if calllib('phidget21', 'CPhidget_waitForAttachment', device, 2500) == 0
     % Insert your code here
  end

Step Three: Do Things with the Phidget

MATLAB does not support event handling, so all data must be read and sent directly.

The most common thing you might want to do is read data from sensors. For example, in the code below, we might want to read data from a sensor on the Phidget Interface Kit.

Simply use the C API functions such as CPhidgetInterfaceKit_getSensorValue() or CPhidgetInterfaceKit_setOutState() for Interface Kits. The following reads and displays data from a sensor ten times as quickly as the while loop can execute:

  while n<10
    dataPointer = libpointer('int32Ptr',0);
    calllib('phidget21', 'CPhidgetInterfaceKit_getSensorValue', device, 0, dataPointer)
    disp(get(dataPointer, 'Value'));
    n=n+1;
  end

Step Four: Close and Delete

  calllib('phidget21', 'CPhidget_close', ikhandle);
  calllib('phidget21', 'CPhidget_delete', ikhandle);

At the end of your program, don’t forget to call close to free any locks on the Phidget that the open() call put in place!

The complete set of functions you have available for all Phidgets can be found in the C/C++ API. Note, however, MATLAB does not make use of the event functions in the C/C++ API.

If you are looking for more information about a particular function, we provide that as well. You can find more description on any function either in:

1. Our API Overview which describes the set of calls common to all Phidgets, or
2. The Device API page for calls available only on your specific Phidget.

Common Problems and Solutions

Octave Problem: The function calls loadlibrary() and callib() are not supported in Octave

Likely Fix: As use of Phidgets in MATLAB requires these calls, the best is probably to choose a programming language that is not MATLAB. You can choose from many languages that we support.

However, this may not be possible if, for example, you already have a lot of external code written in MATLAB that you would like to interface your Phidget with. Here are a few suggestions to help you find a way to use your existing MATLAB code:

• Write your overall program in Python. Python natively controls Phidgets, and you can use Pytave to interface between the Python Phidget code and your Octave code.
• If you are using a version of Octave that Pytave does not support, write your program in Python as above. Then, you can try reading your matlab code through R, and using RPy to interface with Python.
• External foreign linking libraries (Swig, FFCall) might be made to work...

All Operating Systems: You get a warning: The library class 'libphidget21' already exists. Use a classname alias.

Note that the phidget21 library is not unloaded at the end of our example .m files. This is because rapidly unloading the library just after linking it can cause problems in short programs.

So, when you run the program again within the same MATLAB session, you will get this warning. Your code will still work, it is just that running the same code again loads the library again without closing it first.

OS X: The examples do not run with Rosetta under OS X.

The example programs uses the MATLAB timer() call, which relies on the Java Virtual Machine. Since Rosetta does not support Java, the examples will not operate as expected.