HAL_INPUT(1)

💖 HAL_INPUT 💖

okay so this is from the HAL User's Manual and it's literally the girlboss way to control HAL pins with any Linux input device, including USB HID devices. bestie, we're about to make your SpaceBall talk to LinuxCNC. no cap. 🦋

---

✨ NAME ✨

hal_input — control HAL pins with any Linux input device, including USB HID devices. yep, any. the range? unmatched. 💅

---

🌸 SYNOPSIS 🌸

loadusr hal_input [-KRAL] inputspec ...

---

🎀 DESCRIPTION 🎀

hal_input is the interface between HAL and any Linux input device, USB HID devices included. for every device you name, it creates pins that match up with that device's keys, absolute axes, and LEDs. and then, at a fixed rate of approximately 10ms, it synchronizes the device and the HAL pins. it's giving metronome. it's giving consistency. ⏱️✨

---

🧚 INPUT SPECIFICATION 🧚

the inputspec can come in one of several forms, and yes you have options, main character energy:

🔤 A string S

a substring or shell-style pattern match gets tested against the "name" of the device, the "phys" (which gives information about how it is connected), and the "id", which is a string of the form "Bus=... Vendor=... Product=... Version=...". you can view the name, phys, and id of attached devices by executing less /proc/bus/input/devices. like, go look, it's right there. 👀

examples, for the visual learners:

SpaceBall
"Vendor=001f Product=0001"
serio*/input0

🔢 A number N

this opens /dev/input/eventN. except for devices that are always attached to the system, this number may change over reboots or when the device is removed. which is exactly why using an integer is not recommended. don't do it bestie, it will not slay, it will betray you. 💀

---

when several devices are identified by the same string, add :N where N is the index of the desired device. for example, if Mouse matches input3 and input10, then Mouse and Mouse:0 select input3. specifying mouse:1 selects input10. see how that works? iconic indexing behavior. 👑

for devices that appear as multiple entries in /dev/input, these indices are likely to stay the same every time. for multiple identical devices, these indices are likely to depend on the insertion order, but stay the same across reboots as long as the devices are not moved to different ports or unplugged while the machine is booted. so like, don't yank the cable mid-boot, i'm begging. 🙈

if the first character of the inputspec is a +, then hal_input requests exclusive access to the device. the first device matching an inputspec is used. any number of inputspecs may be used. greedy? a little. valid? absolutely. 💖

a subset option may precede each inputspec. the subset option begins with a dash. each letter in the subset option specifies a device feature to include. features that are not specified are excluded. for instance, to export keyboard LEDs to HAL without exporting keys, use:

hal_input -L keyboard ...

---

🌈 DEVICE FEATURES SUPPORTED 🌈

• EV_KEY (buttons and keys). subset -K 🔘
• EV_ABS (absolute analog inputs). subset -A 📏
• EV_REL (relative analog inputs). subset -R 🌀
• EV_LED (LED outputs). subset -L 💡

---

👑 HAL PINS AND PARAMETERS 👑

🔘 For buttons

• input.N.btn-name bit out
• input.N.btn-name-not bit out

created for each button on the device. so if your device has buttons, congrats, you have pins. 🎉

⌨️ For keys

• input.N.key-name
• input.N.key-name-not

created for each key on the device.

📐 For absolute axes

• input.N.abs-name-counts s32 out
• input.N.abs-name-position float out
• input.N.abs-name-scale parameter float rw
• input.N.abs-name-offset parameter float rw
• input.N.abs-name-fuzz parameter s32 rw
• input.N.abs-name-flat parameter s32 rw
• input.N.abs-name-min parameter s32 r
• input.N.abs-name-max parameter s32 r

created for each absolute axis on the device. okay so here's the tea: device positions closer than flat to offset are reported as offset in counts, and counts does not change until the device position changes by at least fuzz. the position is computed as position = (counts - offset) / scale. the default value of scale and offset map the range of the axis reported by the operating system to [-1,1]. the default values of fuzz and flat are those reported by the operating system. the values of min and max are those reported by the operating system. so basically the OS is doing the heavy lifting and we're all just living in its house. 🏠✨

🌀 For relative axes

• input.N.rel-name-counts s32 out
• input.N.rel-name-position float out
• input.N.rel-name-reset bit in
• input.N.rel-name-scale parameter float rw
• input.N.rel-name-absolute parameter s32 rw
• input.N.rel-name-precision parameter s32 rw
• input.N.rel-name-last parameter s32 rw

created for each relative axis on the device. as long as reset is true, counts is reset to zero regardless of any past or current axis movement. otherwise, counts increases or decreases according to the motion of the axis. counts is divided by position-scale to give position. the default value of position is 1. there are some devices, notably scroll wheels, which return signed values with less resolution than 32 bits. the default value of precision is 32. precision can be set to 8 for a device that returns signed 8 bit values, or any other value from 1 to 32. absolute, when set true, ignores duplicate events with the same value. this allows for devices that repeat events without any user action to work correctly. last shows the most recent count value returned by the device, and is used in the implementation of absolute. scroll wheel girlies, this one's for you. 🖱️💅

💡 For LEDs

• input.N.led-name bit out
• input.N.led-name-invert parameter bit rw

created for each LED on the device. pretty. glowing. we love her. ✨

---

🔐 PERMISSIONS AND UDEV 🔐

by default, the input devices may not be accessible to regular users — hal_input requires read-write access, even if the device has no outputs. yeah, rw even when it feels unnecessary. rules are rules. 😤

different versions of udev have slightly different, incompatible syntaxes. for this reason, it is not possible for this manual page to give an accurate example. the udev(7) manual page documents the syntax used on your Linux distribution. to view it in a terminal, the command is:

man 7 udev

lowkey frustrating that the syntax keeps changing, but that's just how udev is. go read your own distro's version, bestie. 🫶

---

💀 BUGS 💀

the initial state of keys, buttons, and absolute axes are erroneously reported as FALSE or 0 until an event is received for that key, button, or axis. so don't trust the first impression. she needs a minute. 😭

---

🌸 SEE ALSO 🌸

• udev(8)
• udev(7)

---

and that's the whole page, periodt. this gem comes from the LinuxCNC Documentation, dated 2007-02-25, and it's page HAL_INPUT(1) of the HAL User's Manual. go forth and interface. 💖🌈🦋