tools.txt
1 [[cha:hal-tools]] 2 3 = HAL Tools 4 5 [[sec:halcmd]] 6 7 == Halcmd 8 9 Halcmd is a command line tool for manipulating the HAL. There is a 10 rather complete man page for halcmd, which will be installed if you 11 have installed LinuxCNC from either source or a package. The manpage 12 provides usage info: 13 14 ---- 15 man halcmd 16 ---- 17 18 If you have compiled LinuxCNC for “run-in-place”, you must source 19 the rip-environment script to make the man page available: 20 21 ---- 22 cd toplevel_directory_for_rip_build 23 . scripts/rip-environment 24 man halcmd 25 ---- 26 27 The <<cha:hal-tutorial,HAL Tutorial>> has a number of examples of halcmd 28 usage, and is a good tutorial for halcmd. 29 30 [[sec:halmeter]](((Halmeter))) 31 32 == Halmeter 33 34 Halmeter is a 'voltmeter' for the HAL. It lets you look at a pin, 35 signal, or parameter, and displays the current value of that item. It 36 is pretty simple to use. Start it by typing *halmeter* in an X 37 windows shell. Halmeter is a GUI application. It will pop up 38 a small window, with two buttons labeled 'Select' and 'Exit'. Exit is 39 easy - it shuts down the program. Select pops up a larger window, with 40 three tabs. One tab lists all the pins currently defined in the HAL. 41 The next lists all the signals, and the last tab lists all the 42 parameters. Click on a tab, then click on a pin/signal/parameter. Then 43 click on 'OK'. The lists will disappear, and the small window will 44 display the name and value of the selected item. The display is updated 45 approximately 10 times per second. If you click 'Accept' instead of 46 'OK', the small window will display the name and value of the selected 47 item, but the large window will remain on the screen. This is 48 convenient if you want to look at a number of different items quickly. 49 50 You can have many halmeters running at the same time, if you want to 51 monitor several items. If you want to launch a halmeter without tying 52 up a shell window, type 'halmeter &' to run it in the background. 53 You can also make halmeter start 54 displaying a specific item immediately, by adding 'pin|sig|par[am] 55 <name>' to the command line. It will display the pin, signal, or 56 parameter 57 <name> as soon as it starts. (If there is no such item, it will simply 58 start normally.) And finally, if you specify an item to display, you 59 can add '-s' before the pin|sig|param to tell halmeter to use a small 60 window. The item name will be displayed in the title bar instead of 61 under the value, and there will be no buttons. Useful when you want a 62 lot of meters in a small amount of screen space. 63 64 Refer to <<sec:tutorial-halmeter,Halmeter Tutorial>> section for more 65 information. 66 67 Halmeter can be loaded from a terminal or from Axis. Halmeter is 68 faster than Halshow at displaying values. Halmeter has two windows, one 69 to pick the pin, signal, or parameter to monitor and one that displays 70 the value. Multiple Halmeters can be open at the same time. If you use 71 a script to open multiple Halmeters you can set the position of each 72 one with -g X Y relative to the upper left corner of your screen. 73 For example: 74 75 ---- 76 loadusr halmeter pin hm2.0.stepgen.00.velocity-fb -g 0 500 77 ---- 78 79 See the man page for more options. See section <<sec:halmeter,Halmeter>>. 80 81 .Halmeter 82 83 image::images/hal-meter01.png[alt="Halmeter"] 84 85 image::images/hal-meter02.png[alt="Halmeter"] 86 87 == Halshow 88 89 Halshow (see separate section for complete usage description) 90 can be started from the command line to show details for selected 91 components, pins, parameters, signals, functions, and threads of a running HAL. 92 The WATCH tab provides a continuous display of selected pin, parameters, and 93 signal items. The File menu provides buttons to 1) save the watch items to 94 a watch list and to load and existing watch list. The watch list items can 95 also be loaded automatically on startup. For command line usage: 96 97 ---- 98 halshow --help 99 Usage: 100 halshow [Options] [watchfile] 101 Options: 102 --help (this help) 103 --fformat format_string_for_float 104 --iformat format_string_for_int 105 106 Notes: 107 Create watchfile in halshow using: 'File/Save Watch List' 108 linuxcnc must be running for standalone usage 109 ---- 110 111 LinuxCNC must be running for standalone usage 112 113 A watchfile created using the 'File/Save Watch List' menu item 114 is formatted as a single line with tokens "pin+", "param+", "sig=+" 115 followed by the appropriate pin, param, or signal name. The 116 token-name pairs are separated by a space character. 117 118 Example: 119 pin+joint.0.pos-hard-limit pin+joint.1.pos-hard-limit sig+estop-loop 120 121 A watchfile created using the 'File/Save Watch List (multiline)' menu item 122 is formatted with separate lines for each item identified with token-name 123 pairs as described above. 124 125 Example: 126 pin+joint.0.pos-hard-limit 127 pin+joint.1.pos-hard-limit 128 sig+estop-loop 129 130 When loading a watchfile with the 'File/Load Watch List' menu item, the 131 token-name pairs may appear as single or mulitple lines. Blank lines and 132 lines beginning with a # character are ignored. 133 134 135 [[sec:halscope]] 136 137 == Halscope 138 139 Halscope is an 'oscilloscope' for the HAL. It lets you capture the 140 value of pins, signals, and parameters as a function of time. Complete 141 operating instructions should be located here eventually. For now, 142 refer to section <<sec:tutorial-halscope>> in the tutorial chapter, 143 which explains the basics. 144 145 The halscope File menu selector provides buttons to save a configuration 146 or open a previously saved configuration. When halscope is terminated, 147 the last configuration is saved in a file named autosave.halscope. 148 149 Configuration files may also be specified when starting halscope from 150 the commandline. Commandline help (-h) usage: 151 ---- 152 halscope -h 153 Usage: 154 halscope [-h] [-i infile] [-o outfile] [num_samples] 155 ---- 156 157 == Sim Pin 158 159 sim_pin is a command line utility to display and update any number of 160 writable pins, parameters or signals. Usage: 161 ---- 162 Usage: 163 sim_pin [Options] name1 [name2 ...] & 164 165 Options: 166 --help (this text) 167 --title title_string (window title, default: sim_pin) 168 169 Note: LinuxCNC (or a standalone Hal application) must be running 170 A named item can specify a pin, param, or signal 171 The item must be writable, e.g.: 172 pin: IN or I/O (and not connected to a signal with a writer) 173 param: RW 174 signal: connected to a writable pin 175 176 Hal item types bit,s32,u32,float are supported 177 178 When a bit item is specifed, a pushbutton is created 179 to manage the item in one of three manners specified 180 by radio buttons: 181 toggle: Toggle value when button pressed 182 pulse: Pulse item to 1 once when button pressed 183 hold: Set to 1 while button pressed 184 The bit pushbutton mode can be specifed on the command 185 line by formatting the item name: 186 namei/mode=[toggle | pulse | hold] 187 If the mode begins with an uppercase letter, the radio 188 buttons for selecting other modes are not shown 189 ---- 190 For complete information, see the man page: 191 ---- 192 man sim_pin 193 ---- 194 Example (with LinuxCNC running): 195 ---- 196 halcmd loadrt mux2 names=example; halcmd net sig_example example.in0 197 sim_pin example.sel example.in1 sig_example & 198 ---- 199 image::images/sim_pin.png[alt="sim_pin is a command line utility to display and update any number of writable pins, parameters or signals"] 200 201 == Simulate Probe 202 203 simulate_probe is a simple gui to simulate activation of the pin 204 motion.probe-input. Usage: 205 ---- 206 simulate_probe & 207 ---- 208 209 image::images/simulate_probe.png[alt="simulate_probe is a simple gui to simulate activation of the pin motion.probe-input"] 210 211 == Hal Histogram 212 213 hal-histogram is a command line utility to display histograms for hal pins. 214 ---- 215 Usage: 216 hal-histogram --help | -? 217 or 218 hal-histogram [Options] [pinname] 219 220 Options: 221 --minvalue minvalue (minimum bin, default: 0) 222 --binsize binsize (binsize, default: 100) 223 --nbins nbins (number of bins, default: 50) 224 225 --logscale 0|1 (y axis log scale, default: 1) 226 --text note (text display, default: "" ) 227 --show (show count of undisplayed nbins, default off) 228 --verbose (progress and debug, default off) 229 230 Notes: 231 1) LinuxCNC (or another Hal application) must be running 232 2) If no pinname is specified, default is: motion-command-handler.time 233 3) This app may be opened for 5 pins 234 4) pintypes float, s32, u32, bit are supported 235 5) The pin must be associated with a thread supporting floating point 236 For a base thread, this may require using: 237 loadrt motmod ... base_thread_fp=1 238 ---- 239 image::images/hal-histogram.png[alt="hal-histogram is a command line utility to display histograms for hal pins"] 240 241 == Halreport 242 243 halreport is a command-line utility that generates a report about hal 244 connections for a running LinuxCNC (or other hal) application. The 245 report shows all signal connections and flags potential problems. 246 Information included: 247 248 . System description and kernel version. 249 . Signals and all connected output, io, and input pins. 250 . Each pin's component_function, thread, and addf-order. 251 . Userspace component pins having non-ordered functions. 252 . Identification of unknown functions for unhandled components. 253 . Signals with no output. 254 . Signals with no inputs. 255 . Functions with no addf. 256 . Warning tags for components marked as deprecated/obsolete in docs. 257 . Real names for pins that use alias names. 258 259 The report can be generated from the command line and directed to 260 an output file (or stdout if no outfilename is specified): 261 262 ---- 263 Usage: 264 halreport -h | --help (this help) 265 or 266 halreport [outfilename] 267 ---- 268 269 To generate the report for every LinuxCNC startup, include halreport 270 and an output filename as an [APPLICATIONS]APP entry in the ini file. 271 Example: 272 273 ---- 274 [APPLICATIONS] 275 APP = halreport /tmp/halreport.txt 276 ---- 277 278 The function addf-ordering can be important for servo loops where 279 the sequence of the functions computed at each servo period is 280 important. Typically, the order is: read input pins, do the 281 motion command-handler and motion-controller functions, perform 282 pid calculations, and finally write output pins. 283 284 For each signal in a critical path, the addf-order of the output 285 pin should be numerically lower than the addf-order of the 286 critical input pins that it connects to. 287 288 For routine signal paths that handle switch inputs, user-space 289 pins, etc., the addf-ordering is often not critical. Moreover, 290 the timing of user-space pin value changes cannot be controlled 291 or guaranteed at the intervals typically employed for hal threads. 292 293 Example report file excerpts showing a pid loop for a hostmot2 294 stepgen operated in velocity mode on a trivkins machine with 295 joint.0 corresponding to the X axis coordinate: 296 297 ---- 298 SIG: pos-fb-0 299 OUT: h.00.position-fb hm2_7i92.0.read servo-thread 001 300 (=hm2_7i92.0.stepgen.00.position-fb) 301 IN: X_pid.feedback X_pid.do-pid-calcs servo-thread 004 302 IN: joint.0.motor-pos-fb motion-command-handler servo-thread 002 303 .................... motion-controller servo-thread 003 304 ... 305 SIG: pos-cmd-0 306 OUT: joint.0.motor-pos-cmd motion-command-handler servo-thread 002 307 ..................... motion-controller servo-thread 003 308 IN: X_pid.command X_pid.do-pid-calcs servo-thread 004 309 ... 310 SIG: motor-cmd-0 311 OUT: X_pid.output X_pid.do-pid-calcs servo-thread 004 312 IN: h.00.velocity-cmd hm2_7i92.0.write servo-thread 008 313 (=hm2_7i92.0.stepgen.00.velocity-cmd) 314 ---- 315 316 In the example above, the HALFILE uses halcmd aliases to simplify pin names 317 for an hostmot2 fpga board with commands like: 318 ---- 319 alias pin hm2_7i92.0.stepgen.00.position-fb h.00.position-fb 320 ---- 321 322 [NOTE] 323 Questionable component function detection may occur for 1) 324 unsupported (deprecated) components, 2) user-created components 325 that use multiple functions or unconventional function naming, or 326 3) gui-created userspace components that lack distinguishing 327 characteristics such as a prefix based on the gui program name. 328 Questionable functions are tagged with a question mark "?". 329 330 [NOTE] 331 Component pins that cannot be associated with a known thread 332 function report the function as "Unknown". 333 334 [NOTE] 335 halreport generates a connections report for a running hal 336 application to aid in designing and verifying connections. Pin 337 types and current values are not shown. For this information use 338 applications like halshow, halmeter, halscope or the 'show' 339 command available with comand-line halcmd program.