:lang: en
:toc:

[[cha:moveoff]]
= Moveoff Component(((Moveoff)))

// Custom lang highlight
// must come after the doc title, to work around a bug in asciidoc 8.6.6
:ini: {basebackend@docbook:'':ini}
:hal: {basebackend@docbook:'':hal}
:ngc: {basebackend@docbook:'':ngc}

The moveoff HAL component is a HAL-only method
for implementing offsets.  See the manpage ('$ man moveoff')
for the IMPORTANT limitations and warnings.

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

Sim configurations that demonstrate the component and a
GUI (moveoff_gui) are located in:

* configs/sim/axis/moveoff  (axis-ui)
* configs/sim/touchy/ngcgui (touchy-ui)

== Modifying an existing configuration

A system-provided HAL file (LIB:hookup_moveoff.tcl) can be used to adapt an
existing configuration to use the moveoff component.  Additional INI file
settings support the use of a simple GUI (moveoff_gui) for controlling offsets.

When the system HAL file (LIB:hookup_moveoff.tcl) is properly specified in
a configuration INI file, it will:

. Disconnect the original joint.N.motor-pos-cmd and joint.N.motor-pos-fb pin
  connections
. Load (loadrt) the moveoff component (using the name mv) with a personality
  set to accommodate all axes identified in the INI file
. Add (addf) the moveoff component functions in the required sequence
. Reconnect the joint.N.motor-pos-cmd and joint.N.motor-pos-fb pins to use
  the moveoff component
. Set the moveoff component operating parameters and limits for each axis
  in accordance with additional INI file settings

Note: The moveoff_gui application supports configurations that use known
kinematics modules with KINEMATICS_TYPE=KINEMATICS_IDENTITY.  Supported
modules include: trivkins.  With identity kins, moveoff_gui
assigns each axis name specified with the command line parameter '-axes axisnames'
to the corresponding joint.

Modify an existing configuration as follows:

Make sure there is an INI file entry for [HAL]HALUI and create a new
[HAL]HALFILE entry for LIB:hookup_moveoff.tcl.
The entry for LIB:hookup_moveoff.tcl should follow all HALFILE= entries
for HAL files that connect the pins for joint.N.motor-pos-cmd,
joint.N.motor-pos-fb, and any components connected to these pins (pid
and encoder components in a servo system for instance).

[source,{ini}]
----
[HAL]
HALUI   = halui
HALFILE = existing_configuration_halfile_1
...
HALFILE = existing_configuration_halfile_n
HALFILE = LIB:hookup_moveoff.tcl
----

Add INI file entries for the per-axis settings for each axis in use (if an
entry is not defined, the corresponding entry from the [AXIS_n] section will be
used, if no entry is found, then the moveoff component default will be used).

[NOTE]
Using component defaults or [AXIS_n] section values for per-axis offset
settings is NOT recommended.

[source,{ini}]
----
[MOVEOFF_n]
MAX_LIMIT =
MIN_LIMIT =
MAX_VELOCITY =
MAX_ACCELERATION =
----

Add INI file entries for moveoff component settings (omit to use moveoff defaults):

[source,{ini}]
----
[MOVEOFF]
EPSILON =
WAYPOINT_SAMPLE_SECS =
WAYPOINT_THRESHOLD =
----

The moveoff_gui is used to make additional required connections and provide
a popup GUI to:

. Provide a control togglebutton to Enable/Disable offsets
. Provide a control togglebutton to Enable/Disable backtracking
. Provide control pushbuttons to Increment/Decrement/Zero each axis offset
. Display each axis offset current value
. Display current offset status (disabled, active, removing, etc)

The provided control buttons are optional depending upon the state of
the moveoff component move-enable pin.  Both a display and controls
for enabling offsetting are provided if the pin mv.move-enable
is NOT connected when the moveoff_gui is started.  For this case,
the moveoff_gui manages the moveoff component move-enable pin
(named mv.move-enable) as well as the offsets (mv.move-offset-in-M)
and the backtracking enable (mv.backtrack-enable)

If the mv.move-enable pin IS connected when the moveoff_gui
is started, the moveoff_gui will provide a display but NO controls.
This mode supports configurations that use a jog wheel or other methods
of controlling the offset inputs and the enable pins (mv.offset-in-M,
mv.move-enable, mv.backtrack-enable).

