P5 Glove and Pure-Data (pd) in Linux

Last updated 2008-07-11

About

The P5 glove can be used in Linux with pure-data (pd). The pieces that are required for this approach:

The obvious things you need are: Linux (duh!) with working USB and sound support, a P5 glove, and pure-data. The installation/configuration of these pieces is not covered here.

The additional (more interesting) pieces are:

News

On 6/24/07 I gave a short talk on the p5 glove at the DorkbotPDX event. The slides and demo patches are available here.

PD screenshots

These screenshots should give you an idea about what things are like once the glove is up and running in pd. In other words, here's a little sneak peak:

p5glove demo avi

The Approach

Unfortunately, the process is hardly straightforward...far from trivial. If you're looking for a 5 minute setup, we're just not there yet. I'll likely forget something important...but hopefully the info here is enough to help others get going.

I initially created a pd external for the P5 by using Jason's usb driver. This approach seemed to make the most sense for my purposes, but there were some problems that quickly developed...notably blocking calls inside of libusb. Because libp5glove uses libusb and libusb uses blocking calls, pd would eventually block data (yeah, this is bad). Apparently a future version of libusb will support nonblocking calls, but for now I guess we're stuck. A work-around would be to put the usb calls into a thread, but that seemed like overkill.

Instead of putting the USB calls in a thread, a simpe solution is to use OSC as the transport and just drop the USB calls into a separate process. This also has the benefit of working over networks and connecting to environments other than pd.

blockdiagram

Step 0: For the impatient

