If you have ever tried to use an Xbox controller with the Raspberry Pi, you will find very quickly that they do not work correctly right out of the box. In fact to get them working you will be required to install a special driver.
With the newer Xbox One controllers that feature the Bluetooth functionality, you will also find that they will need extra work on top of the driver installation to get them to run. Namely, they are not properly supported by some of the Bluetooth functionality that is switched on by default.
This guide will show you how to get your Xbox Controllers up and running on the Raspberry Pi while also walking you through how to get the newer Bluetooth enabled controllers to pair successfully on the Pi.
Be sure to check out our guide on setting up Bluetooth on the Raspberry Pi if you require more info regarding Bluetooth.
Below are all the bits and pieces that I used for this setting up Xbox controllers tutorial.
Raspberry Pi 2, 3, or 4
Bluetooth Adapter (Only if not using a Pi 3 or Zero W)
Methods to set up an Xbox Controller
There are three different ways you can connect your Xbox One and Xbox 360 controllers to the Raspberry Pi. The two easiest ways of connecting your controllers are via USB cable or using the official wireless adapters.
Xbox Controller USB Wireless Adapter
The Xbox USB Wireless adapter is one of the easiest ways to connect your controllers while retaining their wireless functionality. This option is also required if you want to use the wireless Xbox 360 controllers or utilize the generation one Xbox One controller wirelessly.
Please note that Xbox 360 controllers and Xbox One controllers use different USB adapters.
Using Bluetooth is only a viable option for the newer Xbox One controllers that were introduced when the Xbox One S was released. Using Bluetooth requires a few different steps to get working correctly.
If you would like to know how to connect your Xbox One Bluetooth controller to your Raspberry Pi, then proceed down to the next section.
A USB Cable is the easiest way to setup any Xbox One controllers. However, if you use a 360 controller you will only be able to use the wired ones this way since the port available on that controller is purely for charging.
Just plug a Micro USB cable into the Xbox One controller and the USB-A end into the Raspberry Pi. and you should be ready to go.
Setting up the Raspberry Pi for Xbox Controllers
1. Before we get started with anything in this tutorial, we should make sure our Raspberry Pi is entirely up to date by running the following two commands within the terminal. These commands will make sure we have the latest available software.
sudo apt-get update sudo apt-get upgrade
2. While we don’t necessarily need to install xboxdrv anymore since the Xpad driver is now included in Raspbian’s kernel, we will install it for any programs that might be built to utilize xboxdrv. It also allows us to do a few things within the user space by using xboxdrv.
A userland driver means that it works just like an application and is not built into the core system.
To install the userland driver that allows us to interact with the Xbox One and Xbox 360 controllers type the following command into the terminal on your Raspberry Pi.
sudo apt-get install xboxdrv
Pairing Bluetooth Xbox Controllers to the Raspberry Pi
1. Before you try to pair your Bluetooth Xbox Controller with the Raspberry Pi ensure you have installed the appropriate driver like mentioned in our previous section.
Once you have that installed the driver, we can then proceed with the process of getting the controller to pair. Begin by running the following command on your Raspberry Pi.
This command disables the Enhanced Re-Transmission Mode (ERTM) of the Bluetooth module, with it, enabled the Xbox Controller won’t pair correctly.
echo 'options bluetooth disable_ertm=Y' | sudo tee -a /etc/modprobe.d/bluetooth.conf
2. Now before this change takes effect, we are required to restart the Raspberry Pi. Run the following command on your Raspberry Pi to restart it.
3. With the Raspberry Pi now booted we can proceed with pairing our Bluetooth Xbox One Controller with the Raspberry Pi.
To be able to pair our Xbox One controller we will need to start up the Bluetooth tools by running the following command on our Raspberry Pi.
4. Within the Bluetooth tool, we can now run a few different commands that will allow us to find and pair our Bluetooth Xbox One controller. We begin by switching the agent on by typing in the following two lines.
agent on default-agent
5. With that done we can now begin a scan for devices, simply type in the following command to start the scanning process.
Once the scanning process has begun, you should begin to see any Bluetooth device that is discoverable pop-up within the terminal.
6. When you press the sync button located on the front of your Xbox One Controller you should see a new entry appear on your Raspberry Pi’s command line, such as below.
Take note of the MAC address of your controller. The MAC Address is the hexadecimal number that is separated by colons “:”.
[NEW] Device B8:27:EB:A4:59:08 Wireless Controller
7. With the MAC Address of your Bluetooth Xbox One Controller, we can now make a connection with it by using the Raspberry Pi’s Bluetooth stack.
Just type in the following command, making sure that you replace “YOUR_MAC_ADDRESS” with the one that appeared when you started the syncing process on your controller in step 6. In our case, this was B8:27:EB:A4:59:08
8. Now once you have had a successful connection with the controller, you should see something like below appear in your command line on the Raspberry Pi.
Attempting to connect to B8:27:EB:A4:59:08 [CHG] Device B8:27:EB:A4:59:08 Modalias: usb:v054Cp0268d0100 [CHG] Device B8:27:EB:A4:59:08 UUIDs: 00001124-0000-1000-8000-00805f9b34fb 00001200-0000-1000-8000-00805f9b34fb
9. Once we have made a successful connection with the Xbox One controller, we need to add it to our trusted devices list. Doing this will allow the Xbox One controller to reconnect to the Bluetooth on our Raspberry Pi automatically.
To do this, we need to run the following command on our Raspberry Pi. Make sure that you replace “YOUR_MAC_ADDRESS” with the same MAC Address that you used to connect to the device in step 8.
10. Now that you have paired your Bluetooth Xbox One Controller you can quit out of the bluetoothctl software by either typing in “quit” or pressing Ctrl + D.
11. Lets now install the joystick toolset. This toolset will allow us to check to see whether our Xbox One controller is working correctly. Run the following command on your Raspberry Pi to install it.
sudo apt-get install joystick
12. With the joystick toolset now installed to our Raspberry Pi, we can proceed to test whether our controller is working correctly. Run the following command to test the joystick set to js0.
sudo jstest /dev/input/js0
You should see a screen with a bunch of numbers, moving and pressing buttons should change the text on the screen. If anything changes then your controller should be fully set up and ready to go.
Controlling your Raspberry Pi with an Xbox controller
If you want to control your Raspberry Pi by using an Xbox Controller, you can just use the following command in terminal. This command allows the Xbox Controller to interact with the computer and will enable it to imitate the mouse.
sudo xboxdrv --detach-kernel-driver --silent --mouse
Once you have run that command, you should now be able to control your mouse on your Raspberry Pi with your Xbox controller. The following buttons are bound to specific mouse actions.
- A: Left click
- B: Right-click
- X: Middle mouse click
- Y: Enter
- Left Joystick: Mouse movement
- Right Joystick: Scroll wheel
- D-Pad: Arrow keys
- Start: Forward
- Back: Back
- LB: Page up
- RB: Page down
Hopefully, by the end of this guide, you have now got your Raspberry Pi up and running with your Xbox controllers successfully connecting to it.
Having this controller working will come in handy when it comes to gaming on the Raspberry Pi.
If you have any feedback or need assistance with this tutorial feel free to drop a comment below.