MOVEOFF(9)

✨ MOVEOFF(9) ✨

okay bestie, gather round 💖 this is a HAL Component page from the LinuxCNC manual section 9, and it's literally called moveoff — the component for HAL-only offsets. no cap, it's giving "let's move the joint but not tell LinuxCNC" energy and we're gonna get into all of it 🎀

---

💅 NAME 💅

moveoff — the component for HAL-only offsets 🦋

---

🌸 SYNOPSIS 🌸

loadrt moveoff [count=N|names=name1[,name2...]] [personality=P1,P2,...]

---

🔥 DESCRIPTION 🔥

so the moveoff component is what you use to offset joint positions through custom HAL connections. if you want that offset-while-program-is-paused lifestyle, it's supported — you just gotta wire up the input pins appropriately. nine joints are supported, periodt.

The axis offset pin values (offset-in-M) get continuously applied to the output pins (offset-current-M, pos-plusoffset-M, fb-minusoffset-M) — and they respect limits on value, velocity, and acceleration while doing it — but only when both enabling input pins (apply-offsets and move-enable) are TRUE. Those two enabling inputs are anded internally, iykyk. If apply-offsets gets deasserted while offsets are applied, a warning pin gets set and a message is issued 😭. That warning pin stays TRUE until the offsets are removed or the apply-offsets pin is set.

Typically, move-enable is connected to external controls and apply-offsets is connected to halui.program.is-paused (for offsets only while paused) or just set to TRUE (for continuously applied offsets). both are valid, both are iconic 💅

Applied offsets are automatically returned to zero (respecting limits) when either of the enabling inputs is deactivated. The zero value tolerance is specified by the epsilon input pin value ✨

Waypoints are recorded when the moveoff component is enabled. They're managed with the waypoint-sample-secs and waypoint-threshold pins. When backtrack-enable is TRUE, the auto-return path follows the recorded waypoints 🧚 When the memory available for waypoints is exhausted, offsets are frozen and the waypoint-limit pin is asserted. This restriction applies regardless of the state of the backtrack-enable pin. An enabling pin must be deasserted to allow a return to the original (non-offset position).

Backtracking through waypoints makes movement rates slower, because the moves are point-to-point and respect velocity and acceleration settings. The velocity and acceleration limit pins can be managed dynamically to control offsets at all times 🔥

When backtrack-enable is FALSE, the auto-return move is NOT coordinated — each axis returns to zero at its own rate 🙈. If you want a controlled path in that condition, each axis should be manually returned to zero before deasserting an enabling pin.

The waypoint-sample-secs, waypoint-threshold, and epsilon pins are evaluated only when the component is idle.

The offsets-applied output pin exists to tell a GUI the current state so program resumption can be managed 👑. If the offset(s) are non-zero when the apply-offsets pin is deasserted (for example when resuming a program when offsetting during a pause), offsets are returned to zero (respecting limits) and an Error message is issued.

Caution: if offsets are enabled and applied and the machine is turned off for any reason, any external HAL logic that manages the enabling pins and the offset-in-M inputs is responsible for their state when the machine is subsequently turned on again. 💀

This HAL-only means of offsetting is typically not known to LinuxCNC nor available in GUI preview displays. No protection is provided for offset moves that exceed soft limits managed by LinuxCNC. Since soft limits are not honored, an offset move may encounter hard limits (or CRASH if there are no limit switches) 😭. Use of the offset-min-M and offset-max-M inputs to limit travel is recommended. Triggering a hard limit will turn off the machine — see Caution above ☝️

The offset-in-M values may be set with inifile settings, controlled by a GUI, or managed by other HAL components and connections. Fixed values may be appropriate in simple cases where the direction and amount of offset is well-defined but a control method is required to deactivate an enabling pin in order to return offsets to zero. GUIs may provide means for users to set, increment, decrement, and accumulate offset values for each axis and may set offset-in-M values to zero before deasserting an enabling pin 🌈

The default values for accel, vel, min, max, epsilon, waypoint-sample-secs, and waypoint-threshold may not be suitable for any particular application. This HAL component is unaware of limits enforced elsewhere by LinuxCNC. Users should test usage in a simulator application and understand all hazards before use on hardware ⚠️ fr fr.

