Setting up Xbox Controllers on the Raspberry Pi

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.

Equipment List

Below are all the bits and pieces that I used for this setting up Xbox controllers tutorial.

Optional

Raspberry Pi Case

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.

Bluetooth

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.

USB Cable

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 update
sudo apt 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 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.

sudo reboot

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.

sudo bluetoothctl

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.

scan on

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

connect YOUR_MAC_ADDRESS

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.

trust YOUR_MAC_ADDRESS

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.

7 Comments

Segio on February 14, 2021 at 7:27 am

For anyone having issues with connecting your controller to the pi. If you already know your mac address for the controller, try removing it using the command “remove [MAC-ADDRESS]. Once you have removed it, rescan and try to connect again. Encountered a weird issue with not being able to connect, and this fixed it.

Timg3000 on May 16, 2019 at 9:59 am

Error: No Xbox or Xbox360 controller found

no idea what the issue is.

1. Gus on June 6, 2019 at 10:02 pm
  
  Editor
  
  Hi Timg3000,
  
  We published a fix to the tutorial. Hopefully this will resolve your issue.
Thomas on May 5, 2019 at 6:31 am

Thanks, my xbox-controller-robot is moving 🙂

Joshua Pearlmutter on April 21, 2019 at 2:08 pm

The method for disabling ERTM does not work on the latest version of Raspbian Stretch, but this method works instead:

1. Make a new file using nano

sudo nano /etc/modprobe.d/bluetooth.conf

2. Add this single line:

options bluetooth disable_ertm=Y

Reboot and then pair your Xbox One controller.

1. Emmet on April 21, 2019 at 3:23 pm
  
  Editor
  
  Hi Josh,
  
  Thank you for pointing that out, we will update the tutorial with this method shortly.
  
  Thank you for your contribution!
  
  Cheers,
  Emmet
2. Dick Cumson on June 1, 2019 at 7:01 am
  
  This worked for me
  
  I’ll add though that I had trouble at first when I was trying to pair a controller that I had already attempted to pair before disabling the ERTM. It would pair for a moment, then fail and unpair.
  
  After it didn’t work, I tried with a new controller, and it worked fine.
  
  Then, I used the “remove” command in the MAC of the first controller, and tried again, and it worked.
  
  Hope this helps in case someone else runs into this problem