Provided by: linuxcnc-uspace_2.9.0~pre0+git20220402.2500863908-4build1_amd64 bug

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-types
              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-types 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-types 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-types 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-types  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.  If any jog is active when the pin state changes to TRUE  then  that  jog
              will be stopped.

       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.

SEE ALSO

       iocontrol(1), milltask(1)