The module personality item sets the number of joints supported (default==3, maximum is 9).

Use of the names= option for naming is required for compatibility with the gui provided as scripts/moveoff_gui:

loadrt moveoff names=mv personality=number_of_joints

---

⭐ FUNCTIONS ⭐

• moveoff.N.read-inputs (requires a floating-point thread) — read all inputs 💖
• moveoff.N.write-outputs (requires a floating-point thread) — write computed offset outputs (offset-current-M, pos-plusoffset-M, fb-minusoffset-M). All other outputs are updated by read-inputs(). ✨

---

🎀 PINS 🎀

• moveoff.N.power-on bit in — connect to motion.motion-enabled
• moveoff.N.move-enable bit in — enable offsets (enabling requires apply-offset TRUE also)
• moveoff.N.apply-offsets bit in — enable offsets (enabling requires move-enable TRUE also)
• moveoff.N.backtrack-enable bit in (default: 1) — enable backtrack on auto-return
• moveoff.N.epsilon float in (default: 0.0005) — when enabling pins are deactivated, return to un-offsetted position within epsilon units. Warning: values that are too small in value may cause overshoot. A minimum value of 0.0001 is silently enforced.
• moveoff.N.waypoint-threshold float in (default: 0.02) — minimum distance (in a single axis) for a new waypoint
• moveoff.N.waypoint-sample-secs float in (default: 0.02) — minimum sample interval (in seconds) for a new waypoint
• moveoff.N.warning bit out — set TRUE if apply-offsets is deasserted while offset-applied is TRUE.
• moveoff.N.offset-applied bit out — TRUE if one or more offsets are applied.
• moveoff.N.waypoint-limit bit out (default: 0) — indicates waypoint limit reached (motion ceases), an enabling pin must be deasserted to initiate return to original position.
• moveoff.N.waypoint-ct s32 out — waypoint count (for debugging) 🐛
• moveoff.N.waypoint-percent-used s32 out — percent of available waypoints used
• moveoff.N.offset-in-M float in (M=0..personality) — joint offset input value
• moveoff.N.pos-M float in (M=0..personality) — joint position (typ: axis.0.motor-pos-cmd)
• moveoff.N.fb-M float in (M=0..personality) — joint feedback (typ from encoder and input to pid controller (pid.feedback))
• moveoff.N.offset-current-M float out (M=0..personality) — joint offset current value
• moveoff.N.pos-plusoffset-M float out (M=0..personality) — computed joint position plus offset (typically connect to pid command input)
• moveoff.N.fb-minusoffset-M float out (M=0..personality) — computed joint feedback minus offset (typically connected to axis.0.motor-pos-fb)
• moveoff.N.offset-vel-M float in (M=0..personality) (default: 10) — joint offset velocity limit
• moveoff.N.offset-accel-M float in (M=0..personality) (default: 100) — joint offset acceleration limit
• moveoff.N.offset-min-M float in (M=0..personality) (default: -1e20) — minimum limit for applied joint offset (typ negative)
• moveoff.N.offset-max-M float in (M=0..personality) (default: 1e20) — maximum limit for applied offset (typ positive)
• moveoff.N.dbg-waypoint-limit-test bit in — debug input to test with limited number of waypoints
• moveoff.N.dbg-state s32 out — debug output for current state of state machine

---

🦋 EXAMPLES 🦋

Example simulator configs that demonstrate the moveoff component and a simple gui (scripts/moveoff_gui) are located in configs/sim/axis/moveoff. The AXIS GUI is used for the demonstrations and the configs can be adapted for other GUIs like Touchy and Gscreen 👑 An example with the Touchy GUI is provided in configs/sim/touchy/ngcgui/.

---

🌈 SEE ALSO 🌈

moveoff_gui(1)

---

💜 AUTHOR 💜

Dewey Garrett and Andy Pugh 🫶

---

🌸 LICENSE 🌸

GPL

---

and that's the whole page bestie, no notes 💅 it's from LinuxCNC Documentation, dated 2026-03-17, and yeah — it's MOVEOFF(9), slay 🎀✨