MOTION(9)

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

okay bestie, welcome to MOTION(9) from the HAL Component section 💖 this is the manual page for motion, and it's literally the realtime motion module that accepts NML motion commands and interacts with HAL in realtime. no cap, it's giving main character energy for your CNC. 🎀

💖 NAME 💖

motion — accepts NML motion commands, interacts with HAL in realtime. periodt.

✨ SYNOPSIS ✨

so you load it like this, and yes the line breaks are exactly like this:

loadrt motmod [base_period_nsec=period] [base_thread_fp=0 or 1]
[servo_period_nsec=period] [traj_period_nsec=period] [num_joints=[1-16]]
[num_dio=[1-64]] [num_aio=[1-64]] [num_misc_error=[0-64] |
names_misc_errors] [num_spindles=[1-8]]  [unlock_joints_mask=jointmask]
[num_extrajoints=[0-16]]

here's the full vibe check on those loadrt args, one by one:

  • [base_period_nsec=period]
  • [base_thread_fp=0 or 1]
  • [servo_period_nsec=period]
  • [traj_period_nsec=period]
  • [num_joints=[1-16]]
  • [num_dio=[1-64]]
  • [num_aio=[1-64]]
  • [num_misc_error=[0-64] | names_misc_errors]
  • [num_spindles=[1-8]]
  • [unlock_joints_mask=jointmask]
  • [num_extrajoints=[0-16]]
the limits for the following items are compile-time settings, so don't try to fight them:
  • num_joints: maximum number of joints is set by EMCMOT_MAX_JOINTS.
  • num_dio: maximum number of digital inputs is set by EMCMOT_MAX_DIO.
  • num_aio: maximum number of analog inputs is set by EMCMOT_MAX_AIO.
  • num_misc_error: maximum number of extra error inputs is set by EMCMOT_MAX_MISC_ERRORS.
  • names_misc_errors: a comma-separated list of names for extra error inputs.
    • this parameter is mutually exclusive with num_misc_error. if you're using num_misc_error the additional error input pins will have names like motion.misc-error-00 whereas names_misc_errors=overtemp,undertemp will create hal pins motion.err-overtemp and motion.err-undertemp.
  • num_spindles: maximum number of spindles is set by EMCMOT_MAX_SPINDLES.

optionally the number of Digital I/O is set with num_dio. the number of Analog I/O is set with num_aio. the default is 4 each. 💅

pin names starting with "joint" or "axis" are read and updated by the motion-controller function.

🌸 DESCRIPTION 🌸

by default, the base thread does not support floating point. software stepping, software encoder counting, and software pwm do not use floating point. base_thread_fp can be used to enable floating point in the base thread (for example for brushless DC motor control). fr fr.

these pins and parameters are created by the realtime motmod module. this module provides a HAL interface for LinuxCNC's motion planner. basically motmod takes in a list of waypoints and generates a nice blended and constraint-limited stream of joint positions to be fed to the motor drives. it's iconic, honestly.

the optional num_extrajoints parameter specifies a quantity of joints that participate in homing but are not used by kinematics transformations. after homing, control of an 'extra' joint is transferred to a posthome command HAL pin (joint.N.posthome-cmd) and the motor feedback value is ignored. 'extra' joints must be managed by independent motion planners/controllers (typically using limit3 HAL components). extra joints maybe unhomed only when motion is disabled. periodt.

the maximum num_extrajoints value is equal to the num_joints value. (note that using the maximum value would allow no operation in world coordinates). the num_joints value must be equal to the sum of the number of joints used for kinematics calculations plus the number of 'extra' joints.

the num_joints parameter is conventionally set using the INI file setting [KINS]JOINTS=value. the num_extrajoints is set by the additional motmod parameter [EMCMOT]motmod num_extrajoints=value. Hal pin numbering for all joints is zero based [0 ... num_joints-1]. when specified, 'extra' joints are assigned the last num_extrajoints in the numbering sequence. for example, specifying [KINS]JOINTS=5 and [EMCMOT]motmod num_extrajoints=2 for a 3 joint trivkins configuration [KINS] KINEMATICS=trivkins coordinates=xyz uses joints 0,1,2 for the kinematic joints and joints 3,4 for the 'extra' joints. 💖

