[Home]Using A XHC-HB04 Wireless MPG Pendant

LinuxCNCKnowledgeBase | RecentChanges | PageIndex | Preferences | LinuxCNC.org

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:

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)
ModelVersionDescriptionKey LayoutUSB deviceWorks?/Comment?
HB04see photo above; V3.0; 16 keys + handwheel40 meters wireless distance with electronic handwheel110CE:EB70the one this driver/manual was originally written for
WHB04-S18 keys + 7 keys instead of the handwheel40 meters wireless distance without electronic handwheelunknownunknown
WHB04-L18 keys + handwheel40 meters wireless distance with electronic handwheel2unknownLinuxCNC 2.6.7 works fine
LHB0418 keys + handwheelWith 5 m USB cable with electronic handwheel210ce:eb70 Silicon Labsxhc-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:

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:

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.


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"


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.

 HALFILE = xhc-hb04.hal

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


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:

  APP = monitor-xhc-hb04

 <existing entries here>
  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.

  # 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

  # 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


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

If LinuxCNC stops and complains about missing halui items:

Slow Acceleration

LinuxCNCKnowledgeBase | RecentChanges | PageIndex | Preferences | LinuxCNC.org
This page is read-only. Follow the BasicSteps to edit pages. | View other revisions
Last edited January 8, 2022 6:17 pm by Rszemeti (diff)
Published under a Creative Commons License