Before we begin, be sure you've got the latest version of Raspberry Pi OS installed on your Pi. Visit our guide on how to update Raspberry Pi OS for details on this process.
Xpad drivers are included with the latest version of Raspberry Pi OS—so this step is technically optional. We still recommend installing it in case you come across an application built around the old xboxdrv driver.
Run the following command to install it:
sudo apt-get install xboxdrv
Wireless Xbox controllers use a USB wireless adapter. Connect the USB adapter to the Raspberry Pi. It should recognize and respond to the input as a normal USB controller.
If you're using a wired USB controller, plug the controller into a USB port on the Raspberry Pi. The Pi should detect the controller as a usable device.
To connect an Xbox controller using Bluetooth, you'll need a terminal window. Open one on Raspberry Pi OS or remote into the Pi using a terminal application of your choice.
1. Disable Enhanced Re-Transmission Mode (ERTM)
If ERTM is enabled, the controller won't pair with the Pi. To disable the ERTM, run the following command:
Restart the Pi.
echo 'options bluetooth disable_ertm=Y' | sudo tee -a /etc/modprobe.d/bluetooth.conf
2. Start Bluetooth Tools
After the Pi reboots, start Bluetooth Tools with the following command:
3. Search for the Xbox controller
Now we need to search for the Xbox controller. Don't put the controller into pairing mode just yet. We have a few settings to adjust first. Enable agent with the following commands:
Next, we'll start scanning for available Bluetooth devices. Run this command to start scanning:
agent on default-agent
4. Connect to the Xbox controller
Put the Xbox controller into Pairing mode. It should appear in the list of devices with a unique MAC address and the words "wireless controller" at the end. Take note of the MAC address, we'll need it to connect the controller.
In the terminal window, enter the following command, replacing
MAC_ADDRESS with the Xbox controller MAC address.
After connecting the controller, make sure it's listed as a trusted device with this command—again replacing
MAC_ADDRESSwith the one for the Xbox.
Close the bluetoothctl application by typing
5. Test the connection
We'll use the joystick toolset to make sure everything is working. Install it with this command:
When it finishes installing, run this command to start the test:
sudo apt-get install joystick
You will see a screen of numbers. If everything is working properly, pressing buttons on the controller will cause them to change.
sudo jstest /dev/input/js0
Now that your controller is connected, you may want to use it in place of a mouse. Run the following command in a terminal window to enable this feature:
sudo xboxdrv --detach-kernel-driver --silent --mouse
If you need a specific mouse button, check the chart below for a corresponding button on the Xbox controller. It also includes a few keyboard functions.
|Function||Xbox Controller Button|
|Move Cursor||Left Joystick|
|Scroll Wheel||Right Joystick|