💖 MOTION PINS 💖

okay bestie, here come the pins the motion module itself is serving. every single one, no skipping, we're thorough in this house. 💅

  • motion-command-handler.time OUT S32 — time (in CPU clocks) for the motion module motion-command-handler. yes it's a pin name with a dash instead of a dot, that's just how it is, don't @ me.
  • motion-controller.time OUT S32 — time (in CPU clocks) for the motion module motion-controller.
  • motion.adaptive-feed IN FLOAT — when adaptive feed is turned on with M52 P1, the commanded velocity gets multiplied by this value. this stacks multiplicatively with the NML-level feed override value and motion.feed-hold. and listen — negative values are valid and they will run the G-code path in reverse. iconic behaviour honestly. 🔄
  • motion.analog-in-NN IN FLOAT — these pins are used by the M66 Enn wait-for-input mode.
  • motion.analog-out-NN OUT FLOAT — these pins are used by M67-68.
  • motion.coord-error OUT BIT — TRUE when motion has hit an error, like exceeding a soft limit. 🚨
  • motion.coord-mode OUT BIT — TRUE when motion is in "coordinated mode", as opposed to "teleop mode".
  • motion.current-vel OUT FLOAT — current cartesian velocity.
  • motion.digital-in-NN IN BIT — these pins are used by M66 Pnn wait-for-input mode.
  • motion.digital-out-NN OUT BIT — these pins are controlled by the M62 through M65 words.
  • motion.distance-to-go OUT FLOAT — distance remaining in the current move.
  • motion.enable IN BIT — if this bit gets driven FALSE, motion stops, the machine goes into the "machine off" state, and a message pops up for the operator. for normal motion, drive this bit TRUE. 💅
  • motion.eoffset-active OUT BIT — says external offsets are active (non-zero).
  • motion.eoffset-limited OUT BIT — says motion with external offsets was limited by a soft limit constraint ([AXIS_L]MIN_LIMIT,MAX_LIMIT).
  • motion.feed-hold IN BIT — when Feed Stop Control is enabled with M53 P1, and this bit is TRUE, the feed rate is set to 0.
note: feed-hold applies to G-code commands — not jogs.
  • motion.feed-inhibit IN BIT — when this pin is TRUE, machine motion is inhibited for G-code commands.

if the machine is doing a spindle synchronized move when this pin goes TRUE, the spindle synchronized motion will finish, and any following moves will be inhibited (this is to prevent damage to the machine, the tool, or the work piece 🫣).

if the machine is in the middle of a (non-spindle synchronized) move when this pin goes TRUE, the machine will decelerate to a stop at the maximum allowed acceleration rate.

motion resumes when this pin goes FALSE.

