Introduction

This howto explains the configuration of a gamepad (joystick) to keyboard keys. The following approach is based on the joystick module of an [http://x.org xorg] server. Thus it is applicable for Linux or *BSD systems.

gamepad

a small hand-held device with a few buttons and one or more joysticks. It is usually connected to a computer via USB, bluetooth or another serial connector.

Hardware

The following description is based on a gamepad labeled by Hama as Black Force. It is identified by lsusb with the following attributes:

 Bus 002 Device 009: ID 0079:0006 DragonRise Inc. Generic USB Joystick

Preparing the system

You need to install the joystick module for your xorg server.

Debian or Ubuntu users should run the following command as root:

apt-get install xserver-xorg-input-joystick

Keycodes for useful Axis commands

You can use xmodmap -pke for determining the keycodes of the Axis hotkeys that you want to emit via the gamepad. The following selection should be a good starting point. See [http://www.linuxcnc.org/docs/2.4/html/gui_axis.html#r1_4 hotkeys of Axis] for a list of important keys to be used within Axis.

Gamepad buttons and axes

The Black Force gamepad has 12 buttons and 6 axes. Your X server reports 7 axes, but the first and the third one are basically the same.

The following picture illustrates the numbering scheme of the Black Force gamepad: attachment:pad_numbers.png

Configure the X server

Add the following lines to your /etc/X11/xorg.conf. The ServerLayout and ServerFlags sections should be merged with existing sections in your config (if they exist).

Section "InputDevice"
        Identifier      "joystick"
        Driver          "joystick"
        # proper path to your joypad could be found by looking into '/dev/input/by-id' directory
        Option "Device"         "/dev/input/by-id/usb-DragonRise_Inc._Generic_USB_Joystick-joystick"
        # keyboard controls for Axis: http://www.linuxcnc.org/docs/2.4/html/gui_axis.html#r1_4
        # keycodes: "xmodmap -pke"
        # choose axis X (x)
        Option "MapButton1"     "key=53"
        # choose axis Y (y)
        Option "MapButton2"     "key=29"
        # choose axis Z (z)
        Option "MapButton3"     "key=52"
        # axis "zero G54 offset on selected axis" (END)
        Option "MapButton4"     "key=103"
        # axis +Z
        Option "MapButton5"     "key=99"
        # increase jogging speed (comma)
        Option "MapButton6"     "key=60"
        # axis -Z
        Option "MapButton7"     "key=105"
        # reduce jogging speed (period)
        Option "MapButton8"     "key=59"
        # axis "pause program" (p)
        Option "MapButton9"     "key=33"
        # axis "continus program" (s)
        Option "MapButton10"    "key=39"
        # mouse button: left
        Option "MapButton11"    "button=1"
        # mouse button: right
        Option "MapButton12"    "button=3"
        # axis X - Left /Right
        Option "MapAxis1"       "mode=relative deadzone=28000 keylow=100 keyhigh=102 axis=0.15key"
        # axis Y - Up / Down
        Option "MapAxis2"       "mode=relative deadzone=28000 keylow=98 keyhigh=104 axis=0.15key"
        # same as Axis1 - should be ignored
        Option "MapAxis3"       "mode=none"
        # Mouse (horizontal)
        Option "MapAxis4"       "mode=relative deadzone=2000 axis=+0.5x"
        # Mouse (vertical)
        Option "MapAxis5"       "mode=relative deadzone=2000 axis=+0.5y"
        # Homing (HOME) / jogging control continous mode (c)
        Option "MapAxis6"       "mode=accelerated deadzone=10000 keylow=97 keyhigh=54"
        # change jogging step (i / I)
        Option "MapAxis7"       "mode=accelerated deadzone=10000 keylow=31 keyhigh=50,31"
EndSection

Section "ServerLayout"
        Identifier      "DefaultServerLayout"
        InputDevice     "Joystick"      "SendCoreEvents"
EndSection

Section "ServerFlags"
        # This is an ugly way to disable the mouse pointer ability of the
        # gamepad. Otherwise the gamepad is interpreted as a mouse _and_
        # as a keyboard input (as defined above).
        Option "AutoAddDevices" "False"
EndSection

You need to restart the X server afterwards by pressing CTRL-ALT-Backspace.

Test

After restarting the X server with the new settings you should take a look at /var/log/Xorg.0.log and check for any errors (in case you changed the config above).

Now you can open a text editor (e.g. gedit) and check if all configured keys arrive at the editor window.

Potential issues

Fix for xserver-xorg

Symptom: X server crashes when pressing any gamepad button

The version of xserver-org (1.4.1~git20080131-1ubuntu9.3) currently delivered with Ubuntu Hardy (the default EMC2 system) is broken. You need to fix it following the instructions at http://wiki.linuxcnc.org/emcinfo.pl?Using_X11_Joystick_Driver (see the end of the page).

Fix for xserver-xorg-input-joystick

Symptom: error message bad valuator for input ... in /var/log/Xorg.0.log (X refuses to start normally)

The problem can be fixed by removing the lines 252 to 254 in src/jstk.c of the xserver-xorg-input-joystick:

apt-get source xserver-xorg-input-joystick
cd xserver-xorg-input-joystick-*
sed -i 252,254d src/jstk.c
dpkg-buildpackage -us -uc
dpkg -i ../xserver-xorg-input-joystick-*.deb

Weird behaviour of buttons in non-analog mode

Try to switch to analog mode by pressing the Analog button of the gamepad (Black Force by Hama). Sadly this can't be done by software.

References

• list of Axis hotkeys: http://www.linuxcnc.org/docs/2.4/html/gui_axis.html#r1_4

• basic howto for configuring joysticks for EMC2: http://wiki.linuxcnc.org/emcinfo.pl?Using_X11_Joystick_Driver