Ubuntu Manpage: halcmd - manipulate the LinuxCNC HAL from the command line

Provided by: linuxcnc-uspace_2.9.4-2ubuntu1_amd64

NAME

       halcmd - manipulate the LinuxCNC HAL from the command line

SYNOPSIS

       halcmd [OPTIONS] [COMMAND [ARG]]

DESCRIPTION

       halcmd  is  used  to  manipulate  the HAL (Hardware Abstraction Layer) from the command line.  halcmd can
       optionally read commands from a file, allowing complex HAL configurations to be  set  up  with  a  single
       command.

       If  the  readline  library is available when LinuxCNC is compiled, then halcmd 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.

OPTIONS

-I Before tearing down the realtime environment, run an interactive halcmd. halrun only. If -I is
used, it must precede all other commandline arguments.

-f [<file>]
Ignore commands on command line, take input from file instead. If file is not specified, take
input from stdin.

-i <INI file>
Use variables from the specified INI file for substitutions. See SUBSTITUTION below.

-k Keep going after failed command(s). The default is to stop and return failure if any command
fails.

-q display errors only (default)

-Q display nothing, execute commands silently

-s Script-friendly mode. In this mode, show 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.

-R Release the HAL mutex. This is useful for recovering when a HAL component has crashed while
holding the HAL mutex.

-v display results of each command

-V display lots of debugging junk

-h [<command>]
display a help screen and exit, displays extended help on command if specified

COMMANDS

Commands tell halcmd what to do. Normally halcmd reads a single command from the command line and
executes it. If the '-f' option is used to read commands from a file, halcmd reads each line of the file
as a new command. Anything following '#' on a line is a comment.

loadrt modname
(load realtime module) Loads a realtime HAL module called modname. halcmd looks for the module
in a directory specified at compile time.

In systems with kernel-based realtime support (e.g. RTAI), halcmd calls the linuxcnc_module_helper
to load realtime modules. linuxcnc_module_helper is a setuid program and is compiled with a
whitelist of modules it is allowed to load. This is currently just a list of LinuxCNC-related
modules. The linuxcnc_module_helper execs insmod, so return codes and error messages are those
from insmod. Administrators who wish to restrict which users can load these LinuxCNC-related
kernel modules can do this by setting the permissions and group on linuxcnc_module_helper
appropriately.

In systems with userspace-based realtime support (e.g. Preempt-RT) and in systems without realtime
support halcmd calls the rtapi_app which creates the realtime environment (simulated realtime, on
systems with no userspace realtime support) if it did not yet exist, and then loads the requested
component with a call to dlopen(3).

unloadrt modname
(unload realtime module) Unloads a realtime HAL module called modname. If modname is "all", it
will unload all currently loaded realtime HAL modules. unloadrt also works by execing
linuxcnc_module_helper or rtapi_app, just like loadrt.

loadusr [flags] unix-command
(load Userspace component) Executes the given unix-command, usually to load a non-realtime
component. [flags] may be one or more of:

• -W to wait for the component to become ready. The component is assumed to have the same name
as the first argument of the command.

• -Wn name to wait for the component, which will have the given name.

• -w to wait for the program to exit

• -i to ignore the program return value (with -w)

waitusr name
(wait for Userspace component) Waits for non-realtime component name to disconnect from HAL
(usually on exit). The component must already be loaded. Useful near the end of a HAL file to
wait until the user closes some user interface component before cleaning up and exiting.

unloadusr compname
(unload Userspace component) Unloads a non-realtime component called compname. If compname is
"all", it will unload all non-realtime components. unloadusr works by sending SIGTERM to all non-
realtime components.

unload compname
Unloads a non-realtime component or realtime module. If compname is "all", it will unload all
non-realtime components and realtime modules.

newsig signame type
(OBSOLETE - use net instead) (new signal) Creates a new HAL signal called signame that may later
be used to connect two or more HAL component pins. type is the data type of the new signal, and
must be one of "bit", "s32", "u32", or "float". Fails if a signal of the same name already
exists.

delsig signame
(delete signal) Deletes HAL signal signame. Any pins currently linked to the signal will be
unlinked. Fails if signame does not exist.

sets signame value
(set signal) Sets the value of signal signame to value. Fails if signame does not exist, if it
already has a writer, or if value is not a legal value. Legal values depend on the signals's
type.

stype name
(signal type) Gets the type of signal name. Fails if name does not exist as a signal.

gets signame
(get signal) Gets the value of signal signame. Fails if signame does not exist.

linkps pinname [arrow] signame
(OBSOLETE - use net instead) (link pin to signal) Establishes a link between a HAL component pin
pinname and a HAL signal signame. Any previous link to pinname will be broken. arrow can be
"=>", "<=", "<=>", or omitted. halcmd 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 pinname or signame does not exist, or if they
are not the same type type.

linksp signame [arrow] pinname
(OBSOLETE - use net instead) (link signal to pin) Works like linkps but reverses the order of the
arguments. halcmd treats both link commands exactly the same. Use whichever you prefer.

linkpp pinname1 [arrow] pinname2
(OBSOLETE - use net instead) (link pin to pin) Shortcut for linkps that creates the signal (named
like the first pin), then links them both to that signal. halcmd treats this just as if it were:
halcmd newsig pinname1
halcmd linksp pinname1 pinname1
halcmd linksp pinname1 pinname2

