Skip to main content

A tool to map joystick events to the one of an Xbox 360 controller

Project description


This python program can help you to map buttons and axes of a gamepad to match the layout of an Xbox 360 controller.

Xbox 360 controller

In other words, it can map gamepad axis and buttons (or even keys of a keyboard) to XBox 360 Linux events. These XBox 360 controller Linux events (listed in /usr/include/linux/input-event-codes.h) are:


This script (which is creating a virtual gamepad) is probably the latest solution. If playing an SDL game, just consider using gamecontroller as explained in

ubox360 program name comes from the fact that events binding is done in userspace.



ubox360 depends on:

  • python-evdev (automatically installed by pip)
  • the uinput kernel module (mainline)

Installation from Pypi

pip install ubox360

Installation from sources

git clone
cd python-ubox360
pip install .


It is required to configure udev permissions rules prior to run ubox360. The following instructions have been applied on an ArchLinux installation but they should be applicable to any Linux distribution using a recent version of systemd.

uinput rule

When loading the uinput kernel module, the device /dev/uinput belongs to root:root by default. Let's create an uinput group for this special device:

shell> sudo groupadd --system uinput

... and let's set permissions with a new udev rules file /etc/udev/rules.d/99-uinput.rules:

shell> cat /etc/udev/rules.d/99-uinput.rules
SUBSYSTEM=="misc", KERNEL=="uinput", GROUP="uinput", MODE="0660"

You can now load the uinput module:

shell> sudo modprobe uinput
shell> ls -l /dev/uinput
crw-rw---- 1 root uinput 10, 223 May 22 21:42 /dev/uinput

If permissions are wrong, you can try to trigger the udev rule:

shell> sudo udevadm trigger /dev/uinput

Gamepad event device rule

The ubox360 program will copy events from the real device to a new virtual device. In order to avoid your game to believe that 2 gamepads are connected to your computer, the real gamepad needs to be hidden. This can be performed by removing read permissions to the current logged user by creating the udev rule /etc/udev/rules.d/70.1-uaccess.rules (don't forget to replace idVendor and idProduct with yours):

shell> cat /etc/udev/rules.d/70.1-uaccess.rules
SUBSYSTEM=="input", ENV{ID_INPUT_JOYSTICK}=="?*", ATTRS{idVendor}=="0458", ATTRS{idProduct}=="100a", TAG-="uaccess"

Once this rule has been written, you need to unplug and re-plug your gamepad (udevadm triggering does reset the permissions correctly).


Heyyy, we're almost ready!

You first need to generate a gamecontrollerdb.txt mapping file with controllermap as explained in

Then, run ubox360 with the generated file:

shell> sudo runuser --user=$USER --group=$USER --supp-group=input --supp-group=uinput -- ubox360 --controllerdb /PATH/TO/gamecontrollerdb.txt
Info: Adding a new gamepad mapping:
  ,-- device /dev/input/event11, name "HID 0458:100a", phys "usb-0000:00:14.0-9/input0"
  '-> device /dev/input/event21, name "ubox360", phys "py-evdev-uinput"

You should see a new event file under /dev/input. You can check everything is fine with evtest:

shell> evtest /dev/input/event21
Event: time 1590177160.054931, type 3 (EV_ABS), code 2 (ABS_Z), value 255
Event: time 1590177160.054931, -------------- SYN_REPORT ------------
Event: time 1590177160.183246, type 3 (EV_ABS), code 2 (ABS_Z), value 0
Event: time 1590177160.183246, -------------- SYN_REPORT ------------
Event: time 1590177161.615009, type 3 (EV_ABS), code 5 (ABS_RZ), value 255
Event: time 1590177161.615009, -------------- SYN_REPORT ------------
Event: time 1590177161.758994, type 3 (EV_ABS), code 5 (ABS_RZ), value 0
Event: time 1590177161.758994, -------------- SYN_REPORT ------------

Note that running ubox360 with runuser is essential. Here is an explanation of runuser options:

  1. --supp-group=input: allows access to /dev/input/event*
  2. --supp-group=uinput: allows access to /dev/uinput
  3. --user=$USER: allows read access of /dev/input/event21 by your UNIX user

Using ubox360 with any input device (keyboard, keypad ...)

ubox360 can also be used with any input device generating evdev events. To do so, the gamecontrollerdb.txt file must be created manually with a non-standard syntax.

In the following instructions, let's we want to use a USB keyboard (here a simple keypad) as an XBox 360 controller.

shell> lsusb
Bus 001 Device 028: ID 04d9:1203 Holtek Semiconductor, Inc. Keyboard

The keypad vendor is 0x04d9 and the product is 0x1203.

The following steps (explain below) must be followed:

  1. exclude this input device from Xorg or Wayland
  2. generate a custom gamecontrollerdb.txt file
  3. run ubox360

Exclude your device from your graphic environment


Create an X11 configuration with a content like:

shell> cat /etc/X11/xorg.conf.d/01-keypad.conf
Section "InputClass"
    Identifier "Keypad"
    MatchIsKeyboard "on"
    MatchUSBID "04d9:1203"

    Option "Ignore" "true"

Generate the gamecontrollerdb.txt file

The format of the gamecontrollerdb.txt file is:



  • GAMEPAD_UUID = bus type (swapped) + 0000 + vendor (swapped) + 0000 + product (swapped) + 0000 + version + 0000
  • GAMEPAD_NAME = any suite of characters
  • BINDINGS = list of "XBox-event:Linux-event"

For example:

shell> cat gamecontrollerdb.txt
03000000d90400000312000000010000,HID 04d9:1203,platform:Linux,a:KEY_KP6,b:KEY_KPPLUS,x:KEY_KP9,y:KEY_KPMINUS,back:KEY_BACKSPACE,start:KEY_KPASTERISK,leftshoulder:KEY_KP7,rightshoulder:KEY_KP8,leftx:KEY_KP1-KEY_KP3,lefty:KEY_KP5-KEY_KP2,lefttrigger:KEY_NUMLOCK,righttrigger:KEY_KPSLASH,

Run ubox360 as usual

shell> sudo runuser --user=$USER --group=$USER --supp-group=input --supp-group=uinput -- ubox360 --controllerdb /PATH/TO/gamecontrollerdb.txt


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ubox360-0.3.0.tar.gz (14.3 kB view hashes)

Uploaded source

Built Distribution

ubox360-0.3.0-py3-none-any.whl (21.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page