OS - Linux

Phidgets can run on Linux directly using USB, or remotely over a network using the Phidget Webservice.

You need kernel version 2.6 or later.

Getting Started (Libraries and Drivers)

Linux does not have a graphical user interface to check your Phidget, but it does have a complete API for many languages.

For any language, you will need the basic Phidget Libraries for Linux:

• Phidget Libraries

Installing

To install the libraries, follow these steps:

1. Download libusb-0.1 and its development libraries
   • Try apt-cache search libusb in a terminal to find current packages
   • Or install from source, which includes the libusb development libraries
2. Unpack and install the Phidget Libraries for Linux (download above)
   • From the main libraries directory, run:

     ./configure

     make

     sudo make install

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

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 C Examples:

• Phidget C Examples

The easiest way to confirm correct installation will be to compile and run the HelloWorld 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 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 C Examples (download above)
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)

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 (usually /usr/lib). These files are automatically put in the library location during the make install step of installing the libraries above.

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 simply 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 limitations 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 0.1 (not 1.0 or later)
• 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 getting started section above 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 limitations 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 guide). If you are still having problems after 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:

• C/C++
• Java
• Python
• C# (Using Mono)
• Flash AS3

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

• MATLAB

Webservice

The Phidget Webservice allows you to remotely control a Phidget over a network.
Before using these webservice drivers, it may help to learn about how the Phidget Webservice works.

• Linux Phidgets Webservice libraries
• The Webservice on Linux uses avahi

Installing the Webservice

To install the webservice, follow these steps:

1. Download avahi and its development libraries
   • 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 Phidget Webservice source code tarball for Linux (download above)
   • From the unpacked Webservice source code directory, run:

     ./configure

     make

     sudo make install

   • This will compile the executable phidgetwebservice21 and place the it into /usr/bin/phidgetwebservice21

Setting Up the Webservice

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

  phidgetwebservice21 -h

Which returns:

  '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

If you see this help, it means the webservice was correctly hooked in to avahi. Using a server name to connect would not be an option without avahi; otherwise you would have to use an IP address.

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 the Webservice

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

1. Start the webservice on both the computer that directly connects to the Phidget and the computer that will remotely control it
2. Run your program on the remote computer that will control the Phidget via code.

To start the webservice on Linux, on the command line type:

  phidgetwebservice21

Let's say your computer that is directly connected to the Phidget has a default name of phidget-test. Then, to connect

Directly Controlling Computer	Remotely Controlling Computer
Start

More content needed here.

• Install instructions
• Example setup
• Show in use

Advanced Uses

Check with Patrick about BSD differences

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.

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

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. For example, let's say you're building the libraries to develop code for the 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 arm-linux-gnueabi. 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:

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

Common Problems and Solutions

Maybe talk about udev rules?

Limitations

• Linux will only schedule one low-speed interrupt transfer per millisecond. 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.