Raspberry Pi‘s are amazing devices. A lot of people turn them into gaming devices by running Retropie and even building arcade machines from them. So it only makes sense that some of us would want to connect an Xbox One controller to the Raspberry Pi!  However, using Xbox One controllers on a Raspberry Pi is a little more difficult than other controller setups. So in this tutorial we will walk through the setup and configuration.

Recommended Components for this Project

If you don’t already have all of the components for this project, we’ve created a handy parts guide for you:

One item of note. The Xbox One controller in the parts list above supports Bluetooth connectivity. Older Xbox One controllers require this wireless adapter to work, or they must be connected wired via USB.  We’ll go into detail and cover connectivity options next!

Xbox One Controller Connectivity Options

Microsoft is the king of making things confusing. They’ve been at it since Windows 1.0. And the Xbox controller connectivity options are certainly confusing to say the least.  Let’s cover them and sort out the mess.

Connect the Xbox Controller with the Official USB Wireless Adapter

The simplest wireless option for using Xbox One controllers on a Raspberry Pi is to use the official Xbox Wireless Adapter (link above).

This is the method we recommend. It simple, it works, and its supported.  Even though there’s a little extra cost to purchase the adapter if you don’t already have one.

(Note: This is not the same wireless adapter used on the Xbox 360.  Yes, Microsoft loves to confuse us.)

Connect the Xbox Controller Using Bluetooth

This is the most difficult option as it requires making some configuration changes on the Raspberry Pi. It also only works with newer versions of the Xbox One Controllers (basically Xbox One S controllers).  Yes, Microsoft confuses us more!  I generally don’t recommend this option, but we’ll show you how to make it work below.

Connect the Xbox Controller using USB

This isn’t our favorite option, because it relies on wires, but its hands down the simplest way of using Xbox One Controllers on a Raspberry Pi. All you’ll need is a micro-USB to USB Type A cable in your preferred length to get up and running.

Configuring the Raspberry Pi for Xbox One Controllers

As always, before we begin we highly recommend a clean installation of Raspbian before you begin new projects.

Step 1: Make sure Raspbian is up to date with the latest patches.  Almost all issues you’ll run into in the tutorial are solved by updating your software to the latest versions.

sudo apt-get update
sudo apt-get upgrade

Step 2 (Possible Optional): The latest versions of Raspbian already include the Xbox controller diver as part of the Raspbian build.  However, some games and applications still specifically look for this driver to be installed separately. Mostly older software that has not been updated to no longer check for the driver.  Installing the driver will not cause any harm. If you decide not to install it, you can always add it later if you run into issues with certain software.

sudo apt-get install xboxdrv

That’s all there is to it unless your using Bluetooth.  To configure your Raspberry Pi for Xbox One Bluetooth connections continue reading. Everyone else can skip the next section.

Pairing Bluetooth Xbox One Controllers to the Raspberry Pi

We highly recommend installing the xboxdrv from step 2 above when using Bluetooth to connect your Xbox one controllers to the Raspberry Pi. It will likely save you some frustration down the road.

Xbox One controllers to do not support Enhanced Re-Transmission Mode (ERTM), something enabled by default on the Raspberry Pi.  With ERTM enabled the Xbox Controller won’t pair correctly. If you have other devices that require this functionality you should not use be using Xbox One Controllers on a Raspberry Pi with Bluetooth, and instead use the Xbox wireless adapter or a USB cable.

Run the following command to disable ERTM:

sudo bash -c echo 1 > /sys/module/bluetooth/parameters/disable_ertm

Once that is complete issue a sudo reboot so this change will take effect.  We can then begin the pairing process.

Step 1: Open the Bluetooth configuration tool.

sudo bluetoothctl

Step 2: Prepare the Bluetooth radio for pairing.

agent on
default-agent

Step 3: Start the Raspberry Pi scanning for new devices.

scan on

Step 4: With the Raspberry Pi‘s Bluetooth radio scanning for new devices, press the pairing button on your Xbox One controller.  You should see something similar to [NEW] Device B8:27:EB:A4:AC:11 Wireless Controller display on the screen indicating your controller has been recognized.

Step 4: Issue the command connect followed by the device address show on the screen.  In our case it would be:

connect B8:27:EB:A4:AC:11

Step 5: If you typed everything correctly, you’ll see a response similar to the following:

Attempting to connect to B8:27:EB:A4:AC:11
[CHG] Device B8:27:EB:A4:AC:11 Modalias: usb:v054Bp0264a0101
[CHG] Device B8:27:EB:A4:AC:11 UUIDs:
00001124-0000-1000-8000-00805f9b34fb
00001200-0000-1000-8000-00805f9b34fb

Step 6: The last step is to now tell your Raspberry Pi‘s Bluetooth module to trust this device going forward. Without this command, nothing will work as the devices will refuse to talk.  Issue the trust command followed by your device address.  In our case it would be:

trust B8:27:EB:A4:AC:11

Step 7: Exit the Bluetooth configuration tool by pressing CTRL-D or typing quit.

That’s all there is to it. Your Bluetooth connected Xbox One controller is ready to go. If you’d like to set that controller up as a mouse, keep reading!

Using the Xbox One Controller as a Mouse on the Raspberry Pi

If you’d like to use your Xbox One controller as a mouse, you only need to execute a simple command. This is a handy feature, especially for those who primarily want to use their Raspberry Pi as a gaming device and may not have a mouse connected normally.

Enter the following command to enable Xbox One controller mouse support:

sudo xboxdrv --detach-kernel-driver --silent --mouse

Once that command has completed your Xbox One controller should be imitating a mouse on your screen.  It’s buttons are mapped as follows:

  • 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

Feel free to leave comments below with how you are using your Xbox One controller with the Raspberry Pi!  You may also want to check out our RetroPie Setup Guide.