note: feed-inhibit applies to G-code commands — not jogs.
  • motion.feed-upm OUT FLOAT — current feed rate in G-code program units per minute for motion.motion-type feed(2) and arc(3). the value is the G-code program F value multiplied by the current feed override value and the motion.adaptive-feed setting (if M52 is active). the value is zero if motion.feed-hold or motion.feed-inhibit are asserted. and if units (G20 or G21) aren't specified in the G-code file then units will be the last units used.
  • motion.feed-inches-per-minute OUT FLOAT — current feed rate in inches per minute for motion.motion-type feed(2) and arc(3). value is the inch equivalent of the G-code program F value multiplied by the current feed override value and the motion.adaptive-feed setting (if M52 active). value is zero if motion.feed-hold or motion.feed-inhibit are asserted.
  • motion.feed-inches-per-second OUT FLOAT — current feed rate in inches per second for motion.motion-type feed(2) and arc(3). value is the inch equivalent of the G-code program F value multiplied by the current feed override value and the motion.adaptive-feed setting (if M52 active). value is zero if motion.feed-hold or motion.feed-inhibit are asserted.
  • motion.feed-mm-per-minute OUT FLOAT — current feed rate in mm per minute for motion.motion-type feed(2) and arc(3). value is the mm equivalent of the G-code program F value multiplied by the current feed override value and the motion.adaptive-feed setting (if M52 active). value is zero if motion.feed-hold or motion.feed-inhibit are asserted.
  • motion.feed-mm-per-second OUT FLOAT — current feed rate in mm per second for motion.motion-type feed(2) and arc(3). value is the mm equivalent of the G-code program F value multiplied by the current feed override value and the motion.adaptive-feed setting (if M52 active). value is zero if motion.feed-hold or motion.feed-inhibit are asserted.
  • motion.homing-inhibit IN BIT — if this bit is TRUE, starting any joint homing move (including "Home All") is disallowed and an error is reported. by default, homing is allowed in joint mode whenever motion is enabled.
  • motion.is-all-homed OUT BIT — TRUE if all active joints is homed.
  • motion.jog-inhibit IN BIT — if this bit is TRUE, jogging of any joint or axis is disallowed and an error is reported. 🙅
  • motion.jog-stop IN BIT — if any jog is active when the pin state changes to TRUE, then that jog will be stopped following the associated acceleration values.
  • motion.jog-stop-immediate IN BIT — if any jog is active when the pin state changes to TRUE, then that jog will be stopped immediately. no decel, just vibes ending. 💀
  • motion.jog-is-active OUT BIT — TRUE if any joint or axis is jogging.
  • motion.in-position OUT BIT — TRUE if the machine is in position (ie, not currently moving towards the commanded position).
  • motion.misc-error-NN IN BIT — extra error inputs for faults like over-temperature sensors, low coolant warnings, custom HAL component errors. if driven TRUE this will disable a machine. similar to spindle.amp-fault-in.
  • motion.motion-enabled OUT BIT — (no description given, she just exists, mysterious queen 👑)
  • motion.motion-type OUT S32 — these values are from src/emc/nml_intf/motion_types.h.
    1. 0 — Idle (no motion)
    2. 1 — Traverse
    3. 2 — Linear feed
    4. 3 — Arc feed
    5. 4 — Tool change
    6. 5 — Probing
    7. 6 — Rotary unlock for traverse
  • motion.on-soft-limit OUT BIT — (also no description, keep it moving 🎀)
  • motion.probe-input IN BIT — G38.n uses the value on this pin to determine when the probe has made contact. TRUE for probe contact closed (touching), FALSE for probe contact open.
  • motion.program-line OUT S32 — the current program line while executing. zero if not running or between lines while single stepping.
  • motion.requested-vel OUT FLOAT — the current requested velocity in user units per second. this value is the F-word setting from the G-code file, possibly reduced to accommodate machine velocity and acceleration limits. the value on this pin does not reflect the feed override or any other adjustments.
  • motion.servo.last-period OUT U32 — the number of CPU clocks between invocations of the servo thread. typically, this number divided by the CPU speed gives the time in seconds, and can be used to determine whether the realtime motion controller is meeting its timing constraints.
  • motion.switchkins-type IN float — kinematics modules that define the functions kinematicsSwitchable() and kinematicsSwitch() receive the integer value of this pin to select the machine kinematics functions. extra G-code commands may be required to synchronize task and motion before and after changes to the pin value.
  • motion.teleop-mode OUT BIT — motion mode is teleop (axis coordinate jogging available).
  • motion.tooloffset.L OUT FLOAT — current tool offset for each axis where (L is the axis letter, one of: x y z a b c u v w).
  • motion.tp-reverse OUT BIT — trajectory planning is reversed (reverse run).

🦋 AXIS PINS 🦋

