Control your Raspberry Pi by using a wireless Xbox 360 controller

In addition to the control of the Raspberry Pi via infrared remote controls, 433 Mhz transmitter, messengers and many more, also a wireless Xbox 360 controller can be read from the Raspberry Pi. This allows the gamepad to be used as an external mouse (in desktop mode) or in scripts and thus the GPIOs can be controlled. In RetroPie, the Xbox Controller can also be used as input media for games on the Raspberry Pi.

In this tutorial several of these possibilities are shown. From the installation of the required software, to the use as a mouse, to the switching of the GPIOs and the control of a servo motor with the joystick.



To use the Raspberry Pi with the Xbox 360 controller, you do not need a lot of accessories:

  • Xbox 360 Wireless Controller (US / UK)
  • Xbox 360 USB Receiver (US / UK)

Each Raspberry Pi with at least one free USB port can be used, for example, the more powerful Raspberry Pi 3.

If you want to rebuild the small project below, you also need:



Raspberry Pi Software for the Xbox 360 Controller

For Linux distributions, there is a developed driver, especially for communicating with (wireless) Xbox controllers.

We first install the driver so that it can be communicated with the controller:

sudo apt-get install xboxdrv

Now the USB receiver can be connected. With lsusb, you can check if it has been detected:

pi@raspberrypi:~ $ lsusb
Bus 001 Device 005: ID 045e:0291 Microsoft Corp. Xbox 360 Wireless Receiver for Windows
Bus 001 Device 003: ID 0424:ec00 Standard Microsystems Corp. SMSC9512/9514 Fast Ethernet Adapter
Bus 001 Device 002: ID 0424:9514 Standard Microsystems Corp.
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub


Now you can turn the controller on and test if it is detected. To do this, start the driver using:

sudo xboxdrv --detach-kernel-driver

After that, press the keys to change the log, which indicates which key(s) is/are pressed and its value.

On the documentation page, there are all commands with a brief explanation. For example, it is possible to make the LEDs of the Xbox 360 controller light / flash (--led NUM)  or vibrate (-r 255,255). In total, up to 4 radio controllers can be used and addressed or read out.

Use the Xbox 360 Controller as Raspberry Pi Mouse

A feature I particularly like is the mouse option. Since I have rarely connected a keyboard to the Raspberry Pi (I use almost exclusively SSH and sometimes the Remotedesktop) and even more rarely a mouse, I find it very handy to use the Xbox 360 wireless controller as a mouse for the Raspberry Pi. Everything we need is already installed.

Only one other parameter must be specified:

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

You can also change the speed and selection of the buttons (as described in the documentation). If the command should be executed at system start, you can either write an autostart script or use crontab.

The following (standard) assignment of the keys for use as a mouse applies:

  • 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



Use the Xbox 360 Controller to start scripts and commands

One way to use the driver in your own scripts is the manual readout of the output values. In order to save us this effort, we can go back to an already created Python library.

git clone
cd Xbox

