XHC-HB04 wireless MPG pendant LinuxCNC HAL module

Current Version of LinuxCNC

The xhc-hb04 driver and a sample config are included in LinuxCNC versions starting with 2.6.0. There is no need to download and compile the driver.

Versions of LinuxCNC older than 2.6.0

You will need to download and compile the driver if you want to use the XHC-HB04 with a version of LinuxCNC older than 2.6.0

For LinuxCNC versions before 2.6.0, download the package from here:

This HAL module is designed for the XHC-HB04 V3.0 identified as USB device 10CE:EB70. Most of the pendant features are handled:

buttons converted to hal pins
jog wheel with variable scale (use STEP button to select scale)
LCD screen

Models/Versions? of XHC-HB04

(It seems there are at least 4 different models out there which all are marked with "XHC" on the wheel and "HB04" on the dial. The Model-Names below are from descriptions/instuction manuals)

Model	Version	Description	Key Layout	USB device	Works?/Comment?
HB04	see photo above; V3.0; 16 keys + handwheel	40 meters wireless distance with electronic handwheel	1	10CE:EB70	the one this driver/manual was originally written for
WHB04-S	18 keys + 7 keys instead of the handwheel	40 meters wireless distance without electronic handwheel	unknown		unknown
WHB04-L	18 keys + handwheel	40 meters wireless distance with electronic handwheel	2	unknown	LinuxCNC 2.6.7 works fine
LHB04	18 keys + handwheel	With 5 m USB cable with electronic handwheel	2	10ce:eb70 Silicon Labs	xhc-hb04-V05.tgz/LinuxCNC? 2.5.3 works fine

Compilation instructions

This module requires standard C development packages and libusb-1.0 You may need to install following packages on your system:

libc6-dev
libusb-1.0-0-dev

Use the following commands

 sudo apt-get install libc6-dev
 sudo apt-get install libusb-1.0-0-dev

Then go to the directory where you have extracted the module files and use the two following commands:

make
make install

Now, the xhc-hb04 executable HAL module should be available in /usr/local/bin and directly usable by LinuxCN? after udev configuration and integration of xhc-hb04.hal as described below.

Installation

Also copy xhc-hb04.hal and xhc-hb04-layout*.ini files into your config directory.

UDev Rules

You must add the file /etc/udev/rules.d/90-xhc.rules with the following content to get access to USB without root privileges

 SYSFS{idProduct}=="eb70", SYSFS{idVendor}=="10ce", MODE="666", OWNER="root", GROUP="users"

Note: SYSFS was deprecated in favor of ATTR/ATTRS.

If the above does not work try with:

 ATTRS{idVendor}=="10ce", ATTRS{idProduct}=="eb70", MODE="666", OWNER="root", GROUP="users"

Configuration

The xhc-HB04.hal file shows a typical configuration to be integrated by the following line in you .ini file: If halui is not activated in some other way (see integrators manual) make shure HALUI = halui is also in the [HAL] section of your .ini file.

 [HAL]
 ....
 HALFILE = xhc-hb04.hal

It assumes MDI commands 06 to 09 are reserved for the following 4 pendant buttons:

X=0
Y=0
Z=0
Goto zero

 [HALUI]
 MDI_COMMAND=...
 MDI_COMMAND=...
 MDI_COMMAND=...
 MDI_COMMAND=...
 MDI_COMMAND=...
 MDI_COMMAND=...
 MDI_COMMAND=G10 L20 P1 X0
 MDI_COMMAND=G10 L20 P1 Y0
 MDI_COMMAND=G10 L20 P1 Z0
 MDI_COMMAND=G0 X0 Y0 Z0

In xhc-hb04.hal you can change your keyboard layout preference: loadusr -W xhc-hb04 -I xhc-hb04-layout1.ini -H

The layout can be adapted by editing the layout file.

If you want to test the output for your specific keyboard just run /usr/local/bin/xhc-hb04 on the linux command line and watch the hexdump after pressing specific keys.

Using xhc-hb04-layout*.ini files to modify your own .ini

