:lang: en
:toc:

[[cha:hal-tools]]
= HAL Tools(((HAL Tools)))

// Custom lang highlight
// must come after the doc title, to work around a bug in asciidoc 8.6.6
:ini: {basebackend@docbook:'':ini}
:hal: {basebackend@docbook:'':hal}
:ngc: {basebackend@docbook:'':ngc}

[[sec:halcmd]]
== Halcmd

Halcmd is a command line tool for manipulating the HAL. There is a
rather complete man page for link:../man/man1/halcmd.1.html[halcmd], which will be installed if you
have installed LinuxCNC from either source or a package. The manpage
provides usage info:

----
man halcmd
----

If you have compiled LinuxCNC for "run-in-place", you must source
the rip-environment script to make the man page available:

----
cd toplevel_directory_for_rip_build
. scripts/rip-environment
man halcmd
----

The <<cha:hal-tutorial,HAL Tutorial>> has a number of examples of halcmd
usage, and is a good tutorial for halcmd.

[[sec:halmeter]]
== Halmeter(((Halmeter)))

Halmeter is a 'voltmeter' for the HAL. It lets you look at a pin,
signal, or parameter, and displays the current value of that item. It
is pretty simple to use. Start it by typing *halmeter* in an X
windows shell. Halmeter is a GUI application. It will pop up
a small window, with two buttons labeled 'Select' and 'Exit'. Exit is
easy - it shuts down the program. Select pops up a larger window, with
three tabs. One tab lists all the pins currently defined in the HAL.
The next lists all the signals, and the last tab lists all the
parameters. Click on a tab, then click on a pin/signal/parameter. Then
click on 'OK'. The lists will disappear, and the small window will
display the name and value of the selected item. The display is updated
approximately 10 times per second. If you click 'Accept' instead of
'OK', the small window will display the name and value of the selected
item, but the large window will remain on the screen. This is
convenient if you want to look at a number of different items quickly.

You can have many halmeters running at the same time, if you want to
monitor several items. If you want to launch a halmeter without tying
up a shell window, type 'halmeter &' to run it in the background.
You can also make halmeter start
displaying a specific item immediately, by adding 'pin|sig|par[am]
<name>' to the command line. It will display the pin, signal, or
parameter
<name> as soon as it starts. (If there is no such item, it will simply
start normally.) And finally, if you specify an item to display, you
can add '-s' before the pin|sig|param to tell halmeter to use a small
window. The item name will be displayed in the title bar instead of
under the value, and there will be no buttons. Useful when you want a
lot of meters in a small amount of screen space.

Refer to <<sec:tutorial-halmeter,Halmeter Tutorial>> section for more information.

Halmeter can be loaded from a terminal or from Axis. Halmeter is
faster than Halshow at displaying values. Halmeter has two windows, one
to pick the pin, signal, or parameter to monitor and one that displays
the value. Multiple Halmeters can be open at the same time. If you use
a script to open multiple Halmeters you can set the position of each
one with -g X Y relative to the upper left corner of your screen.
For example:

[source,{hal}]
----
loadusr halmeter pin hm2.0.stepgen.00.velocity-fb -g 0 500
----

See the man page for more options. See section <<sec:halmeter,Halmeter>>.

.Halmeter selection window
image::images/hal-meter01.png["Halmeter selection window"]

.Halmeter watch window
image::images/hal-meter02.png["Halmeter watch window"]

== Halshow

Halshow (<<cha:halshow,complete usage description>>)
can be started from the command line to show details for selected
components, pins, parameters, signals, functions, and threads of a running HAL.
The WATCH tab provides a continuous display of selected pin, parameters, and
signal items.  The File menu provides buttons to 1) save the watch items to
a watch list and to load and existing watch list.  The watch list items can
also be loaded automatically on startup.  For command line usage:

----
halshow --help
Usage:
  halshow [Options] [watchfile]
  Options:
           --help    (this help)
           --fformat format_string_for_float
           --iformat format_string_for_int

