linmctool - Linux motion-sensing controller tool

linmctool is a command-line utility which handles Bluetooth communications with several models of motion-sensing game controllers, and outputs sensor data in plain text. It is intended as a simple and portable tool for educational and research purposes in relation to such topics as 3D coordinate systems, Newtonian physics, robotics, sensor fusion, motion tracking and new user interfaces. Motion-sensing game controllers are a great opportunity to introduce children and students to a wide range of scientific topics, from the basic concept of inertial forces all the way to Kalman filtering.

The following devices are supported:

Sample output follows:

0 00:25:xx:xx:xx:xx WIIMOTE aX=-11 aY=-10 aZ=14  ir0x=966 ir0y=406 ir1x=747 ir1y=419  \
  ir2x=554 ir2y=430 ir3x=467 ir3y=389  gX=209 gY=-298 gZ=232
1 00:19:xx:xx:xx:xx SIXAXIS aX=-3 aY=-21 aZ=-111  gZ=-21 
2 00:06:xx:xx:xx:xx PSMOVE  seq=0 aX=-2613 aY=-329 aZ=3271  gX=5 gY=8 gZ=8  mX=-197 mY=-157 mZ=-58

These game controllers are marketed as peripherals with Bluetooth connectivity (Bluetooth is an open standard which promotes interoperability between computers and wireless devices) and linmctool communicates with their open interfaces via the standard Bluetooth HID protocol. There is no need to modify the devices or circumvent any protection. Still, since this software is not endorsed by manufacturers, we cannot guarantee that it configures the hardware exactly as intended. There is always a risk of voiding the warranty, damaging the hardware by operating it beyond safe ratings, or worse. Use at your own risk !

For example, it is unknown whether the PS Move autonomously regulates the power of its RGB LEDs or whether the Bluetooth host is supposed to do it based on temperature readings. As a precaution, linmctool will limit brightness to 25 %.

Unlike other approaches which tend to face compatibility and integration issues, linmctool is designed to compile and run easily on any Linux distribution, with barely any dependency.

# wget http://www.pabr.org/linmctool/linmctool-20110304.c
# gcc --std=gnu99 -Wall linmctool-20110304.c -lusb -o linmctool 

For systems without libusb, compile with -DWITHOUT_USB. USB pairing, if needed, will have to be performed on another host (see Pairing ).

# gcc --std=gnu99 -Wall -DWITHOUT_USB linmctool-20110304.c -o linmctool 

Here are debugging techniques which can help improve support for these devices.

mccalibrate turns raw data from linmctool into physically-relevant metric values.

The current implementation simply performs a linear mapping. Two reference values (±1 g, ±1 rad/s) for each sensor axis are stored in the working directory.

# wget http://www.pabr.org/linmctool/mccalibrate-20110304.c
# gcc --std=gnu99 -Wall mccalibrate-20110304.c -lm -o mccalibrate 

# ./linmctool --nostdin  |  ./mccalibrate --static
Incoming connection...
New device 0 00:06:xx:xx:xx:xx is a PS Move
Read calibration from 00:06:xx:xx:xx:xx.cal
Put PS MOVE in at least 6 orientations.
Press RETURN to sample when it is stationary.
Please wait 1s... Got 1 samples, please continue.
Please wait 1s... Got 2 samples, please continue.
Please wait 1s... Got 3 samples, please continue.
Please wait 1s... Got 4 samples, please continue.
Please wait 1s... Got 5 samples, please continue.
Please wait 1s... Computing...
ACC: 6 samples, coverage 99% 99% 99%, err 19.792511
MAG: 6 samples, coverage 98% 95% 99%, err 0.741071
A0   min   +656 ppm   max  +1339 ppm
A1   min  -2325 ppm   max   +204 ppm
A2   min   -496 ppm   max  -2189 ppm
G0   min     +0 ppm   max     +0 ppm
G1   min     +0 ppm   max     +0 ppm
G2   min     +0 ppm   max     +0 ppm
M0   min -101515 ppm   max +78074 ppm
M1   min -72260 ppm   max +102799 ppm
M2   min -98625 ppm   max +91781 ppm
Wrote 00:06:xx:xx:xx:xx.cal

# ./linmctool  |  ./mccalibrate
Waiting for Bluetooth connections.
Incoming connection...
New device 0 00:06:xx:xx:xx:xx is a PS Move
Read calibration from 00:06:xx:xx:xx:xx.cal
0 00:06:xx:xx:xx:xx PSMOVE seq=12  aX=-0.10400 aY=9.82060 aZ=-0.00367  \
  gX=0.00000 gY=0.00500 gZ=0.03833  mX=0.1890 mY=0.9726 mZ=-0.3458 

mctrack estimates and graphically displays the position and orientation of up to four devices. The current version works only with the PS Move.

# wget http://www.pabr.org/linmctool/mctrack-20110304.c
# gcc --std=gnu99 -Wall mctrack-20110304.c -lX11 -lm -o mctrack
# ./linmctool  |  ./mccalibrate  |  ./mctrack 

There is plenty of published research on motion estimation with accelerometers, gyros and magnetometers. mctrack is intended as a basic example; it implements naive Euler integration of instantaneous rotation and acceleration, with long-term registration to a reference position and an absolute orientation defined by gravity and magnetic field. Damping factors are hard-coded.

The HID-over-L2CAP-socket code is inspired from the hidd daemon in Bluez. This approach, which achieves maximum portability, was explored earlier by Jim Paris.

Wiimote support is based on technical information published by the Wiibrew project.

SIXAXIS/DS3 support is from [SIXLINUX], with additional support for LEDs, gyro and rumble.

The MoveOnPC project pioneered work toward open-source support for the PS Move, primarily on Windows, and with a wider scope including optical tracking with the PS Eye camera.

Thanks to Sony and Nintendo for adopting Bluetooth, an open standard, in their gaming systems. Although they are sometimes criticized for not fully complying with the HID specifications, their protocols remain reasonably open and intelligible. Things would have been much worse if the product designers had opted to actively impede third-party projects such as this one.