Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Clone this wiki locally
PS3 Dualshock 3 Controller
The PS3 Controller like most game controllers have bulk inputs, analog joysticks, triggers and buttons. The unique thing about PS3 controllers is that almost all the buttons can be read either as analog values or digital, directly from the controller. Another feature is the ability to communicate via both USB and Bluetooth.
This library implements a PS3 controller functionality via a Bluetooth dongle or via USB using the USB Host Shield from Circuitsathome.
Table of Contents
The PS3 controller uses both bluetooth and USB for communication. To communicate over USB you simply plug in the cable tell the controller to send you data and away you go. If you want to change the LED's or make it rumble you just send the controller a command and it happens. For bluetooth communication you need to first get the bluetooth address of your adapter then over USB connection set this in the PS3 controller. Then once you press the PS button the controller searches for that address adapter and communication can begin. The controller also has a 3 axis accelerometer and a single axis gyro which can all be read.
The datastream sent by the PS3 Controller and some explanation can be found at the following link.
For information about the PS3 Controller USB communication protocol see the following links:http://blog.tkjelectronics.dk/2011/06/guide-gyro-and-accelerometer-kalman-filtering-with-the-arduino/
And here is the link for the datasheet for the Kionix KXPA4, which is equivalent to KXPC4, which is inside the DualShock 3 controller.
For information about the HID protocol, see the following link page 48. See under "Get_Report Request" and " Set_Report Request" which are the commands used for the PS3 controller. For further details see this link under "9.3 USB Device Requests".
The HCI ACL Data Packet has the following structure:
The bluetooth communication works in these steps:
1. First you have to set up the Bluetooth dongle using the HCI protocol.
2. Then you wait for the incoming request from the PS3 Controller.
3. When the request arrives, you accept, and change the role, so the Arduino, becomes the master of the connection.
4. Then you listen on the Bulkin endpoint. The controller will then send a L2CAP connection request, for the HCI Control channel (PSM: 0x11).
5. You respond by sending an connection response. First with the result: pending, and then with the result success.
6. Then you have to send a configuration request. The controller will then respond with a configuration request as well.
7. You then respond, and the controller will then respond, that the channel have been successfully established.
8. The program then repeats the steps from 4-7, but this time it sets up the HID Interrupt (PSM: 0x13) channel.
9. Just like for USB connection, the host has to sent a special command to make the Dualshock 3 and Navigation controller sent buttons reports ect. back. It is a little different for bluetooth. This time you have to send a Set Feature Report (0x53) with a report ID (0xF4) and the following data: 0x42, 0x03, 0x00, 0x00.
See this patch made for linux for more information.
10. Then just listen on the bulkin endpoint, and you will see the bytes changing, when you push a button, use the joysticks etc.
For information about the Bluetooth Protocol. See this pdf: https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=229737
Take a good look at the categories: "HCI COMMANDS AND EVENTS" Volume 2 p. 458, "HCI ACL Data Packets" Volume 2 p.428 and "SIGNALING PACKET FORMATS" Volume 3 p. 54.
See this pdf, for standard BT HID Commands, used by the program, at "Bluetooth HID L2CAP Protocol Specification" p. 50.
I used this program to sniff the Bluetooth Commands sent from my mac: PacketLogger.app. It is developed by apple, so it is mac only! If you are on a mac, this is what the program decoded: PS3Controller_Protocol.pklg
The Protocol and Service Multiplexor (PSM) used by the L2CAP Protocol (HID_Control and HID_Interrupt), are defined here: http://www.bluetooth.org/Technical/AssignedNumbers/logical_link.htm.
You will need the following hardware for it to work:
A Bluetooth a dongle which supports bluetooth version 2.0+EDR. A list of dongle that are confirmed to work can be found at this wiki page: https://github.com/felis/USB_Host_Shield_2.0/wiki/Bluetooth-dongles
An Arduino board - tested with Arduino Duemilanove, Arduino Uno, Arduino Leonardo, Arduino Mega, and Mega ADK.
And of couse a Playstation controller.
This unoriginal controller is confirmed to work too:
In order to use your Playstation controller you have to set the Bluetooth address of the dongle internally to your PS3 Controller. This can be achieved by plugging the controller in via USB and letting the library set it automatically.
NB: To obtain the address you have to plug in the bluetooth dongle before connecting the controller, or alternatively you could set it in code like so: https://github.com/felis/USB_Host_Shield_2.0/blob/master/examples/Bluetooth/PS3BT/PS3BT.ino#L22
If you are using the USB Host Shield from Sparkfun, you might have to connect an external powersupply to set the bluetooth address to the controller.
The Navigation and Motion controller The two additional controllers are also supported.
The Navigation controller, works identically to the original Dualshock 3 controller, but it doesn't feature rumble, LED's, accelerometer and gyro functionality. The great thing about it though is due to it's small formfactor, it can be used with one hand, which makes it ideal for a remote control for a robot.
The Motion controller works a bit different than the Navigation and the Dualshock 3 controller, as it doesn't need a special command before it's starts sending data to the host, but unfortunately one can not read the buttons via USB, only via bluetooth. Another difference, is that all the commands to the controller are sent via the HID Interrupt channel, and not the HID Control channel as the Dualshock 3 and Navigation controller. It also use a DATA output request instead of a set output report request. For more information, see the source code.
The Bluetooth protocol can been seen in this log: PS3Move.pklg.
A great thing about the Motion controller is that it features a 3-axis accelerometer, 3-axis gyro, 3-axis magnetomer, a thermometer, and the shinny bulb on the top of course.
For more information visit these sites:
Here is a video of my balancing robot which uses the library for remote control:
The code used in the video: http://blog.tkjelectronics.dk/wp-content/uploads/PS3BluetoothNXT.zip
Demonstration of the three controllers
The code used in the video: http://wiki.tinyclr.com/images/4/4e/PS3BluetoothNXTVersion2.zip