Attached is also an example (, which can be viewed if necessary.

I have therefore built a small example with a servo motor and 4 LEDs as inspiration. The wiring is quite simple (resistance to the LEDs), therefore only shown here as a schematic structure:

Raspberrya Pi Xbox 360 Steckplatine


The code for this is as follows (create a file with sudo nano and with CTRL + O, X save and exit):

Then you can run the code (sudo nano and use the buttons to turn the LEDs on and off or use the left joystick to control the servo motor. To stop, press the BACK button.

In the following video you can also watch this small project:

In addition, many more things can be done with the Raspberry Pi and Xbox 360 Controller. For example, using Recallbox or with a robot control with the help of the joystick and changing the modes with the buttons.

Well, what will be your next scheduled projects with the controller? 🙂

32 Responses

  1. Great post!, just what I was looking for. But, when y tried to compile the code, it said an error with
    import xbox
    ImportError: No module named xbox.
    What should I do?

  2. What do you think the question?

    Traceback (most recent call last):
     File “”, line 7, in
      joy = xbox.Joystick()
     File “/home/pi/Xbox/”, line 72, in __init__
      raise IOError(‘Unable to detect Xbox controller/receiver – Run python as sudo’)
     IOError: Unable to detect Xbox controller/receiver – Run python as sudo

      • I ran the code with sudo also, there this error still.
        raise IOError(‘Unable to detect Xbox controller/receiver – Run python as sudo’)

  3. Hi,
    Good job with this tutorial.
    I wanted to use Xbox controller to just turn on an LED by pressing button A. I wrote a small program regarding that. But I am getting this error
    Traceback (most recent call last):

    ‘ File “/home/pi/Xbox/”, line 8, in
    joy = xbox.Joystick()
    File “/home/pi/Xbox/”, line 72, in __init__
    raise IOError(‘Unable to detect Xbox controller/receiver – Run python as sudo’)
    OSError: Unable to detect Xbox controller/receiver – Run python as sudo’

    I ran Python as sudo and I even used the xbox controller as mouse and tested if it is communicating with receiver, it is definitely communicating with receiver.

    I can leave u my code, you could tell me if I have done any mistake. I am running this code in Xbox folder as well

    Here is my program:

    import RPi.GPIO as GPIO
    import time
    import math
    import xbox
    joy = xbox.Joystick()
    GPIO.setup(21, GPIO.OUT)
    my_pwm = GPIO.PWM(21,50)
    if joy.A():  
    • I had issued with the receiver sometimes not being read correct by the RPi even after I had initially connected to it from an Xbox controller. I simply unplugged and replugged it back in. The error you are getting is saying it is not getting communication from the receiver, which it seems to suggest one possible reason is because it has to be run as root (sudo).

      In addition if you are wanting to just turn on an LED you should not use the PWM signal mode of the raspberry pi with 100% on duty cycle, instead just set that pin to high, this will be more efficient for the Raspberry Pi to do.

      if joy.A():
  4. Please help me. I am unable to install Xboxdrv on raspberry pi 3. I have a raspberry pi running raspbian jessie and it gives the following output on executing the ‘apt-get’ command:
    E: Unable to locate package xboxdrv

  5. Can you do this with Xbox One Controller and Xbox One Wireless Receiver stick. If so let me know how.

  6. Great tutorial is it possible to use a wired Xbox controller, how would I do this?

  7. Hello,

    Does anybody know how to control Raspberry Pi 3 B + with any game controller over the Ethernet?

    I have a ROV with brushless motors, each with ESC. I’d like joysticks from a game controller to control engines and button to launch python scripts. But the main obstacle is that i only have Ethernet tether to the Raspberry Pi.

    Is it possible? Has anyone done it? Could anybody please shed some light on it?

    Thank you.

  8. Hello,
    Does anyone know how to write similar program but with the use of pigpio instead of RPi.GPIO? Pigpio seems to not have jitters on my servos and works more efficiently, but I am quite new to this stuff and cannot convert this code into the one with pigpio library.

    Thank you

  9. So, after trying multiple times on reinstalling the driver and redoing all the code that is mentioned here, along with different Xbox controllers, I’ve had no luck.
    I’ve attached the input and output of what I’ve typed in the terminal along with what it responded back. Any advice is much appreciated.

    pi@raspberrypi:~ $ sudo apt-get install xboxdrv
    Reading package lists… Done
    Building dependency tree
    Reading state information… Done
    xboxdrv is already the newest version (0.8.8-1).
    The following package was automatically installed and is no longer required:
    Use ‘sudo apt autoremove’ to remove it.
    0 upgraded, 0 newly installed, 0 to remove and 10 not upgraded.

    pi@raspberrypi:~ $ sudo xboxdrv –detach-kernel-driver
    xboxdrv 0.8.8 –
    Copyright © 2008-2011 Ingo Ruhnke
    Licensed under GNU GPL version 3 or later
    This program comes with ABSOLUTELY NO WARRANTY.
    This is free software, and you are welcome to redistribute it under certain
    conditions; see the file COPYING for details.

    — [ ERROR ] ——————————————————
    No Xbox or Xbox360 controller found

    pi@raspberrypi:~ $ lsusb
    Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
    Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
    Bus 001 Device 006: ID 1a2c:4c5e China Resource Semico Co., Ltd
    Bus 001 Device 009: ID 045e:02ea Microsoft Corp. Xbox One S Controller
    Bus 001 Device 007: ID 05ac:12a8 Apple, Inc. iPhone5/5C/5S/6
    Bus 001 Device 003: ID 046d:c534 Logitech, Inc. Unifying Receiver
    Bus 001 Device 002: ID 2109:3431 VIA Labs, Inc. Hub
    Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

    pi@raspberrypi:~ $

    • I also typed lsusb in terminal to verify the Xbox controller was mounted ( thats the best I know how to describe that ) and it shows that it is mounted, Its also connected via bluetooth and I have the same results.

  10. Seriously easy-to-use tutorial. Blasted through it in record time and ran the code (added the LeftTrg as well). Thanks for making life easy.
    Raspberry Pi 4B, generic xbox 360 usb receiver connected to USB v2 connector
    Works with both Py2/Py3.
    I note that I did have to `sudo apt-get install git` in order to clone the repository.

  11. I have published this xbox module to pip. The person who wrote it didn’t know how to publish to pip and asked someone to do it if they can and I did it. Now it can be installed via pip using:

    pip install xbox-remote

    And then importing via:

    import xbox

  12. Every time I try to run the: sudo xboxdrv –detach-kernel-driver –silent –mouse
    It does this. It instantly finishes the program. Using Xbox 360 wireless receiver, I am definitely paired to it with my controller.

    xboxdrv 0.8.8 –
    Copyright © 2008-2011 Ingo Ruhnke
    Licensed under GNU GPL version 3 or later
    This program comes with ABSOLUTELY NO WARRANTY.
    This is free software, and you are welcome to redistribute it under certain conditions; see the file COPYING for

    Controller: Xbox 360 Wireless Receiver
    Vendor/Product: 045e:0719
    USB Path: 001:004
    Wireless Port: 0
    Controller Type: Xbox360 (wireless)
    pure virtual method called
    terminate called without an active exception

  13. Thank you for this. I’ve built a simple led control basing on this for my son and it was great for me and him! Cheers


Leave a Comment

Your email address will not be published.

Subscribe to Raspberry Pi Tutorials and don't miss any new Tutorial!