OS - Linux

Quick Downloads

Already know what you're doing? Here you go:

• Phidget22 Library for Linux
• Phidget22Extra Library for Linux (Required for Network Server)
• Phidget Network Server for Linux
• PhidgetAdmin Tool for Linux
• Software License

If you need older versions of the Linux libraries, click here.

Getting Started with Linux

Welcome to using Phidgets with Linux. If you haven't already, check out the user guide for your device. If you are ready to go, the first step in creating Linux applications with Phidgets is installing the Phidget libraries!

Installing

If your Linux machine is running Debian, keep reading. For all other Linux distributions, jump ahead to generic installs.

Debian Install

To install the Phidget libraries on Debian, follow theses steps:

1. Enter the following command in the terminal:

wget -qO- http://www.phidgets.com/gpgkey/pubring.gpg | apt-key add -

2. If you are running jessie (Debian 8), enter the following command:

echo 'deb http://www.phidgets.com/debian jessie main' > /etc/apt/sources.list.d/phidgets.list

We also support squeeze (Debian 6), and wheezy (Debian 7). If you are running one of these older releases, simply replace jessie in the command above with your release.

3. Next, update your package lists:

apt-get update

4. Finally, install the recommended packages by entering the command below:

apt-get install libphidget22 libphidget22-dev phidget22networkserver libphidget22java phidget22admin

You have finished installing the Phidget libraries onto your Debian machine. Next, we will verify everything is working properly. Jump ahead to verifying.

Generic Install

To install the Phidget libraries, follow these steps:

1. Install libusb-1.0 development libraries by entering the command into the terminal:

apt-get install libusb-1.0-0-dev

2. Download and unpack the following files:

• libphidget22
• libphidget22extra
• libphidget22java
• phidget22networkserver
• phidget22admin

3. Open the README file that is included at the top of each directory. This file will give you important information about how to properly install the files.

You have finished installing the Phidget libraries onto your Linux machine. Next, we will verify everything is working properly.

Verify

The best way to verify that your libraries are installed and your Phidget is working is to compile and run the HelloWorld C example. To compile and run the example, follow these steps:

1. Unpack the C examples and open a terminal window at this location

2. Compile the HelloWorld.c example:

 gcc HelloWorld.c -o HelloWorld -lphidget22

3. Run the HelloWorld example:

./HelloWorld

Your terminal should look something like this:

The HelloWorld program will simply communicate when a Phidget has been attached or detached, as can be seen in the image above.

Your Phidget is now able to communicate with your development machine. The next step is selecting a programming language so you can start to write some code!

Programming

Ready to write some code? Select one of the programming languages below:

Great choices for beginners:

• C/C++
• Java
• Python

Also supported:

• C#
• VB.Net
• JavaScript

Phidget Network Server

The Phidget Network Server is an extremely useful feature of Phidgets that allows you to remotely control Phidgets over your network. If you haven't already, check out the Phidget Network Server page for a complete overview.

Try it out!

In order to try the Phidget Network Server out, you will need a host computer, and a client computer with the Phidget libraries installed:

• Host computer: the computer that is physically connected to the Phidgets via USB and is running the Phidget Network Server.
• Client computer: a computer running a Phidgets application that accesses Phidgets connected to the host computer.

If you only have one computer, don't worry, your machine can act as both a host and a client.

Next, follow these steps:

1. Open the terminal on the host computer and type in the following command:

 phidget22networkserver

The Network Server is now running on your machine with the default configuration. If you would like to change the Network Server configuration, you can do so by modifying the following file:

• /etc/phidgets/phidget22networkserver.pc

Now that you have the Network Server running on your host computer, the next step will be accessing the Phidgets connected to your host computer from your client computer. Follow the steps below:

1. Open the terminal on the client computer and type in the following command:

phidget22admin -s

Advanced Information

Setting udev Rules

If you don't want to be using sudo to run Phidget programs (including the Network Server) 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, or continue reading here.

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. Simply find the file named 99-libphidget22.rules included with our library files, and move it into /etc/udev/rules.d/.

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 Network Server at Boot

If you are tired of starting the network server on the command line all the time, you can have the network server 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 Network Server start when your x server starts.

In this case, the network server 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 window like this one:

Simply add the /usr/bin/phidget22networkserver program to the list.

As A Service

You would want to set the boot start of phidgetnetworkserver21 to be a service if you are running a server, or a headless machine. It is handy any time you need the network server 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 network server, however, is just a binary on Linux - phidgetnetworkserver21 - 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 networkserver (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 network server on the Single Board Computer:

#!/bin/sh

### BEGIN INIT INFO
# Provides:          phidgetnetworkserver
# 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 Network Server
# Description:       Phidget Network Server for controlling Phidgets over the network.
### END INIT INFO

DESC="Phidget Network Server"
NAME=phidgetnetworkserver
BIN=phidgetnetworkserver21
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 phidgetnetworkserver, 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 phidgetnetworkserver

The insserv program is the program that makes use of the ### BEGIN INIT INFO...### END INIT INFO that appears at the top of the phidgetnetworkserver 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 phidgetnetworkserver is on the service list with:

 service --status-all

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

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

At this point, you can follow the client instructions on using the network server to create a loopback test for the new network server 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/phidgetnetwork server upon starting up. The file is expected to contain the port, server ID, and password for the server side of the network server. These are also set in the phidgetnetworkserver 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 phidgetnetworkserver 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!