XHC-HB04(1)

📦
version 2.9.4 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 XHC-HB04(1) — HAL User's Manual 💖

okay bestie, welcome to the pendant page 🎀 this is the HAL User's Manual entry, and it is long, so buckle up

✨ NAME ✨

xhc-hb04 — a HAL non-realtime component for the xhc-hb04 pendant. that's it, that's the name, short and iconic 💅

🌈 DESCRIPTION 🌈

so this component is the whole support system for a super common USB pendant, and that pendant is giving main character energy: it's got a bunch of pushbuttons, a manual pulse generator (that's the mpg — aka the jog wheel, your lil spinny bestie), and a selector switch that decides what the wheel is even doing. 🔥

heads up, there's more than one hardware version out here — at least two, no cap. one has 16 buttons, and the more common one has 18 buttons. everything on this page is based on the 18 button device, whose USB Vendor:Product code is 10CE:EB70. ✨

and it's not just buttons — the pendant provides an LCD display, and it's showing you:

  • the current stepsize multiplier (picked from a set of available integer values)
  • position, both absolute and relative — labeled MC and WC respectively
  • feedrate — override percent and the value in units per minute
  • spindle speed — override percent and the value in revolutions per minute (RPM)

the display is managed by a rotary switch that selects one of four axes for wheel positioning, feed override, spindle override, or OFF. 🦋

the pendant display, its rotary selector switch, and the component pin names all use the designators x,y,z,a. and like, yes, this arrangement presumes a machine configured as XYZA — but the pins can be assigned independently as required in a HAL configuration, so do you, bestie. 💜

🎀 UDEV 🎀

the xhc-hb04 executable needs permission for reading the pendant's USB device. Debian package installs (debs) handle this automatically, but Run-In-Place (RIP) builds may need a udev rules file. this file should be created (using sudo and a text editor) as:

/etc/udev/rules.d/99-xhc-hb04.rules

with the single line:

ATTR{idProduct}=="eb70", ATTR{idVendor}=="10ce", MODE="0666", OWNER="root", GROUP="plugdev"

🌸 Standalone Usage 🌸

the xhc-hb04 program can be run from the command line without LinuxCNC to test a pendant in a simulation mode. this standalone mode is used to identify the button codes produced for each button press, and to verify proper counting of the jog wheel. the identified button codes can be used to create a button-cfg-file. when a button-cfg-file exists, pendant operation can be verified using the -I option to specify the file. 🫶

Usage:

$ xhc-hb04 [options]

⭐ Options ⭐

  • -h — list command line options and exit
  • -I button-cfg-file — (see below for file format)
  • -H — run in real-time HAL mode (simulation mode is default)
  • -x — wait for pendant detection before creating HAL pins.
  • -s n — n is one of the following stepsize sequences
    • 1: 1,10,100,1000 (default)
    • 2: 1,5,10,20
    • 3: 1,10,100
    • 4: 1,5,10,20,50,100
    • 5: 1,10,50,100,1000
    • The stepsize selected is always multiplied by 0.001

💜 button-cfg-file format 💜

standard configuration files are provided in the distribution for known button configurations:

/usr/share/linuxcnc/hallib/xhc-hb04-layout1.cfg
/usr/share/linuxcnc/hallib/xhc-hb04-layout2.cfg

or for a RIP build:

rip_base_dir/lib/hallib/xhc-hb04-layout1.cfg
rip_base_dir/lib/hallib/xhc-hb04-layout2.cfg

layout1 describes the 16 button pendant, layout2 describes the more common 18 button pendant.

the button configuration file follows the same format as INI files but should use a file suffix of .cfg.

File format:

[XHC-HB04]
BUTTON=X1:button-thename1
BUTTON=X2:button-thename2
BUTTON=X3:button-thename3
etc.

XN is the code reported for a button press and button-thenameN is the name to be assigned to the pin created for the button. 🍓

🔥 HAL Usage 🔥

use the -H option to specify HAL mode and other options as required:

loadusr -W  xhc-hb04 -H [Options]

Example: loadusr -W xhc-hb04 -H -I path_to_cfg_file -s 2

💅 Input Pins (Control) 💅

  • (bit in) xhc-hb04.stepsize-up — a 1 pulse on this pin changes the stepsize to the next higher stepsize in the stepsize sequence specified in the xhc-hb04 (loadusr) command.
  • (bit in) xhc-hb04.stepsize-down — a 1 pulse on this pin changes the stepsize to the next lower stepsize in the stepsize sequence specified in the xhc-hb04 (loadusr) command.

