HAL Tutorial

For this tutorial, commands for the operating system are typically shown without the prompt provided by the UNIX shell, i.e typically a dollar sign ($) or a hash/double cross (#). When communicating directly with the HAL through halcmd or halrun, the prompts are shown in the examples. The terminal window is in Applications/Accessories from the main Ubuntu menu bar.

Your version of halcmd may include tab-completion. Instead of completing file names as a shell does, it completes commands with HAL identifiers. You will have to type enough letters for a unique match. Try pressing tab after starting a HAL command:

RTAPI stands for Real Time Application Programming Interface. Many HAL components work in realtime, and all HAL components store data in shared memory so realtime components can access it. Regular Linux does not support realtime programming or the type of shared memory that HAL needs. Fortunately, there are realtime operating systems (RTOS’s) that provide the necessary extensions to Linux. Unfortunately, each RTOS does things a little differently.

Um diese Unterschiede zu beseitigen, hat das LinuxCNC-Team die RTAPI entwickelt, die einen einheitlichen Weg für Programme bietet, um mit dem RTOS zu kommunizieren. Wenn Sie ein Programmierer sind, der an den Interna von LinuxCNC arbeiten will, sollten Sie vielleicht linuxcnc/src/rtapi/rtapi.h studieren, um die API zu verstehen. Aber wenn Sie eine normale Person sind, ist alles, was Sie über RTAPI wissen müssen, dass es (und das RTOS) in den Speicher Ihres Computers geladen werden muss, bevor Sie etwas mit HAL machen.

Für dieses Tutorial gehen wir davon aus, dass Sie die Live-CD erfolgreich installiert haben und, falls Sie eine RIP footnote: [Run In Place, wenn die Quelldateien in ein Benutzerverzeichnis heruntergeladen wurden und direkt von dort aus kompiliert und ausgeführt werden] Installation verwenden, das Skript "rip-environment" aufrufen, um Ihre Shell vorzubereiten. In diesem Fall müssen Sie nur noch die erforderlichen RTOS- und RTAPI-Module in den Speicher laden. Führen Sie einfach den folgenden Befehl in einem Terminalfenster aus:

Nachdem das Echtzeitbetriebssystem und die RTAPI geladen sind, können wir mit dem ersten Beispiel beginnen. Beachten Sie, dass die Eingabeaufforderung jetzt als "halcmd:" angezeigt wird. Das liegt daran, dass die nachfolgenden Befehle als HAL-Befehle und nicht als Shell-Befehle interpretiert werden.

For the first example, we will use a HAL component called siggen, which is a simple signal generator. A complete description of the siggen component can be found in the SigGen section of this Manual. It is a realtime component. To load the "siggen" component, use the HAL command loadrt.

Now that the module is loaded, it is time to introduce halcmd, the command line tool used to configure the HAL. This tutorial will introduce only a selection of halcmd features. For a more complete description try man halcmd, or see the reference in HAL Commands section of this document. The first halcmd feature is the show command. This command displays information about the current state of the HAL. To show all installed components:

Since halcmd itself is also a HAL component, it will always show up in the list. The number after "halcmd" in the component list is the UNIX process ID. It is possible to run more than one copy of halcmd at the same time (in different terminal windows for example), so the PID is added to the end of the name to make it unique. The list also shows the siggen component that we installed in the previous step. The RT under Type indicates that siggen is a realtime component. The User under Type indicates it is a non-realtime component.

Next, let’s see what pins siggen makes available:

This command displays all of the pins in the current HAL. A complex system could have dozens or hundreds of pins. But right now there are only nine pins. Of these pins eight are floating point and one is bit (boolean). Six carry data out of the siggen component and three are used to transfer settings into the component. Since we have not yet executed the code contained within the component, some the pins have a value of zero.

Der nächste Schritt ist die Betrachtung der Parameter:

The show param command shows all the parameters in the HAL. Right now, each parameter has the default value it was given when the component was loaded. Note the column labeled Dir. The parameters labeled -W are writable ones that are never changed by the component itself, instead they are meant to be changed by the user to control the component. We will see how to do this later. Parameters labeled R- are read only parameters. They can be changed only by the component. Finally, parameter labeled RW are read-write parameters. That means that they are changed by the component, but can also be changed by the user. Note: The parameters siggen.0.update.time and siggen.0.update.tmax are for debugging purposes and won’t be covered in this section.

Most realtime components export one or more functions to actually run the realtime code they contain. Let’s see what function(s) siggen exported:

The siggen component exported a single function. It requires floating point. It is not currently linked to any threads, so users is zero
[CodeAddr and Arg fields were used during development and should probably disappear.]
.

To actually run the code contained in the function siggen.0.update, we need a realtime thread. The component called threads that is used to create a new thread. Lets create a thread called "test-thread" with a period of 1 ms (1,000 µs or 1,000,000 ns):

Mal sehen, ob das funktioniert:

It did. The period is not exactly 1,000,000 ns because of hardware limitations, but we have a thread that runs at approximately the correct rate, and which can handle floating point functions. The next step is to connect the function to the thread:

Up till now, we’ve been using halcmd only to look at the HAL. However, this time we used the addf (add function) command to actually change something in the HAL. We told halcmd to add the function siggen.0.update to the thread test-thread, and if we look at the thread list again, we see that it succeeded:

There is one more step needed before the siggen component starts generating signals. When the HAL is first started, the thread(s) are not actually running. This is to allow you to completely configure the system before the realtime code starts. Once you are happy with the configuration, you can start the realtime code like this:

Jetzt läuft der Signalgenerator. Schauen wir uns seine Ausgangspins an:

Und schauen wir noch einmal hin:

We did two show pin commands in quick succession, and you can see that the outputs are no longer zero. The sine, cosine, sawtooth, and triangle outputs are changing constantly. The square output is also working, however it simply switches from +1.0 to -1.0 every cycle.

The real power of HAL is that you can change things. For example, we can use the setp command to set the value of a parameter. Let’s change the amplitude of the signal generator from 1.0 to 5.0:

Note that the value of parameter siggen.0.amplitude has changed to 5, and that the pins now have larger values.

Das meiste, was wir bisher mit halcmd gemacht haben, war einfach das Anzeigen von Dingen mit dem show-Befehl. Zwei der Befehle haben jedoch tatsächlich Dinge verändert. Wenn wir komplexere Systeme mit HAL entwerfen, werden wir viele Befehle verwenden, um die Dinge genau so zu konfigurieren, wie wir sie haben wollen. HAL hat ein Gedächtnis wie ein Elefant und behält diese Konfiguration bei, bis wir es abschalten. Aber was ist beim nächsten Mal? Wir wollen nicht jedes Mal, wenn wir das System benutzen wollen, eine Reihe von Befehlen manuell eingeben.

The output of the save command is a sequence of HAL commands. If you start with an empty HAL and run all these commands, you will get the configuration that existed when the save command was issued. To save these commands for later use, we simply redirect the output to a file:

When you’re finished with your HAL session type exit at the "halcmd:" prompt. This will return you to the system prompt and close down the HAL session. Do not simply close the terminal window without shutting down the HAL session.

To restore the HAL configuration stored in the file "saved.hal", we need to execute all of those HAL commands. To do that, we use "-f _<file name>_" which reads commands from a file, and "-I" (upper case i) which shows the halcmd prompt after executing the commands:

Notice that there is not a "start" command in saved.hal. It’s necessary to issue it again (or edit the file saved.hal to add it there).

Wenn eine HAL-Sitzung unerwartet beendet wird, müssen Sie möglicherweise HAL entladen, bevor eine neue Sitzung beginnen kann. Geben Sie dazu den folgenden Befehl in ein Terminalfenster ein.

Now we are going to load the step pulse generator component. For a detailed description of this component refer to the stepgen section of the Integrator Manual. In this example we will use the velocity control type of StepGen. For now, we can skip the details, and just run the following commands.

In diesem Beispiel wird der Kontrolltyp velocity aus der Komponente stepgen verwendet.

The first command loads two step generators, both configured to generate stepping type 0. The second command loads our old friend siggen, and the third one creates two threads, a fast one with a period of 50 microseconds (µs) and a slow one with a period of 1 millisecond (ms). The fast thread doesn’t support floating point functions.

As before, we can use halcmd show to take a look at the HAL. This time we have a lot more pins and parameters than before:

Wir haben also zwei Schrittimpulsgeneratoren und einen Signalgenerator. Nun ist es an der Zeit, einige HAL-Signale zu erzeugen, um die beiden Komponenten zu verbinden. Wir tun so, als ob die beiden Schrittimpulsgeneratoren die X- und Y-Achse einer Maschine antreiben würden. Wir wollen den Tisch im Kreis bewegen. Dazu senden wir ein Kosinussignal an die X-Achse und ein Sinussignal an die Y-Achse. Das siggen-Modul erzeugt den Sinus und den Cosinus, aber wir brauchen "Drähte", um die Module miteinander zu verbinden. Im HAL werden diese "Drähte" Signale genannt. Wir müssen zwei davon erstellen. Wir können sie nennen, wie wir wollen, in diesem Beispiel werden sie X-vel und Y-vel heißen. Das Signal "X-vel" soll vom Cosinus-Ausgang des Signalgenerators zum Geschwindigkeitseingang des ersten Schrittimpulsgenerators führen. Der erste Schritt besteht darin, das Signal mit dem Ausgang des Signalgenerators zu verbinden. Um ein Signal mit einem Pin zu verbinden, verwenden wir den Netzbefehl.

To see the effect of the net command, we show the signals again.

When a signal is connected to one or more pins, the show command lists the pins immediately following the signal name. The arrow shows the direction of data flow - in this case, data flows from pin siggen.0.cosine to signal X-vel. Now let’s connect the X-vel to the velocity input of a step pulse generator.

We can also connect up the Y axis signal Y-vel. It is intended to run from the sine output of the signal generator to the input of the second step pulse generator. The following command accomplishes in one line what two net commands accomplished for X-vel.

Werfen wir nun einen letzten Blick auf die Signale und die mit ihnen verbundenen Pins.

The show sig command makes it clear exactly how data flows through the HAL. For example, the X-vel signal comes from pin siggen.0.cosine, and goes to pin stepgen.0.velocity-cmd.

Thinking about data flowing through "wires" makes pins and signals fairly easy to understand. Threads and functions are a little more difficult. Functions contain the computer instructions that actually get things done. Thread are the method used to make those instructions run when they are needed. First let’s look at the functions available to us.

In general, you will have to refer to the documentation for each component to see what its functions do. In this case, the function siggen.0.update is used to update the outputs of the signal generator. Every time it is executed, it calculates the values of the sine, cosine, triangle, and square outputs. To make smooth signals, it needs to run at specific intervals.

Die anderen drei Funktionen beziehen sich auf die Schrittimpulsgeneratoren.

The first one, stepgen.capture_position, is used for position feedback. It captures the value of an internal counter that counts the step pulses as they are generated. Assuming no missed steps, this counter indicates the position of the motor.

The main function for the step pulse generator is stepgen.make_pulses. Every time make_pulses runs it decides if it is time to take a step, and if so sets the outputs accordingly. For smooth step pulses, it should run as frequently as possible. Because it needs to run so fast, make_pulses is highly optimized and performs only a few calculations. Unlike the others, it does not need floating point math.

The last function, stepgen.update-freq, is responsible for doing scaling and some other calculations that need to be performed only when the frequency command changes.

Für unser Beispiel bedeutet dies, dass wir siggen.0.update mit einer moderaten Rate ausführen wollen, um die Sinus- und Kosinuswerte zu berechnen. Unmittelbar nachdem wir siggen.0.update ausgeführt haben, wollen wir stepgen.update_freq ausführen, um die neuen Werte in den Schrittimpulsgenerator zu laden. Schließlich müssen wir stepgen.make_pulses so schnell wie möglich ausführen, um gleichmäßige Impulse zu erhalten. Da wir keine Positionsrückmeldung verwenden, brauchen wir stepgen.capture_position überhaupt nicht auszuführen.

We run functions by adding them to threads. Each thread runs at a specific rate. Let’s see what threads we have available.

The two threads were created when we loaded threads. The first one, slow, runs every millisecond, and is capable of running floating point functions. We will use it for siggen.0.update and stepgen.update_freq. The second thread is fast, which runs every 50 microseconds (µs), and does not support floating point. We will use it for stepgen.make_pulses. To connect the functions to the proper thread, we use the addf command. We specify the function first, followed by the thread.

After we give these commands, we can run the show thread command again to see what happened.

Nun folgen auf jeden Thread die Namen der Funktionen in der Reihenfolge, in der sie ausgeführt werden sollen.

We are almost ready to start our HAL system. However we still need to adjust a few parameters. By default, the siggen component generates signals that swing from +1 to -1. For our example that is fine, we want the table speed to vary from +1 to -1 inches per second. However the scaling of the step pulse generator isn’t quite right. By default, it generates an output frequency of 1 step per second with an input of 1.0. It is unlikely that one step per second will give us one inch per second of table movement. Let’s assume instead that we have a 5 turn per inch leadscrew, connected to a 200 step per rev stepper with 10x microstepping. So it takes 2000 steps for one revolution of the screw, and 5 revolutions to travel one inch. That means the overall scaling is 10000 steps per inch. We need to multiply the velocity input to the step pulse generator by 10000 to get the proper output. That is exactly what the parameter stepgen.n.velocity-scale is for. In this case, both the X and Y axis have the same scaling, so we set the scaling parameters for both to 10000.

This velocity scaling means that when the pin stepgen.0.velocity-cmd is 1.0, the step generator will generate 10000 pulses per second (10 kHz). With the motor and leadscrew described above, that will result in the axis moving at exactly 1.0 inches per second. This illustrates a key HAL concept - things like scaling are done at the lowest possible level, in this case in the step pulse generator. The internal signal X-vel is the velocity of the table in inches per second, and other components such as siggen don’t know (or care) about the scaling at all. If we changed the leadscrew, or motor, we would change only the scaling parameter of the step pulse generator.

We now have everything configured and are ready to start it up. Just like in the first example, we use the start command.

Although nothing appears to happen, inside the computer the step pulse generator is cranking out step pulses, varying from 10 kHz forward to 10 kHz reverse and back again every second. Later in this tutorial we’ll 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.

An diesem Punkt ist Halscope einsatzbereit. Wir haben bereits eine Abtastrate und eine Aufzeichnungslänge gewählt, so dass der nächste Schritt darin besteht, zu entscheiden, was wir uns ansehen wollen. Dies ist gleichbedeutend mit dem Anschließen von "virtuellen Oszilloskop-Sonden" an den HAL. Halscope verfügt über 16 Kanäle, aber die Anzahl, die Sie gleichzeitig verwenden können, hängt von der Aufzeichnungslänge ab - mehr Kanäle bedeuten kürzere Aufzeichnungen, da der für die Aufzeichnung verfügbare Speicher auf etwa 16.000 Samples festgelegt ist.

Die Kanalschaltflächen befinden sich am unteren Rand des Halskop-Bildschirms. Wenn Sie auf die Schaltfläche "1" klicken, wird das Dialogfeld "Select Channel Source" (Kanalquelle auswählen) angezeigt, wie in der folgenden Abbildung dargestellt. Dieser Dialog ist dem von Halmeter verwendeten Dialog sehr ähnlich. Wir möchten uns die Signale ansehen, die wir zuvor definiert haben, also klicken wir auf die Registerkarte "Signale", und der Dialog zeigt alle Signale im HAL an (in diesem Beispiel nur zwei).

Um ein Signal auszuwählen, klicken Sie es einfach an. In diesem Fall möchten wir, dass auf Kanal 1 das Signal "X-vel" angezeigt wird. Klicken Sie auf die Registerkarte "Signale" und dann auf "X-vel". Das Dialogfeld schließt sich und der Kanal ist nun ausgewählt.

Die Taste für Kanal 1 wird gedrückt, und die Kanalnummer 1 und die Bezeichnung "X-vel" erscheinen unter der Tastenreihe. Diese Anzeige zeigt immer den ausgewählten Kanal an - Sie können mehrere Kanäle auf dem Bildschirm haben, aber der ausgewählte Kanal ist hervorgehoben, und die verschiedenen Steuerelemente wie vertikale Position und Skalierung funktionieren immer für den ausgewählten Kanal.

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.

Nachdem wir nun mehrere Sonden an den HAL angeschlossen haben, ist es an der Zeit, einige Wellenformen zu erfassen. Zum Starten des Oszilloskops klicken Sie auf die Schaltfläche "Normal" im Abschnitt "Run Mode" des Bildschirms (oben rechts). Da wir eine Aufzeichnungslänge von 4000 Samples haben und 1000 Samples pro Sekunde erfassen, wird halscope etwa 2 Sekunden brauchen, um die Hälfte seines Puffers zu füllen. Während dieser Zeit zeigt ein Fortschrittsbalken direkt über dem Hauptbildschirm an, dass der Puffer gefüllt ist. Sobald der Puffer halb voll ist, wartet das Scope auf einen Trigger. Da wir noch keinen konfiguriert haben, wird es ewig warten. Um es manuell auszulösen, klicken Sie auf die Schaltfläche "Erzwingen" im Abschnitt "Auslöser" oben rechts. Sie sollten sehen, wie sich der Rest des Puffers füllt, und dann werden die erfassten Wellenformen auf dem Bildschirm angezeigt. Das Ergebnis sieht ungefähr so aus wie in der folgenden Abbildung.

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.

Die Spuren sind nur schwer zu unterscheiden, da alle vier übereinander liegen. Um dies zu beheben, verwenden wir die "Vertikal"-Steuerungen in der Box auf der rechten Seite des Bildschirms. Diese Regler wirken sich auf den aktuell ausgewählten Kanal aus. Bei der Einstellung der Verstärkung ist zu beachten, dass sie einen riesigen Bereich abdeckt - im Gegensatz zu einem echten Oszilloskop kann dieses Gerät Signale von sehr kleinen (Pico-Einheiten) bis zu sehr großen (Tera-Einheiten) anzeigen. Mit dem Positionsregler wird die angezeigte Kurve nur über die Höhe des Bildschirms nach oben und unten bewegt. Für größere Einstellungen sollte die Offset-Taste verwendet werden.

Die große Schaltfläche Ausgewählter Kanal am unteren Rand zeigt an, dass Kanal 1 der aktuell ausgewählte Kanal ist und dass er mit dem X-vel-Signal übereinstimmt. Versuchen Sie, auf die anderen Kanäle zu klicken, um ihre Spuren sichtbar zu machen und sie mit dem Pos-Cursor verschieben zu können.

Die Verwendung des Button "Erzwingen" ist eine eher unbefriedigende Art, das Oszilloskop auszulösen. Um eine echte Triggerung einzurichten, klicken Sie auf die Schaltfläche "Quelle" unten rechts. Daraufhin wird das Dialogfeld "Trigger Source" (Triggerquelle) angezeigt, das einfach eine Liste aller derzeit angeschlossenen Sonden enthält. Wählen Sie eine Sonde für die Triggerung aus, indem Sie auf sie klicken. In diesem Beispiel verwenden wir Kanal 3, die Dreieckswelle, wie in der folgenden Abbildung dargestellt.

Nachdem Sie die Triggerquelle eingestellt haben, können Sie den Triggerpegel und die Triggerposition mit den Schiebereglern im Feld "Trigger" am rechten Rand einstellen. Der Pegel kann vom oberen bis zum unteren Rand des Bildschirms eingestellt werden und wird unter den Schiebereglern angezeigt. Die Position ist die Lage des Auslösepunkts innerhalb der gesamten Aufzeichnung. Ist der Schieberegler ganz unten, befindet sich der Auslösepunkt am Ende der Aufzeichnung, und halscope zeigt an, was vor dem Auslösepunkt passiert ist. Wenn der Schieberegler ganz nach oben geschoben ist, befindet sich der Auslösepunkt am Anfang des Datensatzes und es wird angezeigt, was nach dem Auslösen passiert ist. Der Triggerpunkt ist als vertikale Linie in der Fortschrittsanzeige über dem Bildschirm sichtbar. Die Triggerpolarität kann durch Klicken auf die Schaltfläche direkt unter der Triggerpegelanzeige geändert werden. Sie wird dann absteigend. Beachten Sie, dass die Änderung der Triggerposition das Oszilloskop anhält, sobald die Position angepasst wurde, starten Sie das Oszilloskop erneut, indem Sie auf die Schaltfläche Normal des Run-Modus der Gruppe klicken.

Nachdem wir nun die vertikalen Regler und die Triggerung eingestellt haben, sieht die Anzeige des Oszilloskops etwa wie in der folgenden Abbildung aus.

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.

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.

Wenn Sie mehr Samples auf einmal aufnehmen wollen, starten Sie realtime neu und laden Sie halscope mit einem numerischen Argument, das die Anzahl der Samples angibt, die Sie aufnehmen wollen.

Wenn die Komponente scope_rt noch nicht geladen war, lädt halscope sie und fordert 80000 Gesamtsamples an, so dass bei der Abtastung von 4 Kanälen gleichzeitig 20000 Samples pro Kanal zur Verfügung stehen. (Wenn scope_rt bereits geladen war, hat das numerische Argument für halscope keine Auswirkungen).