####################################
##FILL ME IN
####################################
## links to any required tutorials
## note.0= [[ROS/Tutorials| ROS tutorials]]
## descriptive title for the tutorial
## title = How to Pair the PS3 Joystick with a Bluetooth Dongle
## multi-line description to be displayed in search 
## description = This tutorial is an introduction to using the PS3 !DualShock 3 Joystick connected via bluetooth to a desktop computer. After reading it, you should be able to bring up the ps3joy node and  display the data coming from the joystick.
## the next tutorial description 
## next =
## links to next tutorial
## next.0.link= [[ps3joy/Tutorials/WritingTeleopNode|Writing a teleop node]]
## next.1.link=
## what level user is this tutorial for
## level= BeginnerCategory
## keywords = PS3, joystick, driver
####################################

<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

<<TOC(4)>>

= Compiling =
Start by installing the dependencies and compiling the driver:

{{{
$ rosdep install ps3joy
$ rosmake ps3joy
}}}
= Pairing =

If this joystick has already been paired to this dongle you can skip this section and go directly to "Connecting to the Joystick Via Bluetooth". This will usually be the case when you are working on the PR2.

== For Computers with More than One USB Port ==
Plug the USB bluetooth dongle into your computer. Then, plug the PS3 bluetooth joystick into the computer using a USB cable.

Load the bluetooth dongle's MAC address into the PS3 joystick using:

{{{
$ sudo bash
$ rosrun ps3joy sixpair
}}}
You will see something similar to:

 . {{{
Current Bluetooth master: 00:22:b0:d0:5a:09
Setting master bd_addr to 00:22:b0:d0:5a:09
}}}

Press `Ctrl-D` now so that you do not continue to run as root.

If you get something like the following:

  . {{{
Current Bluetooth master: 00:1b:dc:00:07:3c
Unable to retrieve local bd_addr from `hcitool dev`.
Please enable Bluetooth or specify an address manually.
}}}

Run the command:

{{{
$ hciconfig hci0 reset
}}} 

and then retry:

{{{
$ rosrun ps3joy sixpair
}}}

== For Computers with One USB Port ==
Plug the USB bluetooth dongle into the computer and read the MAC address from the dongle:

{{{
$ sudo hciconfig hci0 up
$ hciconfig
}}}
You will see something like this:

 . {{{
hci0:   Type: USB
        BD Address: 00:22:B0:D0:5A:09 ACL MTU: 384:8 SCO MTU: 64:8
        UP RUNNING PSCAN
        RX bytes:1013623 acl:17474 sco:0 events:35 errors:0
        TX bytes:247 acl:10 sco:0 commands:16 errors:0
}}}

(In the above example, the MAC address is: 00:22:B0:D0:5A:09)

Now unplug the bluetooth dongle and  plug the PS3 joystick into the computer using a USB cable. Replace the joystick's MAC address using the following command:

{{{
$ sudo bash
$ rosrun ps3joy sixpair [MAC address]
}}}
You will see something like this:

 . {{{
$ rosrun ps3joy sixpair 00:22:B0:D0:5A:09
Current Bluetooth master: 00:22:b0:d0:5a:09
Setting master bd_addr to 00:22:b0:d0:5a:09
}}}

Press `Ctrl-D` now so that you do not continue to run as root.

= Connecting to the Joystick Via Bluetooth =
Unplug the joystick from the computer and make sure that the USB bluetooth dongle is plugged in. Now, start the program to create the connection between the bluetooth dongle and the joystick:

{{{
$ sudo bash
$ rosrun ps3joy ps3joy.py
}}}
You will see:

 . {{{
Waiting for connection. Disconnect your PS3 joystick from USB and press the pairing button.
}}}

Press the PS button in the middle of the joystick and the connection will be activated.

 . {{attachment:pairing.png}}

You will see:

 . {{{
Connection is Activated.
}}}

If you do not see the above message and you are running Karmic or Lucid versions of Ubuntu you may need to follow these [[ps3joy/KarmicInstructions|instructions]].

= Confirming Joystick Input =
In a '''new terminal''', confirm that the joystick is sending data to your computer. You can test this with jstest:

{{{
$ sudo jstest /dev/input/js?
}}}
(if this does not work, try replacing ? with the number of your joystick --try tab completing, i.e. /dev/input/js0 )

You will see output that looks like this and changes as you press buttons and move the joysticks:

 . {{{
Axes:  0:     2  1:    -2  2:    -2  3:    -2  4:     0  5:     0  6:     0  7:     0  8:     0  9:     0 10:     0 11:     0 12:     0 13:     0 14:     0 15:     0 16:     7 17:   -27 18:  -112 19:   -29 Buttons:  0:off  1:off  2:off  3:off  4:off  5:off  6:off  7:off  8:off  9:off 10:off 11:off 12:off 13:off 14:off
Axes:  0:     2  1:    -2  2:    -2  3:    -2  4:     0  5:     0  6:     0  7:     0  8:     0  9:     0 10:     0 11:     0 12:     0 13:     0 14:     0 15:     0 16:     6 17:   -27 18:  -112 19:   -29 Buttons:  0:off  1:off  2:off  3:off  4:off  5:off  6:off  7:off  8:off  9:off 10:off 11:off 12:off 13:off 14:off
Axes:  0:     2  1:    -2  2:    -2  3:    -2  4:     0  5:     0  6:     0  7:     0  8:     0  9:     0 10:     0 11:     0 12:     0 13:     0 14:     0 15:     0 16:     6 17:   -27 18:  -112 19:   -30 Buttons:  0:off  1:off  2:off  3:off  4:off  5:off  6:off  7:off  8:off  9:off 10:off 11:off 12:off 13:off 14:off 15:off 16:off
}}}

= Unpairing the Joystick =

If you ever need to unpair the joystick, you can simply press the pairing button for 10 seconds. The lights on the joystick should stop blinking.

----
## TutorialCategory
## JoyStickDriverCategory