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

NAME

       moveoff - Component for HAL-only offsets

SYNOPSIS

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

DESCRIPTION

       The  moveoff  component  is  used  to offset joint positions using custom HAL connections.
       Implementing an offset-while-program-is-paused functionality is supported with appropriate
       connections for the input pins.  Nine joints are supported.

       The  axis  offset  pin values (offset-in-M) are continuously applied (respecting limits on
       value, velocity, and acceleration) to the output pins (offset-current-M, pos-plusoffset-M,
       fb-minusoffset-M)  when both enabling input pins (apply-offsets and move-enable) are TRUE.
       The two enabling inputs are anded internally.  A warning pin is set and a  message  issued
       if the apply-offsets pin is deasserted while offsets are applied.  The warning pin remains
       TRUE until the offsets are removed or the apply-offsets pin is set.

       Typically, the move-enable pin is connected to external controls and the apply-offsets pin
       is  connected  to  halui.program.is-paused  (for offsets only while paused) or set to TRUE
       (for continuously applied offsets).

       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 componenent is  enabled.   Waypoints  are  managed
       with  the waypoint-sample-secs and waypoint-threshold pins.  When the backtrack-enable pin
       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 results in slower movement rates as the moves are point-to-
       point respecting 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 a controlled path is wanted  in  this  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 is provided to indicate the current state to a GUI so  that
       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.

       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