HALCMD

NAME

halcmd — manipulate the Machinekit HAL from the command line

SYNOPSIS

halcmd

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 Machinekit 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 inifile
Use variables from inifile 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.

No prompt will be printed if both -s and -f are specified.

-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

loadrt modname [names=n,n,n [count=N]] (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 realtime, 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 Machinekit-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.

names= is followed by a comma delimited list of new names to be applied to the components
count= is followed by the number of components required, numbered component0 to componentX

Note	The 'linuxcnc' name is retained for the time being in several files where there is a complex interdependence chain

In systems without realtime halcmd calls the rtapi_app which creates the simulated realtime environment if it did not yet exist, and then loads the requested component with a call to dlopen.

unloadrt

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

loadusr [flags] unix-command (load Userspace component)

Executes the given unix-command, usually to load a userspace component.

[flags] may be one or more of:

-W
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
Wait for the component, which will have the given name.

-w
Wait for the program to exit

-i
Ignore the program return value (with -w)

waitusr

waitusr [-i] name (wait for Userspace component)

Waits for user space component name to disconnect from HAL (usually on exit).

If the component is not loaded, or exited already, waitusr will fail the halcmd script with a nonzero exit status.
This can be suppressed using the [-i] flag.

Usefull near the end of a HAL file to wait until the user closes some user interface component before cleaning up and exiting.

unloadusr

unloadusr compname (unload Userspace component)

Unloads a userspace component called compname.

If compname is "all", it will unload all userspace components.
unloadusr works by sending SIGTERM to all userspace components.

unload

unload compname

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

newsig

newsig signame type (new signal)

Note	OBSOLETE - use 'net' instead

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

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

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

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

linkps pinname [arrow] signame (link pin to signal)

Note	OBSOLETE - use 'net' instead

Establishs 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

linksp signame [arrow] pinname (link signal to pin)

Note	OBSOLETE - use 'net' instead

Works like linkps but reverses the order of the arguments.
halcmd treats both link commands exactly the same. Use whichever you prefer.

linkpp

linkpp pinname1 [arrow] pinname2 (link pin to pin)

Note	OBSOLETE - use 'net' instead

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

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

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

setp name value (set parameter or pin)

Sets the value of parameter or pinname 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

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

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.

newthread

newthread threadname [options] period

Creates a new HAL thread named threadname which runs every period nanoseconds. Options are:

fp thread supports floating point

nofp (default) thread does not support floating point

cpu=N run thread on CPU #N

cgname=/N run thread in cgroup cpuset:N

NB. See threads and latency information for advanced settings.

nowait (experimental) ignores period, thread free-runs and must be synchronized externally

posix (experimental) non-realtime posix thread. Can make Linux system calls, but has no timing guarantees

addf

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

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 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

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

sleep

sleep [seconds] Pause the halcmd script for the specified time.

show

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
    alias

The type "all" can be used to show matching items of all the preceeding types.
If item is omitted, show will print everything.

item

item This is equivalent to show all [item].

save

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.
"sig" generates a newsig command for each signal
"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" generates a similar command using arrows.
"param" generates one setp command for each parameter.
"thread" generates one addf command for each function in each realtime thread.

If item is omitted, save does the equivalent of comp, sigu, link, param, and thread.

source

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

alias

alias type name alias

Note	DEPRECATED - use 'loadrt <compname> names=' instead

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.

unalias

unalias type alias

Note	DEPRECATED - use 'loadrt <compname> names=' instead

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

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.

lock

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

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

status

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

If 'type' is omitted, it assumes 'all'.

help

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)

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

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

[SECTION](VAR)

EXAMPLES

HISTORY

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 that project and has been heavily modified within the Machinekit project.

REPORTING BUGS

Report bugs to the Machinekit forum https://groups.google.com/forum/#!forum/machinekit