diff --git a/docs/src/Master_Documentation.adoc b/docs/src/Master_Documentation.adoc index c642b51085e..9315491a307 100644 --- a/docs/src/Master_Documentation.adoc +++ b/docs/src/Master_Documentation.adoc @@ -88,6 +88,8 @@ include::hal/basic-hal.adoc[] include::hal/twopass.adoc[] +include::hal/tools.adoc[] + include::hal/tutorial.adoc[] include::hal/hal-examples.adoc[] @@ -110,8 +112,6 @@ include::hal/halmodule.adoc[] include::hal/canonical-devices.adoc[] -include::hal/tools.adoc[] - :leveloffset: 1 = Hardware Drivers diff --git a/docs/src/Submakefile b/docs/src/Submakefile index 72e1f07151c..b62c9d5546f 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -158,7 +158,6 @@ DOC_SRCS_EN := \ hal/general-ref.adoc \ hal/hal-examples.adoc \ hal/halmodule.adoc \ - hal/halshow.adoc \ hal/haltcl.adoc \ hal/halui-examples.adoc \ hal/intro.adoc \ diff --git a/docs/src/gui/qtvcp-widgets.adoc b/docs/src/gui/qtvcp-widgets.adoc index 1c2b689a9c4..1a75c744866 100644 --- a/docs/src/gui/qtvcp-widgets.adoc +++ b/docs/src/gui/qtvcp-widgets.adoc @@ -1527,7 +1527,7 @@ Enter any of these _case sensitive_ commands to load the respective program or a link:../hal/tools.html#sec:halmeter[`halmeter`] utility. *`HALSHOW`*:: Starts LinuxCNC - link:../hal/halshow.html#cha:halshow[`halshow`] utility. + link:../hal/tutorial.html#sec:halshow[`halshow`] utility. *`HALSCOPE`*:: Starts LinuxCNC link:../hal/tutorial.html#sec:tutorial-halscope[`halscope`] utility. diff --git a/docs/src/hal/halscope.adoc b/docs/src/hal/halscope.adoc new file mode 100644 index 00000000000..ae36e2f030f --- /dev/null +++ b/docs/src/hal/halscope.adoc @@ -0,0 +1,220 @@ +[[sec:tutorial-halscope]] +== Halscope + +(((Tutorial Halscope))) +The previous example generates some very interesting signals. But much +of what happens is far too fast to see with halmeter. To take a closer +look at what is going on inside the HAL, we want an oscilloscope. +Fortunately HAL has one, called halscope. + +Halscope has two parts - a realtime part that reads the HAL signals, and a non-realtime part that provides the GUI and display. However, you don't need to worry about this because the non-realtime part will automatically load the realtime part when needed. + +With LinuxCNC running in a terminal you can start halscope with the following command. + +.Starting Halscope +---- +halcmd loadusr halscope +---- + +If LinuxCNC is not running or the autosave.halscope file does not match +the pins available in the current running LinuxCNC the scope GUI window +will open, immediately followed by a 'Realtime function not linked' +dialog that looks like the following figure. To change the sample rate +left click on the samples box. + +[[fig:halscope-rt-function-not-linked]] +.Realtime function not linked dialog +image::images/halscope-01.png["Realtime function not linked dialog",align="center"] + +This dialog is where you set the sampling rate for the oscilloscope. +For now we want to sample once per millisecond, so click on the 1.00 ms +thread 'slow' and leave the multiplier at 1. We will also leave the +record length at 4000 samples, so that we can use up to four channels +at one time. When you select a thread and then click 'OK', the dialog +disappears, and the scope window looks something like the following +figure. + +[[fig:halscope-init-window]] +.Initial scope window +image::images/halscope-02.png["Initial scope window",align="center"] + +=== Hooking up the scope probes + +At this point, Halscope is ready to use. We have already selected a +sample rate and record length, so the next step is to decide what to +look at. This is equivalent to hooking 'virtual scope probes' to the +HAL. Halscope has 16 channels, but the number you can use at any one +time depends on the record length - more channels means shorter +records, since the memory available for the record is fixed at +approximately 16,000 samples. + +The channel buttons run across the bottom of the halscope screen. +Click button '1', and you will see the 'Select Channel Source' dialog +as shown in the following figure. This dialog is very similar to the +one used by Halmeter. We would like to look at the signals we defined +earlier, so we click on the 'Signals' tab, and the dialog displays all +of the signals in the HAL (only two for this example). + +[[fig:halscope-channel-source-selection]] +.Select Channel Source +image::images/halscope-03.png["Select Channel Source",align="center"] + +To choose a signal, just click on it. In this case, we want channel 1 +to display the signal 'X-vel'. Click on the Signals tab then click on +'X-vel' and the dialog closes and the channel is now selected. + +[[fig:halscope-source-signal-selection]] +.Select Signal +image::images/halscope-04.png["Select Signal",align="center"] + +The channel 1 button is pressed in, and channel number 1 and the name +'X-vel' appear below the row of buttons. That display always indicates +the selected channel - you can have many channels on the screen, but +the selected one is highlighted, and the various controls like vertical +position and scale always work on the selected one. + +[[fig:halscope]] +.Halscope +image::images/halscope-05.png["Halscope",align="center"] + +To add a signal to channel 2, click the '2' button. When the dialog +pops up, click the 'Signals' tab, then click on 'Y-vel'. We also want +to look at the square and triangle wave outputs. There are no signals +connected to those pins, so we use the 'Pins' tab instead. For channel +3, select `siggen.0.triangle` and for channel 4, select +`siggen.0.square`. + +=== Capturing our first waveforms + +Now that we have several probes hooked to the HAL, it's time to +capture some waveforms. To start the scope, click the 'Normal' button +in the 'Run Mode' section of the screen (upper right). Since we have a +4000 sample record length, and are acquiring 1000 samples per second, +it will take halscope about 2 seconds to fill half of its buffer. +During that time a progress bar just above the main screen will show +the buffer filling. Once the buffer is half full, the scope waits for a +trigger. Since we haven't configured one yet, it will wait forever. To +manually trigger it, click the 'Force' button in the 'Trigger' section +at the top right. You should see the remainder of the buffer fill, then +the screen will display the captured waveforms. The result will look +something like the following figure. + +[[fig:halscope-captured-owaveform]] +.Captured Waveforms +image::images/halscope-06.png["Captured Waveforms",align="center"] + +The 'Selected Channel' box at the bottom tells you that the purple +trace is the currently selected one, channel 4, which is displaying the +value of the pin `siggen.0.square`. Try clicking channel buttons 1 +through 3 to highlight the other three traces. + +=== Vertical Adjustments + +The traces are rather hard to distinguish since all four are on top of +each other. To fix this, we use the 'Vertical' controls in the box to +the right of the screen. These controls act on the currently selected +channel. When adjusting the gain, notice that it covers a huge range - +unlike a real scope, this one can display signals ranging from very +tiny (pico-units) to very large (Tera-units). The position control +moves the displayed trace up and down over the height of the screen +only. For larger adjustments the offset button should be used. + +[[fig:halscope-vertical-adjustment]] +.Vertical Adjustment +image::images/halscope-07.png["Vertical Adjustment",align="center"] + +The large _Selected Channel_ button at the bottom indicates that channel 1 is +currently selected channel and that it matches the _X-vel_ signal. +Try clicking on the other channels to put their traces in evidence and +to be able to move them with the _Pos_ cursor. + +=== Triggering + +Using the 'Force' button is a rather unsatisfying way to trigger the +scope. To set up real triggering, click on the 'Source' button at the +bottom right. It will pop up the 'Trigger Source' dialog, which is +simply a list of all the probes that are currently connected. Select a +probe to use for triggering by clicking on it. For this example we will +use channel 3, the triangle wave as shown in the following figure. + +[[fig:halscope-trigger-source]] +.Trigger Source Dialog +image::images/halscope-08.png["Trigger Source Dialog",align="center"] + +After setting the trigger source, you can adjust the trigger level and +trigger position using the sliders in the 'Trigger' box along the right +edge. The level can be adjusted from the top to the bottom of the +screen, and is displayed below the sliders. The position is the +location of the trigger point within the overall record. With the +slider all the way down, the trigger point is at the end of the record, +and halscope displays what happened before the trigger point. When the +slider is all the way up, the trigger point is at the beginning of the +record, displaying what happened after it was triggered. The trigger +point is visible as a vertical line in the progress box above the +screen. The trigger polarity can be changed by clicking the button just +below the trigger level display. It will then become _descendant_. +Note that changing the trigger position stops the scope once the position +has been adjusted, you relaunch the scope by clicking on the _Normal_ +button of _Run mode_ the group. + +Now that we have adjusted the vertical controls and triggering, the +scope display looks something like the following figure. + +[[fig:halscope-waveforms-with-triggering]] +.Waveforms with Triggering +image::images/halscope-09.png["Waveforms with Triggering",align="center"] + +=== Horizontal Adjustments + +To look closely at part of a waveform, you can use the zoom slider at +the top of the screen to expand the waveforms horizontally, and the +position slider to determine which part of the zoomed waveform is visible. +However, sometimes simply expanding the waveforms isn't enough and you need to increase the sampling rate. +For example, we would like to look at the actual step pulses that are being generated in our example. +Since the step pulses may be only 50 µs long, sampling at 1 kHz isn't fast enough. +To change the sample rate, click on the button that displays the number +of samples and sample rate to bring up the 'Select Sample Rate' dialog figure. +For this example, we will click on the 50 µs thread, 'fast', which gives us a sample rate of about 20 kHz. +Now instead of displaying about 4 seconds worth of data, one record is 4000 samples at 20 kHz, or about 0.20 seconds. + +[[fig:halscope-sample-rate-choice]] +.Sample Rate Dialog +image::images/halscope-10.png["Sample Rate Dialog",align="center"] + +=== More Channels + +Now let's look at the step pulses. +Halscope has 16 channels, but for this example we are using only 4 at a time. +Before we select any more channels, we need to turn off a couple. +Clicking on a selected channel button (black border) will turn the channel off. +So click on the channel 2 button, then click again on this button and the channel will turn off. +Then click twice on channel 3 and do the same for channel 4. +Even though the channels are turned off, they still remember what they +are connected to, and in fact we will continue to use channel 3 as the trigger source. +To add new channels, select channel 5, and choose pin `stepgen.0.dir`, then channel 6, and select `stepgen.0.step`. +Then click run mode 'Normal' to start the scope, and adjust the horizontal zoom to 5 ms per division. +You should see the step pulses slow down as the velocity command (channel 1) approaches zero, +then the direction pin changes state and the step pulses speed up again. +You might want toincrease the gain on channel 1 to about 20 milli per division to better see +the change in the velocity command. +The result should look like the following figure. + +[[fig:halscope-step-pulses]] +.Step Pulses +image::images/halscope-11.png["Step Pulses",align="center"] + +=== More samples + +If you want to record more samples at once, restart realtime and load +halscope with a numeric argument which indicates the number of samples +you want to capture. + +---- +halcmd loadusr halscope 80000 +---- + +If the 'scope_rt' component was not already loaded, halscope will +load it and request 80000 total samples, so that when sampling +4 channels at a time there will be 20000 samples per channel. +(If 'scope_rt' was already loaded, the numeric argument to +halscope will have no effect). diff --git a/docs/src/hal/halshow.adoc b/docs/src/hal/halshow.adoc index ce9d08d0cf5..6fce76ab21f 100644 --- a/docs/src/hal/halshow.adoc +++ b/docs/src/hal/halshow.adoc @@ -1,8 +1,8 @@ :lang: en :toc: -[[cha:halshow]] -= Halshow +[[sec:halshow]] +== Halshow // Custom lang highlight // must come after the doc title, to work around a bug in asciidoc 8.6.6 @@ -20,7 +20,7 @@ When the configuration of LinuxCNC changes, so will the output of halshow be dif As we will soon see, this ability of HAL to document itself is one key to establish an effective CNC system. -== Starting Halshow +=== Starting Halshow Halshow is available @@ -61,9 +61,9 @@ image::images/halshow-layout.png["Halshow Layout",align="center"] At the left of its display as shown in above figure is a tree view, resembling what you may have seen as file browsers. At the right is a tabbed notebook with tabs for show, watch and settings. -== HAL Tree Area +=== HAL Tree Area -=== Filter Tree +.Filter Tree Per default this entry filters the tree by pin names or tree-nodes by a regular expression. For example, entering "lim-sw" would filter the tree to the following: @@ -81,7 +81,7 @@ joint.3.pos-lim-sw-in If you would like to display all `joint.0`-related, you have to click the settings icon and select "Full path". Pay attention to escape the regex special characters, so you have to enter "joint\.1\." to explicitly request the dot and not also find joint 10. -=== Tree +.Tree The tree shows all of the major parts of a HAL. In front of each is a small plus (+) or minus (-) sign in a box to expand or collapse the corresponding section of the tree. @@ -93,7 +93,7 @@ _Expand All_, _Collapse All_; _Expand Pins_, _Expand Parameters_, _Expand Signal _Reload tree view_ is useful when new components are loaded during runtime and should be displayed. -== HAL Show Area +=== HAL Show Area [[fig:halshow-show-tab]] .Halshow: Show Tab @@ -126,7 +126,7 @@ The Show area allows to add pins from selected text by using the right-click men All valid pins that are enclosed in the selection are added to the Watch tab. **** -== Watch Tab Area +=== Watch Tab Area Clicking the watch tab produces a blank canvas. You can add signals and pins to this canvas and watch their values. @@ -182,7 +182,7 @@ The context menu allows further: image::images/halshow-5.png["Halshow: Watch Tab Context Menu",align="center"] -== Command Entry +=== Command Entry In the lower part is an entry box to test HAL commands. The commands you enter here and the effect that they have on the running HAL are not saved. @@ -206,7 +206,7 @@ An error message from halcmd will be shown when these commands are not properly If you are not certain how to set up a proper command, you'll need to read again the documentation on halcmd and the specific modules that you are working with. [[sec:halshow-settings]] -== Settings +=== Settings .New in 2.9 **** @@ -222,7 +222,7 @@ The further settings should be self-explaining. image::images/halshow-settings.png["Halshow Settings",align="center"] -== Example/Tutorial +=== Example/Tutorial Let's use this editor to add a differential module to a HAL and connect it to axis position so that we could see the rate of change in position, i.e., acceleration. We first need to load a HAL component named ddt, add it to the servo thread, then connect it to the position pin of a joint. diff --git a/docs/src/hal/tools.adoc b/docs/src/hal/tools.adoc index f540f2e5871..bf1b4ff3db2 100644 --- a/docs/src/hal/tools.adoc +++ b/docs/src/hal/tools.adoc @@ -12,6 +12,8 @@ (((HAL Tools))) +For most of the tools, a more detailed description can be found in the chapter <> + [[sec:halcmd]] == Halcmd @@ -40,7 +42,7 @@ usage, and is a good tutorial for `halcmd`. == Halmeter (((Halmeter))) -Halmeter is a 'voltmeter' for the HAL. +`halmeter` is like 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. @@ -66,7 +68,7 @@ And finally, if you specify an item to display, you can add `-s` before the `pin 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 <> section for more information. +In the <> you will find 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. @@ -89,12 +91,14 @@ image::images/hal-meter02.png["Halmeter watch window"] == Halshow -`halshow` (<>) can be started from the command line -to show details for selected components, pins, parameters, signals, functions, and threads of a running HAL. +`halshow` shows the values of chosen pins, parameters or signals of a running HAL. It further provides buttons to also modify those items. The WATCH tab provides a continuous display of selected pin, parameters, and signal items. The File menu provides buttons to save the watch items to a watch list and to load an existing watch list. The watch list items can also be loaded automatically on startup. -For command line usage: + +More detailed information can be found in the section <> in the tutorial chapter. + +It can be started from the command line: ---- halshow --help @@ -111,7 +115,7 @@ Notes: ---- .Halshow Watch Tab -image::images/halshow-4.png["Halshow Watch Tab",align="center"] +image::images/halshow-4.png["Halshow Watch Tab"] 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. diff --git a/docs/src/hal/tutorial.adoc b/docs/src/hal/tutorial.adoc index 8a84abd9b99..cacd61d7c55 100644 --- a/docs/src/hal/tutorial.adoc +++ b/docs/src/hal/tutorial.adoc @@ -420,111 +420,6 @@ To do this type the following command in a terminal window. halrun -U ---- -[[sec:tutorial-halmeter]] -== Halmeter - -(((Halmeter,Tutorial Halmeter))) -You can build very complex HAL systems without ever using a graphical -interface. However there is something satisfying about seeing the -result of your work. The first and simplest GUI tool for the HAL is -halmeter. It is a very simple program that is the HAL equivalent of the -handy multimeter (or analog meter for the old timers). - -It allows to observe the pins, signals or parameters by displaying the current value of these entities. -It is very easy to use application for graphical environments. -In a console type: - ----- -halmeter ----- - -//FIXME Add halmeter screenshot(s) - -Two windows will appear. The selection window is the largest and includes -three tabs: - -* One lists all the pins currently defined in HAL, -* one lists all the signals, -* one lists all the parameters. - -Click on a tab, then click on one of the items to select it. The small -window will show the name and value of the selected item. -The display is updated approximately 10 times per second. To free screen -space, the selection window can be closed with the _Close_ button. -On the little window, hidden under the selection window at program launch, -the _Select_ button, re-opens the selection window and the _Exit_ button -stops the program and closes both windows. - -It is possible to run several halmeters simultaneously, which makes it -possible to visualize several items at the same time. To open a halmeter -and release the console by running it in the background, run the following command: - ----- -halmeter & ----- - -It is possible to launch halmeter and make it immediately display an item. -For this, add _pin|sig|par[am] name_ arguments on the command line. It -will display the signal, pin, or parameter _name_ as soon as it -will start. If the indicated item does not exist, it will start normally. - -//FIXME Add halmeter command example for direct item display - -Finally, if an item is specified for display, it is possible -add _-s_ in front of pin|sig|param to tell halmeter to use -an even smaller window. The item name will be displayed in the -title bar instead of below the value and there will be no button. -This is useful for displaying a lot of halmeters in a small space. - -//FIXME Add halmeter run with '-s' screenshot - -We will use the siggen component again to check out halmeter. If you -just finished the previous example, then you can load siggen using the -saved file. If not, we can load it just like we did before: - ----- -halrun -halcmd: loadrt siggen -halcmd: loadrt threads name1=test-thread period1=1000000 -halcmd: addf siggen.0.update test-thread -halcmd: start -halcmd: setp siggen.0.amplitude 5 ----- - -At this point we have the siggen component loaded and running. -It's time to start halmeter. - -.Starting Halmeter ----- -halcmd: loadusr halmeter ----- - -The first window you will see is the "Select Item to Probe" window. - -.Halmeter Select Window -image::images/halmeter-select.png["Halmeter Select Window",align="center"] - -This dialog has three tabs. The first tab displays all of the HAL pins in the system. -The second one displays all the signals, and the third displays all the parameters. -We would like to look at the pin `siggen.0.cosine` first, so click on it then click the "Close" button. -The probe selection dialog will close, and the meter looks something like the following figure. - -.Halmeter Window -image::images/halmeter-1.png["Halmeter Window",align="center"] - -To change what the meter displays press the "Select" button which -brings back the "Select Item to Probe" window. - -You should see the value changing as siggen generates its cosine wave. -Halmeter refreshes its display about 5 times per second. - -To shut down halmeter, just click the exit button. - -If you want to look at more than one pin, signal, or parameter at a -time, you can just start more halmeters. The halmeter window was -intentionally made very small so you could have a lot of them on the -screen at once. - == Stepgen Example (((stepgen Example))) @@ -835,225 +730,113 @@ generator is cranking out step pulses, varying from 10 kHz forward to see how to bring those internal signals out to run motors in the real world, but first we want to look at them and see what is happening. -[[sec:tutorial-halscope]] -== Halscope - -(((Tutorial Halscope))) -The previous example generates some very interesting signals. But much -of what happens is far too fast to see with halmeter. To take a closer -look at what is going on inside the HAL, we want an oscilloscope. -Fortunately HAL has one, called halscope. - -Halscope has two parts - a realtime part that reads the HAL signals, and a non-realtime part that provides the GUI and display. However, you don't need to worry about this because the non-realtime part will automatically load the realtime part when needed. - -With LinuxCNC running in a terminal you can start halscope with the following command. - -.Starting Halscope ----- -halcmd loadusr halscope ----- - -If LinuxCNC is not running or the autosave.halscope file does not match -the pins available in the current running LinuxCNC the scope GUI window -will open, immediately followed by a 'Realtime function not linked' -dialog that looks like the following figure. To change the sample rate -left click on the samples box. - -[[fig:halscope-rt-function-not-linked]] -.Realtime function not linked dialog -image::images/halscope-01.png["Realtime function not linked dialog",align="center"] - -This dialog is where you set the sampling rate for the oscilloscope. -For now we want to sample once per millisecond, so click on the 1.00 ms -thread 'slow' and leave the multiplier at 1. We will also leave the -record length at 4000 samples, so that we can use up to four channels -at one time. When you select a thread and then click 'OK', the dialog -disappears, and the scope window looks something like the following -figure. - -[[fig:halscope-init-window]] -.Initial scope window -image::images/halscope-02.png["Initial scope window",align="center"] - -=== Hooking up the scope probes - -At this point, Halscope is ready to use. We have already selected a -sample rate and record length, so the next step is to decide what to -look at. This is equivalent to hooking 'virtual scope probes' to the -HAL. Halscope has 16 channels, but the number you can use at any one -time depends on the record length - more channels means shorter -records, since the memory available for the record is fixed at -approximately 16,000 samples. - -The channel buttons run across the bottom of the halscope screen. -Click button '1', and you will see the 'Select Channel Source' dialog -as shown in the following figure. This dialog is very similar to the -one used by Halmeter. We would like to look at the signals we defined -earlier, so we click on the 'Signals' tab, and the dialog displays all -of the signals in the HAL (only two for this example). - -[[fig:halscope-channel-source-selection]] -.Select Channel Source -image::images/halscope-03.png["Select Channel Source",align="center"] - -To choose a signal, just click on it. In this case, we want channel 1 -to display the signal 'X-vel'. Click on the Signals tab then click on -'X-vel' and the dialog closes and the channel is now selected. - -[[fig:halscope-source-signal-selection]] -.Select Signal -image::images/halscope-04.png["Select Signal",align="center"] - -The channel 1 button is pressed in, and channel number 1 and the name -'X-vel' appear below the row of buttons. That display always indicates -the selected channel - you can have many channels on the screen, but -the selected one is highlighted, and the various controls like vertical -position and scale always work on the selected one. - -[[fig:halscope]] -.Halscope -image::images/halscope-05.png["Halscope",align="center"] - -To add a signal to channel 2, click the '2' button. When the dialog -pops up, click the 'Signals' tab, then click on 'Y-vel'. We also want -to look at the square and triangle wave outputs. There are no signals -connected to those pins, so we use the 'Pins' tab instead. For channel -3, select `siggen.0.triangle` and for channel 4, select -`siggen.0.square`. - -=== Capturing our first waveforms - -Now that we have several probes hooked to the HAL, it's time to -capture some waveforms. To start the scope, click the 'Normal' button -in the 'Run Mode' section of the screen (upper right). Since we have a -4000 sample record length, and are acquiring 1000 samples per second, -it will take halscope about 2 seconds to fill half of its buffer. -During that time a progress bar just above the main screen will show -the buffer filling. Once the buffer is half full, the scope waits for a -trigger. Since we haven't configured one yet, it will wait forever. To -manually trigger it, click the 'Force' button in the 'Trigger' section -at the top right. You should see the remainder of the buffer fill, then -the screen will display the captured waveforms. The result will look -something like the following figure. - -[[fig:halscope-captured-owaveform]] -.Captured Waveforms -image::images/halscope-06.png["Captured Waveforms",align="center"] - -The 'Selected Channel' box at the bottom tells you that the purple -trace is the currently selected one, channel 4, which is displaying the -value of the pin `siggen.0.square`. Try clicking channel buttons 1 -through 3 to highlight the other three traces. - -=== Vertical Adjustments - -The traces are rather hard to distinguish since all four are on top of -each other. To fix this, we use the 'Vertical' controls in the box to -the right of the screen. These controls act on the currently selected -channel. When adjusting the gain, notice that it covers a huge range - -unlike a real scope, this one can display signals ranging from very -tiny (pico-units) to very large (Tera-units). The position control -moves the displayed trace up and down over the height of the screen -only. For larger adjustments the offset button should be used. - -[[fig:halscope-vertical-adjustment]] -.Vertical Adjustment -image::images/halscope-07.png["Vertical Adjustment",align="center"] - -The large _Selected Channel_ button at the bottom indicates that channel 1 is -currently selected channel and that it matches the _X-vel_ signal. -Try clicking on the other channels to put their traces in evidence and -to be able to move them with the _Pos_ cursor. - -=== Triggering - -Using the 'Force' button is a rather unsatisfying way to trigger the -scope. To set up real triggering, click on the 'Source' button at the -bottom right. It will pop up the 'Trigger Source' dialog, which is -simply a list of all the probes that are currently connected. Select a -probe to use for triggering by clicking on it. For this example we will -use channel 3, the triangle wave as shown in the following figure. - -[[fig:halscope-trigger-source]] -.Trigger Source Dialog -image::images/halscope-08.png["Trigger Source Dialog",align="center"] - -After setting the trigger source, you can adjust the trigger level and -trigger position using the sliders in the 'Trigger' box along the right -edge. The level can be adjusted from the top to the bottom of the -screen, and is displayed below the sliders. The position is the -location of the trigger point within the overall record. With the -slider all the way down, the trigger point is at the end of the record, -and halscope displays what happened before the trigger point. When the -slider is all the way up, the trigger point is at the beginning of the -record, displaying what happened after it was triggered. The trigger -point is visible as a vertical line in the progress box above the -screen. The trigger polarity can be changed by clicking the button just -below the trigger level display. It will then become _descendant_. -Note that changing the trigger position stops the scope once the position -has been adjusted, you relaunch the scope by clicking on the _Normal_ -button of _Run mode_ the group. - -Now that we have adjusted the vertical controls and triggering, the -scope display looks something like the following figure. - -[[fig:halscope-waveforms-with-triggering]] -.Waveforms with Triggering -image::images/halscope-09.png["Waveforms with Triggering",align="center"] - -=== Horizontal Adjustments - -To look closely at part of a waveform, you can use the zoom slider at -the top of the screen to expand the waveforms horizontally, and the -position slider to determine which part of the zoomed waveform is visible. -However, sometimes simply expanding the waveforms isn't enough and you need to increase the sampling rate. -For example, we would like to look at the actual step pulses that are being generated in our example. -Since the step pulses may be only 50 µs long, sampling at 1 kHz isn't fast enough. -To change the sample rate, click on the button that displays the number -of samples and sample rate to bring up the 'Select Sample Rate' dialog figure. -For this example, we will click on the 50 µs thread, 'fast', which gives us a sample rate of about 20 kHz. -Now instead of displaying about 4 seconds worth of data, one record is 4000 samples at 20 kHz, or about 0.20 seconds. - -[[fig:halscope-sample-rate-choice]] -.Sample Rate Dialog -image::images/halscope-10.png["Sample Rate Dialog",align="center"] - -=== More Channels - -Now let's look at the step pulses. -Halscope has 16 channels, but for this example we are using only 4 at a time. -Before we select any more channels, we need to turn off a couple. -Clicking on a selected channel button (black border) will turn the channel off. -So click on the channel 2 button, then click again on this button and the channel will turn off. -Then click twice on channel 3 and do the same for channel 4. -Even though the channels are turned off, they still remember what they -are connected to, and in fact we will continue to use channel 3 as the trigger source. -To add new channels, select channel 5, and choose pin `stepgen.0.dir`, then channel 6, and select `stepgen.0.step`. -Then click run mode 'Normal' to start the scope, and adjust the horizontal zoom to 5 ms per division. -You should see the step pulses slow down as the velocity command (channel 1) approaches zero, -then the direction pin changes state and the step pulses speed up again. -You might want toincrease the gain on channel 1 to about 20 milli per division to better see -the change in the velocity command. -The result should look like the following figure. - -[[fig:halscope-step-pulses]] -.Step Pulses -image::images/halscope-11.png["Step Pulses",align="center"] - -=== More samples - -If you want to record more samples at once, restart realtime and load -halscope with a numeric argument which indicates the number of samples -you want to capture. - ----- -halcmd loadusr halscope 80000 ----- - -If the 'scope_rt' component was not already loaded, halscope will -load it and request 80000 total samples, so that when sampling -4 channels at a time there will be 20000 samples per channel. -(If 'scope_rt' was already loaded, the numeric argument to -halscope will have no effect). +[[sec:tutorial-halmeter]] +== Halmeter + +(((Halmeter,Tutorial Halmeter))) +You can build very complex HAL systems without ever using a graphical +interface. However there is something satisfying about seeing the +result of your work. The first and simplest GUI tool for the HAL is +halmeter. It is a very simple program that is the HAL equivalent of the +handy multimeter (or analog meter for the old timers). + +It allows to observe the pins, signals or parameters by displaying the current value of these entities. +It is very easy to use application for graphical environments. +In a console type: + +---- +halmeter +---- + +//FIXME Add halmeter screenshot(s) + +Two windows will appear. The selection window is the largest and includes +three tabs: + +* One lists all the pins currently defined in HAL, +* one lists all the signals, +* one lists all the parameters. + +Click on a tab, then click on one of the items to select it. The small +window will show the name and value of the selected item. +The display is updated approximately 10 times per second. To free screen +space, the selection window can be closed with the _Close_ button. +On the little window, hidden under the selection window at program launch, +the _Select_ button, re-opens the selection window and the _Exit_ button +stops the program and closes both windows. + +It is possible to run several halmeters simultaneously, which makes it +possible to visualize several items at the same time. To open a halmeter +and release the console by running it in the background, run the following command: + +---- +halmeter & +---- + +It is possible to launch halmeter and make it immediately display an item. +For this, add _pin|sig|par[am] name_ arguments on the command line. It +will display the signal, pin, or parameter _name_ as soon as it +will start. If the indicated item does not exist, it will start normally. + +//FIXME Add halmeter command example for direct item display + +Finally, if an item is specified for display, it is possible +add _-s_ in front of pin|sig|param to tell halmeter to use +an even smaller window. The item name will be displayed in the +title bar instead of below the value and there will be no button. +This is useful for displaying a lot of halmeters in a small space. + +//FIXME Add halmeter run with '-s' screenshot + +We will use the siggen component again to check out halmeter. If you +just finished the previous example, then you can load siggen using the +saved file. If not, we can load it just like we did before: + +---- +halrun +halcmd: loadrt siggen +halcmd: loadrt threads name1=test-thread period1=1000000 +halcmd: addf siggen.0.update test-thread +halcmd: start +halcmd: setp siggen.0.amplitude 5 +---- + +At this point we have the siggen component loaded and running. +It's time to start halmeter. + +.Starting Halmeter +---- +halcmd: loadusr halmeter +---- + +The first window you will see is the "Select Item to Probe" window. + +.Halmeter Select Window +image::images/halmeter-select.png["Halmeter Select Window",align="center"] + +This dialog has three tabs. The first tab displays all of the HAL pins in the system. +The second one displays all the signals, and the third displays all the parameters. +We would like to look at the pin `siggen.0.cosine` first, so click on it then click the "Close" button. +The probe selection dialog will close, and the meter looks something like the following figure. + +.Halmeter Window +image::images/halmeter-1.png["Halmeter Window",align="center"] + +To change what the meter displays press the "Select" button which +brings back the "Select Item to Probe" window. + +You should see the value changing as siggen generates its cosine wave. +Halmeter refreshes its display about 5 times per second. + +To shut down halmeter, just click the exit button. + +If you want to look at more than one pin, signal, or parameter at a +time, you can just start more halmeters. The halmeter window was +intentionally made very small so you could have a lot of them on the +screen at once. + +include::halshow.adoc[] +include::halscope.adoc[] // vim: set syntax=asciidoc: + diff --git a/docs/src/index.tmpl b/docs/src/index.tmpl index 9833803b5fd..4d2df8f1ab5 100644 --- a/docs/src/index.tmpl +++ b/docs/src/index.tmpl @@ -185,6 +185,7 @@ function setup_page(){
  • HAL Introduction
  • HAL Basics
  • HAL Twopass
    • +
  • HAL Tools
  • HAL Tutorial
  • HAL Examples
  • HAL Core Components
    • @@ -196,7 +197,6 @@ function setup_page(){
  • HALUI Examples
  • Creating Non-Realtime Python Components
  • Canonical Device Interfaces
    • -
  • HAL Tools
    • diff --git a/docs/src/plasma/qtplasmac.adoc b/docs/src/plasma/qtplasmac.adoc index 97a6fd313e7..4d609012900 100644 --- a/docs/src/plasma/qtplasmac.adoc +++ b/docs/src/plasma/qtplasmac.adoc @@ -1217,7 +1217,7 @@ To return the *EXIT WARNING MESSAGE* text to the last saved value press the *REL Some standard LinuxCNC utilities are provided as an aid in the diagnosis of issues that may arise: -- link:../hal/halshow.html#cha:halshow[Halshow] +- link:../hal/tutorial.html#sec:halshow[Halshow] - link:../hal/tutorial.html#sec:tutorial-halscope[Halscope] - link:../hal/tutorial.html#sec:tutorial-halmeter[Halmeter] - link:../man/man1/emccalib.1.html[Calibration]