quick heads up before we dive in: (L is the axis letter, one of: x y z a b c u v w). every one of these gets the L swapped out for whichever axis you're talking about. slay. ✨

  • axis.L.eoffset OUT FLOAT — current external offset.
  • axis.L.eoffset-clear IN BIT — clear external offset request.
  • axis.L.eoffset-counts IN S32 — counts input for external offset. the eoffset-counts are transferred to an internal register. the applied external offset is the product of the register counts and the eoffset-scale value. the register is reset to zero at each machine startup. if the machine is turned off with an external offset active, the eoffset-counts pin should be set to zero before restarting. 🫶
  • axis.L.eoffset-enable IN BIT — enable for external offset (also requires INI file setting for [AXIS_L]OFFSET_AV_RATIO).
  • axis.L.eoffset-request OUT FLOAT — debug pin for requested external offset.
  • axis.L.eoffset-scale IN FLOAT — scale for external offset.
  • axis.L.jog-accel-fraction IN FLOAT — sets acceleration for wheel jogging to a fraction of the INI max_acceleration for the axis. values greater than 1 or less than zero are ignored.
  • axis.L.jog-counts IN S32 — connect to the "counts" pin of an external encoder to use a physical jog wheel. 🎡
  • axis.L.jog-enable IN BIT — when TRUE (and in manual mode), any change to "jog-counts" will result in motion. when false, "jog-counts" is ignored.
  • axis.L.jog-scale IN FLOAT — sets the distance moved for each count on "jog-counts", in machine units.
  • axis.L.jog-vel-mode IN BIT — when FALSE (the default), the jogwheel operates in position mode. the axis will move exactly jog-scale units for each count, regardless of how long that might take. when TRUE, the wheel operates in velocity mode — motion stops when the wheel stops, even if that means the commanded motion is not completed.
  • axis.L.kb-jog-active OUT BIT — (free planner axis jogging active (keyboard or halui))
  • axis.L.pos-cmd OUT FLOAT — the axis commanded position. there may be several offsets between the axis and motor coordinates: backlash compensation, screw error compensation, and home offsets. external offsets are reported separately (axis.L.eoffset).
  • axis.L.teleop-pos-cmd OUT FLOAT — (no description, she's just there 💜)
  • axis.L.teleop-tp-enable OUT BIT — TRUE when the "teleop planner" is enabled for this axis.
  • axis.L.teleop-vel-cmd OUT FLOAT — the axis's commanded velocity.
  • axis.L.teleop-vel-lim OUT FLOAT — the velocity limit for the teleop planner.
  • axis.L.wheel-jog-active OUT BIT — (no description, but she's out here living her best life 🌸)

🦋 JOINT PINS 🦋

okay so N is the joint number and it goes (0 ... num_joints-1)) 💖

🚨 bestie listen — pins marked (DEBUG) are literally just debugging aids and they're subject to change or removal at any time. they could get deleted tomorrow and we'd all have to cope. 🙈
  • joint.N.acc-cmd OUT FLOAT (DEBUG) — the joint's commanded acceleration ✨
  • joint.N.active OUT BIT (DEBUG) — TRUE when this joint is active, like it's awake and doing the thing 🫶
  • joint.N.amp-enable-out OUT BIT — TRUE if the amplifier for this joint should be enabled 🔥
  • joint.N.amp-fault-in IN BIT — you should drive this TRUE if an external fault is detected with the amplifier for this joint 💀
  • joint.N.backlash-corr OUT FLOAT (DEBUG) — backlash or screw compensation raw value
  • joint.N.backlash-filt OUT FLOAT (DEBUG) — backlash or screw compensation filtered value, and yes it respects motion limits 💅
  • joint.N.backlash-vel OUT FLOAT (DEBUG) — backlash or screw compensation velocity
  • joint.N.coarse-pos-cmd OUT FLOAT (DEBUG)
  • joint.N.error OUT BIT (DEBUG) — TRUE when this joint has encountered an error, like a limit switch closing 😭
  • joint.N.f-error OUT FLOAT (DEBUG) — the actual following error
  • joint.N.f-error-lim OUT FLOAT (DEBUG) — the following error limit
  • joint.N.f-errored OUT BIT (DEBUG) — TRUE when this joint has exceeded the following error limit 🚨
  • joint.N.faulted OUT BIT (DEBUG)
  • joint.N.free-pos-cmd OUT FLOAT (DEBUG) — the "free planner" commanded position for this joint
  • joint.N.free-tp-enable OUT BIT (DEBUG) — TRUE when the "free planner" is enabled for this joint
  • joint.N.free-vel-lim OUT FLOAT (DEBUG) — the velocity limit for the free planner
  • joint.N.home-state OUT S32 (DEBUG) — homing state machine state, the whole journey fr
  • joint.N.home-sw-in IN BIT — should be driven TRUE if the home switch for this joint is closed 🏠
  • joint.N.homed OUT BIT (DEBUG) — TRUE if the joint has been homed 🎀
  • joint.N.homing OUT BIT — TRUE if the joint is currently homing, like it's mid-glow-up ✨
  • joint.N.in-position OUT BIT (DEBUG) — TRUE if the joint is using the "free planner" and has come to a stop ✋
  • joint.N.index-enable IO BIT — should be attached to the index-enable pin of the joint's encoder so you can enable homing to index pulse 🌀
  • joint.N.is-unlocked IN BIT — indicates the joint is unlocked (peep the JOINT UNLOCK PINS section below) 🔓
  • joint.N.jog-accel-fraction IN FLOAT — sets acceleration for wheel jogging to a fraction of the INI max_acceleration for the joint. values greater than 1 or less than zero are just ignored, respectfully 💅
  • joint.N.jog-counts IN S32 — connect this to the "counts" pin of an external encoder if you want to use a physical jog wheel 🎡
  • joint.N.jog-enable IN BIT — when TRUE (and you're in manual mode), any change to "jog-counts" will result in motion. when false, "jog-counts" gets ignored entirely 🙈
  • joint.N.jog-scale IN FLOAT — sets the distance moved for each count on "jog-counts", in machine units 📏
  • joint.N.jog-vel-mode IN BIT — when FALSE (that's the default btw), the jogwheel operates in position mode. the joint will move exactly jog-scale units for each count, no matter how long that might take. when TRUE, the wheel operates in velocity mode — motion stops when the wheel stops, even if that means the commanded motion is not completed 👑
  • joint.N.kb-jog-active OUT BIT (DEBUG) — (free planner joint jogging active (keyboard or halui))
  • joint.N.motor-offset OUT FLOAT (DEBUG) — joint motor offset established when the joint is homed
  • joint.N.motor-pos-cmd OUT FLOAT — the commanded position for this joint
  • joint.N.motor-pos-fb IN FLOAT — the actual position for this joint
  • joint.N.neg-hard-limit OUT BIT (DEBUG) — the negative hard limit for the joint
  • joint.N.neg-lim-sw-in IN BIT — should be driven TRUE if the negative limit switch for this joint is tripped
  • joint.N.pos-cmd OUT FLOAT — the joint (as opposed to motor) commanded position. heads up, there may be several offsets between the joint and motor coordinates: backlash compensation, screw error compensation, and home offsets 🧠
  • joint.N.pos-fb OUT FLOAT — the joint feedback position. this value is computed from the actual motor position minus joint offsets. super useful for machine visualization ✨
  • joint.N.pos-hard-limit OUT BIT (DEBUG) — the positive hard limit for the joint
  • joint.N.pos-lim-sw-in IN BIT — should be driven TRUE if the positive limit switch for this joint is tripped
  • joint.N.unlock OUT BIT — TRUE if the axis is a locked joint (typically a rotary) and a move is commanded (see JOINT UNLOCK PINS) 🔓
  • joint.N.vel-cmd OUT FLOAT (DEBUG) — the joint's commanded velocity
  • joint.N.wheel-jog-active OUT BIT (DEBUG)

🌸 JOINT posthome pins 🌸

every joint that's designated as an 'extra' joint gets its very own HAL pin, joint.N.posthome-cmd 🫶 before homing happens, the pin value is literally ignored. but after homing, the pin value gets augmented by the motor offset value and then routed to joint.N.motor-pos-cmd. that's the whole pipeline bestie 💫

🔓 JOINT unlock pins 🔓

the joint pins used for unlocking a joint (joint.N.unlock, joint.N.is-unlocked) are created according to the unlock_joints_mask=jointmask parameter for motmod. these pins may be required for locking indexers (typically a rotary joint) 🔐

the jointmask bits are: (lsb)0:joint0, 1:joint1, 2:joint2, ...

example:

loadrt motmod ... unlock_joints_mask=0x38

that one creates unlock pins for joints 3,4,5 💅 slay.

🌈 SPINDLE PINS 🌈

(M is the spindle number (0 ... num_spindles-1))

  • spindle.M.amp-fault-in IN BIT — should be driven TRUE if an external fault is detected with the amplifier for this spindle 💀
  • spindle.M.at-speed IN BIT — motion will pause until this pin is TRUE, under these conditions: before the first feed move after each spindle start or speed change; before the start of every chain of spindle-synchronized moves; and if in CSS mode, at every rapid->feed transition ✋
  • spindle.M.brake OUT BIT — TRUE when the spindle brake should be applied 🛑
  • spindle.M.forward OUT BIT — TRUE when the spindle should rotate forward ➡️
  • spindle.M.index-enable I/O BIT — for correct operation of spindle synchronized moves, this signal must be hooked to the index-enable pin of the spindle encoder 🔗
  • spindle.M.inhibit IN BIT — when TRUE, the spindle speed is set and held to 0 🙅
  • spindle.M.is-oriented IN BIT — acknowledge pin for spindle-orient. completes the orient cycle. if spindle-orient was true when spindle-is-oriented was asserted, the spindle-orient pin is cleared and the spindle-locked pin is asserted. also, the spindle-brake pin is asserted 💅
  • spindle.M.locked OUT BIT — spindle orient complete pin. cleared by any of M3,M4,M5 🔒
  • spindle.M.on OUT BIT — TRUE when spindle should rotate 🔥
  • spindle.M.orient OUT BIT — indicates start of spindle orient cycle. set by M19. cleared by any of M3,M4,M5.

if spindle-orient-fault is not zero during spindle-orient true, the M19 command fails with an error message 🚨

  • spindle.M.orient-angle OUT FLOAT — desired spindle orientation for M19. value of the M19 R word parameter plus the value of the [RS274NGC]ORIENT_OFFSET INI parameter 🎯
  • spindle.M.orient-fault IN S32 — fault code input for orient cycle. any value other than zero will cause the orient cycle to abort 💀
  • spindle.M.orient-mode OUT BIT — desired spindle rotation mode. reflects the M19 P parameter word 🔄
  • spindle.M.reverse OUT BIT — TRUE when the spindle should rotate backward ⬅️
  • spindle.M.revs IN FLOAT — for correct operation of spindle synchronized moves, this signal must be hooked to the position pin of the spindle encoder 🔗
  • spindle.M.speed-cmd-rps FLOAT OUT — commanded spindle speed in units of revolutions per second
  • spindle.M.speed-in IN FLOAT — actual spindle speed feedback in revolutions per second; used for G96 (constant surface speed) and G95 (feed per revolution) modes 📈
  • spindle.M.speed-out OUT FLOAT — desired spindle speed in rotations per minute
  • spindle.M.speed-out-abs OUT FLOAT — desired spindle speed in rotations per minute, always positive regardless of spindle direction ✨
  • spindle.M.speed-out-rps OUT FLOAT — desired spindle speed in rotations per second
  • spindle.M.speed-out-rps-abs OUT FLOAT — desired spindle speed in rotations per second, always positive regardless of spindle direction ✨

🧠 MOTION PARAMETERS 🧠

ngl, a lot of these parameters are debugging aids, and they are subject to change or removal at any time. don't get too attached 🙈

  • motion-command-handler.tmax RW S32 — show information about the execution time of these HAL functions in CPU clocks ⏱️
  • motion-command-handler.tmax-increased RO S32
  • motion-controller.tmax RW S32 — show information about the execution time of these HAL functions in CPU clocks ⏱️
  • motion-controller.tmax-increased RO BIT
  • motion.debug-* — these values are used for debugging purposes 🐛

⚡ FUNCTIONS ⚡

generally, these functions are both added to the servo-thread in the order shown 👑

  • motion-command-handler — receive and process incoming motion commands. the pin named motion-command-handler.time and parameters motion-command-handler.tmax,tmax-increasedare are created for this function 📥
  • motion-controller — runs the LinuxCNC motion controller. the pin named motion-controller.time and parameters motion-controller.tmax,tmax-increased are created for this function 🎮

💀 BUGS 💀

  • this manual page is incomplete. yeah. we know. 😭
  • identification of pins categorized with (DEBUG) is dubious 👀

🫶 SEE ALSO 🫶

iocontrol(1), milltask(1), spindle(9)

okay that's a wrap bestie 💖 this one's straight outta the LinuxCNC Documentation, filed under MOTION(9) — go forth and wire up your pins, you absolute icon 👑✨

📦 where this page comes from