Notes:
       Create watchfile in halshow using: 'File/Save Watch List'
       linuxcnc must be running for standalone usage
----

LinuxCNC must be running for standalone usage.

.Halshow Watch Tab
image::images/halshow-4.png["Halshow Watch Tab",align="center"]

A watchfile created using the 'File/Save Watch List' menu item
is formatted as a single line with tokens "pin+", "param+", "sig=+"
followed by the appropriate pin, param, or signal name. The
token-name pairs are separated by a space character.

.Single Line Watchfile Example
----
pin+joint.0.pos-hard-limit pin+joint.1.pos-hard-limit sig+estop-loop
----

A watchfile created using the 'File/Save Watch List (multiline)' menu item
is formatted with separate lines for each item identified with token-name
pairs as described above.

.Separated Lines Watchfile Example
----
pin+joint.0.pos-hard-limit
pin+joint.1.pos-hard-limit
sig+estop-loop
----

When loading a watchfile with the 'File/Load Watch List' menu item, the
token-name pairs may appear as single or multiple lines.  Blank lines and
lines beginning with a # character are ignored.

[[sec:halscope]]
== Halscope

Halscope is an 'oscilloscope' for the HAL. It lets you capture the
value of pins, signals, and parameters as a function of time. Complete
operating instructions should be located here eventually. For now,
refer to section  <<sec:tutorial-halscope>> in the tutorial chapter,
which explains the basics.

The halscope File menu selector provides buttons to save a configuration
or open a previously saved configuration.  When halscope is terminated,
the last configuration is saved in a file named autosave.halscope.

Configuration files may also be specified when starting halscope from
the commandline.  Commandline help (-h) usage:

----
halscope -h
Usage:
  halscope [-h] [-i infile] [-o outfile] [num_samples]
----

== Sim Pin

sim_pin is a command line utility to display and update any number of
writable pins, parameters or signals.

.`sim_pin` Usage
----
  Usage:
         sim_pin [Options] name1 [name2 ...] &

  Options:
         --help                (this text)
         --title title_string  (window title, default: sim_pin)

  Note:  LinuxCNC (or a standalone Hal application) must be running
         A named item can specify a pin, param, or signal
         The item must be writable, e.g.:
            pin:    IN or I/O (and not connected to a signal with a writer)
            param:  RW
            signal: connected to a writable pin

         Hal item types bit,s32,u32,float are supported

         When a bit item is specified, a pushbutton is created
         to manage the item in one of three manners specified
         by radio buttons:
             toggle: Toggle value when button pressed
             pulse:  Pulse item to 1 once when button pressed
             hold:   Set to 1 while button pressed
         The bit pushbutton mode can be specified on the command
         line by formatting the item name:
             namei/mode=[toggle | pulse | hold]
         If the mode begins with an uppercase letter, the radio
         buttons for selecting other modes are not shown
----

For complete information, see the man page:

----
man sim_pin
----

.`sim_pin` Example (with LinuxCNC running)
----
halcmd loadrt mux2 names=example; halcmd net sig_example example.in0
sim_pin example.sel example.in1 sig_example &
----

.`sim_pin` Window
image::images/sim_pin.png["sim_pin Window"]

== Simulate Probe

simulate_probe is a simple gui to simulate activation of the pin motion.probe-input.
Usage:

----
simulate_probe &
----

.`simulate_probe` Window
image::images/simulate_probe.png["simulate_probe Window"]

== Hal Histogram

hal-histogram is a command line utility to display histograms for hal pins.

.`hal-histogram` Usage
----
Usage:
   hal-histogram --help | -?
or
   hal-histogram [Options] [pinname]

Options:
  --minvalue  minvalue (minimum bin, default: 0)
  --binsize   binsize  (binsize, default: 100)
  --nbins     nbins    (number of bins, default: 50)

  --logscale  0|1      (y axis log scale, default: 1)
  --text      note     (text display, default: "" )
  --show               (show count of undisplayed nbins, default off)
  --verbose            (progress and debug, default off)