🦋 Input Pins (to the pendant LCD display) 🦋

  • (float in) xhc-hb04.[xyza].pos-absolute — absolute position display. the LCD display for pos-absolute is fixed format with a sign, 4 number digits and 3 fraction digits (+XXXX.XXX), require: -9999.999 <= value <= 9999.999 (typically connect to: halui.axis.N.pos-feedback).
  • (float in) xhc-hb04.[xyza].pos-relative — relative position display (typically connect to: halui.axis.N.pos-relative). the LCD display for pos-relative is fixed format with a sign, 4 number digits and 3 fraction digits (+XXXX.XXX), require: -9999.999 <= value <= 9999.999.
  • (float in) xhc-hb04.feed-override — feed-override value. the float value is converted to a 16 bit integer and multiplied by 100 in order to display as percent, require: 0 <= pinvalue <= 655 (typically connect to: halui.feed-override.value).
  • (float in) xhc-hb04.feed-value — current Feed-value (units/sec). the float value is converted to a 16 bit integer and multiplied by 60 in order to display as units-per-minute, require: 0 <= pinvalue <= 1092 (65520 units-per-minute) (typically connect to: motion.current-vel).
  • (float in) xhc-hb04.spindle-override — spindle-override value. the float value is converted to a 16 bit integer and multiplied by 100 in order to display as percent, require: 0 <= pinvalue <= 655) (typically connect to: halui.spindle-override.value).
  • (float in) xhc-hb04.spindle-rps — spindle speed in RPS (revolutions per second). the float value is converted to a 16 bit integer and multiplied by 60 in order to display as RPMs, require: 0 <= pinvalue <= 1092 (65520 RPM) (typically connect to: spindle.N.speed-out-rps-abs).
  • (bit in) xhc-hb04.inch-icon — use inch icon (default is mm):

👑 Output Pins (Status) 👑

  • (bit out) xhc-hb04.sleeping — True when the driver receives a pendant inactive (sleeping) message.
  • (bit out) xhc-hb04.jog.enable-off — True when the pendant rotary selector switch is in the OFF position or when the pendant is sleeping.
  • (bit out) xhc-hb04.enable-[xyza] — True when the pendant rotary selector switch is in the [xyza] position and not sleeping.
  • (bit out) xhc-hb04.enable-spindle-override — True when the pendant rotary selector switch is in the Spindle position and not sleeping (typically connect to: halui.spindle-override-count-enable).
  • (bit out) xhc-hb04.enable-feed-override — True when the pendant rotary selector switch is in the feed position and not sleeping (typically connect to: halui.feed-override-count-enable).
  • (bit out) xhc-hb04.connected — True when connection to the pendant is established over the USB interface.
  • (bit out) xhc-hb04.require_pendant — True if driver started with the -x option.
  • (s32 out) xhc-hb04.stepsize — current stepsize in the stepsize sequence as controlled by the stepsize-up and/or stepsize-down pins.

🌈 Output Pins (for jogging using axis.N.jog-counts) 🌈

  • (s32 out) xhc-hb04.jog.counts — number of counts of the wheel since start-up (50 counts per wheel revolution) (typically connect to axis.N.jog-counts (lowpass filtering may be helpful)).
  • (s32 out) xhc-hb04.jog.counts-neg — the value of the xhc-hb04.jog.counts multiplied by -1.
  • (float out) xhc-hb04.jog.scale — value is the current stepsize multiplied by 0.001 (typically connect to axis.N.jog-scale).

🧚 Experimental: Pins for halui plus/minus jogging. 🧚

these pins provide some support for non-trivkins, world mode jogging.

  • (float in) xhc-hb04.jog.max-velocity — connect to halui.max-velocity.value.
  • (float out) xhc-hb04.jog.velocity — connect to halui.jog-speed.
  • (bit out) xhc-hb04.jog.plus-[xyza] — connect to halui.jog.N.plus.
  • (bit out) xhc-hb04.jog.minus-[xyza] — connect to halui.jog.N.minus.
  • (float out) xhc-hb04.jog.increment — debug pin — abs(delta_pos).

🍓 Button output pins (for the 18 button, layout2 pendant) 🍓

