Joystick Controller Pairing

Joystick controllers are used for teleoperation; they allow you to remotely drive the robot, whether it is a physical robot, or a simulated robot. The following instructions below detail how to pair different controllers to the robot's computer; however, these instructions can also be used to pair these controllers to your own computer.

note

If your robot comes with a controller (either PS4 or PS5), it will be paired already. Simply turn on the robot and turn on the controller.

PS4 Controller

To re-pair the PS4 controller or pair a new PS4 controller:

1. Install the python3-ds4drv package if it is not installed already. In terminal, run:

sudo apt install python3-ds4drv

2. Put the controller in pairing mode. Press and hold the PS and Share buttons on your controller until the LED begins rapidly flashing white.
3. Run the ds4drv-pair script to pair the controller to the computer. In terminal, run:

sudo ds4drv-pair

This script will scan for nearby Bluetooth devices, and pair automatically to the controller.

Alternatively, if ds4drv-pair fails to detect the controller, you can pair the controller using bluetoothctl:

1. Install the bluez package if it is not installed already. In terminal, run:

sudo apt install bluez

2. Run the bluetoothctl command. In terminal, run:

sudo bluetoothctl

3. Use bluetoothctl to scan for nearby devices. In the Bluetooth control application, run:

agent on
scan on

4. Put the controller in pairing mode. Press and hold the PS and Share buttons on your controller until the LED begins rapidly flashing white.
5. The Bluetooth scan will display the MAC addresses of nearby devices. Determine which MAC address corresponds to the controller and copy it. In the Bluetooth control application, run:

scan off
pair <MAC Address>
trust <MAC Address>
connect <MAC Address>

The controller should now be paired.

PS5 Controller

The PS5 (DualSense) controller does not require ds4drv; it is supported directly through the Linux kernel. To re-pair the PS5 controller or pair a new PS5 controller:

1. Put the controller in pairing mode. Press and hold the PS and Create buttons on your controller until the light bar begins rapidly flashing blue.
2. Run the pair_bt_controller script. In terminal, run:

ros2 run clearpath_bt_joy pair_bt_controller

The script will automatically scan for a nearby DualSense that is in pairing mode, then trust, pair, and connect it. Previously paired controllers that are not in pairing mode are ignored. If the controller being paired was paired to this computer before, its old pairing is removed first so a fresh pairing is created. Once paired, the controller will reconnect automatically on every subsequent power-on.

Optionally, if you already know the controller's Bluetooth MAC address, you can skip scanning and pass it directly:

ros2 run clearpath_bt_joy pair_bt_controller <MAC Address>

note

If pair_bt_controller fails, you can pair manually using bluetoothctl:

1. Install the bluez package if it is not installed already. In terminal, run:

sudo apt install bluez

2. Run the bluetoothctl command. In terminal, run:

bluetoothctl

3. Use bluetoothctl to scan for nearby devices. In the Bluetooth control application, run:

agent on
default-agent
scan on

4. Put the controller in pairing mode. Press and hold the PS and Create buttons on your controller until the light bar begins rapidly flashing blue.
5. The Bluetooth scan will display the MAC addresses of nearby devices. Determine which MAC address corresponds to the controller and copy it. If the controller was paired to this computer before, first run remove <MAC Address> and wait for it to reappear in the scan. Then, in the Bluetooth control application, run:

scan off
trust <MAC Address>
pair <MAC Address>
connect <MAC Address>

Wait for each command to report success before entering the next one.

The controller should now be paired.

note

Make sure to set the correct controller type in your robot.yaml file. See Joystick Controller setup in the Clearpath Configuration.