1.  Introduction

Ever since the PS3 platform was released (Japan: 2006-11-11; USA: 2006-11-17; Europe: 2007-03-23) there has been speculation as to whether its wireless controller, dubbed "SIXAXIS", could be used in non-gaming applications. It is already known that the SIXAXIS operates as a regular HID device in USB mode. Since it is being marketed as a Bluetooth device, it was fair and legitimate to expect it to also work with any Bluetooth-compliant computer, just like the Wiimote.

This document explains how to configure Linux to recognize the SIXAXIS as a Bluetooth HID device.

2.  Disclaimer

  • These instructions are not endorsed by Sony. There is no guarantee that you will not damage your SIXAXIS or your PS3 by following them.

  • The use of Bluetooth authentication and encryption has not been investigated yet. Running in non-secure mode, as described in this document, might be inappropriate for some applications, and may also make the host computer temporarily vulnerable to attacks.

3.  Support as a Bluetooth HID joystick

3.1.  Requirements

At the time of writing, mainstream Linux distributions do not explicitly support the SIXAXIS in wireless mode. Hence, the following customizations are required.

  • linux-2.6.21 or later .  Earlier kernels do not support Bluetooth HID devices in "Report Protocol" mode.

  • patch-hidd-3.9-pabr3 or patch-hidd-3.19-pabr3 This patch causes the Linux Bluetooth HIDP daemon (hidd) to send a special command to the SIXAXIS when it connects. Sony already published a similar patch for enabling reporting in USB mode.

  • sixpair.c (Only required if the SIXAXIS is to be used with a non-PS3 Bluetooth master.) The SIXAXIS apparently does not support the standard Bluetooth pairing procedure; instead, pairing is done over USB, which is arguably simpler and more secure. This command-line utility searches USB buses for SIXAXIS controllers and tells them to connect to a new Bluetooth master.

Alternatively, it might be possible to support the Bluetooth HID "Report Protocol" on older kernels by using bthid instead of hidd, with a similar patch.

Besides, the new "input service" (bluetoothd-service-input), which replaces hidd in recent versions of bluez-utils, should support the SIXAXIS without any patch. However, since it does not accept connections from unknown Bluetooth devices, authorizations must be set-up by another utility, such as a udev plugin, as suggested in this discussion.

Note.  Bluetooth experts use the word "controller" to refer to the Bluetooth network adapter inside the host or the PS3, whereas everybody else thinks "game controller" (a.k.a. joystick). This sometimes causes confusion.


3.2.  Operation

  • Ensure /etc/bluetooth/hcid.conf contains:

    iscan disable;
    pscan enable;
    #auth enable;                                        
    #encrypt enable;                                     
    

  • Enable Bluetooth:

    # service bluetooth restart
    

  • If the host is not the PS3, pairing is required:

    • Connect the SIXAXIS with a USB cable.

    • Run sixpair:

      # wget http://www.pabr.org/sixlinux/sixpair.c
      # gcc -o sixpair sixpair.c -lusb
      # ./sixpair
      Current Bluetooth master: xx:xx:xx:xx:xx:xx
      Setting master bd_addr to xx:xx:xx:xx:xx:xx
      

    • Disconnect the USB cable.

  • Restart the HIDP daemon with suitable options:

    # service hidd stop
    # hidd --server --nocheck -n
    

    (Note: --nocheck is only required for the first connection.)

  • Optionally run hcidump in another shell, for troubleshooting and comparison with this successful trace:

    # hcidump -t -V -x
    

  • Press the PS button on the SIXAXIS.

  • hidd should report:

    # hidd --server --nocheck -n
    hidd[8332]: Bluetooth HID daemon
    hidd[8332]: New HID device 00:19:C1:xx:xx:xx (Sony Computer Entertainment Wireless Controller)
    

  • /var/log/messages should report:

    input: Sony Computer Entertainment Wireless Controller as /class/input/inputX
    

  • Check that the SIXAXIS is recognized as a joystick:

    # modprobe joydev
    # jstest /dev/js0      # or jstest /dev/input/js0
    

    jstest should report buttons being pressed and sticks being moved.

  • After testing, restore the security settings in /etc/bluetooth/hcid.conf:

    auth enable;                                        
    encrypt enable;                                     
    

    and apply them with:

    # service bluetooth restart
    

4.  Using inertial sensors with the hidraw interface

The Linux joystick interface (joydev.ko, /dev/input/js*) does not report inertial measurements from the accelerometers and gyro.

For research purposes, the quick-and-dirty way to access all features of the device is with raw L2CAP Bluetooth sockets (see [LINMCTOOL]).

For better integration with the operating system, the hidraw interface should be used instead, as explained in this section. It transfers raw HID input reports to user-space and works identically in USB mode and in Bluetooth mode.

4.1.  Requirements

