Alert.png

Notice: This page contains information for the legacy Phidget21 Library.

Phidget21 is out of support. Bugfixes may be considered on a case by case basis.

Phidget21 does not support VINT Phidgets, or new USB Phidgets released after 2020. We maintain a selection of legacy devices for sale that are supported in Phidget21.

We recommend that new projects be developed against the Phidget22 Library.


Click on the 2phidget22.jpg button in the menu bar to go to the Phidget22 version of this page.

Alert.png

Language - MATLAB: Difference between revisions

From Phidgets Legacy Support
 
(56 intermediate revisions by 6 users not shown)
Line 1: Line 1:
[[Category:Language]]
[[Category:Language]]
[[File:Icon-Matlab.png|64x64px]] MATLAB is a scientific and numerical analysis oriented language, with many graphical libraries and a wide user base.
{{OSLang|[[File:Icon-Matlab.png|64x64px]]|MATLAB is a scientific and numerical analysis oriented language, with many graphical libraries and a wide user base.}}
 
__TOC__
__TOC__


Line 7: Line 6:


{{LanguageSupport|MATLAB|the non-[[General Phidget Programming#Event Driven Code|event driven]] part of the Phidget API|AdvancedServo, Encoder, InterfaceKit, Servo and Stepper.|any operating system that can run MATLAB code|}}
{{LanguageSupport|MATLAB|the non-[[General Phidget Programming#Event Driven Code|event driven]] part of the Phidget API|AdvancedServo, Encoder, InterfaceKit, Servo and Stepper.|any operating system that can run MATLAB code|}}
As a result of MATLAB's lack of event support there are some things that cannot be done in MATLAB.  The most prominent of which is sample at the full rate possible for certain boards.  For example, in order to achieve the full 1000 samples/s specified by the analog inputs on an interface kit you need to set the datarate to 1ms.  This will queue up events on the interface kit and send all 8 of them at 8ms intervals.  Since MATLAB cannot use events, it must poll the device for data.  You cannot poll faster than 8ms however and thus MATLAB is limited to 125 samples/s (8ms) rather than 1000 samples/s (1ms).  There are similar effects on other boards with datarates higher than 125 samples/s.


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:
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:
Line 13: Line 14:
* SciPy (scientific functions similar to MATLAB libraries)
* 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 [[Language - Python | Python Phidget libraries]], and Python as your main Phidget programming language, not MATLABPython has excellent [http://python.org/ web documentation], and it is interpreted like MATLAB so there is no need to compile.
For Windows and Mac users who do not want to manage individual packages, there is [http://www.enthought.com/products/epd.php Enthought] which includes all of the above in addition to wxPython for graphing and other GUI-type programming.  For Linux users, matplotlib may be downloaded from [http://matplotlib.sourceforge.net/ its website], and the other packages are in the Debian package and other package repositories.
 
==Quick Downloads==


Just need the MATLAB drivers, libraries, and examples? Here they are.
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 [[Language - Python | Python Phidget libraries]], and Python as your main Phidget programming language, not MATLAB. Python has excellent [http://python.org/ web documentation], and we even have an application guide to use [[Live Data Graphing|Python graphics instead of MATLAB graphics]].


* [http://www.phidgets.com/downloads/examples/Matlab_2.1.8.20110615.zip MATLAB Sample Code], including the '''<code>phidget21Matlab.h</code>''' library file, needed for any MATLAB project.
We do not support Octave. Phidgets in MATLAB depend on the <code>calllib()</code> function, which Octave does not have.  For workarounds, see our [[#Common Problems and Solutions|common problems]] section.  Also, the {{Code|calllib}} library uses our C libraries, so programming in MATLAB for Phidgets uses the C API.


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:
==Quick Downloads==
*[http://www.phidgets.com/documentation/Phidget21_C_Doc.zip C/C++ API Manual Download] or [http://www.phidgets.com/documentation/web/cdoc/index.html (HTML online version)]
{{QuickDownloads|MATLAB|
*[[General API]] (more help on functions common to all Phidgets)
{{APIQuickDownloads|{{SERVER}}/documentation/Phidget21_C_Doc.zip}}
*[[Device List | Device Specific APIs]] (more help on functions specific to your Phidget)
{{ExtraAPIQuickDownloads|{{SERVER}}/documentation/web/cdoc/index.html|HTML Version of}}|
 
{{ExampleQuickDownloads|{{SERVER}}/downloads/phidget21/examples/c/Matlab.zip MATLAB|}}|
Libraries and Drivers which MATLAB depends on:
{{WindowsQuickDownloads}}
*[http://www.phidgets.com/downloads/libraries/phidget21-x86_2.1.8.20110615.zip 32 bit Windows (drivers, with libraries)]
{{MacQuickDownloads}}
*[http://www.phidgets.com/downloads/libraries/phidget21-x64_2.1.8.20110615.zip 64 bit Windows (drivers, with libraries)]
{{LinuxQuickDownloads}}}}
*[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 OSX | Mac OSX Library Setup Instructions]])


==Getting Started with MATLAB (Windows)==
==Getting Started with MATLAB==


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


We do not support Octave. Phidgets in MATLAB depend on the <code>callib()</code> function, which Octave does not have.  For workarounds, see our [[#Common Problems and Solutions|common problems]] section.
Instructions are divided up by operating system. Choose:
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#OS X |OS X]]
*[[#Linux | Linux]]
 
==Windows XP/Vista/7/8==


===Use Our Examples===
===Use Our Examples===
Line 43: Line 45:
Start by using and modifying existing examples.  You can find the MATLAB example code here:
Start by using and modifying existing examples.  You can find the MATLAB example code here:


*[http://www.phidgets.com/downloads/examples/Matlab_2.1.8.20111028.zip MATLAB Examples]
*[{{SERVER}}/downloads/phidget21/examples/c/Matlab.zip MATLAB Examples]


If you are using a 64 bit version of Windows, a small modification to the {{Code|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:
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 at index X from a Phidget Interface Kit:
 
<div class="source">
<syntaxhighlight lang=c>
 
  #ifndef WIN32
  #define __stdcall
  #endif
 
</syntaxhighlight>
</div>
 
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:


<div class="source">
<div class="source">
<syntaxhighlight lang=matlab>
<syntaxhighlight lang=matlab>


   run analogin.m
   >>analogin(X)


</syntaxhighlight>
</syntaxhighlight>
Line 103: Line 93:


   function phidgettest(n)
   function phidgettest(n)
    loadlibrary phidget21 phidget21Matlab.h;
      loadphidget21;
       % More code goes here
       % More code goes here
   end
   end
Line 110: Line 100:
</div>
</div>


Also, before running your code, remember to '''copy phidget21Matlab.h to your project directory'''.
loadphidget21 is a .m file we have included that will check your OS and reference the proper phidget21Matlab.h file (there is a different one for each OS).  Also, before running your code, remember to '''copy Phidget header files and loadphidget21.m to your project directory'''.


==Getting Started with MATLAB (Mac OS)==
==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:
If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:
{{ExampleCodeReasons}}
{{ExampleCodeReasons}}
We do not support Octave.  Phidgets in MATLAB depend on the <code>callib()</code> function, which Octave does not have.  For workarounds, see our [[#Common Problems and Solutions|common problems]] section.


===Use Our Examples===
===Use Our Examples===
The phidget21matlab_unix.h file as well as the loadphidget21.m file should be either in the current project directory, or in a MATLAB path (type {{Code|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 {{Code|loadlibrary}} function on the [http://www.mathworks.com/help/techdoc/ref/loadlibrary.html MathWorks website].


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.
To run an example make sure the .m file is in your working directory in MATLAB, and type the name into the MATLAB command window. For example to run the example that reads the analog input of index X from a Phidget Interface kit:
First, you need to make one change to {{Code|phidget21Matlab.h}}, by adding the following to the top of the file:
 
<div class="source">
<syntaxhighlight lang=c>
 
  #ifndef WIN32
  #define __stdcall
  #endif
 
</syntaxhighlight>
</div>
 
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 {{Code|.m}} source code file you are using.  In all of the example code {{Code|.m}} files, there is a line near the very top (line 4 or so) that says:


<div class="source">
<div class="source">
<syntaxhighlight lang=matlab>
<syntaxhighlight lang=matlab>
loadlibrary phidget21 phidget21Matlab.h;
</syntaxhighlight>
</div>


or:
  >>analogin(X)


<div class="source">
<syntaxhighlight lang=matlab>
loadlibrary ('phidget21', 'phidget21Matlab.h');
</syntaxhighlight>
</syntaxhighlight>
</div>
</div>


On '''Mac OSX''', this needs to be changed to:
This will allow you to:
 
{{ExampleCodeReasons}}
<div class="source">
<syntaxhighlight lang=matlab>
loadlibrary /Library/Phidget21.framework/Versions/Current/Phidget21 phidget21Matlab.h alias phidget21
</syntaxhighlight>
</div>
 
On '''Linux''', this needs to be changed to:
 
<div class="source">
<syntaxhighlight lang=matlab>
loadlibrary /usr/lib/libphidget21.so phidget21Matlab.h alias phidget21
</syntaxhighlight>
</div>
 
For both systems, the location of {{Code|Phidget21}} (Mac) and {{Code|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 {{Code|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 {{Code|Phidget21}}.  Because it does not have exactly the same name as ''phidget21'' (which is used as the alias in the rest of the {{Code|.m}} code), you have to link it and alias it explicitly. The same goes for Linux, where the library to be linked is {{Code|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 {{Code|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:
 
<div class="source">
<syntaxhighlight lang=text>
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
</syntaxhighlight>
</div>
 
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 {{Code|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 {{Code|loadlibrary}} function on the [http://www.mathworks.com/help/techdoc/ref/loadlibrary.html MathWorks website].
 
Once you have made the changes above to both the {{Code|phidget21Matlab.h}} file and the {{Code|*.m}} example file you want to run, running the example you want is easy.  Just put the {{Code|*.m}} example and the {{Code|phidget21Matlab.h}} file into your current directory in Matlab, and type the example name.
 
For instance, to use the {{Code|analogin.m}} example to read analog in data from a Phidget Interface Kit, you can just type it on the MATLAB command line:
 
<div class="source">
<syntaxhighlight lang=text>
< 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
</syntaxhighlight>
</div>


===Write Your Own Code===
===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.
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:


<div class="source">
<div class="source">
Line 223: Line 131:


   function phidgettest(n)
   function phidgettest(n)
    loadlibrary /Library/Phidget21.framework/Versions/Current/Phidget21 phidget21Matlab.h alias phidget21
      loadphidget21;
       % More code goes here
       % More code goes here
   end
   end
Line 230: Line 138:
</div>
</div>


loadphidget21 is a .m file we have included that will check your OS and reference the proper phidget21Matlab.h file (there is a different one for each OS).  Also, before running your code, remember to '''copy Phidget header files and loadphidget21.m to your project directory'''.


==Getting Started with MATLAB (Linux)==
==Linux==


If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:
If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:
{{ExampleCodeReasons}}
{{ExampleCodeReasons}}
We do not support Octave.  Phidgets in MATLAB depend on the <code>callib()</code> function, which Octave does not have.  For workarounds, see our [[#Common Problems and Solutions|common problems]] section.


===Use our Examples===
===Use our Examples===
Download the and unzip the [{{SERVER}}/downloads/phidget21/examples/c/Matlab.zip Phidget examples for MATLAB].  Put the {{Code|phidget21Matlab.h}} header file that you just compiled into the unzipped example directory.


====Step 1: Compile the MATLAB Library====
The {{Code|phidget21Matlab.h}} file as well as the {{Code|loadphidget21.m}} should be either in the current project directory, or in a MATLAB path (type {{Code|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 {{Code|loadlibrary}} function on the [http://www.mathworks.com/help/techdoc/ref/loadlibrary.html MathWorks website].


In the [http://www.phidgets.com/downloads/libraries/libphidget_2.1.8.20120216.tar.gz Phidget Linux libraries] (not the MATLAB libraries) you have already have compiled the {{Code|phidget21.h}} for running all Phidgets on Linux.
Then just put the {{Code|*.m}} example into your current directory in Matlab, and type the example name.


There is ''another'' make target in those libraries to make the MATLAB library header file for your Linux system.
For instance, to use the {{Code|analogin.m}} example to read analog in data from index X of a Phidget Interface Kit, you can just type it on the MATLAB command line:
 
To make this MATLAB library:
# Re-download the [http://www.phidgets.com/downloads/libraries/libphidget_2.1.8.20120216.tar.gz Phidget Linux libraries] if you have deleted the Phidget Library source code
#* If you re-download, also make the main {{Code|phidget21.h}} Phidget library as described on the [[OS - Linux]] page so the MATLAB library matches
#Then, in the source code directory where you ran {{Code|./configure}}, {{Code|make}}, and {{Code|make install}} for the main libraries, also run:
#:{{Code|make phidget21matlab.h}}
 
This will generate a file called {{Code|phidget21matlab.h}} which you can rename to phidget21Matlab.h so that it works with our examples:


<div class="source">
<div class="source">
<syntaxhighlight lang=bash>
<syntaxhighlight lang=text>
mv phidget21matlab.h phidget21Matlab.h
>> analogin(X)
</syntaxhighlight>
</div>
 
===64-Bit Linux===
 
MATLAB does not use the 32-bit bridge available on Linux, so if you have a 64 bit Linux system, you almost certainly have 64-MATLAB for Linux.
 
There seems to be a problem in 64-bit Linux MATLAB with Phidgets.  Using 32 bit pointers within Phidget code will not work, but changing the pointers to 64 bit causes a segmentation fault in MATLAB.  Therefore, if you are using 64-bit MATLAB, we recommend using Phidgets in Python using SciPy ([http://www.scipy.org/ http://www.scipy.org/]) for fast numerical analysis, and Matplotlib ([http://matplotlib.sourceforge.net/ http://matplotlib.sourceforge.net/]) for graphical plotting, both free, and both with similar syntax to MATLAB.
 
In addition, the API for Phidgets in Python is much cleaner, and you can use events - which you cannot do in pure MATLAB as MATLAB does not support them.
 
 
On '''Linux''', this needs to be changed to:
 
<div class="source">
<syntaxhighlight lang=matlab>
loadlibrary /usr/lib/libphidget21.so phidget21Matlab.h alias phidget21
</syntaxhighlight>
</syntaxhighlight>
</div>
</div>
Line 283: Line 163:


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.
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:
And on Linux:
Line 304: Line 183:
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.
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:
Programming with Phidgets in MATLAB makes extensive use of the '''calllib()''' function to the C/C++ library, so your main reference for coding will be the C/C++ API reference:


{{UsingAPhidgetInCodeGeneral|although you can only use the logic code type design in MATLAB|[http://www.phidgets.com/documentation/Phidget21_C_Doc.zip C/C++ API]}}
{{UsingAPhidgetInCodeGeneral|although you can only use the logic code type design in MATLAB|[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}


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 | support]] section at the top of this page.
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 | support]] section at the top of this page.
Line 316: Line 195:
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.
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 [[Product - 1018 - PhidgetInterfaceKit 8/8/8 | Phidget Interface Kit]] as our device, the general calls would look like this:
For example, if we were using a [{{SERVER}}/products.php?product_id=1018 Phidget Interface Kit] as our device, the general calls would look like this:


====Step One: Initialize and Open====
====Step One: Initialize and Open====
Line 323: Line 202:
<syntaxhighlight lang=matlab>
<syntaxhighlight lang=matlab>


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


</syntaxhighlight>
</syntaxhighlight>
</div>
</div>


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 phid is created 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.
The handle '''phid''' 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.
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.  
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====  
====Step Two: Wait for Attachment (plugging in) of the Phidget====  
Line 345: Line 224:
<syntaxhighlight lang=matlab>
<syntaxhighlight lang=matlab>


  calllib('phidget21', 'CPhidget_open', device, -1);
   if calllib('phidget21', 'CPhidget_waitForAttachment', phid, 500) == 0
   if calllib('phidget21', 'CPhidget_waitForAttachment', device, 2500) == 0
     % Insert your code here
     % Insert your code here
   end
   end
Line 357: Line 235:
MATLAB does not support event handling, so all data must be read and sent directly.  
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 [[Product - 1018 - PhidgetInterfaceKit 8/8/8 | Phidget Interface Kit]].
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 [{{SERVER}}/products.php?product_id=1018 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:  
Simply use the C API functions such as {{Code|CPhidgetInterfaceKit_getSensorValue()}} or {{Code|CPhidgetInterfaceKit_setOutState()}} for Interface Kits.  The following reads and displays data from a sensor ten times as quickly as the while loop can execute:  


<div class="source">
<div class="source">
Line 365: Line 243:


   while n<10
   while n<10
     dataPointer = libpointer('int32Ptr',0);
     dataptr = libpointer('int32Ptr', 0);
     calllib('phidget21', 'CPhidgetInterfaceKit_getSensorValue', device, 0, dataPointer)
     if calllib('phidget21', 'CPhidgetInterfaceKit_getSensorValue', phid, n, dataptr) == 0
     disp(get(dataPointer, 'Value'));
     sensorvalue = dataptr.Value;
     n=n+1;
     n=n+1;
   end
   end
Line 379: Line 257:
<syntaxhighlight lang=matlab>
<syntaxhighlight lang=matlab>


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


</syntaxhighlight>
</syntaxhighlight>
Line 387: Line 265:
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!
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 [http://www.phidgets.com/documentation/Phidget21_C_Doc.zip C/C++ API].  Note, however, MATLAB does not make use of the event functions in the C/C++ API.
{{MoreHowTos}}
 
The ''complete'' set of functions you have available for all Phidgets can be found in the [{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API].  Note, however, MATLAB does not make use of the event functions in the C/C++ API. You can also find more description on any device-specific function in the Device API page for your specific Phidget, which can be found in its [[:Category:UserGuide|user guide]].


If you are looking for more information about a particular function, we provide that as wellYou can find more description on any function either in:
==Using the MATLAB Engine from a C program==
# Our [[General API|API Overview]] which describes the set of calls common to all Phidgets, or
It is possible to use events while still having a MATLAB like environment by using the MATLAB engine library in C.  In MathWorks' own words: "The MATLAB® engine library contains routines that allow you to call MATLAB software from your own programs, thereby employing MATLAB as a computation engine..."[http://www.mathworks.com/help/matlab/matlab_external/using-matlab-engine.html]  This allows you to write a C program that uses normal C syntax structure but calls MATLAB to take care of the complex math algorithms that you do not want to implement in C.  To get the MATLAB engine set up just follow these steps (note that these steps are for a Windows system with Visual Studio installed, you can download a free version of VS from Microsoft under the Express name)
# The [[Device List|Device API]] page for calls available only on your specific Phidget.
 
*Create a new Visual Studio empty project.
*Add a new CPP source file be sure to include the following header files:
**<nowiki>#include <windows.h></nowiki>
**<nowiki>#include <stdlib.h></nowiki>
**<nowiki>#include <stdio.h></nowiki>
**<nowiki>#include <string.h></nowiki>
**<nowiki>#include <engine.h></nowiki>
*Under Project Properties:
**Add <code>/<Matlab install directory>/extern/include</code> to "Additional include directories"
**Make sure that precompiled headers are disabled
**In the "Linker" section add <code>/<Matlab install directory>/extern/lib/win32(or 64)/microsoft</code> to "Additional library dependencies".
**Under "Linker->Input" add <code>libmx.lib libmat.lib libeng.lib</code> to "Additional dependendcies". 
*Now open a cmd terminal and navigate to <code>/<Matlab install directory>/bin/win32(or 64)</code> and enter in the following command:
**<code>matlab /regserver</code>
*Close the MATLAB window that opens. 
*Next, make sure that <code>/<Matlab install directory>/bin/win32(or 64)</code> is included in your PATH environment variable. 
*Finally, restart Visual StudioYour project should now be configured to be able to use the MATLAB engine.
 
Here is a modified version of Spatial-simple.c which uses the MATLAB engine to pass the spatial data through a high-pass filter to monitor for sudden changes in acceleration such as if a car were running off road or a structure was experiencing unexpected vibrations (an earthquake say):
*[{{SERVER}}/docs21/images/e/ef/Main.cpp Main]
*[{{SERVER}}/docs21/images/e/ee/Spatialfilter.h Header]
 
The full API and documentation package for the MATLAB engine can be found on MathWorks' website.
 
A number of things can be tweaked in this example, such as the filter parameters and type of filter used, the threshold at which we take note of the vibrations etc...  If we look at the unaltered data vs the filtered data we can see that the filtering operation was a success:
 
[[File:Filtereddata.png|800px|center|link=]]


==Common Problems and Solutions==
==Common Problems and Solutions==
{{ProblemSolution|Octave Problem|The function calls loadlibrary() and callib() are not supported in Octave}}
 
===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 [[Software Overview#Language Support|from many languages]] that we support.
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 [[Software Overview#Language Support|from many languages]] that we support.
Line 403: Line 311:
* External foreign linking libraries (Swig, FFCall) might be made to work...
* External foreign linking libraries (Swig, FFCall) might be made to work...


{{ProblemSolution|All Operating Systems|You get a warning: The library class 'libphidget21' already exists.  Use a classname alias.}}
===All Operating Systems: You get a warning "The library class 'libphidget21' already exists.  Use a classname alias."===


Note that the {{Code|phidget21}} library is not unloaded at the end of our example {{Code|.m}} files.  This is because rapidly unloading the library just after linking it can cause problems in short programs.
Note that the {{Code|phidget21}} library is not unloaded at the end of our example {{Code|.m}} files.  This is because rapidly unloading the library just after linking it can cause problems in short programs.
Line 409: Line 317:
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.
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.


{{ProblemSolution|OS X|The examples do not run with Rosetta under OS X.}}
===OS X: The examples do not run with Rosetta under OS X.===


The example programs uses the MATLAB {{Code|timer()}} call, which relies on the Java Virtual Machine. Since Rosetta does not support Java, the examples will not operate as expected.
The example programs uses the MATLAB {{Code|timer()}} call, which relies on the Java Virtual Machine. Since Rosetta does not support Java, the examples will not operate as expected.
===There are no compilers listed under the mex -setup menu===
64-bit versions of Matlab do not have a C compiler included with them.  You will need to use another compiler such as the Visual Studio compiler.  If you do not have Visual Studio then you can install a free version from Microsoft's website which has a compiler with it or you download another free C compiler of which there are many.

Latest revision as of 21:08, 6 June 2017

Icon-Matlab.png 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.

As a result of MATLAB's lack of event support there are some things that cannot be done in MATLAB. The most prominent of which is sample at the full rate possible for certain boards. For example, in order to achieve the full 1000 samples/s specified by the analog inputs on an interface kit you need to set the datarate to 1ms. This will queue up events on the interface kit and send all 8 of them at 8ms intervals. Since MATLAB cannot use events, it must poll the device for data. You cannot poll faster than 8ms however and thus MATLAB is limited to 125 samples/s (8ms) rather than 1000 samples/s (1ms). There are similar effects on other boards with datarates higher than 125 samples/s.

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)

For Windows and Mac users who do not want to manage individual packages, there is Enthought which includes all of the above in addition to wxPython for graphing and other GUI-type programming. For Linux users, matplotlib may be downloaded from its website, and the other packages are in the Debian package and other package repositories.

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 we even have an application guide to use Python graphics instead of MATLAB graphics.

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

Example Code

Libraries and Drivers

Getting Started with MATLAB

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 XP/Vista/7/8

Use Our Examples

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

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 at index X from a Phidget Interface Kit:

  >>analogin(X)

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.

Compile 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

Mex Setup

Next, select y to view all installed compilers.

Choose your Compiler

Finally, select the compiler you wish MATLAB to use.

Mex Setup Output

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)
      loadphidget21;
      % More code goes here
  end

loadphidget21 is a .m file we have included that will check your OS and reference the proper phidget21Matlab.h file (there is a different one for each OS). Also, before running your code, remember to copy Phidget header files and loadphidget21.m to your project directory.

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

The phidget21matlab_unix.h file as well as the loadphidget21.m 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.

To run an example make sure the .m file is in your working directory in MATLAB, and type the name into the MATLAB command window. For example to run the example that reads the analog input of index X from a Phidget Interface kit:

  >>analogin(X)

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)
      loadphidget21;
      % More code goes here
  end

loadphidget21 is a .m file we have included that will check your OS and reference the proper phidget21Matlab.h file (there is a different one for each OS). Also, before running your code, remember to copy Phidget header files and loadphidget21.m to your project directory.

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

Download the and unzip the Phidget examples for MATLAB. Put the phidget21Matlab.h header file that you just compiled into the unzipped example directory.

The phidget21Matlab.h file as well as the loadphidget21.m 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.

Then just put the *.m example 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 index X of a Phidget Interface Kit, you can just type it on the MATLAB command line:

>> analogin(X)

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 your main reference for coding will be the C/C++ API reference:

  • 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

  phid = libpointer('int32Ptr');
  calllib('phidget21', 'CPhidgetInterfaceKit_create', phid);
  calllib('phidget21', 'CPhidget_open', phid, -1);

The phid is created 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 phid 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:

  if calllib('phidget21', 'CPhidget_waitForAttachment', phid, 500) == 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
    dataptr = libpointer('int32Ptr', 0);
    if calllib('phidget21', 'CPhidgetInterfaceKit_getSensorValue', phid, n, dataptr) == 0
    sensorvalue = dataptr.Value;
    n=n+1;
  end

Step Four: Close and Delete

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

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!

More How-To's

The General Phidget Programming page gives more information about:

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. You can also find more description on any device-specific function in the Device API page for your specific Phidget, which can be found in its user guide.

Using the MATLAB Engine from a C program

It is possible to use events while still having a MATLAB like environment by using the MATLAB engine library in C. In MathWorks' own words: "The MATLAB® engine library contains routines that allow you to call MATLAB software from your own programs, thereby employing MATLAB as a computation engine..."[1] This allows you to write a C program that uses normal C syntax structure but calls MATLAB to take care of the complex math algorithms that you do not want to implement in C. To get the MATLAB engine set up just follow these steps (note that these steps are for a Windows system with Visual Studio installed, you can download a free version of VS from Microsoft under the Express name)

  • Create a new Visual Studio empty project.
  • Add a new CPP source file be sure to include the following header files:
    • #include <windows.h>
    • #include <stdlib.h>
    • #include <stdio.h>
    • #include <string.h>
    • #include <engine.h>
  • Under Project Properties:
    • Add /<Matlab install directory>/extern/include to "Additional include directories"
    • Make sure that precompiled headers are disabled
    • In the "Linker" section add /<Matlab install directory>/extern/lib/win32(or 64)/microsoft to "Additional library dependencies".
    • Under "Linker->Input" add libmx.lib libmat.lib libeng.lib to "Additional dependendcies".
  • Now open a cmd terminal and navigate to /<Matlab install directory>/bin/win32(or 64) and enter in the following command:
    • matlab /regserver
  • Close the MATLAB window that opens.
  • Next, make sure that /<Matlab install directory>/bin/win32(or 64) is included in your PATH environment variable.
  • Finally, restart Visual Studio. Your project should now be configured to be able to use the MATLAB engine.

Here is a modified version of Spatial-simple.c which uses the MATLAB engine to pass the spatial data through a high-pass filter to monitor for sudden changes in acceleration such as if a car were running off road or a structure was experiencing unexpected vibrations (an earthquake say):

The full API and documentation package for the MATLAB engine can be found on MathWorks' website.

A number of things can be tweaked in this example, such as the filter parameters and type of filter used, the threshold at which we take note of the vibrations etc... If we look at the unaltered data vs the filtered data we can see that the filtering operation was a success:

Filtereddata.png

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.

There are no compilers listed under the mex -setup menu

64-bit versions of Matlab do not have a C compiler included with them. You will need to use another compiler such as the Visual Studio compiler. If you do not have Visual Studio then you can install a free version from Microsoft's website which has a compiler with it or you download another free C compiler of which there are many.