the output bit type pins are TRUE when the button is pressed. 👑

ROW 1

  • (bit out) xhc-hb04.button-reset
  • (bit out) xhc-hb04.button-stop

ROW 2

  • (bit out) xhc-hb04.button-goto-zero
  • (bit out) xhc-hb04.button-rewind
  • (bit out) xhc-hb04.button-start-pause
  • (bit out) xhc-hb04.button-probe-z

ROW 3

  • (bit out) xhc-hb04.button-spindle
  • (bit out) xhc-hb04.button-half
  • (bit out) xhc-hb04.button-zero
  • (bit out) xhc-hb04.button-safe-z

ROW 4

  • (bit out) xhc-hb04.button-home
  • (bit out) xhc-hb04.button-macro-1
  • (bit out) xhc-hb04.button-macro-2
  • (bit out) xhc-hb04.button-macro-3

ROW 5

  • (bit out) xhc-hb04.button-step
  • (bit out) xhc-hb04.button-mode
  • (bit out) xhc-hb04.button-macro-6
  • (bit out) xhc-hb04.button-macro-7

✨ Synthesized button pins ✨

additional buttons are synthesized for buttons named zero, goto-zero, and half. these synthesized buttons are active when the button is pressed AND the selector-switch is set to the corresponding axis [xyza]. 🔥

  • (bit out) xhc-hb04.button-zero-[xyza]
  • (bit out) xhc-hb04.button-goto-zero-[xyza]
  • (bit out) xhc-hb04.button-half-[xyza]

💀 DEBUGGING 💀

for debugging USB activity, use environmental variable LIBUSB_DEBUG:

export LIBUSB_DEBUG=[2 | 3 | 4]; xhc-hb04 [options]
        2:warning, 3:info, 4:debug

🌈 SIM CONFIGS 🌈

okay so bestie, here's the part where they feed you — the distribution ships with a whole lil bundle of simulation configurations, and they live right here:

/usr/share/doc/linuxcnc/examples/sample-configs/sim/axis/xhc-hb04/

or, if you're running a RIP build 🍓:

rip_base_dir/configs/sim/axis/xhc-hb04/

These configs are not doing it alone — they lean on a distribution-provided script called xhc-hb04.tcl to configure the pendant and wire up all the necessary HAL connections, all based on a bunch of INI file settings. That script also pulls in an additional HAL component, xhc_hb04_util, to handle the common functionality, and it comes with support for a standard method for the start-pause button. iconic behavior tbh ✨

The settings you get to play with are:

  1. specify button-cfg-file for standard layout1 or layout2
  2. select axes (up to 4 axes from set of x y z a b c u v w)
  3. implement per-axis filtering coefficients
  4. implement per-axis acceleration for mpg jogging
  5. implement per-axis scale settings
  6. select normal or velocity based jog modes
  7. select stepsize sequence
  8. option to initialize pin for inch or mm display icon
  9. option to require pendant on startup

and the sim configs also show off button connections that:

  1. connect pendant stepsize-up button to the step input pin.
  2. connect buttons to halui.* pins
  3. connect buttons to motion.* pins

There's also another script bundled in that monitors the pendant and reports any loss of USB connectivity 👀 (so you're not sitting there wondering why your lil buddy went silent). Check the README and .txt files in that directory above for how to actually use it.

Note: The sim configs use the AXIS GUI, but the scripts are available with any HAL configuration or GUI. The same scripts can be used to adapt the xhc-hb04 to existing configurations, provided that the halui, motion, and axis.N pins needed are not otherwise claimed. Instructions are included in the README file in the directory named above.

Want to peek at the pins and signals that the xhc-hb04.tcl script is using? just hit it with halcmd, she's easy:

halcmd show pin xhc-hb04       (show all xhc-hb04 pins)
halcmd show pin pendant_util   (show all pendant_util pins)
halcmd show sig pendant:       (show all pendant signals)

periodt. that's the whole vibe check on the sim configs 💅

👑 AUTHOR 👑

  • Frederick Rible (frible@teaser.fr) 🫶

and that's a wrap on the whole page bestie!! 🌸🦋 this doc came from the LinuxCNC Documentation, dated 2015-03-06, and it's page XHC-HB04(1) — go forth and slay your pendant setup, you've absolutely got this 💖✨

📦 where this page comes from