4.2.  Operation

  • Connect the device with a USB cable and press PS. dmesg should report:

    input,hidraw1: USB HID v1.11 Joystick [Sony PLAYSTATION(R)3 Controller] on usb-xxxx:xx:xx.x-x
    

    and /dev/hidraw1 (or another minor number) should be created automatically.

  • In Bluetooth mode, a /dev/hidrawX device is created as well, but dmesg does not report its minor number.

  • Raw input reports can be read from /dev/hidraw1:

    # hexdump -v -e '48/1 "%02x " "\n"' < /dev/hidraw1   # For kernels <  2.6.26
    # hexdump -v -e '49/1 "%02x " "\n"' < /dev/hidraw1   # For kernels >= 2.6.26
    00 00 00 00 00 74 7b 7c 7c 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  \
    00 00 00 00 02 ee 10 00 00 00 00 02 b2 77 01 81 02 05 01 ed 01 a4 00 02
    

  • sixhidtest.c decodes inertial measurements:

    # wget http://www.pabr.org/sixlinux/sixhidtest.c
    # gcc -o sixhidtest sixhidtest.c
    # ./sixhidtest < /dev/hidraw1
    ax= 517 ay= 493 az= 420
    

  • xsixhidtest.c graphically displays speed, position and orientation derived from accelerometer measurements. High-pass filtering is used to control integration drift; this works well for fast periodic signals, e.g. circular motion. In this simple example, no attempt is made to track simultaneous translations and rotations, nor rotations around the vertical axis.

    # wget http://www.pabr.org/sixlinux/xsixhidtest.c
    # gcc -o xsixhidtest xsixhidtest.c -lX11 -lm
    # ./xsixhidtest < /dev/hidraw1
    

5.  Known issues

  • On some kernels, at least from 2.6.32 to 2.6.33.3, /dev/hidrawX returns 50 bytes instead of 49. This is fixed in 2.6.34.

  • If sixhidtest says "Unsupported report length", either upgrade the kernel to 2.6.26 or later, or use sixhidtest-20080426.c and xsixhidtest-20080426.c.

  • A 2.0 Bluetooth adapter is recommended. Otherwise, incoming input reports may be truncated to 12 bytes.

  • On some PS3 hosts, hcidump shows "Role Change" "Role: Master" and dmesg reports "hci_acldata_packet: hci0 ACL packet for unknown connection handle". Upgrading to linux-2.6.23 or later should solve this problem.

  • Maybe the Linux HID joystick driver should decode inertial measurements as joystick axes. Use [USBHID] and [HIDP] for troubleshooting.

  • The Bluetooth adapter in the PS3 supports remote wake-up. This has not been tested with Linux.

  • Bluetooth authentication and encryption have not been investigated. This probably requires a key exchange procedure over USB.

  • The LEDs are not supported. /dev/js0 should have the first LED turned on, and so on.

  • Hand-over between USB mode and Bluetooth mode is not transparent for applications.

  • Monitoring of battery status has not been tested.

  • Related PlayStation controllers also require pairing over USB, but the protocols are slightly different. Some of them are supported by [LINMCTOOL].


6.  About the demo videos

The six-degrees-of-freedom mechanical arrangement in the first video is known as a "parallel manipulator" or "parallel kinematic chains". The six R/C servos are connected to a Gumstix board with built-in Bluetooth module. Inertial measurements from the SIXAXIS are received directly through a PF_BLUETOOTH socket (not through the joystick API, due to HID descriptor issues). Heuristics explicitly discriminate between two types of motion (rotation or translation).

In the second video, the on-board Linux computer translates HID reports from the SIXAXIS into a PPM signal which is injected into the helicopter's control board (see [CHROMICRO]). "Stick mode" emulates a mode 2 RC helicopter transmitter, with throttle mapped to L2. In "tilt sensor mode", cyclic pitch is controlled by two accelerometers rather than by the right stick.

7.  Acknowledgements

Jim Paris and Samson Yeung contributed help and protocol traces which were invaluable in understanding how the SIXAXIS operates.

Thanks to Sony for allowing Linux to run on the PS3 (albeit in a hypervisor sandbox). Most other gaming systems are not as open.

Bibliography

[CHROMICRO] ChRoMicro - Cheap Robotic Microhelicopter HOWTO (EN) . http://www.pabr.org/chromicro/doc/chromicro.en.html .

[LINMCTOOL] linmctool - Linux motion-sensing controller tool . http://www.pabr.org/linmctool/linmctool.en.html .

[USBHID] Universal Serial Bus. Device Class Definition for Human Interface Devices (HID). http://www.usb.org/developers/devclass_docs/HID1_11.pdf.

[HIDP] Bluetooth Specification. Human Interface Device (HID) Profile. http://www.bluetooth.com/Specification%20Documents/HID_SPEC_V10.pdf.