Gamepad

Joysticks can be a bit of a hassle to get working in Linux. Not because they are poorly supported, but simply because you need to determine which modules to load to get your joystick working, and it's not always very obvious!

Joystick input systems

Linux has two different input systems for Joysticks – the original Joystick interface and the newer evdev-based interface.

/dev/input/jsX maps to the Joystick API interface and /dev/input/event* maps to the evdev ones (this also includes other input devices such as mice and keyboards). Symbolic links to those devices are also available in /dev/input/by-id/ and /dev/input/by-path/ where the legacy Joystick API has names ending with -joystick while the evdev have names ending with -event-joystick.

Most new games will default to the evdev interface as it gives more detailed information about the buttons and axes available and also adds support for force feedback.

While SDL1 defaults to evdev interface you can force it to use the old Joystick API by setting the environment variable SDL_JOYSTICK_DEVICE=/dev/input/js0. This can help many games such as X3. SDL2 supports only the new evdev interface.

Determining which modules you need

Unless you're using very old joystick that uses gameport or proprietary USB protocol, you will need just the generic USB human interface device (HID) modules.

For an extensive overview of all joystick related modules in Linux, you will need access to the Linux kernel sources -- specifically the Documentation section. Unfortunately, pacman kernel packages do not include what we need. If you have the kernel sources downloaded, have a look at Documentation/input/joydev/. You can browse the kernel source tree at kernel.org by clicking the "browse" (cgit - the git frontend) link for the kernel that you're using, then clicking the "tree" link near the top. Here's a link to the documentation from the latest kernel.

Some joysticks need specific modules, such as the Microsoft Sidewinder controllers (sidewinder), or the Logitech digital controllers (adi). Many older joysticks will work with the simple analog module. If your joystick is plugging in to a gameport provided by your soundcard, you will need your soundcard drivers loaded - however, some cards, like the Soundblaster Live, have a specific gameport driver (emu10k1-gp). Older ISA soundcards may need the ns558 module, which is a standard gameport module.

As you can see, there are many different modules related to getting your joystick working in Linux, so I couldn't possibly cover everything here. Please have a look at the documentation mentioned above for details.

Loading the modules for analogue devices

You need to load a module for your gameport (ns558, emu10k1-gp, cs461x, etc...), a module for your joystick (analog, sidewinder, adi, etc...), and finally the kernel joystick device driver (joydev). Add these to a new file in /etc/modules-load.d/, or simply modprobe them. The gameport module should load automatically, as this is a dependency of the other modules.

USB joysticks

You need to get USB working, and then modprobe your joystick driver, which is usbhid, as well as joydev.
If you use a usb mouse or keyboard, usbhid will be loaded already and you just have to load the joydev module.

Testing your configuration

Once the modules are loaded, you should be able to find a new device: /dev/input/js0 and a file ending with -event-joystick in /dev/input/by-id directory. You can simply cat those devices to see if the joystick works - move the stick around, press all the buttons - you should see mojibake printed when you move the sticks or press buttons.

Both interfaces are also supported in wine and reported as separate devices. You can test them with wine control joy.cpl.

Tip: Input devices by default have input group, for example pcsx2 have no access to gamepad without rights. Make sure your user in input group.

Joystick API

There are a lot of applications that can test this old API, jstest from the joyutils package is the simplest one. If the output is unreadable because the line printed is too long you can also use graphical tools. Plasma has a built in one in Input Devices panel in System Settings or jstest-gtk-gitAUR is an alternative.

Use of jstest is fairly simple, you just run jstest /dev/input/js0 and it will print a line with state of all the axes (normalised to {-32767,32767}) and buttons.

After you start jstest-gtk, it will just show you a list of joysticks available, you just need to select one and press Properties.

evdev API

The new 'evdev' API can be tested using the SDL2 joystick test application or using evtest from community repository. Install sdl2-jstest-gitAUR and then run sdl2-jstest --test 0. Use sdl2-jstest --list to get IDs of other controllers if you have multiple ones connected.

To test force feedback on the device, use fftest from linuxconsole package:

$ fftest /dev/input/by-id/usb-*event-joystick

Setting up deadzones and calibration

If you want to set up the deadzones (or remove them completely) of your analog input you have to do it separately for the xorg (for mouse and keyboard emulation), Joystick API and evdev API.

Wine deadzones

Add the following registry entry and set it to a string from 0 to 10000 (affects all axes):

Xorg deadzones

