SHUTTLE(1)

✨ SHUTTLE ✨

okay bestie, gather round, because this one is a whole vibe 💅 it lives in the HAL User's Manual, and it's called SHUTTLE(1) — yes, all caps, main character energy only 🔥

---

🦋 NAME 🦋

shuttle — control HAL pins with the ShuttleXpress, ShuttlePRO, and ShuttlePRO2 device made by Contour Design. periodt.

---

🌸 SYNOPSIS 🌸

loadusr shuttle [DEVICE ...]

that's it, that's the whole summoning ritual ✨

---

💖 DESCRIPTION 💖

so shuttle is a non-realtime HAL component, and what it does is interface Contour Design's ShuttleXpress, ShuttlePRO, and ShuttlePRO2 devices with LinuxCNC's HAL. it's giving matchmaker, honestly 🫶

if the driver is started without command-line arguments, it will probe all /dev/hidraw* device files for Shuttle devices, and use all devices found. if it is started with command-line arguments, it will only probe the devices specified. no cap.

now let's talk about the devices themselves, because they are each a little icon 👑

• the ShuttleXpress has five momentary buttons, a 10 counts/revolution jog wheel with detents, and a 15-position spring-loaded outer wheel that returns to center when released.
• the ShuttlePRO has 13 momentary buttons, a 10 counts/revolution jog wheel with detents, and a 15-position spring-loaded outer wheel that returns to center when released.
• the ShuttlePRO2 has 15 momentary buttons, a 10 counts/revolution jog wheel with detents, and a 15-position spring-loaded outer wheel that returns to center when released.

like… the wheel math is identical across all three, only the button count is doing the growing 💀

---

🎀 UDEV 🎀

the shuttle driver needs read permission to the Shuttle devices' /dev/hidraw* device files. the way you do that is by adding a file /etc/udev/rules.d/99-shuttle.rules, with the following contents:

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0b33", ATTRS{idProduct}=="0020", MODE="0444"

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="05f3", ATTRS{idProduct}=="0240", MODE="0444"

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0b33", ATTRS{idProduct}=="0030", MODE="0444"

the LinuxCNC Debian package installs an appropriate udev file automatically, but if you are building LinuxCNC from source and are not using the Debian packaging, you'll need to install this file by hand. 🙈

and if you install the file by hand, you'll also need to tell udev to reload its rules files by running udevadm control --reload-rules. don't skip this step bestie, it's the "press send" of the whole operation 📨

---

⚠️ A warning about the Jog Wheel ⚠️

okay this part is important so listen up 🫢

the Shuttle devices have an internal 8-bit counter for the current jog-wheel position. the shuttle driver can not know this value until the Shuttle device sends its first event. when the first event comes into the driver, the driver uses the device's reported jog-wheel position to initialize counts to 0.

which means: if the first event is generated by a jog-wheel move, that first move will be lost. 💀 gone. never happened. rip to that one click.

but here's the slay part — any user interaction with the Shuttle device will generate an event, informing the driver of the jog-wheel position. so if you (for example) push one of the buttons at startup, the jog-wheel will work fine and notice the first click. little ritual, big payoff ✨

---

👑 Pins 👑

all HAL pin names are prefixed with shuttle followed by the index of the device (the order in which the driver found them), for example "shuttle.0" or "shuttle.2". so like, the vibes are numbered 🧚

• (bit out) (prefix).button-(number)
• (bit out) (prefix).button-(number)-not — the momentary buttons. (number) identifies which button corresponds to the HAL pin. the button-(number) pins are True when the button is pushed, and the button-(number)-not pins are True when the button is not pushed.
• (s32 out) (prefix).counts — accumulated counts from the jog wheel (the inner wheel). 🌀
• (s32 out) (prefix).spring-wheel-s32 — the current deflection of the spring-wheel (the outer wheel). it's 0 at rest, and ranges from -7 at the counter-clockwise extreme to +7 at the clockwise extreme.
• (float out) (prefix).spring-wheel-f — the current deflection of the spring-wheel (the outer wheel). it's 0.0 at rest, -1.0 at the counter-clockwise extreme, and +1.0 at the clockwise extreme. (the Shuttle devices report the spring-wheel position as an integer from -7 to +7, so this pin reports only 15 discrete values in its range.) lowkey a glow-down in resolution but we still love her 💜

---

and that's the whole page, bestie!! 🌈 this beauty comes to you from the LinuxCNC Documentation, dated 2011-01-13 — old money, timeless energy, still eating 💅✨ bye!! 🎀🦋