The moveoff_gui makes the required connections for the moveoff component pins:
mv.power_on and mv.apply-offsets.  The mv.power_on pin is connected to the
motion.motion-enabled pin (a new signal is automatically created if necessary).
The mv.apply-offsets is connected to halui.program.is-paused or set to 1
depending upon the command line option -mode [ onpause | always ].  A new signal
is automatically created if necessary.

To use the moveoff_gui, add an entry in the INI file [APPLICATIONS]
section as follows:

[source,{ini}]
----
[APPLICATIONS]
# Note: a delay (specified in seconds) may be required if connections
# are made using postgui HAL files ([HAL]POSTGUI_HALFILE=)
DELAY = 0
APP = moveoff_gui option1 option2 ...
----

When the HAL file LIB:hookup_moveoff.tcl is used to load and connect the
moveoff component, the mv.move-enable pin will not be connected and
local controls provided by the moveoff_gui will be used.  This is the
simplest method to test or demonstrate the moveoff component when
modifying an existing INI configuration.

To enable external controls while using the moveoff_gui display
for offset values and status, HAL files that follow LIB:hookup_moveoff.tcl
must make additional connections.  For example, the supplied demonstration
configs (configs/sim/axis/moveoff/*.ini) use a simple system HAL file
(named LIB:moveoff_external.hal) to connect the mv.move-enable, mv.offset-in-M,
and mv.bactrack-enable pins to signals:

[source,{ini}]
----
[HAL]
HALUI = halui
...
HALFILE = LIB:hookup_moveoff.tcl
HALFILE = LIB:moveoff_external.hal
----

The connections made by LIB:moveoff_external.hal (for a three axis
configuration) are:

[source,{hal}]
----
net external_enable mv.move-enable

net external_offset_0 mv.offset-in-0
net external_offset_1 mv.offset-in-1
net external_offset_2 mv.offset-in-2

net external_backtrack_en mv.backtrack-enable
----

These signals (external_enable, external_offset_M, external_backtrack_en) may
be managed by subsequent HALFILES (including POSTGUI_HALFILEs) to provide
customized control of the component while using the moveoff_gui display
for current offset values and offset status.

The moveoff_gui is configured with command line options.  For details
on the operation of moveoff_gui, see the man page:

----
$ man moveoff_gui
----

For a brief listing of command line options for moveoff_gui, use the command line help option:

----
$ moveoff_gui --help

Usage:
moveoff_gui [Options]

Options:
    [--help | -? | -- -h ]  (This text)

    [-mode [onpause | always]]  (default: onpause)
                                  (onpause: show gui when program paused)
                                  (always:  show gui always)

    [-axes axisnames]       (default: xyz (no spaces))
                              (letters from set of: x y z a b c u v w)
                              (example: -axes z)
                              (example: -axes xz)
                              (example: -axes xyz)
    [-inc incrementvalue]   (default: 0.001 0.01 0.10 1.0 )
                              (specify one per -inc (up to 4) )
                              (example: -inc 0.001 -inc 0.01 -inc 0.1 )
    [-size integer]         (default: 14)
                              (Overall gui popup size is based on font size)
    [-loc center|+x+y]      (default: center)
                              (example: -loc +10+200)
    [-autoresume]           (default: notused)
                              (resume program when move-enable deasserted)
    [-delay delay_secs]     (default: 5 (resume delay))

Options for special cases:
    [-noentry]              (default: notused)
                             (don't create entry widgets)
    [-no_resume_inhibit]    (default: notused)
                             (do not use a resume-inhibit-pin)
    [-no_pause_requirement] (default: notused)
                             (no check for halui.program.is-paused)
    [-no_cancel_autoresume] (default: notused)
                             (useful for retraact offsets with simple)
                             (external control)
    [-no_display]           (default: notused)
                             (Use when both external controls and displays)
                             (are in use (see Note))

Note: If the moveoff move-enable pin (mv.move-enable) is connected when
      moveoff_gui is started, external controls are required and only
      displays are provided.
----

// vim: set syntax=asciidoc:
