What is it about

This howto explains the configuration of a gamepad (joystick) for the Axis GUI of [http://linuxcnc.org EMC2]. It allows to control the basic operations of a 3-axes machine without a keyboard. 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.

3-axes machine

usually a [http://en.wikipedia.org/wiki/Milling_machine milling machine]

EMC2

the most common [http://www.gnu.org/philosophy/free-sw.html free] machine controller software. It is used for turning toolpaths (GCode) into electric pulses for the drivers of the three axes.

Axis

one of the available graphical user interfaces of EMC2

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:

Mapping of buttons and axes

The following mapping of gamepad buttons and emitted keys can be used:

Additionally Axis4 and Axis5 are used as a mouse pointer replacement. Button11 and Button12 (triggered by pressing the two joysticks) can be used as mouse buttons.

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.

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