net signame pinname ...
Create signname to match the type of pinname if it does not yet exist. Then, link signame to each
pinname in turn. Arrows may be used as in linkps. When linking a pin to a signal for the first
time, the signal value will inherit the pin's default value.

unlinkp pinname
(unlink pin) Breaks any previous link to pinname. Fails if pinname does not exist. An unlinked
pin will retain the last value of the signal it was linked to.

setp name value
(set parameter or pin) Sets the value of parameter or pin name to value. Fails if name 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 value 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.

paramname = value

pinname = value
Identical to setp. This alternate form of the command may be more convenient and readable when
used in a file.

ptype name
(parameter or pin type) Gets the type of parameter or pin name. Fails if name 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.

getp name
(get parameter or pin) Gets the value of parameter or pin name. Fails if name 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.

addf functname threadname
(add function) Adds function functname to realtime thread threadname. functname will run after
any functions that were previously added to the thread. Fails if either functname or threadname
does not exist, or if they are incompatible.

delf functname threadname
(delete function) Removes function functname from realtime thread threadname. Fails if either
functname or threadname does not exist, or if functname is not currently part of threadname.

start Starts execution of realtime threads. Each thread periodically calls all of the functions that
were added to it with the addf command, in the order in which they were added.

stop Stops execution of realtime threads. The threads will no longer call their functions.

show [item]
Prints HAL items to stdout in human readable format. item can be one of "comp" (components),
"pin", "sig" (signals), "param" (parameters), "funct" (functions), "thread", or "alias". The type
"all" can be used to show matching items of all the preceding types. If item is omitted, show
will print everything.

save [item]
Prints HAL items to stdout in the form of HAL commands. These commands can be redirected to a
file and later executed using halcmd -f to restore the saved configuration. item can be one of
the following:

"comp" generates a loadrt command for realtime component.

"alias" generates an alias command for each pin or parameter alias pairing

"sig" (or "signal") generates a newsig command for each signal, and "sigu" generates a newsig
command for each unlinked signal (for use with netl and netla).

"link" and "linka" both generate linkps commands for each link. (linka includes arrows, while
link does not.)

"net" and "neta" both generate one newsig command for each signal, followed by linksp commands
for each pin linked to that signal. (neta includes arrows.)

"netl" generates one net command for each linked signal, and "netla" (or "netal") generates a
similar command using arrows.

"param" (or "parameter) "generates one setp command for each parameter.

"thread" generates one addf command for each function in each realtime thread.

"unconnectedinpins" generates a setp command for each unconnected HAL input pin.

If item is allu), save does the equivalent of comp, alias, sigu, netla, param, thread, and
unconnectedinpins.

If item is omitted (or all), save does the equivalent of comp, alias, sigu, netla, param, and
thread.

source filename.hal
Execute the commands from filename.hal.

alias type name alias
Assigns "alias" 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 pin or param.
"name" must be an existing name or alias of the specified type. Note that the "show" command
will only show the aliased name, but the original name is still valid to use in HAL. The original
names can still be seen with "show all" or "show alias" Existing nets will be preserved when a pin
name is aliased.

unalias type alias
Removes any alias from the pin or parameter alias.
"type" must be pin or param
"alias" must be an existing name or alias of the specified type.

list type [pattern]
Prints the names of HAL items of the specified type.
'type' is 'comp', 'pin', 'sig', 'param', 'funct', or
'thread'. If 'pattern' is specified it prints only
those names that match the pattern, which may be a
'shell glob'.
For 'sig', 'pin' and 'param', the first pattern may be
-tdatatype 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.

print [message]
Prints the filename, linenumber and an optional message.
wrap the message in quotes if it has spaces.

lock [all|tune|none]
Locks HAL to some degree.
none - no locking done.
tune - some tuning is possible (setp & such).
all - HAL completely locked.

unlock [all|tune]
Unlocks HAL to some degree.
tune - some tuning is possible (setp & such).
all - HAL completely unlocked.

status [type]
Prints status info about HAL.
'type' is 'lock', 'mem', or 'all'.
If 'type' is omitted, it assumes 'all'.

debug [level]
Sets the rtapi messaging level (see man3 rtapi_set_msg_level).

help [command]
Give help information for command.
If 'command' is omitted, list command and brief description.

SUBSTITUTION

       After a command is read but before it is executed, several types of variable substitution take place.

   Environment Variables
       Environment variables have the following formats:

              $ENVVAR followed by end-of-line or whitespace

              $(ENVVAR)

   INI file variables
       INI  file variables are available only when an INI file was specified with the halcmd -i flag.  They have
       the following formats:

              [SECTION]VAR followed by end-of-line or whitespace

              [SECTION](VAR)

LINE CONTINUATION

       The backslash character (\) may be used to indicate the line is extended to the next line.  The backslash
       character must be the last character before the newline.

BUGS

       None known at this time.

AUTHOR

       Original version by John Kasunich, as part of the LinuxCNC project.  Now includes major contributions  by
       several members of the project.

REPORTING BUGS

       Report bugs to the LinuxCNC bug tracker ⟨https://github.com/LinuxCNC/linuxcnc/issues⟩.

COPYRIGHT

       Copyright © 2003 John Kasunich.
       This  is  free  software;  see  the  source  for  copying conditions.  There is NO warranty; not even for
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.