.\" Copyright (c) 2014 Dewey Garrett
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
.\" USA.
.\"
.\"
.\"
.TH moveoff_gui "1"  "2014-12-18" "LinuxCNC Documentation" "LinuxCNC"
.SH NAME
moveoff_gui \- a GUI for the moveoff component

.SH SYNOPSIS
.B moveoff_gui \fB[\-\-help | \-\- \-h | \-?]\fR

.PP
.B moveoff_gui [\fBoptions\fR]
.PP

.SH DESCRIPTION
Moveoff_gui is a sample graphical user interface (GUI) for
controlling a HAL moveoff component to implement HAL-only 
offsets.  See the manpage (man moveoff) for \fBIMPORTANT
limitations and warnings\fR.

Supported configurations must use a known kinematics module with
\fBKINEMATICS_TYPE = KINEMATICS_IDENTITY\fR.  The modules currently
supported are:
   \fBtrivkins\fR

.SH OPTIONS

.TP
\fB\-\-help | \-? | \-\- \-h\fR
Show options and exit

.TP
\fB\-mode\fR \fBonpause\fR | always
.br
onpause: popup GUI to control offsets when program paused
.br
always:  show GUI to control offsets always
.br
Default: \fBonpause\fR

.TP
\fB\-axes\fR \fIaxis-names\fR
.br
Letters from set of {x y z a b c u v w}
.br
Examples: \-axes x, \-axes xyz, \-axes xz (no spaces)
.br
Default: \fBxyz\fR

.TP
\fB\-inc\fR \fIincrementvalue\fR
.br
Specify one increment value per \-inc (up to 4)
.br
Defaults: \fB 0.001 0.01 0.10 1.0\fR

.TP
\fB\-size\fR \fIinteger\fR
.br
Overall gui size is based on font size, typically 8 - 20
.br
Default: \fB14\fR

.TP
\fB\-loc\fR center | +x+y
.br
Initial location on screen
.br
Examples: \-loc center, \-loc +20+100
.br
Default: \fBcenter\fR

.TP
\fB\-autoresume\fR
.br
Resume program when move-enable deasserted
.br
Default: notused

.TP
\fB\-delay\fR \fIdelay secs\fR
.br
Delay for autoresume (allow time to restore spindle speed etc)
Default: \fB5\fR

.SH OTHER OPTIONS
These options are available for special cases:

.TP
\fB\-noentry\fR
.br
Disables creation of entry widgets
.br
Default: notused

.TP
\fB\-no_resume_inhibit\fR
.br
Disable use of resume\-inhibit to controlling gui
.br
Default: notused

.TP
\fB\-no_pause_requirement
.br
Disable check for halui.program.is\-paused
.br
Default: notused

.TP
\fB\-no_cancel_autoresume
.br
Useful for retracting offsets with simple external controls
.br
Default: notused

.TP
\fB\-no_display
.br
Use when both external controls and external displays are in use
.br
Default: notused

.SH NOTES
LinuxCNC must be running.
.P
Halui must be loaded, typical INI file setting:
    \fB[HAL]HALUI = halui\fR.
.P
The moveoff component must be loaded with the name 'mv' as:
.br
    \fBloadrt moveoff names=mv personality=number_of_axes\fR
.P
If the pin mv.motion\-enable is \fBnot\fR connected when moveoff_gui is
started, \fBcontrols will be provided\fR to enable offsets and set
offset values.  If the pin \fBis\fR connected, \fBonly a display\fR
of offsets is shown and control must be made by \fBexternal\fR
HAL connections.
.P
If a pin named *.resume\-inhibit exists and is not connected, it will
be set while offsets are applied.  This pin may be provided by the
controlling LinuxCNC GUI in use.  Use of the pin may be disabled
with the option \-no_resume_inhibit.
.P
The \-autoresume option uses halui.program.resume to automatically
resume program execution when the move\-enable pin is deactivated
and all offsets are removed.  The resume pin is not activated
until an additional interval (\-delay delay_secs) elapses.  This
delay interval may be useful for restarting related equipment
(a spindle motor for example)  While timing the delay, a popup is
offered to cancel the automatic program resumption.

.SH USAGE
The INI file in the configuration directory must provide HALFILEs
to loadrt the moveoff component, connect its pins, and addf its
read and write functions in the proper order.  These steps can be
done at runtime using an existing configuration INI file and
specifying a system library HALFILE \fBhookup_moveoff.tcl\fR as
illustrated below:
.P
\fB[HAL]\fR
.br
HALUI = halui
.br
HALFILE = user_halfile_1
.br
etc ...
.br
HALFILE = user_halfile_n
.br
\fBHALFILE = LIB:hookup_moveoff.tcl\fR
.P
The \fBhookup_moveoff.tcl\fR HAL file will use INI file settings for
the moveoff component control pins:
.P
\fB[OFFSET]\fR
.br
EPSILON =
.br
WAYPOINT_SAMPLE_SECS =
.br
WAYPOINT_THRESHOLD =
.br
BACKTRACK_ENABLE =
.P
The \fBhookup_moveoff.tcl\fR will use INI file settings for the moveoff
per-axis limits:
.P
\fB[AXIS_m]\fR
.br
OFFSET_MAX_VELOCITY =
.br
OFFSET_MAX_ACCELERATION =
.br
OFFSET_MAX_LIMIT =
.br
OFFSET_MIN_LIMIT =
.P
The moveoff_gui program should be specified in the APPLICATIONS
stanza of the INI file, for example:
.P
\fB[APPLICATIONS]\fR
.br
DELAY = delay_in_secs_to_allow_hal_connections
.br
\fBAPP = moveoff_gui \-option1 \-option2 ...\fR
.P

.SH "SEE ALSO"
Simulation configurations that demonstrate the moveoff_gui and the
moveoff component are located in:
.P
   configs/sim/axis/moveoff     (axis-ui)
.br
   configs/sim/touchy/ngcgui    (touchy-ui)

See also \fBmoveoff\fR(9) for details on the component.