Ubuntu Manpage: motion - accepts NML motion commands, interacts with HAL in realtime

Provided by: linuxcnc-uspace_2.9.0~pre1+git20230208.f1270d6ed7-1_amd64

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-16]]     [num_dio=[1-64]]     [num_aio=[1-64]]
       [num_misc_error=[0-64]]        [num_spindles=[1-8]]         [unlock_joints_mask=jointmask]
       [num_extrajoints=[0-16]]

       The limits for the following items are compile-time settings:
       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.
       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  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).

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.

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.

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

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. Negative values are valid and will run the G-code path in
reverse.

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.

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

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). Value is 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. If units (G20 or G21) are
not 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, 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.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.

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 such as 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

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

(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 posthome pins

       Each joint designated as an 'extra' joint is provided with a HAL pin joint.N.posthome-cmd.
       The pin value is ignored prior to homing.  After homing, the pin value is augmented by the
       motor offset value and routed to the joint.N.motor-pos-cmd.

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.