path: root/docs/man/man1/halcmd.1

.\" Copyright (c) 2003 John Kasunich
.\"                (jmkasunich AT users DOT sourceforge DOT net)
.\"
.\" 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., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\"
.\"
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH HALCMD "1"  "2003-12-18" "LinuxCNC Documentation" "HAL User's Manual"
.SH NAME
halcmd \- manipulate the LinuxCNC HAL from the command line
.SH SYNOPSIS
.B halcmd
[\fIOPTIONS\fR] [\fICOMMAND\fR [\fIARG\fR]]
.PP
.SH DESCRIPTION
\fBhalcmd\fR is used to manipulate the HAL (Hardware Abstraction
Layer) from the command line.  \fBhalcmd\fR can optionally read
commands from a file, allowing complex HAL configurations to be
set up with a single command.

If the \fBreadline\fR library is available when LinuxCNC is compiled, then
\fBhalcmd\fR offers commandline editing and completion when running
interactively.  Use the up arrow to recall previous commands, and press tab to
complete the names of items such as pins and signals.
.SH OPTIONS
.TP
\fB-I\fR
Before tearing down the realtime environment, run an interactive halcmd.
\fBhalrun\fR only.  If \fB-I\fR is used, it must precede all other
commandline arguments.
.TP
\fB\-f\fR [\fIfile\fR]
Ignore commands on command line, take input from \fIfile\fR
instead.  If \fIfile\fR is not specified, take input from
\fIstdin\fR.
.TP
\fB-i \fIinifile\fR
Use variables from \fIinifile\fR for substitutions.  See \fBSUBSTITUTION\fR
below.
.TP
\fB\-k\fR
Keep going after failed command(s).  The default is to stop
and return failure if any command fails.
.TP
\fB\-q\fR
display errors only (default)
.TP
\fB\-Q\fR
display nothing, execute commands silently
.TP
\fB\-s\fR
Script-friendly mode.  In this mode, \fIshow\fR will not output titles for the items
shown.  Also, module names will be printed instead of ID codes in pin, param, and funct
listings.  Threads are printed on a single line, with the thread period, FP usage and
name first, followed by all of the functions in the thread, in execution order.  Signals
are printed on a single line, with the type, value, and signal name first, followed by
a list of pins connected to the signal, showing both the direction and the pin name.
No prompt will be printed if both \fB-s\fR and \fB-f\fR are specified.
.TP
\fB-R\fR
Release the HAL mutex.  This is useful for recovering when a HAL component has crashed
while holding the HAL mutex.
.TP
\fB\-v\fR
display results of each command
.TP
\fB\-V\fR
display lots of debugging junk
.TP
\fB\-h\fR [\fIcommand\fR]
display a help screen and exit, displays extended help on \fIcommand\fR if specified
.SH COMMANDS
Commands tell \fBhalcmd\fR what to do.  Normally \fBhalcmd\fR
reads a single command from the command line and executes it.
If the '\fB-f\fR' option is used to read commands from a file,
\fBhalcmd\fR reads each line of the file as a new command.
Anything following '\fB#\fR' on a line is a comment.
.TP
\fBloadrt\fR \fImodname\fR
(\fIload\fR \fIr\fReal\fIt\fRime module)  Loads a realtime HAL
module called \fImodname\fR.  \fBhalcmd\fR looks for the module
in a directory specified at compile time.

In systems with realtime, \fBhalcmd\fR calls the
\fBlinuxcnc_module_helper\fR to load realtime modules.
\fBlinuxcnc_module_helper\fR is a setuid program and is compiled with
a whitelist of modules it is allowed to load.  This is currently
just a list of \fBLinuxCNC\fR-related modules.  The
\fBlinuxcnc_module_helper\fR execs insmod, so return codes and error
messages are those from insmod.  Administrators who wish to
restrict which users can load these \fBLinuxCNC\fR-related kernel
modules can do this by setting the permissions and group on
\fBlinuxcnc_module_helper\fR appropriately.

In systems without realtime \fBhalcmd\fR calls the
\fBrtapi_app\fR which creates the simulated realtime environment
if it did not yet exist, and then loads the requested component
with a call to \fBdlopen(3)\fR.
.TP
\fBunloadrt\fR \fImodname\fR
(\fIunload\fR \fIr\fReal\fIt\fRime module)  Unloads a realtime HAL
module called \fImodname\fR.  If \fImodname\fR is "all", it will
unload all currently loaded realtime HAL modules.  \fBunloadrt\fR
also works by execing \fBlinuxcnc_module_helper\fR or \fBrtapi_app\fR, just like
\fBloadrt\fR.
.TP
\fBloadusr\fR \fI[flags]\fR \fIunix-command\fR
(\fIload\fR \fIUs\fRe\fIr\fRspace component) Executes the given
\fIunix-command\fR, usually to load a userspace component.
\fI[flags]\fR may be one or more of:
.RS
.IP \(bu 4
\fB-W\fR to wait for the component to become ready.  The component
is assumed to have the same name as the first argument of the command.
.IP \(bu 4
\fB-Wn name\fR to wait for the component, which will have the given
name.
.IP \(bu 4
\fB-w\fR to wait for the program to exit
.IP \(bu 4
\fB-i\fR to ignore the program return value (with -w)
.RE
.TP
\fBwaitusr\fR \fIname\fR
(\fIwait\fR for \fIUs\fRe\fIr\fRspace component) Waits for user
space component \fIname\fR to disconnect from HAL (usually on exit).
The component must already be loaded.  Usefull near the end of a
HAL file to wait until the user closes some user interface component
before cleaning up and exiting.
.TP
\fBunloadusr\fR \fIcompname\fR
(\fIunload\fR \fIUs\fRe\fIr\fRspace component)  Unloads a userspace
component called \fIcompname\fR.  If \fIcompname\fR is "all", it will
unload all userspace components.  \fBunloadusr\fR
works by sending SIGTERM to all userspace components.
.TP
\fBunload\fR \fIcompname\fR
Unloads a userspace component or realtime module.  If \fIcompname\fR is "all",
it will unload all userspace components and realtime modules.
.TP
\fBnewsig\fR \fIsigname\fR \fItype\fR
(OBSOLETE - use \fBnet\fR instead) (\fInew\fR \fIsig\fRnal)
Creates a new HAL signal called \fIsigname\fR that may later
be used to connect two or more HAL component pins.  \fItype\fR
is the data type of the new signal, and must be one of "\fBbit\fR",
"\fBs32\fR", "\fBu32\fR", or "\fBfloat\fR".
Fails if a signal of the same name already exists.
.TP
\fBdelsig\fR \fIsigname\fR
(\fIdel\fRete \fIsig\fRnal)  Deletes HAL signal \fIsigname\fR.
Any pins currently linked to the signal will be unlinked.
Fails if \fIsigname\fR does not exist.
.TP
\fBsets\fR \fIsigname\fR \fIvalue\fR
(\fIset\fR \fIs\fRignal)  Sets the value of signal \fIsigname\fR
to \fIvalue\fR.  Fails if \fIsigname\fR does not exist, if it
already has a writer, or if \fIvalue\fR is not a legal value.
Legal values depend on the signals's type.
.TP
\fBstype\fR \fIname\fR
(\fIs\fRignal type\fR)  Gets the type of signal
\fIname\fR.  Fails if \fIname\fR does not exist as a signal.
.TP
\fBgets\fR \fIsigname\fR
(\fIget\fR \fIs\fRignal)  Gets the value of signal \fIsigname\fR.  Fails
if \fIsigname\fR does not exist.
.TP
\fBlinkps\fR \fIpinname\fR [\fIarrow\fR] \fIsigname\fR
(OBSOLETE - use \fBnet\fR instead) (\fIlink\fR \fIp\fRin to \fIs\fRignal)
Establishs a link between a HAL component pin \fIpinname\fR and
a HAL signal \fIsigname\fR.  Any previous link to \fIpinname\fR will be
broken.  \fIarrow\fR can be "\fB=>\fR", "\fB<=\fR", "\fB<=>\fR",
or omitted.  \fBhalcmd\fR ignores arrows, but they can be useful
in command files to document the direction of data flow.  Arrows
should not be used on the command line since the shell might try
to interpret them.  Fails if either \fIpinname\fR or \fIsigname\fR
does not exist, or if they are not the same type type.
.TP
\fBlinksp\fR \fIsigname\fR [\fIarrow\fR] \fIpinname\fR
(OBSOLETE - use \fBnet\fR instead) (\fIlink\fR \fIs\fRignal to \fIp\fRin)
Works like \fBlinkps\fR but reverses the order of the arguments.
\fBhalcmd\fR treats both link commands exactly the same.  Use whichever
you prefer.
.TP
\fBlinkpp\fR \fIpinname1\fR [\fIarrow\fR] \fIpinname2\fR
(OBSOLETE - use \fBnet\fR instead) (\fIlink\fR \fIp\fRin to \fIp\fRin)
Shortcut for \fBlinkps\fR that creates the signal (named like the
first pin), then links them both to that signal.  \fBhalcmd\fR treats
this just as if it were:
   \fBhalcmd\fR \fBnewsig\fR pinname1 
   \fBhalcmd\fR \fBlinksp\fR pinname1 pinname1
   \fBhalcmd\fR \fBlinksp\fR pinname1 pinname2
.TP
\fBnet\fR \fIsigname\fR \fIpinname\fR \fI...\fR
Create \fIsignname\fR to match the type of \fIpinname\fR if it does not yet
exist.  Then, link \fIsigname\fR to each \fIpinname\fR in turn.  Arrows may
be used as in \fBlinkps\fR. When linking a pin to a signal for the first
time, the signal value will inherit the pin's default value.

.TP
\fBunlinkp\fR \fIpinname\fR
(\fIunlink\fR \fIp\fRin)  Breaks any previous link to \fIpinname\fR.
Fails if \fIpinname\fR does not exist. An unlinked pin will retain the last
value of the signal it was linked to.

.TP
\fBsetp\fR \fIname\fR \fIvalue\fR
(\fIset\fR \fIp\fRarameter or \fIp\fRin)  Sets the value of parameter or pin
\fIname\fR to \fIvalue\fR.  Fails if \fIname\fR does not exist as a pin or
parameter, if it is a parameter that is not writable, if it is a pin that is an
output, if it is a pin that is already attached to a signal, or if \fIvalue\fR
is not a legal value.  Legal values depend on the type of the pin or parameter.
If a pin and a parameter both exist with the given name, the parameter is acted
on.
.TP
\fIparamname\fR \fB=\fR \fIvalue\fR
.TP
\fIpinname\fR \fB=\fR \fIvalue\fR
Identical to \fBsetp\fR.  This alternate form of the command may
be more convenient and readable when used in a file.
.TP
\fBptype\fR \fIname\fR
(\fIp\fRarameter or \fIp\fRin \fItype\fR)  Gets the type of parameter or
pin \fIname\fR.  Fails if \fIname\fR does not exist as a pin or
parameter.  If a pin and a parameter both exist with the given name, the
parameter is acted on.
.TP
\fBgetp\fR \fIname\fR
(\fIget\fR \fIp\fRarameter or \fIp\fRin)  Gets the value of parameter or
pin \fIname\fR.  Fails if \fIname\fR does not exist as a pin or
parameter.  If a pin and a parameter both exist with the given name, the
parameter is acted on.
.TP
\fBaddf\fR \fIfunctname\fR \fIthreadname\fR
(\fIadd\fR \fIf\fRunction)  Adds function \fIfunctname\fR to realtime
thread \fIthreadname\fR.  \fIfunctname\fR will run after any functions
that were previously added to the thread.  Fails if either
\fIfunctname\fR or \fIthreadname\fR does not exist, or if they
are incompatible.
.TP
\fBdelf\fR \fIfunctname\fR \fIthreadname\fR
(\fIdel\fRete \fIf\fRunction)  Removes function \fIfunctname\fR from
realtime thread \fIthreadname\fR.  Fails if either \fIfunctname\fR or
\fIthreadname\fR does not exist, or if \fIfunctname\fR is not currently
part of \fIthreadname\fR.
.TP
\fBstart\fR
Starts execution of realtime threads.  Each thread periodically calls
all of the functions that were added to it with the \fBaddf\fR command,
in the order in which they were added.
.TP
\fBstop\fR
Stops execution of realtime threads.  The threads will no longer call
their functions.
.TP
\fBshow\fR [\fIitem\fR]
Prints HAL items to \fIstdout\fR in human readable format.
\fIitem\fR can be one of "\fBcomp\fR" (components), "\fBpin\fR",
"\fBsig\fR" (signals), "\fBparam\fR" (parameters), "\fBfunct\fR"
(functions), "\fBthread\fR", or "\fBalias\fR".  The type "\fBall\fR"
can be used to show matching items of all the preceeding types.
If \fIitem\fR is omitted, \fBshow\fR will print everything.
.TP
\fBitem\fR
This is equivalent to \fBshow all [item]\fR.
.TP
\fBsave\fR [\fIitem\fR]
Prints HAL items to \fIstdout\fR in the form of HAL commands.
These commands can be redirected to a file and later executed
using \fBhalcmd -f\fR to restore the saved configuration.
\fIitem\fR can be one of the following: "\fBcomp\fR" generates
a \fBloadrt\fR command for realtime component.  "\fBsig\fR" 
generates a \fBnewsig\fR command for each signal, and "\fBsigu\fR" generates a
\fBnewsig\fR command for each unlinked signal (for use with \fBnetl\fR and
\fBnetla\fR).  "\fBlink\fR" and "\fBlinka\fR" both generate \fBlinkps\fR
commands for each link. (\fBlinka\fR includes arrows, while \fBlink\fR does
not.) "\fBnet\fR" and "\fBneta\fR" both generate one \fBnewsig\fR command for
each signal, followed by \fBlinksp\fR commands for each pin linked to that
signal.  (\fBneta\fR includes arrows.) "\fBnetl\fR" generates one \fBnet\fR
command for each linked signal, and "\fBnetla\fR" generates a similar command
using arrows.  "\fBparam\fR" generates one \fBsetp\fR command for each
parameter.  "\fBthread\fR" generates one \fBaddf\fR command for each function
in each realtime thread.  If \fIitem\fR is omitted, \fBsave\fR does the
equivalent of \fBcomp\fR, \fBsigu\fR, \fBlink\fR, \fBparam\fR, and \fBthread\fR.
.TP
\fBsource\fR  \fIfilename.hal\fR
Execute the commands from \fIfilename.hal\fR.
.TP
\fBalias\fR \fItype\fR \fIname\fR \fIalias\fR
Assigns "\fBalias\fR" as a second name for the pin or parameter
"name".  For most operations, an alias provides a second
name that can be used to refer to a pin or parameter, both the
original name and the alias will work.
   "type" must be \fBpin\fR or \fBparam\fR.
   "name" must be an existing name or \fBalias\fR of the specified type.
.TP
\fBunalias\fR \fItype\fR \fIalias\fR
Removes any alias from the pin or parameter alias.
  "type" must be \fBpin\fR or \fBparam\fR
  "alias" must be an existing name or \fBalias\fR of the specified type.
.TP
\fBlist\fR \fItype\fR [\fIpattern\fR]
  Prints the names of HAL items of the specified type.
  'type' is '\fBcomp\fR', '\fBpin\fR', '\fBsig\fR', '\fBparam\fR', '\fBfunct\fR', or
  '\fBthread\fR'.  If 'pattern' is specified it prints only
  those names that match the pattern, which may be a
  'shell glob'.
  For '\fBsig\fR', '\fBpin\fR' and '\fBparam\fR', the first pattern may be
  -t\fBdatatype\fR where datatype is the data type (e.g., 'float')
  in this case, the listed pins, signals, or parameters
  are restricted to the given data type
  Names are printed on a single line, space separated.
.TP
\fBlock\fR [\fIall\fR|\fItune\fR|\fInone\fR]
  Locks HAL to some degree.
  none - no locking done.
  tune - some tuning is possible (\fBsetp\fR & such).
  all  - HAL completely locked.
.TP
\fBunlock\fR [\fIall\fR|\fItune\fR]
  Unlocks HAL to some degree.
  tune - some tuning is possible (\fBsetp\fR & such).
  all  - HAL completely unlocked.
.TP
\fBstatus\fR [\fItype\fR]
  Prints status info about HAL.
  'type' is '\fBlock\fR', '\fBmem\fR', or '\fBall\fR'.
  If 'type' is omitted, it assumes '\fBall\fR'.
.TP
\fBhelp\fR [\fIcommand\fR]
  Give help information for command.
  If 'command' is omitted, list command and brief description
.SH SUBSTITUTION
After a command is read but before it is executed, several types of variable
substitution take place.
.SS Environment Variables
Environment variables have the following formats:
.IP
\fB$ENVVAR\fR followed by end-of-line or whitespace
.IP
\fB$(ENVVAR)\fR
.SS Inifile Variables
Inifile variables are available only when an inifile was specified with the
halcmd \fB-i\fR flag.  They have the following formats:
.IP
\fB[SECTION]VAR\fR followed by end-of-line or whitespace
.IP
\fB[SECTION](VAR)\fR
.SH EXAMPLES
.SH HISTORY
.SH BUGS
None known at this time.
.SH AUTHOR
Original version by John Kasunich, as part of the LinuxCNC project.  Now
includes major contributions by several members of the project.
.SH REPORTING BUGS
Report bugs to the
.URL http://sf.net/tracker/?group_id=6744&atid=106744 "LinuxCNC bug tracker" .
.SH COPYRIGHT
Copyright \(co 2003 John Kasunich.
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
\fBhalrun(1)\fR -- a convenience script to start a realtime environment,
process a .hal or a .tcl file, and optionally start an interactive command
session using \fBhalcmd\fR (described here) or \fBhaltcl\fR(1).