--- name: "halcmd" section: "1" platform: "linux" package: "linuxcnc-uspace" version: "1:2.9.4-2+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/halcmd" --- # halcmd(1) manipulate the LinuxCNC HAL from the command line ## 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** \[*\*\] Ignore commands on command line, take input from *file* instead. If *file* is not specified, take input from *stdin*. - **-i** *\* 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** \[*\*\] 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* *r*eal*t*ime 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)](/dlopen/3.md)**. - **unloadrt** *modname* (*unload* *r*eal*t*ime 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* *Us*e*r*space 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 *Us*e*r*space 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* *Us*e*r*space 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* *sig*nal) 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* (*del*ete *sig*nal) Deletes HAL signal *signame*. Any pins currently linked to the signal will be unlinked. Fails if *signame* does not exist. - **sets** *signame* *value* (*set* *s*ignal) 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* (*s*ignal type) Gets the type of signal *name*. Fails if *name* does not exist as a signal. - **gets** *signame* (*get* *s*ignal) Gets the value of signal *signame*. Fails if *signame* does not exist. - **linkps** *pinname* \[*arrow*\] *signame* (OBSOLETE - use **net** instead) (*link* *p*in to *s*ignal) 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* *s*ignal to *p*in) 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* *p*in to *p*in) 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* *p*in) 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* *p*arameter or *p*in) 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* (*p*arameter or *p*in *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* *p*arameter or *p*in) 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* *f*unction) 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* (*del*ete *f*unction) 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\ \-t**datatype** 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 ⟨URL: 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. ## SEE ALSO **[halrun(1)](/halrun/1.md)** -- 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)](/haltcl/1.md).