HALCMD(1)

📦
version 2.9.4 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 HALCMD(1) — the HAL User's Manual, but make it a group chat 💖

okay bestie, so this is halcmd, from the LinuxCNC HAL User's Manual, and honestly? she's iconic. she runs the whole Hardware Abstraction Layer from your command line and she does NOT need a GUI to slay. let's get into it. 🫶

✨ NAME ✨

halcmd — manipulate the LinuxCNC HAL from the command line. that's it, that's the girl. 💅

🌸 SYNOPSIS 🌸

halcmd [OPTIONS] [COMMAND [ARG]]

🦋 DESCRIPTION 🦋

so like, halcmd is what you use to manipulate the HAL (Hardware Abstraction Layer, keep up 💜) straight from the command line. and the best part? halcmd can optionally read commands from a file, which means you can set up whole complex HAL configurations with a single command. no cap, one command. 👑

and if the readline library was available when LinuxCNC got compiled? then halcmd gives you commandline editing and completion when you're running interactively. hit the up arrow to recall your previous commands (your history, your lore ✨), and press tab to complete the names of things like pins and signals. it's giving autocomplete luxury. 😌

✨ OPTIONS ✨

  • -I — before tearing down the realtime environment, run an interactive halcmd. halrun only. and if you're using -I, it has to come before all other commandline arguments. it's the line leader, periodt. 🎀
  • -f [<file>] — ignore the commands on the command line, take input from a file instead. if file isn't specified, take input from stdin. 🍓
  • -i <INI file> — use variables from the specified INI file for substitutions. peep SUBSTITUTION below, bestie, it's down there. 💜
  • -k — keep going after failed command(s). the default is to stop and return failure if any command fails, so this one is the "we don't stop, we keep it pushing" flag. 🔥
  • -q — display errors only (this is the default, so if you did nothing, this is what you got 🌸)
  • -Q — display nothing, execute commands silently. stealth mode. 🙈
  • -s — script-friendly mode. in this mode, show will not output titles for the items shown. also, module names get printed instead of ID codes in pin, param, and funct listings. threads get 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 get printed on a single line too, 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. it's giving compact, it's giving parseable. ✨
  • -R — release the HAL mutex. this is the rescue flag 🚑 — 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. and if you pass a command, it displays extended help on that command. 🫶

👑 COMMANDS 👑

commands are what tell halcmd what to do. normally halcmd reads a single command from the command line and executes it. but if you used the -f option to read commands from a file, halcmd reads each line of the file as a new command. and anything following # on a line? that's a comment, bestie. 🎀

🧚 loadrt modname

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

on 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 it's compiled with a whitelist of modules it's allowed to load. currently that's just a list of LinuxCNC-related modules. the linuxcnc_module_helper execs insmod, so the return codes and error messages are the ones from insmod. and admins who want to restrict which users can load these LinuxCNC-related kernel modules can do that by setting the permissions and group on linuxcnc_module_helper appropriately. 💅

on systems with userspace-based realtime support (e.g. Preempt-RT) and on systems with no realtime support at all, halcmd calls the rtapi_app which creates the realtime environment (simulated realtime, on systems with no userspace realtime support) if it didn't exist yet, 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. symmetric queen. ✨

💜 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. super useful near the end of a HAL file, to wait until the user closes some user interface component before cleaning up and exiting. it's giving "we don't leave until she leaves." 😭

🌸 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. she does both, she contains multitudes. 👑

⭐ 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 doesn't exist.

🔥 sets signame value

(set signal) sets the value of signal signame to value. fails if signame doesn't exist, if it already has a writer, or if value isn't a legal value. legal values depend on the signal's type. 🫶

🌈 stype name

(signal type) gets the type of signal name. fails if name doesn't exist as a signal.

✨ gets signame

(get signal) gets the value of signal signame. fails if signame doesn't 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 doesn't exist, or if they aren't the same 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, bestie, no judgement here. 💜

🍓 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 doesn't 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. the modern main character. ⭐

🌸 unlinkp pinname

(unlink pin) breaks any previous link to pinname. fails if pinname doesn't exist. an unlinked pin will retain the last value of the signal it was linked to. she remembers. 😌

💅 setp name value

(set parameter or pin) sets the value of parameter or pin name to value. fails if name doesn't exist as a pin or parameter, if it's a parameter that isn't writable, if it's a pin that's an output, if it's a pin that's already attached to a signal, or if value isn't a legal value. legal values depend on the type of the pin or parameter. and heads up: if both a pin and a parameter 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. yes bestie, it's just vibes and an equals sign. ✨

🌈 ptype name

(parameter or pin type) gets the type of parameter or pin name. fails if name doesn't 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 doesn't exist as a pin or parameter. and yeah — 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 doesn't exist, or if they're incompatible. it's giving queue energy. 🎀

🦋 delf functname threadname

(delete function) removes function functname from realtime thread threadname. fails if either functname or threadname doesn't exist, or if functname isn't 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. go girl, go. 👑

🍓 stop

stops execution of realtime threads. the threads will no longer call their functions. sit down, bestie. 😭

🌸 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. everything. all of it. no notes. ✨

💜 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 — spits out a loadrt command for a realtime component. ✨
    • alias — spits out an alias command for every pin or parameter alias pairing. 🎀
    • sig (or signal) — spits out a newsig command for every signal. And sigu spits out a newsig command for every unlinked signal (that's the one you want when you're pairing it with netl and netla). 🦋
    • link and linka — both spit out linkps commands for each link. (linka includes arrows, link does not. that's literally the whole difference bestie.)
    • net and neta — both spit out one newsig command for each signal, followed by linksp commands for every pin linked to that signal. (neta includes arrows.) 💅
    • netl — spits out one net command for each linked signal. netla (or netal) — same vibe but with arrows. 🏹
    • param (or parameter) — spits out one setp command for each parameter.
    • thread — spits out one addf command for each function in each realtime thread. 🧵
    • unconnectedinpins — spits out 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 — runs the commands in filename.hal. go read your little script, king 👑
  • alias type name alias — gives alias a second name for the pin or parameter name. For most operations an alias is just a second name you can use 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. Heads up though: the show command will only show the aliased name, but the original name is still valid to use in HAL. You can still peep the original names with show all or show alias. And no cap — existing nets are preserved when a pin name gets 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 the 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 that 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, bestie.
  • 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] — gives help information for command. If command is omitted, it lists the command and a brief description. the little built-in tutorial, we love her 📖

✨ SUBSTITUTION ✨

After a command is read but before it is executed, several types of variable substitution take place. it's giving ✨magic✨ but make it documented.

🌍 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. no sneaky trailing spaces, she WILL notice 😭

💀 BUGS 💀

None known at this time. (iconic behaviour, honestly. zero notes.)

👑 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 © 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.

👀 SEE ALSO 👀

halrun(1) — a convenience script to start a realtime environment, process a HAL or a .tcl file, and optionally start an interactive command session using halcmd (described here) or haltcl(1). 💖

and that's the whole page, bestie! 🌈 This lil' slice of LinuxCNC Documentation, dated 2003-12-18, belongs to the HALCMD(1) manual — go forth and save allu) responsibly. 💅✨🎀

📦 where this page comes from