joydevmap

joydevmap is a small userspace tool to change the axis and button mappings of joysticks and gamepads in Linux.

Usage

$ joydevmap --help
Usage:
  src/joydevmap -h
  src/joydevmap --help
  src/joydevmap {commands} --dev <device>

Commands:
  --list-axismap
  --list-buttonmap
  --set-axismap 'id, id, id...'
  --set-buttonmap 'id, id, id...'

Example

The linux joydev API provides the user with the ability to re-map events originating from some axes and buttons to different axes and buttons. For example, the Trust GM-1520T gamepad reports events originating from the left analog stick via the axes 0 and 1 and the events from the right analog stick via the axes 4 and 3. (In order to make the analog sticks working, I have to press the “Analog” button on my gamepad.) You see this by calling jstest from the joystick package:

$ jstest --normal /dev/input/js0

If you play Descent 2, for example, you may want to use the right analog stick , say for panning, and hence the right analog stick should be accesed via axes 2 and 3 instead. In order to change the right analog stick to axes 2 and 3 one could simply exchange the axes map entries of 2 and 4.

In practice one first obtains the current axes map:

$ joydevmap --list-axismap --dev /dev/input/js0
Got 7 axes:
  0 => 0
  1 => 1
  2 => 2
  3 => 3
  4 => 5
  5 => 16
  6 => 17

Hence, we need to map axis 2 to 5 and, in exchange, map 4 to 2. This is achieved by calling

$ joydevmap --set-axismap '0, 1, 5, 3, 2, 16, 17' --dev /dev/input/js0

You can again call jstest to verify that the right analog stick now uses axes 2 and 3.

Installation

In order to obtain the source code you may clone the git repository or obtain a tar.gz snapshot from git.sthu.org. Joydevmap is written in C99. In order to build it use the following commands within the package’s directory.

mkdir build
cd build
cmake -D CMAKE_BUILD_TYPE="Release" ..
make
src/joydevmap -h

To install joydevmap call as privileged user

make install

Gentoo

A Gentoo ebuild is available via my overlay.

udev rules

In order to set the axes and buttons mappings each time the gamepad is plugged you need to define an appropriate udev rule which invokes joydevmap. First, we identify the vendor and model ID by calling lsusb or udevadm:

$ lsusb
[...]
Bus 002 Device 046: ID 0810:0003 Personal Communication Systems, Inc. 
[...]

$ udevadm info --query=all --name=input/js0
[...]
E: ID_VENDOR=0810
[...]
E: ID_MODEL_ID=0003
[...]

Using lsusb I read vendor ID 0810 and model ID 0003 for my gamepad. If you called udevadm, you get the same values by inspecting ID_VENDOR resp. ID_MODEL_ID. Now that we know these IDs we can define a new rule by creating the file /etc/udev/rules.d/90-trust-GM1520T.rules with the following content:

ENV{ID_VENDOR}=="0810",ENV{ID_MODEL_ID}=="0003",RUN+="/etc/udev/scripts/joydevmap-
trust-gm1520t.sh /dev/$name"

(Note that udev rules’ syntax does not allow for line breaks. The code above must be a single line.) Of course, you need to replace the vendor and model ID listed above by the ones you just obtained. This rule tells udev to call the script joydevmap-trust-gm1520t.sh each time the gamepad is plugged, which we need to create with the following content:

#!/bin/sh
/usr/bin/joydevmap --set-axismap '0, 1, 5, 3, 2, 16, 17' --dev $@ > /dev/null

Again, you need to adapt the parameters of –set-axismap to your case.

Alternatives

Quite surprisingly, the only solution to perform joydevmap’s task – without joydevmap – was to patch jscal, which is part of the previously mentioned joystick package joystick. This patch adds the options “–print-mappings, -q” and “–set-mappings, -u” to jscal. However, the patch is buggy (e.g., it by mistake expects ioctl for JSIOCSAXMAP to return 0 on success) and inconvinient to apply. Different versions of the patch and patches for the patched version circulate in the web. Hence, I decided to write joydevmap at the evening when I received my Trust GM-1520T gamepad.

Anyhow, if you are using Gentoo, you can automatically apply the patch to the joystick package using the autopatch method and by downloading jscal-axismap.patch.2. This patch applies to games-util/joystick-20060731.

Update: Gentoo now delivers joystick-1.4.2, which included a patch for the bug described above.