Add a similar line to /etc/X11/xorg.conf.d/51-joystick.conf (create if it doesn't exist):

/etc/X11/xorg.conf.d/51-joystick.conf

Section "InputClass"
Option "MapAxis1" "deadzone=1000"
EndSection

1000 is the default value, but you can set anything between 0 and 30 000. To get the axis number see the "Testing Your Configuration" section of this article.
If you already have an option with a specific axis just type in the deadzone=value at the end of the parameter separated by a space.

Joystick API deadzones

The easiest way is using jstest-gtk from jstest-gtk-gitAUR. Select the controller you want to edit, then click the Calibration button at the bottom of the dialog (don't click Start Calibration there). You can then set the CenterMin and CenterMax values (which control the center deadzone), RangeMin and RangeMax which control the end of throw deadzones. Note that the calibration settings are applied when the application opens the device, so you need to restart your game or test application to see updated calibration settings.

After you set the deadzones use jscal to dump the new values into a shell script:

this maps the EV_ABS event with id of 40 and 41 (use xboxdrv with --evdev-debug to see the events registered), which is the normally inaccessible "mouse pointer" on the throttle, to first gamepad joystick and throttles to second joystick, it also clamps the top and lower ranges as they not always register fully.

this maps the 3 joystick axes to gamepad axes and changes the calibration (min value, centre value, max value), dead zones (negative side, positive side, flag to turn smoothing) and finally change of response curve to a more flat one in the middle.

You can also modify the responsiveness by setting the 'sen' (sensitivity). Setting it to value of 0 will give you a linear sensitivity, value of -1 will give very insensitive axis while value of 1 will give very sensitive axis. You can use intermediate values to make it less or more sensitive. Internally xboxdrv uses a quadratic formula to calculate the resulting value, so this setting gives a more smooth result than 'resp' shown above.

Nice thing about xboxdrv is that it exports resulting device as both old Joystick API and new style evdev API so it should be compatible with basically any application.

Disable joystick from controlling mouse

If you want to play games with your controller, you might want to disable joystick control over mouse cursor. To do this, edit /etc/X11/xorg.conf.d/51-joystick.conf (create if it doesn't exists) so that it looks like this:

Using Joystick to send keystrokes

A couple joystick to keystroke programs exist like qjoypadAUR or antimicroAUR, all work well without the need for X.org configuration.

Xorg configuration example

This is a good solution for systems where restarting Xorg is a rare event because it is a static configuration loaded only on X startup. The example runs on a Kodi media PC, controlled with a Logitech Cordless RumblePad 2. Due to a problem with the d-pad (a.k.a. "hat") being recognized as another axis, Joy2key was used as a workaround. Since upgrade to Kodi version 11.0 and joy2key 1.6.3-1, this setup no longer worked and the following was created for letting Xorg handle joystick events.

Note: The MatchIsJoystick "on" line does not seem to be required for the setup to work, but you may want to uncomment it.

Specific devices

While most joysticks, especially USB based ones should just work, some may require (or give better results) if you use alternative drivers. If it doesn't work the first time, do not give up, and read those docs thoroughly!

Dance pads

Most dance pads should work. However some pads, especially those used from a video game console via an adapter, have a tendency to map the directional buttons as axis buttons. This prevents hitting left-right or up-down simultaneously. This behavior can be fixed for devices recognized by xpad via a module option:

# modprobe -r xpad
# modprobe xpad dpad_to_buttons=1

Logitech Thunderpad Digital

Logitech Thunderpad Digital won't show all the buttons if you use the analog module. Use the device specific adi module for this controller.

Nintendo Gamecube Controller

Dolphin Emulator has a page on their wiki that explains how to use the official Nintendo USB adapter with a Gamecube controller. This configuration also works with the Mayflash Controller Adapter if the switch is set to "Wii U".

By default, the controller will register with udev, but will only be readable by the root user. You can fix this by adding a udev device rule, like the below.

This only matches the USB device with the specified vendor and product IDs, which match those of the official USB adapter. It sets the permissions of the device file to 0666 so that programs that aren't running as root can read the device's input.

udev can be reloaded with the new configuration by executing

# udevadm control --reload-rules

Nintendo Switch Wired Pro Controller

While the controller works for native Linux games, this controller isn't detected by Steam. To fix this, we'll need to add a line to 70-steam-controller.rules.

PlayStation 3/4 controller

The DualShock 3, DualShock 4 and Sixaxis controllers work out of the box when plugged in via USB (the PS button will need to be pushed to begin). They can also be used wirelessly via Bluetooth.

Steam properly recognizes it as a PS3 pad and Big Picture can be launched with the PS button. Big Picture and some games may act as if it was a 360 controller. Gamepad control over mouse is on by default. You may want to turn it off before playing games, see #Joystick moving mouse.

Connecting via Bluetooth

Install the bluez, bluez-plugins, and bluez-utils packages, which includes the sixaxis plugin. Then startbluetooth.service, plug the controller in via USB, and the plugin should program your PC's bluetooth address into the controller automatically.

You can now disconnect your controller. The next time you hit the PlayStation button it will connect without asking anything else.

Alternatively, you can press the share button and the PlayStation button simultaneously to put the gamepad in pairing mode, and pair as you would normally.

Remember to disconnect the controller when you are done as the controller will stay on when connected and drain the battery.

Note: If the controller does not connect, make sure the bluetooth interface is turned on and the controllers have been trusted. (See Bluetooth)

Using generic/clone controllers

Using generic/clone Dualshock controllers is possible, however there are some issues that may require to install patched packages. The default Bluetooth protocol stack doesn't detect some of the clone controllers, the bluez-ps3AUR package is a version patched to be able to detect them. Another issue is a bug where the controller starts to non-stop rumble as soon as it gets connected via USB. That can be fixed by using a patched version of the hid-sony driver, which is available on the dkms-hid-sony-shanwanAUR package.

iPEGA-9017s and other Bluetooth gamepads

If you want to use one of the widely available bluetooth gamepads, such as iPEGA-9017s designed mostly for Android and iOS devices you would need xboxdrvAUR, bluez, bluez-plugins, and bluez-utils. You should connect it in gamepad mode (if there are different modes, choose the gamepad one). Technically it's ready to be used, but in most cases games would not recognize it, and you would have to map it individually for all application. The best way to simplify it and make it work with all applications is to mimic Microsoft X360 controller with xboxdrvAUR.
Once connected you can create a udev rule to give it a persistent name, that would come in handy when setting it up.

Steam Controller

The Steam client will recognize the controller and provide keyboard/mouse/gamepad emulation while Steam is running. The in-game Steam overlay needs to be enabled and working in order for gamepad emulation to work. You may need to run udevadm trigger with root privileges or plug the dongle out and in again, if the controller doesn't work immediately after installing and running Steam. If all else fails, try restarting the computer while the dongle is plugged in.

Alternatively you can install python-steamcontroller-gitAUR to have controller and mouse emulation without Steam or sc-controllerAUR for a versatile graphical configuration tool simillar to what is provided by the Steam client.

On some desktop environments the on-screen keyboard might freeze when trying to input text after one or two characters. This is a problem with window focus. Check the settings for your window manager to see if it is possible to have focus follow the mouse or automatically focus new windows. Preventing the keyboard from receiving focus will fix the issue in Awesome, see Awesome#Steam Keyboard.

Note: If you do not use the Steam runtime, you might actually need to disable the overlay for the controller to work in certain games (Rocket Wars, Rocket League, Binding of Isaac, etc.). Right click on a game in your library, select "Properties", and uncheck "Enable Steam Overlay".

Wine

python-steamcontroller-gitAUR can also be used to make the Steam Controller work for games running under Wine. You need to find and download the application xbox360cemu.v.3.0 (e.g. from here). Then copy the files dinput8.dll, xbox360cemu.ini, xinput1_3.dll and xinput_9_1_0.dll to the directory that contains your game executable. Edit xbox360cemu.ini and only change the following values under [PAD1] to remap the Steam Controller correctly to a XBox controller.

xbox360cemu.ini

Right Analog X=4
Right Analog Y=-5
A=1
B=2
X=3
Y=4
Back=7
Start=8
Left Thumb=10
Right Thumb=11
Left Trigger=a3
Right Trigger=a6

Now start python-steamcontroller in Xbox360 mode (sc-xbox.py start). You might also want to copy XInputTest.exe from xbox360cemu.v.3.0 to the same directory and run it with Wine in order to test if the mappings work correctly. However neither mouse nor keyboard emulation work with this method.

Alternatively you can use sc-controllerAUR for a similar graphical setup as Steam's own configurator. As of writing, it's a bit buggy here and there but offers an easy click and go way of configuring the controller.

Xbox 360 controller

Both the wired and wireless (with the Xbox 360 Wireless Receiver for Windows) controllers are supported by the xpad kernel module and should work without additional packages.

It has been reported that the default xpad driver has some issues with a few newer wired and wireless controllers, such as:

If you experience such issues, you can use either #SteamOS xpad or #xboxdrv instead of the default xpad driver.

If you wish to use the controller for controlling the mouse, or mapping buttons to keys, etc. you should use the xf86-input-joystickAUR package (configuration help can be found using man joystick). If the mouse locks itself in a corner, it might help changing the MatchDevicePath in /etc/X11/xorg.conf.d/50-joystick.conf from /dev/input/event* to /dev/input/js*.

Tip: If you use the TLP power management tool, you may experience connection issues with your Microsoft wireless adapter (e.g. the indicator LED will go out after the adapter has been connected for a few seconds, and controller connection attempts fail). This is due to TLP's USB autosuspend functionality, and the solution is to add the Microsoft wireless adapter's device ID to this feature's blacklist (USB_BLACKLIST, check TLP configuration for more details).

SteamOS xpad

If you have issues with the default xpad kernel module, you can install the SteamOS version. There is still a known issue with compatibility between wireless Xbox360 controllers and games made in GameMaker Studio. If you encounter this problem, the only known workaround is to use xboxdrv. YoYo Games has refused to acknowledge this as a bug with their product and it is unlikely to ever be fixed.

First make sure you have DKMS installed and running, then install the modified kernel module steamos-xpad-dkmsAUR. During the installation you'll see that new xpad kernel module is strapped to your current kernel:

Multiple controllers

xboxdrv supports a multitude of controllers, but they need to be set up in /etc/default/xboxdrv. For each extra controller, add an next-controller = true line. For example, when using 4 controllers, add it 3 times:

Mimic Xbox 360 controller with other controllers

xboxdrv can be used to make any controller register as an Xbox 360 controller with the --mimic-xpad switch. This may be desirable for games that support Xbox 360 controllers out of the box, but have trouble detecting or working with other gamepads.

First, you need to find out what each button and axis on the controller is called. You can use evtest for this. Run evtest and select the device event ID number (/dev/input/event*) that corresponds to your controller. Press the buttons on the controller and move the axes to read the names of each button and axis.

The above example is incomplete. It only maps one axis and 3 buttons for demonstration purposes. Use xboxdrv --help-button to see the names of the Xbox controller buttons and axes and bind them accordingly by expanding the command above. Axes mappings should go after --evdev-absmap and button mappings follow --evdev-keymap (comma separated list; no spaces).

By default, xboxdrv outputs all events to the terminal. You can use this to test that the mappings are correct. Append the --silent option to keep it quiet.

Xbox Wireless Controller / Xbox One Wireless Controller

Connect Xbox Wireless Controller with usb cable

This is supported by the kernel and should work without additional packages.

Connect Xbox Wireless Controller with bluetooth

You should disable ertm to get it work.

either

# echo 1 > /sys/module/bluetooth/parameters/disable_ertm

or

Add this file to your config:

/etc/modprobe.d/xbox_bt.conf

options bluetooth disable_ertm=1

xpadneo

A relatively new driver which does (yet) support only the Xbox One S controller via Bluetooth is called 'xpadneo'.
In exchange for supporting just one hardware so far, it enables one to read out the correct battery level, supports rumble (even the one on the trigger buttons - L2/R2), corrects the (sometimes wrong) button mapping and more.

This should work in USB and Bluetooth mode. (If you want use bluetooth mode, press "home" button and "share" button together, white led of gamepad should blink very quickly, then add wireless controller with your bluetooth manager (bluez, gnome-bluetooth...)

Troubleshooting

Joystick moving mouse

Sometimes USB joystick can be recognized as HID mouse (only in X, it is still being installed as /dev/input/js0 as well). Known issue is cursor being moved by the joystick, or escaping to en edge of a screen right after plugin. If your application can detect joystick by it self, you can remove the xf86-input-joystickAUR package.

Joystick not working in FNA/SDL based games

If you are using a generic non-widely used gamepad you may encounter issues getting the gamepad recognized in games based on SDL. Since 14 May 2015, FNA supports dropping a gamecontrollerdb.txt into the executable folder of the game, for example the SDL_GameControllerDB.

As an alternative and for older versions of FNA or for SDL you can generate a mapping yourself by downloading the SDL source code via http://libsdl.org/, navigating to /test/, compile the controllermap.c program (alternatively install controllermapAUR) and run the test. After completing the controllermap test, a guid will be generated that you can put in the SDL_GAMECONTROLLERCONFIG environment variable which will then be picked up by SDL/FNA games. For example:

Joystick not recognized by all programs

Some software, Steam for example, will only recognize the first joystick it encounters. Due to a bug in the driver for Microsoft wireless periphery devices this can in fact be the bluetooth dongle. If you find you have a /dev/input/js* and /dev/input/event* belonging to you keyboard's bluetooth transceiver you can get automatically get rid of it by creating according udev rules.
Create a /:

Correct the KERNELS=="..." to match your device. The correct value can be found by running

# udevadm info -an /dev/input/js0

Assuming the device in question is /dev/input/js0. After you placed the rule reload the rules with

# udevadm control --reload

Then replug the device making you trouble. The joystick and event devices should be gone, although their number will still be reserved. But the files are out of the way.

Steam Controller not pairing

There are some unknown cases where the packaged udev rule for the Steam controller does not work (FS#47330). The most reliable workaround is to make the controller world readable. Copy the rule /usr/lib/udev/rules.d/70-steam-controller.rules to /etc/udev/rules.d with a later prioritiy and change anything that says MODE="0660" to MODE="0666" e.g.