- Hardware Support
- Supported Distributions
- API Stability
- Getting Started
- ROS API
- Command-Line Options
- Specifics for ps3joy_node
- PS3 Joystick Buttons and Axes
This package provides a driver for the PS3 (SIXAXIS or DUALSHOCK3) bluetooth joystick. This joystick is currently used with the PR2 robot.
This driver exists because Linux's native support for the PS3 joystick is unreliable, and does not give access to the joystick's accelerometers and gyroscope. This driver solves both problems. However in its current form, this driver will not coexist with any other bluetooth device. In future releases, we plan to allow first non-HID and later any bluetooth device to coexist with this driver. If you have a need for such functionality, let it be known.
It has been observed that coexistence is possible, at least in the two following cases:
- Non-HID devices using a userland driver, such as one written using pybluez.
- Keyboards or mice running in HID proxy mode, which appear to the kernel as USB devices.
This driver may only work with Bluetooth 2.0 adapters.
In our experience, the driver works with most 2.x Bluetooth adapters. Please report other incompatible Bluetooth adapters to the issue tracker (you can find the link in the beginning of the page).
Adapters that are known not to work:
- Linksys USBBT100 version 2 (Bluetooth 1.1).
- USB device 0a12:0x0001
ps3joy.py is known to work with Ubuntu 12.10, Ubuntu 12.04, Ubuntu Jaunty 9.04, and Ubuntu Hardy 8.04. To make it work with Ubuntu Karmic 9.10, you will have to follow these instructions.
Sixpair runs on all platforms that have been tested.
We do not anticipate any incompatible changes to the API of this package. With maturing support for the PS3 joystick in BlueZ and the Linux kernel, we hope that most people will no longer need this package unless they want to use the gyroscope and accelerometer axes.
The How to Pair the PS3 Joystick with a Bluetooth Dongle is a good starting point for how to use this package.
Install from source (see repo link above) or from repository:
sudo apt-get install ros-%ROSDISTRO%-joystick-drivers sudo apt-get install ros-indigo-joystick-drivers (ROS Indigo for example)
New in ROS Electric
ps3joy.pyJoystick driver for the PS3 Joystick. Plain Python without any ROS-references, needed to be easily started with sudo, which is the easiest way to grant it permissions to access bluetooth hardware.
New in ROS Fuerte
ps3joy_node.pyJoystick driver for the PS3 Joystick, which is also a ROS node to publish diagnostics and receive controller feedback messages.
Subscribed Topicsjoy/set_feedback (sensor_msgs/JoyFeedbackArray)
- Set the rumble and leds of the joystick. The PS3 has 4 leds (ids:0-3) and two rumblers (ids:0-1). The high frequency rumbler is id 1 and the low frequency rumbler is id 0.
Published Topics/diagnostics (diagnostic_msgs/DiagnosticArray)
- Publishes the battery status, charging status, connection.
This is the same for ps3joy.py and ps3joy_node.py.
$ ./ps3joy.py --help usage: ps3joy.py [--inactivity-timeout=<n>] [--no-disable-bluetoothd] [--redirect-output]=<f> <n>: inactivity timeout in seconds (saves battery life). <f>: file name to redirect output to. Unless --no-disable-bluetoothd is specified, bluetoothd will be stopped.
- Turn off the joystick after a certain period of inactivity. This is useful to save batteries and reduce contention on the 2.4 GHz network.
Tells ps3joy.py not to take down bluetoothd. For this option to work, bluetoothd must be configured not handle input devices, otherwise you will get an "Error binding to socket" error message. (New in 1.1.1 and 1.0.3)
Allows the standard output and error to be redirected to a file. This is useful when ps3joy.py is run in the background. (New in 1.1.1 and 1.0.3)
--continuous-output New in 1.8.1
- Output continuous motion sensor streams, and as a side effect of continuous output, no longer leaves long periods of no messages on the /joy topic.
Specifics for ps3joy_node
Launching with permissions
Starting the ROS node variant of ps3joy is somewhat tricky. It needs higher permissions to access bluetooth hardware, which can be achieved via sudo, but running ROS code as sudo is neither recommended nor trivial. Here is what you can do:
.../ps3joy$ sudo bash -c "source /home/myself/.bashrc; ./scripts/ps3joy_node.py --inactivity-timeout=300"
Or you could write a sudo script for sourcing ROS and starting ps3joy_node; I use ps3joy_node_starter.sh to automatically start the ps3joy_node after booting and a ROS-check.
Sending feedback to the controller
To set the led or rumble from the command line:
rostopic pub /joy/set_feedback sensor_msgs/JoyFeedbackArray '[ [0, 3, 1], [1, 1, 0.8] ]'
There is real world code sending feedback.
PS3 Joystick Buttons and Axes
Buttons 4-15 are reported as axes as well as buttons. The axis corresponding to a button can be used to determine how hard the user is pressing on the button, ranging from 0 when there is no press, to -1 for a hard press. For these buttons, the axis number is the same as the button number.
ps3joy.py also exposes the joystick's three-axis accelerometer and the single-axis gyroscope:
Right-Left (positive is left)
Forward-Backward (positive is forward)
Up-Down (positive is up)
Yaw axis (positive is clockwise)
Button number macros for C++
With these #defines you can access the PS3 buttons within the sensor_msgs/Joy message published by the joy_node without worrying about magic numbers:
// note on plain values: // buttons are either 0 or 1 // button axes go from 0 to -1 // stick axes go from 0 to +/-1 #define PS3_BUTTON_SELECT 0 #define PS3_BUTTON_STICK_LEFT 1 #define PS3_BUTTON_STICK_RIGHT 2 #define PS3_BUTTON_START 3 #define PS3_BUTTON_CROSS_UP 4 #define PS3_BUTTON_CROSS_RIGHT 5 #define PS3_BUTTON_CROSS_DOWN 6 #define PS3_BUTTON_CROSS_LEFT 7 #define PS3_BUTTON_REAR_LEFT_2 8 #define PS3_BUTTON_REAR_RIGHT_2 9 #define PS3_BUTTON_REAR_LEFT_1 10 #define PS3_BUTTON_REAR_RIGHT_1 11 #define PS3_BUTTON_ACTION_TRIANGLE 12 #define PS3_BUTTON_ACTION_CIRCLE 13 #define PS3_BUTTON_ACTION_CROSS 14 #define PS3_BUTTON_ACTION_SQUARE 15 #define PS3_BUTTON_PAIRING 16 #define PS3_AXIS_STICK_LEFT_LEFTWARDS 0 #define PS3_AXIS_STICK_LEFT_UPWARDS 1 #define PS3_AXIS_STICK_RIGHT_LEFTWARDS 2 #define PS3_AXIS_STICK_RIGHT_UPWARDS 3 #define PS3_AXIS_BUTTON_CROSS_UP 4 #define PS3_AXIS_BUTTON_CROSS_RIGHT 5 #define PS3_AXIS_BUTTON_CROSS_DOWN 6 #define PS3_AXIS_BUTTON_CROSS_LEFT 7 #define PS3_AXIS_BUTTON_REAR_LEFT_2 8 #define PS3_AXIS_BUTTON_REAR_RIGHT_2 9 #define PS3_AXIS_BUTTON_REAR_LEFT_1 10 #define PS3_AXIS_BUTTON_REAR_RIGHT_1 11 #define PS3_AXIS_BUTTON_ACTION_TRIANGLE 12 #define PS3_AXIS_BUTTON_ACTION_CIRCLE 13 #define PS3_AXIS_BUTTON_ACTION_CROSS 14 #define PS3_AXIS_BUTTON_ACTION_SQUARE 15 #define PS3_AXIS_ACCELEROMETER_LEFT 16 #define PS3_AXIS_ACCELEROMETER_FORWARD 17 #define PS3_AXIS_ACCELEROMETER_UP 18 #define PS3_AXIS_GYRO_YAW 19