This article talks about gamepad installation and setup. The two stages of configuration are often driver installation, and device configuration. Many devices have support integrated into the kernel and will work as soon as they're plugged in. Others can be more difficult.
Given that the majority of devices have their necessary drivers built-in, the only thing most people might need to do is calibrate their controller afterwards. Many desktops have built-in configuration modules to select any connected gamepads and calibrate them.
The process in the KDE Plasma desktop is documented here but the instructions are near-universally applicable.
Open Application Launcher > Search > Game Controller
Open Application Launcher > System Settings > Input Devices > Game Controller
- Select your gamepad in the "Device" drop-down box
- Hit the "Calibrate" button in the bottom-left and follow the on-screen instructions
There are many useful games in the Debian repositories for verifying that your gamepad works as expected, but supertuxkart is especially recommended due to its fantastic gamepad support.
Within a terminal, you can also monitor input device events, either with the joystick API (older) or the evdev API (newer).
- joystick provides jstest, which will help you monitor /dev/input/js* (older API).
- evtest provides the evtest command, which will help you detect your pads device label names, and listen to their events.
Xbox and PlayStation controllers
Xbox, Xbox 360, and Xbox One controllers, including many knock-offs, should work out-of-the-box with no issues. This includes both wired and wireless variants, whether by using official wireless receivers or through Bluetooth. This also applies for the DualShock 3 and DualShock 4 controllers commonly used by the PlayStation consoles.
In December 2020, Sony published an official Linux driver for the "DualSense" controller that comes with the PlayStation 5 that should bring its support up to parity with previous Sony controllers, but the patchset remains under review.
Support for the Steam Controller is provided through the steam-devices package. By default, it works in "desktop mode" where it emulates mouse input. It will act as a proper controller only for games launched through Steam.
There's a project developing a user-mode driver for the Steam Controller that allows it to emulate an Xbox controller in any game without need for the proprietary Steam client. It is not officially supported in Debian however, and it will require extra configuration of its own: https://github.com/kozec/sc-controller
Nintendo Switch Pro Controller
While support is not integrated into Debian yet, Steam implements its own driver, with udev rules available in the non-free steam-devices package. Patches to the kernel for a generic Nintendo driver are set to be included in Linux 5.16, and the driver will likely become available in Debian 12/Bookworm.
Xbox Controllers over Bluetooth
If you struggle with connecting an Xbox One or Xbox Series controller over Bluetooth, some manipulations might be required.
ERTM and Bluez version < 5.12
According to this comment, disabling ERTM isn't necessary anymore since bluez version 5.12.
It may fix it to disable ERTM. This can be done once by running:
# echo 1 > /sys/module/bluetooth/parameters/disable_ertm
If this fixes it, you may want to set this permanently so it isn't reversed on reboot. To do this, create a new file using Nano (or your preferred editor):
# nano /etc/modprobe.d/bluetooth.conf
And add a single line to the new file:
options bluetooth disable_ertm=Y
Note that ERTM is seldom used by any non-controller devices and it should not interfere with any other normal Bluetooth functionality to disable it. But if you do happen to run into issues with other Bluetooth devices after making this change, it may be helpful to try reverting it.
Connect / Disconnect loops
The device might connect and instantly disconnect, and so on.
Some people had success pairing the device with these bluez settings, under the [General] section:
Privacy = device JustWorksRepairing = always Class = 0x000100 FastConnectable = true
Button events stutter with Bluetooth LE
According to xpadneo author, this affects Xbox Series S|X controllers and is caused by the gamepad not advertising its working frequency while using Bluetooth.
Setting this frequency manually in /etc/bluetooth/main.conf will affect every LE devices, avoid if you can:
[LE] MinConnectionInterval=7 MaxConnectionInterval=9 ConnectionLatency=0
Uncommon gamepads and specific game engines
It can happen although your gamepad works fine with most native linux games, it might not work on some others. This issue mostly happens with proprietary game engines (like Unity3D using the Rewired API).
Some games might check if your gamepad is amongst the most common ones, in order to automatically map the buttons with actions, but might not allow you to reconfigure the mapping or have bugs with less common gamepads (i.e: freeze during the controllers check, whereas they run as usual when controllers are unplugged).
xboxdrv is a userspace gamepad driver which can emulate an Xbox controller, from any gamepad (provided it has enough buttons for your need).
Here is an example which maps a Logitech Rumblepad 2 to look like an Xbox controller:
xboxdrv --evdev /dev/input/by-id/usb-Logitech_Logitech_RumblePad_2_USB-event-joystick \ --evdev-absmap ABS_X=x1,ABS_Y=y1,ABS_HAT0X=dpad_x,ABS_HAT0Y=dpad_y,ABS_Z=y2,ABS_RZ=x2 \ --evdev-keymap BTN_THUMB=a,BTN_THUMB2=b,BTN_TRIGGER=y,BTN_TOP=x,BTN_TOP2=lb,BTN_PINKIE=rb,BTN_BASE=lt,BTN_BASE2=rt,BTN_BASE3=Back,BTN_BASE4=Start \ --axismap -Y1=Y1,-Y2=Y2 \ --mimic-xpad
See xboxdrv --help or the manpage, and more specifically xboxdrv --help-* (or xboxdrv --help-all) for lists of possible mappings.
Map gamepad to keyboard keys
antimicrox is another approach which helps you translate gamepad events to keyboard keys, which might be useful when your game doesn't support your gamepad at all but is keyboard playable.