MOTION

NAME
SYNOPSIS
DESCRIPTION
MOTION PINS
AXIS PINS
JOINT PINS
JOINT UNLOCK PINS
SPINDLE PINS
MOTION PARAMETERS
FUNCTIONS
BUGS
SEE ALSO

NAME

motion − accepts NML motion commands, interacts with HAL in realtime

SYNOPSIS

loadrt motmod [base_period_nsec=period] [base_thread_fp=0 or 1] [servo_period_nsec=period] [traj_period_nsec=period] [num_joints=[1-9]] [num_dio=[1-64]] [num_aio=[1-64]] [num_spindles=[1-8]] [unlock_joints_mask=jointmask]

The limits for the following items are compile-time settings:
Number of joints available (num_joints) is set by EMCMOT_MAX_JOINTS.
Maximum number of digital inputs (num_dio) is set by EMCMOT_MAX_DIO.
Maximum number of analog inputs (num_aio) is set by EMCMOT_MAX_AIO.
Maximum number of spindles (num_spindles) is set by EMCMOT_MAX_SPINDLES

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).

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.

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 are read and updated by the motion-controller function.

MOTION PINS

motion-command-handler.time OUT S32

Time (in CPU clocks) for the motion module motion-command-handler

motion-controller.time OUT S32

Time (in CPU clocks) for the motion module motion-controller

motion.adaptive−feed IN FLOAT

When adaptive feed is enabled with M52 P1, the commanded velocity is multiplied by this value. This effect is multiplicative with the NML-level feed override value and motion.feed−hold.

motion.analog−in−NN IN FLOAT

These pins are used by 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 encountered an error, such as 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 is driven FALSE, motion stops, the machine is placed in the "machine off" state, and a message is displayed for the operator. For normal motion, drive this bit TRUE.

motion.eoffset-active OUT BIT

Indicates external offsets are active (non-zero)

motion.eoffset-limited OUT BIT

Indicates 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.

motion.feed−inhibit IN BIT

When this pin is TRUE, machine motion is inhibited (this includes jogs, programmed feeds, and programmed rapids, aka traverse moves).

If the machine is performing 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.

motion.homing−inhibit IN BIT

If this bit is TRUE, initiation of 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.in−position OUT BIT

TRUE if the machine is in position (ie, not currently moving towards the commanded position).

motion.motion−enabled OUT BIT
motion.motion−type
OUT S32

These values are from src/emc/nml_intf/motion_types.h

0: Idle (no motion)

1: Traverse

2: Linear feed

3: Arc feed

4: Tool change

5: Probing

6: Rotary unlock for traverse

motion.on−soft−limit OUT BIT
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 accomodate 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.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)

AXIS PINS

(L is the axis letter, one of: x y z a b c u v w)
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
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

JOINT PINS

N is the joint number (0 ... num_joints−1))
(Note: pins marked (DEBUG) serve as debugging aids

and are subject to change or removal at any time.)

joint.N.joint−acc−cmd OUT FLOAT (DEBUG)

The joint’s commanded acceleration

joint.N.active OUT BIT (DEBUG)

TRUE when this joint is active

joint.N.amp−enable−out OUT BIT

TRUE if the amplifier for this joint should be enabled

joint.N.amp−fault−in IN BIT

Should be driven 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 (respecting 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, such as 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

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

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 to enable homing to index pulse

joint.N.is−unlocked IN BIT

Indicates joint is unlocked (see JOINT UNLOCK PINS).

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 ignored.

joint.N.jog−counts IN S32

Connect to the "counts" pin of an external encoder to use a physical jog wheel.

joint.N.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.

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 (the default), the jogwheel operates in position mode. The joint 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.

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 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. 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. 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.joint−vel−cmd OUT FLOAT (DEBUG)

The joint’s commanded velocity

joint.N.wheel−jog−active OUT BIT (DEBUG)

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 creates unlock pins
for joints 3,4,5

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 the following 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 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 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

Many of the parameters serve as debugging aids, and are subject to change or removal at any time.
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

Processes motion commands coming from user space. The pin named motion-command-handler.time and parameters motion-command-handler.tmax,tmax-increasedare 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.
Identification of pins categorized with (DEBUG) is dubious.

SEE ALSO

iocontrol(1), milltask(1)