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

OS - Linux: Difference between revisions

From Phidgets Legacy Support
No edit summary
 
(239 intermediate revisions by 8 users not shown)
Line 1: Line 1:
[[Category:OS]]
{{OSLang|[[File:icon-Linux.png|64x64px|link=OS - Linux]]|On Linux, Phidgets can be either plugged directly into a USB Port or run over a network using the [[#WebService | WebService]].}}
__TOC__
__TOC__
You need kernel '''version 2.6''' (released in 2003) or later.


Phidgets can run on Linux directly using USB, or remotely over a network using the [[Phidget Webservice]]. 
==Quick Downloads==


You need kernel '''version 2.6''' or later.
Linux has complete support for all Phidgets and their software APIs; the only thing it lacks when compared to Windows and OS X is a graphical user interface. We walk you through all steps for download,  installation, checking, and starting to write code below.


==Getting Started (Libraries and Drivers)==
If you are already a pro, and just want the downloads:
*[{{SERVER}}/downloads/phidget21/libraries/linux/libphidget.tar.gz Phidget Libraries for Linux]
*[{{SERVER}}/downloads/phidget21/servers/linux/phidgetwebservice.tar.gz Phidget WebService for Linux]
*[[Software License]]


Linux does not have a graphical user interface to check your Phidget, but it does have a complete API for [[#Programming Languages|many languages]].
If you need old versions of the libraries, [{{SERVER}}/downloads/phidget21/libraries/linux/libphidget/ click here].


For any language, you will need the basic Phidget Libraries for Linux:
==Getting Started with Linux==


*[http://www.phidgets.com/downloads/libraries/libphidget_2.1.8.20110615.tar.gz Phidget Libraries]
{{#ev:youtube|6pXWhGzX4Fg}}


===Installing===
===Installing===
Line 17: Line 24:
To install the libraries, follow these steps:
To install the libraries, follow these steps:


#Download '''libusb-0.1''' and its development libraries
#Install libusb-1.0 development libraries - {{Code|libusb-1.0-0-dev}}.
#*Try <code>apt-cache search libusb</code> in a terminal to find current packages
#*Note that libusb-1.0 may be already on your system, but the development libraries probably aren't.
#*Or install [http://www.libusb.org/ from source], which includes the libusb development libraries
#*Search for {{Code|libusb-1.0-0-dev}} or similar in your distribution package directory.
#Unpack and install the '''Phidget Libraries''' for Linux (download above)
#*Or install [http://libusb.info/ from source].
#*From the main libraries directory, run:
#Unpack and install the [{{SERVER}}/downloads/phidget21/libraries/linux/libphidget.tar.gz Phidget Libraries]
#*:<code>./configure</code>
#*From the main unpacked libraries directory, run:
#*:<code>make</code>
#*:{{Code|./configure}}
#*:<code>sudo make install</code>
#*:{{Code|make}}
#*:{{Code|sudo make install}}
#*This will compile phidget21.h and place the library into your gcc path
#*This will compile phidget21.h and place the library into your gcc path


'''Note:''' Although the libraries are written in C, the libraries for Python, Java, and most other Phidget-supported languages depend on them.
'''Note:''' Although these libraries are written in C, the additional libraries for Python, Java, and most other Phidget-supported languages depend on them.


===Checking===
===Checking===
Line 35: Line 43:
====Software====
====Software====


To confirm that the libraries were installed correctly and can be used in code, you can use the Phidget C Examples:
To confirm that the libraries were installed correctly and can be used in code, you can use the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz Phidget Generic C Examples].


*[http://www.phidgets.com/downloads/examples/phidget21-c-examples_2.1.8.20111028.tar.gz Phidget C Examples]
The easiest way to confirm correct installation will be to compile and run the {{Code|HelloWorld}} C example, included in the examples download.  This does not involve writing any C code, but it does involve compiling the example and running it, which is a quick process as we show below.  If you feel more comfortable running the {{Code|HelloWorld}} example for your specific language, you can skip below and pick your language, but keep in mind that any problems could be with the C library installation and not necessarily with your language.
 
The easiest way to confirm correct installation will be to compile and run the '''<code>HelloWorld</code>''' C example.  This does not involve writing any C code, but it does involve compiling the example and running it, which is a quick process as we show below.  If you feel more comfortable running the '''<code>HelloWorld</code>''' example for your specific language, you can skip below and pick your language, but keep in mind that any problems could be with the C library installation and not necessarily with your language.


To compile and run the basic C example for checking your installation:
To compile and run the basic C example for checking your installation:


1. Unpack the '''Phidget C Examples''' (download above)<br>
1. Unpack the Phidget Generic C Examples<br>
2. Open a terminal (often Ctrl-Alt-T) and go to the directory where the examples are unpacked<br>
2. Open a terminal (often Ctrl-Alt-T) and go to the directory where the examples are unpacked<br>
3. Compile the <code>HelloWorld.c</code> example:<br>
3. Compile the {{Code|HelloWorld.c}} example:<br>
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<div class="source">
<font size="3">
<syntaxhighlight lang=bash>
<source lang=bash>


    gcc HelloWorld.c -o HelloWorld -lphidget21
gcc HelloWorld.c -o HelloWorld -lphidget21


</source>
</syntaxhighlight>
</font>
</div>
</div>
4. Run the <code>HelloWorld</code> example:<br>
4. Run the {{Code|HelloWorld}} example:<br>
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<div class="source">
<font size="3">
<syntaxhighlight lang=bash>
<source lang=bash>


    sudo ./HelloWorld
sudo ./HelloWorld


</source>
</syntaxhighlight>
</font>
</div>
</div>
:(The sudo is needed for USB access for now)
(The sudo is needed for USB access for now, see the [[#Setting udev Rules|Setting udev Rules]] section for how to change this)
 
The <code>-lphidget21</code> will look in the standard library location for your Linux distribution (usually <code>/usr/lib/</code>) for the Phidget 21 library file. 


Generally, libraries to be linked on Linux through <code>gcc</code> have a naming convention.  For example, <code>-lphidget21</code> looks for the binary files '''<code>libphidget21.a</code>''' and '''<code>libphidget21.so</code>''' in the library location (usually '''<code>/usr/lib</code>''').  These files are automatically put in the library location during the <code>make install</code> step of [[#Installing | installing the libraries above]].
The {{Code|-lphidget21}} will look in the standard library location for your Linux distribution (usually {{Code|/usr/lib/}}) for the Phidget 21 library file.  Generally, libraries to be linked on Linux through {{Code|gcc}} have a naming convention.  For example, {{Code|-lphidget21}} looks for the binary files '''{{Code|libphidget21.a}}''' and '''{{Code|libphidget21.so}}''' in the library location.  These files are automatically put in the library location during the {{Code|make install}} step of [[#Installing | installing the libraries]].


The HelloWorld program will simply print out basic information for any device you plug in, and print a message upon unplugging the device.  For example, starting the program, plugging in an Interface Kit Phidget, unplugging the Interface Kit, and pressing Enter displays:
The HelloWorld program will simply print out basic information for any device you plug in, and print a message upon unplugging the device.  For example, starting the program, plugging in an Interface Kit Phidget, unplugging the Interface Kit, and pressing Enter displays:


<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<div class="source">
<font size="3">
<syntaxhighlight lang=bash>
<source lang=bash>


  $ sudo ./HelloWorld  
$ sudo ./HelloWorld  
    
    
  Opening...
Opening...
  Press Enter to end
Press Enter to end


  Hello to Device Phidget InterfaceKit 8/8/8, Serial Number: 37299
Hello to Device Phidget InterfaceKit 8/8/8, Serial Number: 37299
  Goodbye Device Phidget InterfaceKit 8/8/8, Serial Number: 37299
Goodbye Device Phidget InterfaceKit 8/8/8, Serial Number: 37299


  Closing...
Closing...


</source>
</syntaxhighlight>
</font>
</div>
</div>


====Hardware====
====Hardware====


If the out-of-the-box examples do not work, make sure the Phidget is seen by your USB interface.  To check this, you can use the kernel log reader '''<code>dmesg</code>'''.  Pipe the output of '''<code>dmesg</code>''' into the utility '''<code>tail</code>''' to simply read the last ten lines of the log:
If the out-of-the-box examples do not work, make sure the Phidget is seen by your USB interface.  To check this, you can use the kernel log reader {{Code|dmesg}}.  Pipe the output of {{Code|dmesg}} into the utility {{Code|tail}} to read the last ten lines of the log:


<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<div class="source">
<font size="3">
<syntaxhighlight lang=bash>
<source lang=bash>


    $> dmesg | tail
$> dmesg | tail
    ....(9 lines)....
....(9 lines)....
    [24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd
[24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd


</source>
</syntaxhighlight>
</font>
</div>
</div>


The number between the [ ] is the system time in seconds since the last boot up, so you can tell whether the event was recent or not.  (This will also tell you the interrupt type of Phidget that is registered by the USB interface, see the [[#Limitations | limitations section below]] for more information on what this means.)
The number between the [ ] is the system time in seconds since the last boot up, so you can tell whether the event was recent or not.  (This will also tell you the interrupt type of Phidget that is registered by the USB interface, see the [[#Common Problems and Solutions | common problems section below]] for more information on what this means.)


The Phidget should both connect and disconnect properly, so unplugging it should result in an additional line at the tail:
The Phidget should both connect and disconnect properly, so unplugging it should result in an additional line at the tail:


<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<div class="source">
<font size="3">
<syntaxhighlight lang=bash>
<source lang=bash>


    $> dmesg | tail
$> dmesg | tail
    ....(8 lines)....
....(8 lines)....
    [24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd
[24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd
    [25094.809328] usb 2-1.2: USB disconnect, device number 5
[25094.809328] usb 2-1.2: USB disconnect, device number 5


</source>
</syntaxhighlight>
</font>
</div>
</div>


Line 131: Line 125:
* No other programs, drivers, or processes are using that USB port in software
* No other programs, drivers, or processes are using that USB port in software
* You are running the example program as root (or your udev rules have been set properly)
* You are running the example program as root (or your udev rules have been set properly)
* You are using libusb 0.1 (not 1.0 or later)
* You are using libusb 1.0 (not the older 0.1 release)
* You have compiled versions of libphidget21.a and libphidget21.so in your system library location (usually <code>/usr/lib</code>)
* You have compiled versions of libphidget21.a and libphidget21.so in your system library location (usually {{Code|/usr/lib}})
* The Phidget libraries are the latest version (visit the [[#Getting Started (Libraries and Drivers)| getting started section above]] to download them)
* The Phidget libraries are the latest version (visit the [[#Quick Downloads| quick downloads section]] to download them)
* Your Linux kernel version is 2.6 or later (type '''<code>uname -r</code>''' in a terminal to get your kernel version)
* Your Linux kernel version is 2.6 or later (type {{Code|uname -r}} in a terminal to get your kernel version)
* Check the [[#Limitations|limitations]] section below, some specific combinations can cause problems
* Check the [[#Common Problems and Solutions|common problems]] section below, some specific combinations can cause problems


If your problem doesn't seem to be fixed by the steps above, make sure that the Phidget is seen '''consistently''' by USB (if it is erratic, try our [[General Troubleshooting|general troubleshooting guide]]).  If you are still having problems after the troubleshooting guide, please [[Contact Information|ask us]]!
If your problem doesn't seem to be fixed by these steps, make sure that the Phidget is seen '''consistently''' by USB (if it is erratic, try our [[General Troubleshooting|general troubleshooting guide]]).  If you are still having problems after using the troubleshooting guide, please [[Contact Us|ask us]]!


==Programming Languages==
==Programming Languages==
Line 143: Line 137:
Now that you have the basic libraries installed, you can pick your language and begin programming!   
Now that you have the basic libraries installed, you can pick your language and begin programming!   


If you are not using the [[#Webservice | webservice]] (discussed below) to control a Phidget over a network, your next step will be to delve into the use of your specific language.  Each page has its own set of specific libraries, code examples, and setup instructions.   
If you are not using the [[#WebService | webservice]] (discussed below) to control a Phidget over a network, your next step will be to delve into the use of your specific language.  Each page has its own set of specific libraries, code examples, and setup instructions.   


On Linux, we recommend the following languages:
On Linux, we recommend the following languages:
Line 150: Line 144:
*[[Language - Java | Java]]
*[[Language - Java | Java]]
*[[Language - Python | Python]]
*[[Language - Python | Python]]
*[[Language - Ruby | Ruby]]
*[[Language - C Sharp | C#]] (Using [[Language - C Sharp#Mono|Mono]])
*[[Language - C Sharp | C#]] (Using [[Language - C Sharp#Mono|Mono]])
*[[Language - Flash AS3 | Flash AS3]]
*[[Language - Flash AS3 | Flash AS3]]
Line 156: Line 151:


*[[Language - MATLAB|MATLAB]]
*[[Language - MATLAB|MATLAB]]
*[[Language - Simulink|Simulink]]
==WebService==
The Phidget WebService allows you to remotely control a Phidget over a network.<br>This section helps you install, check, and use the WebService on Linux, but we also have an overview of the [[Phidget WebService]] in general.
===Installing the WebService===
To install the webservice, you must first have the [[#Installing|Phidget libraries installed]].  Then, follow these steps:
#Download '''avahi''' and its development libraries (mdnsresponder/bonjour is also an option, see the [[#WebService with mDNSResponder|webservice with mDNSResponder]] section)
#*Try {{Code|apt-cache search avahi}} in a terminal to find current packages
#*Often, this is installed in a default system, you may already have it
#Unpack and install the [{{SERVER}}/downloads/phidget21/servers/linux/phidgetwebservice.tar.gz Phidgets WebService] source code tarball for Linux
#*From the unpacked WebService source code directory, run:
#*:{{Code|./configure}}
#*:{{Code|make}}
#*:{{Code|sudo make install}}
#*This will compile the executable {{Code|phidgetwebservice21}} and place it into {{Code|/usr/bin/phidgetwebservice21}}
====WebService with BSD====
For '''BSD''', the webservice has been found to work (BSD 8+) but requires a special configuration at the {{Code|./configure}} step:
<div class="source">
<syntaxhighlight lang=bash>
./configure LIBS=/usr/lib/libphidget21.so CFLAGS=-pthread
</syntaxhighlight>
</div>
Then {{Code|make}} and {{Code|sudo make install}} are the same.
<br>
The {{Code|LIBS}} argument may not be necessary, but sometimes BSD has trouble finding the library install location.  The {{Code|CFLAGS}} argument is needed because BSD needs explicit linking for using threads.
====WebService with mDNSResponder====
To use '''mdnsresponder''' instead of avahi, change the configure script to be:
<div class="source">
<syntaxhighlight lang=bash>
./configure --enable-zeroconf=bonjour
</syntaxhighlight>
</div>
(To see all options, use {{Code|./configure --help}} like you would any configure script)
===Setting Up the WebService===
To set up and use the webservice, it helps to have [[#Setting udev Rules|set your udev rules]].  Otherwise, you must run the webservice as root.
You can get command line help with {{Code|phidgetwebservice21}} by using the {{Code|-h}} option:
<div class="source">
<syntaxhighlight lang=bash>
$ phidgetwebservice21 -h
</syntaxhighlight>


==Webservice==
<syntaxhighlight lang=text>
'phidgetwebservice21' is a Phidget and Dictionary server from Phidgets Inc. See www.phidgets.com for more information.
Usage: phidgetwebservice21 [OPTION]
All parameters are optional. The default parameters are: port=5001, ServerName=(Computer Name) and no password


The Phidget Webservice allows you to remotely control a Phidget over a network.<br>
Options:
Before using these webservice drivers, it may help to learn about how the [[Phidget Webservice]] works.
  -p      Port
  -n      Server Name
  -P      Password
  -v      Debug mode
  -h      Display this help
</syntaxhighlight>
</div>


*[http://www.phidgets.com/downloads/libraries/phidgetwebservice_2.1.8.20111028.tar.gz Linux Phidgets Webservice] libraries
You will see this help regardless of whether the webservice was correctly hooked in to avahi. In fact, you will see it even if you explicitly disabled mDNS in the {{Code|./configure}} step at compile:
*The Webservice on Linux uses <code>avahi</code>


===Installing the Webservice===
<div class="source">
<syntaxhighlight lang=bash>
  ./configure --disable-zeroconf
</syntaxhighlight>
</div>


To install the webservice, follow these steps:
(To see all options, use {{Code|./configure --help}} like you would any configure script)


#Download '''avahi''' and its development libraries
To find the defaults used by {{Code|phidget21webservice}}, the command line is the fastest way to learn the default server name and IP address of your computer:
#*Try <code>apt-cache search avahi</code> in a terminal to find current packages
*For the default server name, use {{Code|hostname}} on the command line.
#*Often, this is installed in a default system, you may already have it
*For your IP address, use {{Code|ifconfig -a}} on the command line.
#Unpack and install the '''Phidget Webservice''' source code tarball for Linux (download above)
**A line in the return text, under your main internet connection (usually {{Code|eth0}}) will say something like {{Code|inet addr:192.168.3.178}}, which is your IP.
#*From the unpacked Webservice source code directory, run:
#*:<code>./configure</code>
#*:<code>make</code>
#*:<code>sudo make install</code>
#*This will compile the executable '''<code>phidgetwebservice21</code>''' and place the it into '''<code>/usr/bin/phidgetwebservice21</code>'''


===Using the Webservice===
Using a server name to connect would not be an option without avahi or some other mDNS service; in this case you would only have the option to use an IP address.


You can get command line help with '''<code>phidgetwebservice21</code>''' by using the '''<code>-h</code>''' option:
===Using the WebService===


To use a Phidget over the webservice, you'll want to:
To use a Phidget over the webservice, you'll want to:
# Start the webservice on both the computer that directly connects to the Phidget and the computer that will remotely control it
* Obtain code you can use to open a Phidget remotely
# Run your program on the remote computer that will control the Phidget via code.
* Start the webservice on the computer that directly connects to the Phidget
* Run your program on the remote computer that will control the Phidget over the network


The easiest way to test these steps on Linux is simply to set up the webservice and run the Phidget program on the same computer, using the loopback interface.  Later, you can replace one of the two ends with a different computer and/or operating system.


To quickly create code to run remotely, in our examples we include commented out lines with openRemote() function calls of different types.  In the C example for your device, find the line that says:


{{Code|CPhidget_open((CPhidgetHandle) device, -1)}}


More content needed here.
and change it to be:
* Install instructions
 
* Example setup
<div class="source">
* Show in use
<syntaxhighlight lang=bash>
int serial_number = 37299
CPhidget_openRemoteIP ((CPhidgetHandle) device, serial_number, "127.0.0.1", 5001, NULL)
</syntaxhighlight>
</div>
 
Except that you should replace '''37299''' with the serial number of your Phidget, which you can obtain from either the Phidget board itself, or from when you [[#Checking|ran the HelloWorld example code]].  The IP address "127.0.0.1" simply loops back to the same computer, and 5001 is the default port as found from using {{Code|phidget21webservice -h}} in [[#Setting Up the WebService|the Setting Up the WebService]] section.  The NULL is used to not specify a password.
 
Save the changed example under a different filename.  In the walkthrough here, we are using the {{Code|InterfaceKit.c}} example, and we rename it to be {{Code|InterfaceKitRemote.c}}
 
Compile your new C file. In our {{Code|InterfaceKitRemote.c}} case, this would be by:
 
<div class="source">
<syntaxhighlight lang=bash>
gcc InterfaceKitRemote.c -o InterfaceKitRemote -lphidget21
</syntaxhighlight>
</div>
 
1. Start two terminals to run this test, usually opened via Ctrl-Alt-T.  Your [[#Setting udev Rules|udev rules]] need to be set up or you should use sudo for every command.  First, start the webservice in Terminal #1:
 
[[Image:Linux_ws_start.png|link=]]
 
This will broadcast any Phidget events, and receive any Phidget requests, both over the network.
 
2. Start the InterfaceKitRemote program that you just compiled which will open the remote Phidget.  In this case, it is {{Code|InterfaceKitRemote}}:
 
[[Image:Linux_ws_step2.png|link=]]
 
3. Now, plug in the Phidget!  The {{Code|phidget21webservice}} program captures the attach and other events and sends them out over the network (in the background in Terminal #1) and the Phidget software objected opened with openRemote in Terminal #2 receives them:
 
[[Image:Linux_ws_step3.png|link=]]
 
4. You can confirm that the webservice was indeed behind this exchange by killing the webservice process while still allowing the remote program to run:
 
[[Image:Linux_ws_step4.png|link=]]
 
===Debugging the WebService===
 
In addition to enabling [[General Phidget Programming#Logging|logging]] in your Phidget code, you can get additional debugging information from the WebService itself.  This additional debugging is enabled via a re-compile of the webservice.  From the webservice source code directory, do:
 
<div class="source">
<syntaxhighlight lang=bash>
make clean
 
./configure --enable-debug
 
make
 
sudo make install
</syntaxhighlight>
</div>
 
If you suspect multicast DNS (mDNS) may be the problem, you can:
* Try compiling the webservice with mDNSResponder, as described in [[#Installing the WebService|Installing the WebService]], or
* Try compiling the webservice completely without mDNS, as described in [[#Setting Up the WebService|Setting Up the WebService]]


==Advanced Uses==
==Advanced Uses==


Check with Patrick about BSD differences
===Setting udev Rules===
 
If you don't want to be using {{Code|sudo}} to run Phidget programs (including the webservice) forever, you will want to create a {{Code|udev}} rule to allow yourself access to the Phidget when you are not root.
 
Udev has an easy way to set the owner and permissions of the USB interface of the Phidget - it finds all devices that match a given set of rules, and applies new traits to them.  But you need to give udev something to match in order to apply the new settings.  Here, we will tell udev to match the vendor code for Phidgets, Inc. 
 
We recommend that you use the rules file included in the library download you have already installed.  Check the README file included in that download for information on how exactly to install it. 
 
The rules for udev are kept in files in {{Code|/etc/udev/rules.d/}} and are traditionally grouped into order of running (10 runs before 20, 30, etc) and device type (cd, network, etc).  There should be one or more files in there already - if this is your first time editing udev rules take a look at them to see the syntax to use:
* Commas separate each pair with == or =
* One rule on each line, no line breaks
* Quotes around the value to be matched or changed
* Comments can be added on lines starting with #
 
Strictly speaking, the files run in lexical order (i.e. the order they're listed when you use {{Code|ls}}).  A device can match many rules, and all will apply (if possible).  If conflicting rules are found, the first rule found is followed.
 
===Starting the WebService at Boot===
 
If you are tired of starting the webservice on the command line all the time, you can have the webservice start when your system starts, every time.
 
====User Space====
 
If you are running a standard Linux machine with an X-server (Unity, KDE) the easiest way to do this is to have the Phidget WebService start when your x server starts.
 
In this case, the webservice will be running in user space, so your [[#Setting udev Rules|udev rules need to be set up]] for the your user permissions to be able to access the USB ports using libusb.
 
Within the X-windowing system, there is usually some sort of {{Code|System &rarr; Settings/Preferences &rarr; Startup}} that you can choose to add programs that start when a user session starts.  On Ubuntu you can use Unity to find programs listing "startup" in their names to accomplish the same thing.  This will eventually lead you to a graphical tool like this to simply add the {{Code|/usr/bin/phidgetwebservice21}} program:
 
[[Image:linux_ws_boot.png|400px|link=]]
 
====As A Service====
 
You would want to set the boot start of {{Code|phidgetwebservice21}} to be a service if you are running a server, or a headless machine.  It is handy any time you need the webservice to be started as a booted, respawning service with a presence in different run levels and for all users.
 
A service is essentially a program that hangs out in the background, waiting to be used by some incoming task.  When the service is needed, the service forks a program to handle that need.  Most services that run on your Linux computer already have the ability to fork themselves. 
 
The webservice, however, is just a binary on Linux - {{Code|phidgetwebservice21}} - and so we need a program that handles the forking for us.  For this, we use the {{Code|start-stop-daemon}} program to spawn a standalone process for us, or kill it, based on our service-like start, stop, and restart commands.
 
To do this, we need:
# A script that tells the boot process how to start and handle the webservice (i.e. by using {{Code|start-stop-daemon}})
# A link from that script to the boot list
# An initialization file for the script
 
First, the script.  We will walk through Debian here, both because it is such a common distribution and because it is the distribution that our [{{SERVER}}/products.php?product_id=1073 Single Board Computer] runs.  But {{Code|init}} is surprisingly diverse on Linux, including everything from a different boot order, to different initialization programs and structure, and even different runlevels. 
 
On Debian (including Ubuntu), the initialization script covers:
* Runlevels that the service should be present on
* Dependencies of the service
* Name of the service and other informative data
* The location of the PIDFILE, which stores the process ID (pid) for later dealing with a spawned instance
* Any configuration file locations
* What to do when the service is given instructions to '''start''', '''stop''', or '''reload'''.
 
The Debian script we use to start the webservice on the [{{SERVER}}/products.php?product_id=1073 Single Board Computer]:
 
<div class="source">
<syntaxhighlight line start="1" lang=bash>
 
#!/bin/sh
 
### BEGIN INIT INFO
# Provides:          phidgetwebservice
# Required-Start:    $network $remote_fs
# Required-Stop:    $network $remote_fs
# Should-Start:      avahi
# Should-Stop:      avahi
# Default-Start:    2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Phidget WebService
# Description:      Phidget WebService for controlling Phidgets over the network.
### END INIT INFO
 
DESC="Phidget WebService"
NAME=phidgetwebservice
BIN=phidgetwebservice21
DAEMON=/usr/bin/$BIN
PIDFILE=/var/run/$NAME.pid
CFG=/etc/default/$NAME
 
# Gracefully exit if the package has been removed.
test -x $DAEMON || exit 0
 
# load config
pws_port="5001"
pws_serverid=""
pws_password=""
[ -f $CFG ] && . $CFG
 
start() {
[ -z "$pws_port" ] || OPTIONS="-p $pws_port "
[ -z "$pws_password" ] || OPTIONS="$OPTIONS-P $pws_password "
 
if [ -z "$pws_serverid" ]; then
OPTIONS="$OPTIONS -n $( hostname )"
else
OPTIONS="$OPTIONS -n $pws_serverid"
fi
echo -n "Starting $DESC: "
start-stop-daemon -S -b -q -p $PIDFILE -m -x $DAEMON -- $OPTIONS && echo "OK" || echo "ALREADY RUNNING"
}
 
stop() {
echo -n "Stopping $DESC: "
start-stop-daemon -K -q -p $PIDFILE -x $DAEMON && echo "OK" || echo "NOT RUNNING"
}
 
case "$1" in
  start)
start
;;
  stop)
stop
;;
  restart|force-reload)
stop
sleep 1
start
;;
  *)
echo "Usage: $0 {start|stop|restart}"
esac
 
exit 0
</syntaxhighlight>
</div>
 
 
Save the script into a file called {{Code|phidgetwebservice}}, and use {{Code|chmod 755}} to make it executable.
 
Also on Debian, startup service scripts should go in {{Code|/etc/init.d}}, and then put within the appropriate runlevel-numbered folder - by symbolic link.  There is a handy tool to do this for you, called {{Code|insserv}}:
 
<div class="source">
<syntaxhighlight lang=bash>
sudo insserv -d phidgetwebservice
</syntaxhighlight>
</div>
 
 
The {{Code|insserv}} program is the program that makes use of the {{Code|### BEGIN INIT INFO...### END INIT INFO}} that appears at the top of the {{Code|phidgetwebservice}} script.  Use {{Code|man insserv}} for more information.  The {{Code|insserv}} tool handles the mess of finding the right runlevel folders (i.e. the {{Code|rc.d}} numbered folders) and making the appropriate links. You can see what links would be updated by running {{Code|insserv}} with the {{Code|-n}} option, for a dry run.
 
'''Note:''' When you run {{Code|insserv}}, all of the dependencies for the boot order are re-written.  This means that all of the initialization scripts in {{Code|/etc/init.d}} are re-examined.  So, you'll probably get a lot of output when you run the command.
 
Then, you can check that {{Code|phidgetwebservice}} is on the service list with:
 
<div class="source">
<syntaxhighlight lang=bash>
service --status-all
</syntaxhighlight>
</div>
 
 
And you can start it right now without rebooting like this:
 
[[Image:linux_system_service_start.png|link=]]
 
The {{Code|service}} command has many options to start and stop services like the phidgetwebservice, try {{Code|man service}} for more information.
 
At this point, you can follow the client instructions on [[#Using the WebService|using the webservice]] to create a loopback test for the new webservice service that should now be running.
 
The final piece, for future configuration changes, is that the {{Code|/etc/init.d}} script looks for the file {{Code|/etc/default/phidgetwebservice}} upon starting up.  The file is expected to contain the port, server ID, and password for the server side of the webservice.  These are also set in the {{Code|phidgetwebservice}} script in {{Code|init.d}}, as you can see from reading the code above, but if you want to change them a lot, you can edit the configuration file rather than changing the {{Code|phidgetwebservice}} script and re-installing by {{Code|insserv}} every time.  The configuration file in {{Code|/etc/default/}} should contain the same syntax as that used in the script source above:
 
<div class="source">
<syntaxhighlight lang=bash>
pws_port="5001"
pws_serverid=""
pws_password=""
</syntaxhighlight>
</div>


===Cross-Compiling with a Custom Toolchain===
===Cross-Compiling with a Custom Toolchain===
Line 205: Line 489:
The collection of tools used to create binary code for a separate system is called a ''toolchain''.  Compiling the Phidget libraries specifically for an embedded system, and placing them into the path for writing code on top of the libraries is like adding another link in this chain.
The collection of tools used to create binary code for a separate system is called a ''toolchain''.  Compiling the Phidget libraries specifically for an embedded system, and placing them into the path for writing code on top of the libraries is like adding another link in this chain.


<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
You can use the typical {{Code|./configure}} setup for custom build targets:
<font size="3">
 
<source lang=bash>
<div class="source">
  sudo apt-get install gcc-arm-linux-gnueabi
<syntaxhighlight lang=bash>
</source>
./configure --prefix=toolchain_location --build=this_system --host=target_system
</font>
</syntaxhighlight>
</div>
</div>


You can use the typical ./configure setup for custom build targets:
For the Phidget libraries, the {{Code|./configure}} tool works this way as well. You'd use this in the [[#Installing|install the libraries section]] setup. For example, let's say you're building the libraries to develop code for the [{{SERVER}}/products.php?product_id=1073 Single Board Computer] as a target.  Your system is a standard Linux system (i686-pc-linux-gnu) and the target system for the SBC is {{Code|arm-linux-gnueabi}}.  For this target, you'll need the base of the GNU embedded Debian chain:


'''<code>./configure --prefix=toolchain_location --build=this_system --host=target_system</code>'''
<div class="source">
<syntaxhighlight lang=bash>
sudo apt-get install gcc-arm-linux-gnueabi
</syntaxhighlight>
</div>


For the Phidget libraries, the '''<code>./configure</code>''' tool works this way as well. For example, let's say you're building the libraries to develop code for the [[SBC|Phidget Single Board Computer (SBC)]] as a target.  Your system is a 32 bit system (i686-pc-linux-gnu) and the target system for the [[SBC]] is <code>arm-linux-gnueabi</code>.  Download the Phidget libraries [[#Getting Started (Libraries and Drivers)|above]] and unpack them into a folder '''<code>phidget_libraries</code>'''.  If <code>/usr/arm-linux-gnueabi</code> is the location of your ARM toolchain (downloaded above in '''<code>gcc-arm-linux-gnueabi</code>'''), type:
Then, download the Phidget libraries [[#Quick Downloads|above]] and unpack them into a folder {{Code|phidget_libraries}}.  If {{Code|/usr/arm-linux-gnueabi}} is the location of your ARM toolchain (downloaded above in {{Code|gcc-arm-linux-gnueabi}}), type:


<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<div class="source">
<font size="3">
<syntaxhighlight lang=bash>
<source lang=bash>
~/phidget_libraries $> ./configure --prefix=/usr/arm-linux-gnueabi --build=i686-pc-linux-gnu --host=arm-linux-gnueabi
</syntaxhighlight>
</div>


  user@server:~/phidget_libraries$ ./configure --prefix=/usr/arm-linux-gnueabi --build=i686-pc-linux-gnu --host=arm-linux-gnueabi
===Linux on Non-Standard Systems===


</source>
We occasionally get requests to use Phidgets on Linux systems other than a standard laptop or desktop.  One example is the Raspberry Pi system.  Often these systems include USB ports, so the combination makes sense.
</font>
 
</div>
Our libraries are installed by building from source, and their main dependency is the {{Code|libusb-1.0-0-dev}} library, so if you can get gcc on your machine (or set up a cross compiler for it) and you can also install the libusb-1.0 development headers, you can probably get Phidgets to work.  Of course, we don't offer much support for these systems, so - depending on your system - expect to spend some raw time getting it up and going. 
 
If you're new to the embedded computer thing, keep in mind that for these super basic systems, once you've gotten a power supply, and storage, and put the kernel you want on it, and then spent a couple of days of time getting things working, and  more time getting your drivers going, costs add up pretty quickly.  If you want a compact system that works right out of the box (and which can use all of our analog sensors in addition to our USB Phidgets), check out our [{{SERVER}}/products.php?product_id=1073 Single Board Computer].  Our SBC3:
* Has many more USB ports than super-stripped devices, and also has digital and analog ports
* Includes a power supply and can run on batteries easily
* Has a nice amount of RAM, a decent embedded processor, and built-in onboard storage (we've run R, GRASS, and X11 on it)
* Includes installed Debian, working Phidget drivers, and [[Phidget WebService|networked Phidget drivers]] from the moment it ships
* Has access to the full Debian repository including Python, Mono .NET, Ruby, and gcc
* Has a kernel development kit with patch file and instructions for adding new drivers (bluetooth, wireless, and so on)
* Comes with very in-depth documentation and technical support by phone and email
* Etc, etc.
The [[Phidget WebService|networked support]] in particular allows it to work with your cell phone and more. 
 
But if you really do want a raw hobbyist system to tinker with, go for it!  We're all nerds here - we've been there too and we certainly understand!


==Common Problems and Solutions==
==Common Problems and Solutions==


Maybe talk about udev rules?
{{ProblemSolution|Low Speed Phidgets (Max of 8)|Linux will only schedule one low-speed interrupt transfer per millisecond.}}
 
You can find out the type of your Phidget by attaching it and then running <code><font size=3>dmesg | tail</font></code>, which will display the type of Phidget from your kernel logs, as described above in the [[#Hardware|hardware section]]. The practical consequence of this is if your system has many low speed Phidgets attached, they will each be throttled down.  Low speed Phidgets require an interrupt transfer as often as every 8 milliseconds.  A Linux system could only have up to 8 of these Phidgets attached.
 
{{ProblemSolution|Sample Overrun Error|The data read from a program, or the first packet on the WebService, can give a sample overrun error (EEPHIDGET_OVERRUN).}}
 
Linux only polls data from the analog inputs on Phidgets when you ask it to.  So there is some delay between when you open the device and when it actually attaches when data from those inputs are accumulating...and overrunning the buffer.  This is simply in the nature of how Linux polls USB - we recommend catching (but ignoring) this one-time initial error.


==Limitations==
{{ProblemSolution|Raspberry Pi USB Current|Your device doesn't seem to run as expected on a Raspberry Pi.}}


* Linux will only schedule one low-speed interrupt transfer per millisecondThe practical consequence of this is if your system has many low speed Phidgets attached, they will each be throttled downLow speed Phidgets require an interrupt transfer as often as every 8 milliseconds.  A Linux system could only have up to 8 of these Phidgets attached.
The USB ports on the standard Raspberry Pi are only capable of supplying around 100mA reliablySince USB specification dictates 500mA of current maximum, many USB devices require several hundred mA to run smoothly.  Since the Pi cannot supply this much current it is common to see buggy performance or complete failure to run at all.  The get around this you should use a USB hub connected to the Pi that has it's own external power supplyThis will allow the devices connected to have as much power as they require.

Latest revision as of 17:17, 18 September 2017

Icon-Linux.png On Linux, Phidgets can be either plugged directly into a USB Port or run over a network using the WebService.

You need kernel version 2.6 (released in 2003) or later.

Quick Downloads

Linux has complete support for all Phidgets and their software APIs; the only thing it lacks when compared to Windows and OS X is a graphical user interface. We walk you through all steps for download, installation, checking, and starting to write code below.

If you are already a pro, and just want the downloads:

If you need old versions of the libraries, click here.

Getting Started with Linux

Installing

To install the libraries, follow these steps:

  1. Install libusb-1.0 development libraries - libusb-1.0-0-dev.
    • Note that libusb-1.0 may be already on your system, but the development libraries probably aren't.
    • Search for libusb-1.0-0-dev or similar in your distribution package directory.
    • Or install from source.
  2. Unpack and install the Phidget Libraries
    • From the main unpacked libraries directory, run:
      ./configure
      make
      sudo make install
    • This will compile phidget21.h and place the library into your gcc path

Note: Although these libraries are written in C, the additional libraries for Python, Java, and most other Phidget-supported languages depend on them.

Checking

To confirm the libraries were installed and work correctly, you can check both the hardware and software sides of the interface. It is worth checking the software side first, because if it works then you know the hardware side is also okay.

Software

To confirm that the libraries were installed correctly and can be used in code, you can use the Phidget Generic C Examples.

The easiest way to confirm correct installation will be to compile and run the HelloWorld C example, included in the examples download. This does not involve writing any C code, but it does involve compiling the example and running it, which is a quick process as we show below. If you feel more comfortable running the HelloWorld example for your specific language, you can skip below and pick your language, but keep in mind that any problems could be with the C library installation and not necessarily with your language.

To compile and run the basic C example for checking your installation:

1. Unpack the Phidget Generic C Examples
2. Open a terminal (often Ctrl-Alt-T) and go to the directory where the examples are unpacked
3. Compile the HelloWorld.c example:

 gcc HelloWorld.c -o HelloWorld -lphidget21

4. Run the HelloWorld example:

 sudo ./HelloWorld

(The sudo is needed for USB access for now, see the Setting udev Rules section for how to change this)

The -lphidget21 will look in the standard library location for your Linux distribution (usually /usr/lib/) for the Phidget 21 library file. Generally, libraries to be linked on Linux through gcc have a naming convention. For example, -lphidget21 looks for the binary files libphidget21.a and libphidget21.so in the library location. These files are automatically put in the library location during the make install step of installing the libraries.

The HelloWorld program will simply print out basic information for any device you plug in, and print a message upon unplugging the device. For example, starting the program, plugging in an Interface Kit Phidget, unplugging the Interface Kit, and pressing Enter displays:

 $ sudo ./HelloWorld 
   
 Opening...
 Press Enter to end

 Hello to Device Phidget InterfaceKit 8/8/8, Serial Number: 37299
 Goodbye Device Phidget InterfaceKit 8/8/8, Serial Number: 37299

 Closing...

Hardware

If the out-of-the-box examples do not work, make sure the Phidget is seen by your USB interface. To check this, you can use the kernel log reader dmesg. Pipe the output of dmesg into the utility tail to read the last ten lines of the log:

 $> dmesg | tail
 ....(9 lines)....
 [24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd

The number between the [ ] is the system time in seconds since the last boot up, so you can tell whether the event was recent or not. (This will also tell you the interrupt type of Phidget that is registered by the USB interface, see the common problems section below for more information on what this means.)

The Phidget should both connect and disconnect properly, so unplugging it should result in an additional line at the tail:

 $> dmesg | tail
 ....(8 lines)....
 [24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd
 [25094.809328] usb 2-1.2: USB disconnect, device number 5

If you don't see similar lines to these at the tail of your kernel log, take a look at the troubleshooting section below, as well as the Communications section of our general troubleshooting page.

Troubleshooting

If the examples do not work but USB does work (i.e. your computer can consistently see the device in the hardware), take a moment to check the basics:

  • No other programs, drivers, or processes are using that USB port in software
  • You are running the example program as root (or your udev rules have been set properly)
  • You are using libusb 1.0 (not the older 0.1 release)
  • You have compiled versions of libphidget21.a and libphidget21.so in your system library location (usually /usr/lib)
  • The Phidget libraries are the latest version (visit the quick downloads section to download them)
  • Your Linux kernel version is 2.6 or later (type uname -r in a terminal to get your kernel version)
  • Check the common problems section below, some specific combinations can cause problems

If your problem doesn't seem to be fixed by these steps, make sure that the Phidget is seen consistently by USB (if it is erratic, try our general troubleshooting guide). If you are still having problems after using the troubleshooting guide, please ask us!

Programming Languages

Now that you have the basic libraries installed, you can pick your language and begin programming!

If you are not using the webservice (discussed below) to control a Phidget over a network, your next step will be to delve into the use of your specific language. Each page has its own set of specific libraries, code examples, and setup instructions.

On Linux, we recommend the following languages:

You can also use these languages, but they do not support event driven code, and must use logic code only:

WebService

The Phidget WebService allows you to remotely control a Phidget over a network.
This section helps you install, check, and use the WebService on Linux, but we also have an overview of the Phidget WebService in general.

Installing the WebService

To install the webservice, you must first have the Phidget libraries installed. Then, follow these steps:

  1. Download avahi and its development libraries (mdnsresponder/bonjour is also an option, see the webservice with mDNSResponder section)
    • Try apt-cache search avahi in a terminal to find current packages
    • Often, this is installed in a default system, you may already have it
  2. Unpack and install the Phidgets WebService source code tarball for Linux
    • From the unpacked WebService source code directory, run:
      ./configure
      make
      sudo make install
    • This will compile the executable phidgetwebservice21 and place it into /usr/bin/phidgetwebservice21

WebService with BSD

For BSD, the webservice has been found to work (BSD 8+) but requires a special configuration at the ./configure step:

 ./configure LIBS=/usr/lib/libphidget21.so CFLAGS=-pthread

Then make and sudo make install are the same.
The LIBS argument may not be necessary, but sometimes BSD has trouble finding the library install location. The CFLAGS argument is needed because BSD needs explicit linking for using threads.

WebService with mDNSResponder

To use mdnsresponder instead of avahi, change the configure script to be:

 ./configure --enable-zeroconf=bonjour

(To see all options, use ./configure --help like you would any configure script)

Setting Up the WebService

To set up and use the webservice, it helps to have set your udev rules. Otherwise, you must run the webservice as root.

You can get command line help with phidgetwebservice21 by using the -h option:

$ phidgetwebservice21 -h
'phidgetwebservice21' is a Phidget and Dictionary server from Phidgets Inc. See www.phidgets.com for more information.
Usage: phidgetwebservice21 [OPTION]
All parameters are optional. The default parameters are: port=5001, ServerName=(Computer Name) and no password

Options:
  -p      Port
  -n      Server Name
  -P      Password
  -v      Debug mode
  -h      Display this help

You will see this help regardless of whether the webservice was correctly hooked in to avahi. In fact, you will see it even if you explicitly disabled mDNS in the ./configure step at compile:

  ./configure --disable-zeroconf

(To see all options, use ./configure --help like you would any configure script)

To find the defaults used by phidget21webservice, the command line is the fastest way to learn the default server name and IP address of your computer:

  • For the default server name, use hostname on the command line.
  • For your IP address, use ifconfig -a on the command line.
    • A line in the return text, under your main internet connection (usually eth0) will say something like inet addr:192.168.3.178, which is your IP.

Using a server name to connect would not be an option without avahi or some other mDNS service; in this case you would only have the option to use an IP address.

Using the WebService

To use a Phidget over the webservice, you'll want to:

  • Obtain code you can use to open a Phidget remotely
  • Start the webservice on the computer that directly connects to the Phidget
  • Run your program on the remote computer that will control the Phidget over the network

The easiest way to test these steps on Linux is simply to set up the webservice and run the Phidget program on the same computer, using the loopback interface. Later, you can replace one of the two ends with a different computer and/or operating system.

To quickly create code to run remotely, in our examples we include commented out lines with openRemote() function calls of different types. In the C example for your device, find the line that says:

CPhidget_open((CPhidgetHandle) device, -1)

and change it to be:

 int serial_number = 37299
 CPhidget_openRemoteIP ((CPhidgetHandle) device, serial_number, "127.0.0.1", 5001, NULL)

Except that you should replace 37299 with the serial number of your Phidget, which you can obtain from either the Phidget board itself, or from when you ran the HelloWorld example code. The IP address "127.0.0.1" simply loops back to the same computer, and 5001 is the default port as found from using phidget21webservice -h in the Setting Up the WebService section. The NULL is used to not specify a password.

Save the changed example under a different filename. In the walkthrough here, we are using the InterfaceKit.c example, and we rename it to be InterfaceKitRemote.c

Compile your new C file. In our InterfaceKitRemote.c case, this would be by:

 gcc InterfaceKitRemote.c -o InterfaceKitRemote -lphidget21

1. Start two terminals to run this test, usually opened via Ctrl-Alt-T. Your udev rules need to be set up or you should use sudo for every command. First, start the webservice in Terminal #1:

Linux ws start.png

This will broadcast any Phidget events, and receive any Phidget requests, both over the network.

2. Start the InterfaceKitRemote program that you just compiled which will open the remote Phidget. In this case, it is InterfaceKitRemote:

Linux ws step2.png

3. Now, plug in the Phidget! The phidget21webservice program captures the attach and other events and sends them out over the network (in the background in Terminal #1) and the Phidget software objected opened with openRemote in Terminal #2 receives them:

Linux ws step3.png

4. You can confirm that the webservice was indeed behind this exchange by killing the webservice process while still allowing the remote program to run:

Linux ws step4.png

Debugging the WebService

In addition to enabling logging in your Phidget code, you can get additional debugging information from the WebService itself. This additional debugging is enabled via a re-compile of the webservice. From the webservice source code directory, do:

 make clean

 ./configure --enable-debug

 make

 sudo make install

If you suspect multicast DNS (mDNS) may be the problem, you can:

Advanced Uses

Setting udev Rules

If you don't want to be using sudo to run Phidget programs (including the webservice) forever, you will want to create a udev rule to allow yourself access to the Phidget when you are not root.

Udev has an easy way to set the owner and permissions of the USB interface of the Phidget - it finds all devices that match a given set of rules, and applies new traits to them. But you need to give udev something to match in order to apply the new settings. Here, we will tell udev to match the vendor code for Phidgets, Inc.

We recommend that you use the rules file included in the library download you have already installed. Check the README file included in that download for information on how exactly to install it.

The rules for udev are kept in files in /etc/udev/rules.d/ and are traditionally grouped into order of running (10 runs before 20, 30, etc) and device type (cd, network, etc). There should be one or more files in there already - if this is your first time editing udev rules take a look at them to see the syntax to use:

  • Commas separate each pair with == or =
  • One rule on each line, no line breaks
  • Quotes around the value to be matched or changed
  • Comments can be added on lines starting with #

Strictly speaking, the files run in lexical order (i.e. the order they're listed when you use ls). A device can match many rules, and all will apply (if possible). If conflicting rules are found, the first rule found is followed.

Starting the WebService at Boot

If you are tired of starting the webservice on the command line all the time, you can have the webservice start when your system starts, every time.

User Space

If you are running a standard Linux machine with an X-server (Unity, KDE) the easiest way to do this is to have the Phidget WebService start when your x server starts.

In this case, the webservice will be running in user space, so your udev rules need to be set up for the your user permissions to be able to access the USB ports using libusb.

Within the X-windowing system, there is usually some sort of System → Settings/Preferences → Startup that you can choose to add programs that start when a user session starts. On Ubuntu you can use Unity to find programs listing "startup" in their names to accomplish the same thing. This will eventually lead you to a graphical tool like this to simply add the /usr/bin/phidgetwebservice21 program:

Linux ws boot.png

As A Service

You would want to set the boot start of phidgetwebservice21 to be a service if you are running a server, or a headless machine. It is handy any time you need the webservice to be started as a booted, respawning service with a presence in different run levels and for all users.

A service is essentially a program that hangs out in the background, waiting to be used by some incoming task. When the service is needed, the service forks a program to handle that need. Most services that run on your Linux computer already have the ability to fork themselves.

The webservice, however, is just a binary on Linux - phidgetwebservice21 - and so we need a program that handles the forking for us. For this, we use the start-stop-daemon program to spawn a standalone process for us, or kill it, based on our service-like start, stop, and restart commands.

To do this, we need:

  1. A script that tells the boot process how to start and handle the webservice (i.e. by using start-stop-daemon)
  2. A link from that script to the boot list
  3. An initialization file for the script

First, the script. We will walk through Debian here, both because it is such a common distribution and because it is the distribution that our Single Board Computer runs. But init is surprisingly diverse on Linux, including everything from a different boot order, to different initialization programs and structure, and even different runlevels.

On Debian (including Ubuntu), the initialization script covers:

  • Runlevels that the service should be present on
  • Dependencies of the service
  • Name of the service and other informative data
  • The location of the PIDFILE, which stores the process ID (pid) for later dealing with a spawned instance
  • Any configuration file locations
  • What to do when the service is given instructions to start, stop, or reload.

The Debian script we use to start the webservice on the Single Board Computer:

#!/bin/sh

### BEGIN INIT INFO
# Provides:          phidgetwebservice
# Required-Start:    $network $remote_fs
# Required-Stop:     $network $remote_fs
# Should-Start:      avahi
# Should-Stop:       avahi
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Phidget WebService
# Description:       Phidget WebService for controlling Phidgets over the network.
### END INIT INFO

DESC="Phidget WebService"
NAME=phidgetwebservice
BIN=phidgetwebservice21
DAEMON=/usr/bin/$BIN
PIDFILE=/var/run/$NAME.pid
CFG=/etc/default/$NAME

# Gracefully exit if the package has been removed.
test -x $DAEMON || exit 0

# load config
pws_port="5001"
pws_serverid=""
pws_password=""
[ -f $CFG ] && . $CFG

start() {
	[ -z "$pws_port" ] || OPTIONS="-p $pws_port "
	[ -z "$pws_password" ] || OPTIONS="$OPTIONS-P $pws_password "

	if [ -z "$pws_serverid" ]; then
		OPTIONS="$OPTIONS -n $( hostname )"
	else
		OPTIONS="$OPTIONS -n $pws_serverid"
	fi
	
	echo -n "Starting $DESC: "
	start-stop-daemon -S -b -q -p $PIDFILE -m -x $DAEMON -- $OPTIONS && echo "OK" || echo "ALREADY RUNNING"
}

stop() {
	echo -n "Stopping $DESC: "
	start-stop-daemon -K -q -p $PIDFILE -x $DAEMON && echo "OK" || echo "NOT RUNNING"
}

case "$1" in
  start)
	start
	;;
  stop)
	stop
	;;
  restart|force-reload)
	stop
	sleep 1
	start
	;;
  *)
	echo "Usage: $0 {start|stop|restart}"
esac

exit 0


Save the script into a file called phidgetwebservice, and use chmod 755 to make it executable.

Also on Debian, startup service scripts should go in /etc/init.d, and then put within the appropriate runlevel-numbered folder - by symbolic link. There is a handy tool to do this for you, called insserv:

 sudo insserv -d phidgetwebservice


The insserv program is the program that makes use of the ### BEGIN INIT INFO...### END INIT INFO that appears at the top of the phidgetwebservice script. Use man insserv for more information. The insserv tool handles the mess of finding the right runlevel folders (i.e. the rc.d numbered folders) and making the appropriate links. You can see what links would be updated by running insserv with the -n option, for a dry run.

Note: When you run insserv, all of the dependencies for the boot order are re-written. This means that all of the initialization scripts in /etc/init.d are re-examined. So, you'll probably get a lot of output when you run the command.

Then, you can check that phidgetwebservice is on the service list with:

 service --status-all


And you can start it right now without rebooting like this:

Linux system service start.png

The service command has many options to start and stop services like the phidgetwebservice, try man service for more information.

At this point, you can follow the client instructions on using the webservice to create a loopback test for the new webservice service that should now be running.

The final piece, for future configuration changes, is that the /etc/init.d script looks for the file /etc/default/phidgetwebservice upon starting up. The file is expected to contain the port, server ID, and password for the server side of the webservice. These are also set in the phidgetwebservice script in init.d, as you can see from reading the code above, but if you want to change them a lot, you can edit the configuration file rather than changing the phidgetwebservice script and re-installing by insserv every time. The configuration file in /etc/default/ should contain the same syntax as that used in the script source above:

 pws_port="5001"
 pws_serverid=""
 pws_password=""

Cross-Compiling with a Custom Toolchain

This would allow you to have the Phidget libraries compiled to include in code for an embedded device. When developing for an embedded device, you will often write code for it on your 'normal' computer, and then build the code to binary with a different target than the processor in your computer. Many microcontrollers do not have the ability to run a full operating system, and hence cannot compile code natively.

The collection of tools used to create binary code for a separate system is called a toolchain. Compiling the Phidget libraries specifically for an embedded system, and placing them into the path for writing code on top of the libraries is like adding another link in this chain.

You can use the typical ./configure setup for custom build targets:

./configure --prefix=toolchain_location --build=this_system --host=target_system

For the Phidget libraries, the ./configure tool works this way as well. You'd use this in the install the libraries section setup. For example, let's say you're building the libraries to develop code for the Single Board Computer as a target. Your system is a standard Linux system (i686-pc-linux-gnu) and the target system for the SBC is arm-linux-gnueabi. For this target, you'll need the base of the GNU embedded Debian chain:

 sudo apt-get install gcc-arm-linux-gnueabi

Then, download the Phidget libraries above and unpack them into a folder phidget_libraries. If /usr/arm-linux-gnueabi is the location of your ARM toolchain (downloaded above in gcc-arm-linux-gnueabi), type:

 ~/phidget_libraries $> ./configure --prefix=/usr/arm-linux-gnueabi --build=i686-pc-linux-gnu --host=arm-linux-gnueabi

Linux on Non-Standard Systems

We occasionally get requests to use Phidgets on Linux systems other than a standard laptop or desktop. One example is the Raspberry Pi system. Often these systems include USB ports, so the combination makes sense.

Our libraries are installed by building from source, and their main dependency is the libusb-1.0-0-dev library, so if you can get gcc on your machine (or set up a cross compiler for it) and you can also install the libusb-1.0 development headers, you can probably get Phidgets to work. Of course, we don't offer much support for these systems, so - depending on your system - expect to spend some raw time getting it up and going.

If you're new to the embedded computer thing, keep in mind that for these super basic systems, once you've gotten a power supply, and storage, and put the kernel you want on it, and then spent a couple of days of time getting things working, and more time getting your drivers going, costs add up pretty quickly. If you want a compact system that works right out of the box (and which can use all of our analog sensors in addition to our USB Phidgets), check out our Single Board Computer. Our SBC3:

  • Has many more USB ports than super-stripped devices, and also has digital and analog ports
  • Includes a power supply and can run on batteries easily
  • Has a nice amount of RAM, a decent embedded processor, and built-in onboard storage (we've run R, GRASS, and X11 on it)
  • Includes installed Debian, working Phidget drivers, and networked Phidget drivers from the moment it ships
  • Has access to the full Debian repository including Python, Mono .NET, Ruby, and gcc
  • Has a kernel development kit with patch file and instructions for adding new drivers (bluetooth, wireless, and so on)
  • Comes with very in-depth documentation and technical support by phone and email
  • Etc, etc.

The networked support in particular allows it to work with your cell phone and more.

But if you really do want a raw hobbyist system to tinker with, go for it! We're all nerds here - we've been there too and we certainly understand!

Common Problems and Solutions

Low Speed Phidgets (Max of 8): Linux will only schedule one low-speed interrupt transfer per millisecond.

You can find out the type of your Phidget by attaching it and then running dmesg | tail, which will display the type of Phidget from your kernel logs, as described above in the hardware section. The practical consequence of this is if your system has many low speed Phidgets attached, they will each be throttled down. Low speed Phidgets require an interrupt transfer as often as every 8 milliseconds. A Linux system could only have up to 8 of these Phidgets attached.

Sample Overrun Error: The data read from a program, or the first packet on the WebService, can give a sample overrun error (EEPHIDGET_OVERRUN).

Linux only polls data from the analog inputs on Phidgets when you ask it to. So there is some delay between when you open the device and when it actually attaches when data from those inputs are accumulating...and overrunning the buffer. This is simply in the nature of how Linux polls USB - we recommend catching (but ignoring) this one-time initial error.

Raspberry Pi USB Current: Your device doesn't seem to run as expected on a Raspberry Pi.

The USB ports on the standard Raspberry Pi are only capable of supplying around 100mA reliably. Since USB specification dictates 500mA of current maximum, many USB devices require several hundred mA to run smoothly. Since the Pi cannot supply this much current it is common to see buggy performance or complete failure to run at all. The get around this you should use a USB hub connected to the Pi that has it's own external power supply. This will allow the devices connected to have as much power as they require.