The following is the brief version of what's covered below. Brief instructions only:

  1. Download and build the libp5glove driver:
    1. mkdir libp5glove; cd libp5glove
    2. svn checkout svn://svn.evillabs.net/ezrec/libp5glove/trunk
      (or download it from me)
    3. cd libp5glove/trunk
    4. ./autogen.sh
      (If/when it complains, edit autogen.sh and strip version numbers from the tools)
    5. edit src/p5glove.c and comment out the #define DEBUG line near the top (to prevent console mess)
    6. ./configure; make all
  2. If necessary, tweak usb device permissions:
    Your mileage may vary depending on your distribution, but modern distros with modern kernels with udev support can do:
    1. sudo echo 'SYSFS{idVendor}=="0d7f", SYSFS{idProduct}=="0100", MODE="0664", GROUP="plugdev"' > /etc/udev/p5glove.rules
    2. sudo ln -s /etc/udev/p5glove.rules /etc/udev/rules.d/p5glove.rules
    3. (unplug the glove and plug it back in)
  3. Test the libp5glove driver with it's included demo progs:
    ./demo/p5dump or ./demo/p5hand
  4. Download and build the OSCx externals for pure-data. You must have the pure-data source available. Fortunately, checking it out from the SVN repository is quite simple:
    1. mkdir pd-externals; cd pd-externals;
    2. svn co https://pure-data.svn.sourceforge.net/svnroot/pure-data/trunk/externals
    3. cd externals/OSCx; ./configure; make; make install
      (If the build can't find the pd source, edit OSCx/src/Makefile and add the pure-data source (src) path to the INCLUDES line near the top.)
  5. Download and build my p5osc application: p5osc-0.01.tar.gz
    1. tar -xvzf p5osc-0.01.tar.gz
    2. cd p5osc-0.01
    3. vi Makefile
      (You must edit the Makefile and add your custom paths)
    4. make all
  6. Copy my p5glove.pd and p5glove_demo.pd patches (included in the p5osc download above) into a location that your pure-data (pd) installation understands.
  7. Start up pure-data and open the p5glove_demo.pd patch
  8. Run the p5osc program and tell it to connect to localhost:9998
    p5osc localhost:9998
  9. Move the P5 glove around and watch the screen. Enjoy.

Step 1: libp5glove

There is a linux driver for the P5 provided by Essential Reality, but it wouldn't work on my machine (hard locked it in fact). I believe that the support from Essential Reality, especially on newer (2.6) kernels is slim to none.

The libp5glove driver by Jason McMullan is a user mode USB driver for the P5 glove. This driver obtains data samples from the glove device and converts the sample data into button, bend, position, and rotation data. Although the driver is still quite young (read: buggy, glitchy), it's still usable. Kudos to Jason for putting it together!

An 0.3 version was released and seemed to be stable enough, but at the time of this writing I could no longer find the tar.gz file distribution. It looks like the libp5glove isn't easily downloadable in a tarball...so...

Go download the latest libp5glove driver from the Subversion repository maintained by the audiomulch guys. This is easily done by issuing

in a new directory.

For the SVN challenged, I've created a snapshot of the trunk, current as of Feb 6th, 2005. You can download it here: libp5glove_svn_20050206.tar.gz, but don't expect me to keep it current (you really are probably better off downloading it from the svn repository).

$ mkdir libp5glove  
$ cd libp5glove  
$ svn checkout svn://svn.evillabs.net/ezrec/libp5glove/trunk

(or download it from me) 

$ cd libp5glove/trunk  
$ ./autogen.sh

(If/when it complains, edit autogen.sh and strip version numbers from the tools) 

$ ./configure; make all

Test the libp5glove driver with it's included demo progs: ./demo/p5dump or ./demo/p5hand. p5dump will scroll 100 samples from the glove, while p5hand uses a GUI to show the glove position. If all goes well, you should have something on your screen that changes when you move your glove hand.

I should also make a brief note that sometimes on my system, the libp5glove version 0.3 failed to properly align samples and would sometimes start incorrectly. I ended up building a small patch that tries 8, 16, and 24 byte samples until it thinks it is properly aligned. I submitted the patch to Jason (via the Yahoo p5 list, which is surprisingly quite active), but I don't think it's been incorporated into the driver. Until then, I keep hack patching my own version.

Step 2: USB device permissions

Assuing that you're running a semi-modern 2.6 kernel and have udev support, when you plug in the glove device, it should show up under /dev/bus/usb/xxx/yyy where xxx and yyy are bus and device numbers, respectively. You can derive the actual values by tailing /var/log/kern.log or doing lsusb -v (as root).

Usually, the permissions of the usb /dev device aren't such that your mortal user can access it. The easy/quick/semi-standard way of solving this problem is to write a simple udev rule. Details may vary by distro, but Debian-based setups can create /etc/udev/p5glove.rules with the following contents:

SYSFS{idVendor}=="0d7f", SYSFS{idProduct}=="0100", MODE="0664", GROUP="plugdev"

and then symlink /etc/udev/p5glove.rules to /etc/udev/rules.d/p5glove.rules

The result should be that when you plug the glove device back in, the corresponding /dev/bus/usb/xxx/yyy device should be created with mode 0664 and group "plugdev". Of course, your mileage may vary, and you may need to change the group/mode to fit your specific setup...thought the vendor ID and product ID are likely not to change.

Step 3: OSCx/libOSC

The OSCx external for pure-data is used in two places. First, it is used in the p5glove abstraction (via the dumpOSC external) to receive OSC messages, and the p5osc application uses the libOSC library to implement message sending. In order for an application to send/receive OSC messages (packets), it can use the libOSC library to simplify things. This seems to be the standard approach. To understand OSC messages within pure-data, the dumpOSC external can be used.

First, you'll need to download the pd-externals package from CVS on sourceforge. The project main project page is at http://pure-data.sourceforge.net/ and the CVS repository is also hosted on sourceforge. To check out the package, do

$ mkdir pd-externals; cd pd-externals;  
$ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/pure-data login

(hit enter for empty password)

$ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/pure-data co -P externals  
$ cd externals/OSCx; ./configure; make; make install

The CVS download might take a while (there are many other externals included in the module, not just OSCx). You might have to be root for 'make install', depending on your installation location. If the build can't find the pd source, edit OSCx/src/Makefile and add the pure-data source (src) path to the INCLUDES line near the top.

Two additional notes: 1) On AMD64, it seems that -fPIC is required and the configure script for OSCx doesn't set this up. You may have to manually add it to the src/Makefile and libOSC/Makefile after running configure. 2) If one of the linker steps complains that it can't find -lpd, simply remove the '-lpd' from inside src/Makefile (it isn't needed).

After the installation is complete, it's probably a good idea to verify that OSCx is available to pure-data. Fire up pd and create a new patch. Create a new object and key in 'dumpOSC'. If all went well, it'll be recognized by pd and will have a single outlet. If it fails, pd should complain with an error message in the console.

Make a note of the absolute path to the OSCx directory. You'll need the full path information when building p5osc (below).

Step 4: p5osc

Ok, the name isn't very clever, and it even conflicts with Tim Kreger's P5osc (note the capital P) for Mac OSX. When I started building p5osc, I considered porting his version but failed to open some .pax archive file, so I just started from scratch.

The p5osc application acts as a bridge: It reads messages from the libp5glove driver and maps these to Open Sound Control (OSC) messages. It is available for download: p5osc-0.01.tar.gz. Be forewarned, the build process needs some serious improvement:

$ tar -xvzf p5osc-0.01.tar.gz  
$ cd p5osc-0.01  
$ vi Makefile  
$ make all

It is important to point out that you must edit the Makefile and add the paths that correspond to the libp5glove source dir (previously compiled!) and the pd externals source dir (previously compiled!). Ideally, this wouldn't be required...but I didn't want to lug around all the other source and I didn't feel like learning automake (what a bitch!)

Future releases will hopefully have a better, more robust build system in place.

The commandline usage for p5osc is simple:

$ p5osc [<host>[:port]]

The host and port default to localhost:999 if they are not specified.

Step 5: p5glove.pd abstraction for pure-data

I wrote an abstraction for pure-data that handles the receiving of OSC messages and turns them into pd messages. The abstraction has no inlets or outlets. In addition to message translation/routing, the abstraction will detect a "fist" sign (ie. all fingers are clenched beyond 75%) and send a corresponding message. If you dig into the [p5glove] object, you can find the following help screen:

p5glove help screen

The above shows all the messages available when [p5glove] is dropped into a patch. A sinlge startup parameter may be given to the abstraction to specify the port number to listen on. You can build a new patch and use the [p5glove] abstraction and receive the various messages, or you can quickly test things out with my p5glove_demo.pd patch...

Step 6: p5glove_demo.pd - Sample patch showing off p5glove

p5glove demo pd

Known Issues / Problems