Notes:
  1) LinuxCNC (or another Hal application) must be running
  2) If no pinname is specified, default is: motion-command-handler.time
  3) This app may be opened for 5 pins
  4) pintypes float, s32, u32, bit are supported
  5) The pin must be associated with a thread supporting floating point
     For a base thread, this may require using:
     loadrt motmod ... base_thread_fp=1
----

.`hal-histogram` Window
image::images/hal-histogram.png["hal-histogram Window"]

== Halreport

halreport is a command-line utility that generates a report about hal
connections for a running LinuxCNC (or other hal) application.  The
report shows all signal connections and flags potential problems.
Information included:

. System description and kernel version.
. Signals and all connected output, io, and input pins.
. Each pin's component_function, thread, and addf-order.
. Userspace component pins having non-ordered functions.
. Identification of unknown functions for unhandled components.
. Signals   with no output.
. Signals   with no inputs.
. Functions with no addf.
. Warning tags for components marked as deprecated/obsolete in docs.
. Real names for pins that use alias names.

The report can be generated from the command line and directed to
an output file (or stdout if no outfilename is specified):

.`halreport` Usage
----
Usage:
  halreport -h | --help (this help)
or
  halreport [outfilename]
----

To generate the report for every LinuxCNC startup, include halreport
and an output filename as an [APPLICATIONS]APP entry in the ini file.

.`halreport` Example
[source,{ini}]
----
[APPLICATIONS]
APP = halreport /tmp/halreport.txt
----

The function addf-ordering can be important for servo loops where
the sequence of the functions computed at each servo period is
important.  Typically, the order is: read input pins, do the
motion command-handler and motion-controller functions, perform
pid calculations, and finally write output pins.

For each signal in a critical path, the addf-order of the output
pin should be numerically lower than the addf-order of the
critical input pins that it connects to.

For routine signal paths that handle switch inputs, user-space
pins, etc., the addf-ordering is often not critical.  Moreover,
the timing of user-space pin value changes cannot be controlled
or guaranteed at the intervals typically employed for hal threads.

Example report file excerpts showing a pid loop for a hostmot2
stepgen operated in velocity mode on a trivkins machine with
joint.0 corresponding to the X axis coordinate:

----
SIG:    pos-fb-0
  OUT:    h.00.position-fb                     hm2_7i92.0.read        servo-thread 001
          (=hm2_7i92.0.stepgen.00.position-fb)
    IN:     X_pid.feedback                     X_pid.do-pid-calcs     servo-thread 004
    IN:     joint.0.motor-pos-fb               motion-command-handler servo-thread 002
            ....................               motion-controller      servo-thread 003
...
SIG:    pos-cmd-0
  OUT:    joint.0.motor-pos-cmd                motion-command-handler servo-thread 002
          .....................                motion-controller      servo-thread 003
    IN:     X_pid.command                      X_pid.do-pid-calcs     servo-thread 004
...
SIG:    motor-cmd-0
  OUT:    X_pid.output                         X_pid.do-pid-calcs     servo-thread 004
    IN:     h.00.velocity-cmd                  hm2_7i92.0.write       servo-thread 008
            (=hm2_7i92.0.stepgen.00.velocity-cmd)
----

In the example above, the HALFILE uses halcmd aliases to simplify pin names
for an hostmot2 fpga board with commands like:

[source,{hal}]
----
alias pin hm2_7i92.0.stepgen.00.position-fb h.00.position-fb
----

[NOTE]
====
Questionable component function detection may occur for

. unsupported (deprecated) components,
. user-created components that use multiple functions or unconventional function naming, or
. GUI-created userspace components that lack distinguishing characteristics such as a prefix based on the GUI program name.

Questionable functions are tagged with a question mark "?".
====

[NOTE]
Component pins that cannot be associated with a known thread
function report the function as "Unknown".

[NOTE]
halreport generates a connections report for a running hal
application to aid in designing and verifying connections.  Pin
types and current values are not shown.  For this information use
applications like halshow, halmeter, halscope or the 'show'
command available with command-line halcmd program.

// vim: set syntax=asciidoc:
