||<tablestyle="float:right;"> '''Inhalt'''<<TableOfContents>> ||

= 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''.

|| '''Action''' || '''Key''' || '''Keycode''' ||
|| move X axis forward || right || 102 ||
|| move X axis backward || left || 100 ||
|| move Y axis forward || up || 98 ||
|| move Y axis backward || down || 104 ||
|| move Z axis up || page up || 99 ||
|| move Z axis down || page down || 105 ||
|| home all axes || home || 97 ||
|| pause program || p || 33 ||
|| resume program || s || 39 ||
|| decrease jogging speed || . (period) || 59 ||
|| increase jogging speed || , (comman) || 60 ||
|| increase jogging step size || I || 50, 31 ||
|| decrese jogging step size || i || 31 ||
|| continuous jogging mode || c || 54 ||
|| select axis X (e.g. for defining an offset) || x || 53 ||
|| select axis Y || y || 29 ||
|| select axis Z || z || 52 ||
|| zero the offset of the current axis || end || 103 ||

= 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

----