Using Xbox Controller With LinuxCNC

The use of a game controller is a nice addition to my LinuxCNC setup,  allowing me to jog axes and to zero axis home offsets while standing at my CNC rather than at the control PC. I bought a PowerA generic USB wired Xbox One controller and with information from a variety of online forums and websites eventually got it working. With this post I hope to coalesce the set up details in case I need to revisit in the future and hopefully it helps someone with their setup. I'm running LinuxCNC v2.8 on Debian 9 (stretch). My homemade CNC is a 3 axis machine with two joints on the Z-axis.

1. Install xpad the Linux USB driver for Xbox compatible controllers

  $ sudo apt-get install xpad


With the controller plugged in you should now see an new input device /dev/input/js0. You can test the joystick with jstest utility

  $ sudo apt-get install joystick
  $ jstest /dev/input/js0


You should see an output similar to below. Pressing controller buttons or moving a joystick will update a corresponding field

  Driver version is 2.1.0.
  Joystick (Generic X-Box pad) has 8 axes (X, Y, Z, Rx, Ry, Rz, Hat0X, Hat0Y) and
  11 buttons (BtnA, BtnB, BtnX, BtnY, BtnTL, BtnTR, BtnSelect, BtnStart, BtnMode, BtnThumbL, BtnThumbR).
  Testing ... (interrupt to exit)
  Axes: 0:0  1:0  2:-32767  3:0  4:0  5:-32767  6:0  7:0
  Buttons: 0:off 1:on 2:off 3:off 4:off 5:off 6:off 7:on 8:off 9:off 10:off

2. Use the hal_input component to control LinuxCNC HAL pins with a Linux input device. You first need to identify the controller details using

  $ less /proc/bus/input/devices


My Xbox controller details are below. You will need to use some of these values when exposing the input device to the LinuxCNC HAL (id.Vendor, id.Product, and Name of the device).

  I: Bus=0003 Vendor=24c6 Product=581a Version=0101
  N: Name="Generic X-Box pad"
  P: Phys=usb-0000:00:15.0-4/input0
  S: Sysfs=/devices/pci0000:00/0000:00:15.0/usb1/1-4/1-4:1.0/input/input16
  U: Uniq=
  H: Handlers=event13 js0
  B: PROP=0
  B: EV=20000b
  B: KEY=7cdb000000000000 0 0 0 0
  B: ABS=3003f
  B: FF=107030000 0

Create a file called joystick.rules in the folder /etc/udev/rules.da and add the line below with the controller id.Vendor and id.Product values.

  $ cd etc/udev/rules.da
  $ sudo nano joystick.rules

    SYSFS{idProduct}=="581a", SYSFS{idVendor}=="24c6", MODE="0660", GROUP="plugdev"

In the LinuxCNC config folder create a file called xboxctrl.hal and add the following line to load the hal_input component referencing the device name "Generic X-box pad" (You don't need to use the full device name string. You can just use enough of the name to uniquely distinguish it from the other input devices).

  loadusr -W hal_input -KRAL Generic X-Box

In the config ini file add a HALFILE reference to the new HAL file

  [HAL]
  HALFILE = xboxctrl.hal

3. To determine the Xbox controller button mapping to the HAL input component pins start the LinuxCNC GUI and browse to Machine > Show HAL Configuration > Pins > inputs.  Use the Watch tab to determine which hal_input pins change when a controller button is pushed or joystick is moved. Below is the pin mapping for my controller. 

LinuxCNC HAL : Xbox controller pin mapping
Front buttons
input.0.abs-z-position	Left trigger
input.0.abs-rz-position	Right trigger
input.0.btn-tl	Left bumper
input.0.btn-tr	Right bumper
Middle buttons
input.0.btn-mode	Xbox Guide button
input.0.btn-select	Back button
input.0.btn-start	Start button
ABXY buttons
input.0.btn-a	A button
input.0.btn-b	B button
input.0.btn-x	X button
input.0.btn-y	Y button
Left joystick
input.0.abs-x-position	Left/Right
input.0.abs-y-position	Up/Down
Right joystick
input.0.abs-rx-position	Left/Right
input.0.abs-ry-position	Up/Down
Directional pad
input.0.abs-hat0x-position	Left/Right
input.0.abs-hat0y-position	Up/Down

4. To complete the interface with LinuxCNC update the config ini file by adding a HALFILE reference to the xboxctrl.hal file (should already be done above) and to adding the G-code MDI commands to zero axis offsets.

  [HAL]
  HALFILE = xboxctrl.hal
  HALUI = halui

  
  [HALUI]
  # Zero X-axis
  MDI_COMMAND = G10 L20 P1 X0			
  # Zero Y-axis
  MDI_COMMAND = G10 L20 P1 Y0
  # Zero Z-axis
  MDI_COMMAND = G10 L20 P1 Z0

The below gist shows my completed xboxctrl.hal file which sets up the Xbox controller for use with LinuxCNC. The left joystick moves the X and Y axes. The right joystick (Up/Down) jogs the Z axis. The X button zeros the X axis offset. The Y button zeros the Y axis offset and the A button zeros the Z axis offset.

Loading https://gist.github.com/deanstheory/689e13b473a109d32679f0f426efccad ...