If using the xhc-hb04-layout*.ini files as an example to modify your own .ini then do the following:

The sim configurations use a single halfile: xhc-hb04.tcl. This halfile can be added to existing configurations by adding the following in the [HAL] section of your ini file:

 [APPLICATIONS]
  APP = monitor-xhc-hb04

 [HAL]
 <existing entries here>
  HALFILE=xhc-hb04.tcl
  HALUI = halui

Then add the [XHC_HB04_CONFIG] and [XHC_HB04_BUTTONS] sections from the xhc-hb04-layout*.ini file to your ini file. Edit to suit e.g. for 3 axis (no A axis) remove the 4th parameter from the "coords", "coefs" and "scales" lines. A "-" (minus) in front of the scales parameters will reverse the direction i.e. scales = "1 -1 1" will reverse the Y axis.

 [XHC_HB04_CONFIG]
  # specify layout = n for xhc-hb04-layout{n}.cfg files
  layout = 2
  # coords: specify 4 letters
  # coords: switch labels are xyza but any unique 4 letters
  #         from the set {xyxabcuvw) can be used (if the coord exists)
  coords = x y z
  # lowpass settings:
  # coef: slows rate of change of output,  range: 0 < coef < 1
  coefs = 1 1 1
  # scale plus or minus, rotaries may require larger scale factor:
  scales = 1 1 1
  # jogmode normal(default) or vnormal
  jogmode = normal
  # accels for jog wheel, set to something a bit less than your max axis accel
  mpg_accels = 50 50 50 
  # sequence 1: 0.001,0.010,0.100 (mm-based machine)
  # sequence 2: 0.001,0.005,0.010 (inch-based machine)
  sequence = 1
  # require_pendant = no: create xhc-hb04 hal pins when pendant not connecte
  #                       at startup
  require_pendant = yes

 [XHC_HB04_BUTTONS]
  # use button names according to layout file xhc-hb04-layout{n}.cfg
  # note: "start-pause" is connected for standard behavior
  #        controlling halui.pause/halui.resume/halui.run
  # these are examples, edit as required:
  goto-zero   = halui.mdi-command-00
  start-pause = std_start_pause
  rewind      = halui.program.step
  # probe-input for simulating a probe, [
  # note: not compatible with the pncconf generated HAL files. uncomment to enable.
  # probe-z     = motion.probe-input
  macro-3     = halui.mdi-command-03
  half        = halui.spindle.stop
  zero        = ""
  safe-z      = halui.mdi-command-10
  # in this sim, home-all only works first time, hold down till finished:
  #home        = halui.home-all
  macro-1     = halui.mdi-command-01
  macro-2     = halui.mdi-command-02
  spindle     = halui.spindle.start
  step        = xhc-hb04.stepsize-up
  mode        = ""
  macro-6     = halui.mdi-command-06
  macro-7     = halui.mdi-command-07
  stop        = halui.program.stop
  reset       = halui.estop.activate

Troubleshooting

Run LinuxCNC from the terminal to see error messages as it is running.

If LinuxCNC stops and complains about missing halui items:

Make shure halui is loaded (see Integrators Manual; e.g. put HALUI = halui in the [HAL] section of your *.ini)
halui.home-all not found: besides not having loaded halui this pin is only available if you set HOME_SEQUENCE in the ini file (see Integrators Manual; if you don't want to set HOME_SEQUENCE option remove also the corresponding entry in xhc-hb04.hal)
depending on your machine configuration (e.g. as a lathe) some pins may not be available and give an error (e.g. axis.3.jog-scale) so you have to remove or change them from xhc-hb04.hal

Slow Acceleration

If you have slow acceleration with the jog wheel, make an entry in the [XHC_HB04_CONFIG] of your .ini file with mpg_accels = 50 50 50 (choose the value a little less than the axis acceleration value to give you a nice smooth jog). The version of xhc-hb04.tcl in the current distributions default to an accel value of 1.0 units/second^2 if no value is given for mpg_accels, which is very slow.

Using A XHC-HB04 Wireless MPG Pendant