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.

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

MATLAB is the same program that runs on different operating systems. So, we simply have one section below for using the examples, and one section below for writing your own code, regardless of your operating system.

We do not support Octave. Phidgets in MATLAB depend on the callib() function, which Octave does not have. For workarounds, see our common problems section.

Use Our Examples

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

• MATLAB Examples

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. If your device does not have an example written for it, try the HelloWorld.m example. Then, run the code within MATLAB as you would any .m file. For example, from the MATLAB command line:

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

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 OSX and Linux)

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

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

Example Flow

The examples for each device all have this general structure so you can follow along. We also have an in-depth general introduction to writing Phidget code (like open, read data, etc), as well as the C/C++ API for specific syntax:

// ----- Main Code ----- Create Device Software Object Open Device Wait until Device Attachment Initialize any hardware (antennas, etc) Loop waiting on requests from user input Get and Print various device statuses on request by input Exit upon specific user input Close Device Delete Device

Because the user must ask for everything in MATLAB (rather than using events to detect when things occur) there is only one main code loop. All of the Phidget functions used are simply calls, through MATLAB, to the C library. You can find the syntax for how each of these are used in the examples within the Code Snippets section below.

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.