Tutorial für Anfänger

Ziel dieses Tutorials

Erstellen einer einfachen Statemachine und Generieren des entsprechenden C Source Codes.

Vorbereitungen

Zur Durchführung dieses Tutorials benötigen Sie folgende Tools:

• Das Modellierungs- und Codegenerierungs-Tool Meta Genius,
• den Embedded Statemachine Codegenerator EmStaMaG
• und den Diagramm Editor yEd.

Eine detaillierte Installationsanleitung für diese Tools finden Sie hier.

Schritt #1: Ein EmStaMaG Modell erstellen

Starten Sie Meta Genius. Wenn Sie vorab die Installationsanleitung vollständig durchgeführt hatten, sollte in Meta Genius bereits das EmStaMaG Metamodell zur Verfügung stehen.

Wenn nicht, dann starten Sie bitte EmStaMaG und führen dort die „Meta Genius Preparation“ aus.

Sobald in Meta Genius das EmStaMaG Metamodell zur Verfügung steht, können Sie über das Kontext-Menü mit dem Punkt New Model ein neues Modell erstellen.

• Erstellen Sie ein neues Model.

Schritt #2: Modell im Model Editor editieren

Das neu erstellte EmStaMaG Modell erscheint im Model Editor und kann dort weiter bearbeitet werden.

Schritt #3: Modell zur Generierung mit EmStaMaG vorbereiten

Um später die Codegenerierung direkt aus Meta Genius heraus starten zu können, muss noch der Installationspfad zur EmStaMaG spezifiziert werden.

Am einfachsten erfolgt dies über neuerliches Ausführen der „Meta Genius Preparation“ aus EmStaMaG.

Danach sollte es im Modell ein <Project> geben und dort der Wert GeneratorExe gesetzt sein.

• Führen Sie „Meta Genius Preparation“ aus.

Schritt #4: Generierungsverzeichnisse festlegen

In diesem Tutorial werden am Ende einige Dateien generiert:

• Eine *.graphml Diagramm-Datei.
• Eine C Unit, bestehend aus einer *.h und einer *.c Datei.

Für diese Dateien, müssen die Zielverzeichnisse der Codegenerierung festgelegt werden. Dies erfolgt in den GenerationOptions.

Neue Modell-Elemente können in Meta Genius durch die Verwendung des „+“-Buttons hinzugefügt werden.

• Fügen Sie dem Model neue GenerationOptions hinzu.

Die GenerationOptions enthalten folgende Verzeichnisse:

Hier ist zu beachten, dass die Verzeichnisse für die Header-Files (IncCodeFolder) und die Implementierungs-Files (SrcCodeFolder) vor jeder Codegenerierung vollständig gelöscht werden. Sie sollten diese also mit Bedacht wählen, um unerwünschten Datenverlust zu vermeiden!

Die Diagramm-Datei wird in einem eigenen Verzeichnis (DiagramFolder) generiert. Bei der ersten Generierung wird die Datei dort neu erstellt. Es ist aber vorgesehen, dass diese Diagramm-Datei danach manuell modifiziert und wieder gespeichert werden kann. Nachfolgende Generierung-Prozesse werden diese Datei dann nur mehr inhaltlich aktualisieren, um die manuellen Layout-Änderungen zu erhalten.

Das Verzeichnis MgrArchivationFolder wird erst wirklich interessant, wenn für die Entwicklung auch ein Versionsverwaltungssystem wie z. B. GIT eingesetzt wird. In diesem Verzeichnis wird bei jeder Generierung eine Kopie des aktuellen Meta Genius Modells gespeichert, um eine exakte Übereinstimmung zwischen Modell und generiertem Sourecode gewährleisten zu können.

• Legen Sie die Generierungsverzeichnisse fest.

Schritt #5: Neue Unit hinzufügen

Als Unit wird hier eine zusammenhängende Einheit aus einer *.h und einer *.c Datei bezeichnet. Diese kann dann bei der Codegenerierung Konstrukte wie z. B. Funktionen, Typen und Variablen beinhalten.

Um in größeren Projekten das Problem von Namenskonflikten zu vermeiden, wird hier eine Unit zur Bildung eines Pseudo-Namespaces verwendet, indem der Unitname allen Identifiern als Präfix vorangestellt wird.

• Fügen Sie dem Model eine neue Unit DemoSm hinzu.

Schritt #6: Neue Statemachine hinzufügen

Eine Statemachine dient zur formalen Beschreibung des Verhaltens einer Unit. Statemachines können daher nur als Bestandteil einer Unit existieren.

• Fügen Sie der Unit eine neue Statemachine hinzu.

Schritt #7: Error Icon untersuchen

In Meta Genius wird im Metamodell genau festgelegt, welche Inhalte in einem Modell enthalten sein können bzw. müssen (mehr dazu hier). Während der Modellierung wird kontinuierlich geprüft ob das Modell alle Anforderungen des Metamodells erfüllt. Wenn nicht, werden die gefundenen Probleme in Form von Error-Icons dargestellt. Damit kann man sofort erkennen, welche erforderlichen Elemente fehlen oder welche Elemente falsch spezifiziert sind.

Wenn man die Maus zu einem Error-Icon führt, wird dann das entsprechende Problem als textueller Tooltip angezeigt.

• Bewegen Sie den Maus Cursor über das rote Icon bei <Statemachine>.

In unserem Modell fehlt aktuell z. B. ein FatalErrorHandler.

Schritt #8: Neue FatalErrorHandler Action hinzufügen

Actions werden bei der Codegenerierung als parameterlose Funktionen generiert. Diese werden üblicherweise verwendet, um spezielles Verhalten bei Zustandsübergängen zu modellieren (mehr dazu hier).

Es gibt aber auch eine spezielle Action, die für die Implementierung jeder Statemachine zwingend erforderlich ist. Der FatalErrorHandler. Dieser wird von der Implementierungslogik in allen schwerwiegenden Fehlerfällen aufgerufen.

Actions werden prinzipiell ohne konkrete Implementierung generiert. Hier ist vorgesehen, diese später manuell hinzuzufügen.

• Fügen Sie der Unit eine neue Action raiseFatalError hinzu.

Schritt #9: FatalErrorHandler referenzieren

Im vorangegangenen Schritt haben Sie der Unit eine neue Action hinzugefügt. Diese muss nun von der Statemachine aus als FatalErrorHandler referenziert werden.

Das Referenzieren von anderen Modell-Elementen ist ein Ablauf, der in der Arbeit mit Meta Genius häufig erforderlich ist, daher wird dieser hier etwas ausführlicher beschrieben.

Im Model Editor wird jede Referenz als ComboBox dargestellt, die durch einen Click geöffnet werden kann. Danach hat man entweder die Möglichkeit, eine bestehende Referenz zu löschen oder eine neue Referenz herzustellen. Will man eine neue Referenz herstellen, wird das User Interface dabei in den Selektionsmodus versetzt und es kann dann das zu referenzierende Modell-Element ausgewählt werden.

• Wählen Sie um eine Action als FatalErrorHandler zu referenzieren.

Der Selektionsmodus ist dadurch gekennzeichnet, dass der Maus Cursor zu einer Selektions-Hand wird, mit der im Model Browser (links) nur jene Objekte selektiert werden können, die zum den Typ der aktuellen Referenz passen.

• Selektieren Sie die Action raiseFatalError.

Schritt #10: Neuen State hinzufügen

Alle bisherigen Schritte waren zwar wichtig als Vorbereitung, allerdings war bisher vom interessanten Inhalt der Statemachine wenig zu erkennen. Das soll sich nun ändern. Zur Erinnerung noch einmal unser Ziel:

Fügen Sie der Statemachine einen neuen State namens Alpha hinzu.

Schritt #11: Initiale Transition festlegen

Ausführliche Informationen zu der Bedeutung von initialen Transitionen finden Sie hier.

• Fügen Sie der Statemachine eine neue InitialTransition hinzu.
• Referenzieren Sie dort als Target den State Alpha.

Schritt #12: Meta Genius Repository speichern

Nun sind plötzlich alle roten Error Icons verschwunden. Könnte man möglicherweise einen Generierungsversuch starten?

Auf jeden Fall wäre nun mal eine gute Gelegenheit, um alle gemachten Änderungen zu speichern.

In Meta Genius werden alle Daten – also alle Metamodelle und alle Modelle – in einer einzigen Datei gespeichert, die als Repository bezeichnet wird.

• Speichern Sie das Meta Genius Repository an einem Ort Ihrer Wahl.

Schritt #13: EmStaMaG Codegenerierung aus Meta Genius starten

Im Schritt #3 wurde als Vorbereitung bereits EmStaMaG als Codegenerator für dieses Modell eingerichtet. EmStaMaG kann nun als Generator für dieses Modell aus dem Kontext Menu heraus über den Punkt „Perform Generation …“ gestartet werden.

• Starten Sie EmStaMaG über das Kontext Menü des Models.

Wie Sie sehen, übernimmt EmStaMaG beim Starten aus dem Modell automatisch alle erforderlichen Eigenschaften, wie z. B. die Generierungsverzeichnisse und zeigt diese zu Kontrollzwecken noch einmal an.

Wie bereits erwähnt, sollten Sie unbedingt beachten, dass am Anfang jeder Generierung der Inhalt der Source Code Verzeichnisse vollständig gelöscht wird!

Um Sie vor unerwünschtem Datenverlust zu schützen, müssen Sie vor jeder Generierung bestätigen, dass Ihnen dieser Umstand bewusst ist und dass Sie die Verzeichnisse mit entsprechender Sorgfalt gewählt haben.

• Prüfen Sie die Generierungsverzeichnisse sorgfältig.
• Wenn die Source Code Verzeichnisse tatsächlich gelöscht werden dürfen, bestätigen Sie dies in der CheckBox.

Schritt #14: Codegenerierung starten

• Starten Sie die Codegenerierung mit dem Generate Button.

Als Resultat wird angezeigt, dass Modellierungsprobleme gefunden wurden. Diese können in Meta Genius genauer untersucht werden.

Schritt #15: Markierte Probleme in Meta Genius untersuchen

EmStaMaG hat beim Generieren Modellierungsprobleme gefunden. Diese werden in Meta Genius in Form von gelben Warnungs Icons angezeigt. Wie Error Icons geben auch die Warnungs Icons zusätzliche textuelle Informationen als Tooltip, wenn man die Maus darüber bewegt.

Die aktuelle Fehlermeldung „Statemachine has to use at least one trigger event“ wird einem Anfänger vermutlich erst mal etwas Kopfzerbrechen bereiten.

Um diese Meldung etwas besser verstehen zu können, muss kurz die Funktionsweise von Zustandsmaschinen in Erinnerung gerufen werden. Eine Zustandsmaschine befindet sich normalerweise in einem stabilen Zustand, der erst verlassen werden kann, wenn ein geeignetes Ereignis als Trigger eintritt. Ist für dieses Ereignis ein Zustandsübergang als Transition spezifiziert, wird der stabile Zustand verlassen, die Transition durchlaufen und dann ein neuer stabiler Zustand erreicht. Für das Auslösen eines Zustandsübergangs ist also im Normalfall ein Ereignis als Trigger Event erforderlich. Eine Zustandsmaschine ganz ohne Trigger Event kann also nicht funktionieren.

Unsere Fehlermeldung deutet also indirekt darauf hin, dass möglicherweise Transitionen oder deren Trigger Events fehlen. In unserem Fall fehlen sogar beide.

Schritt #16: Trigger Event erstellen

Ereignisse werden im generierten Source Code als Wert einer Aufzählung abgebildet. Modelliert werden diese als Events, die jeweils Bestandteil einer EventGroup sind. Eine EventGroup wird bei der Codegenerierung zu einem Aufzählungstyp. Ein Event wird zu einem Aufzählungswert.

Wir benötigen ein Event und müssen dafür eine EventGroup mit zwei Events erstellen. Das zweite Event hat für die Implementierung der Statemachine eine besondere Bedeutung als ungültiger Wert (InvalidEvent).

• Fügen Sie der Unit eine neue EventGroup Event hinzu.
• Fügen Sie der EventGroup ein neues Event INVALID hinzu.
• Referenzieren Sie dieses Event als InvalidEvent der EventGroup.
• Fügen Sie der EventGroup ein neues Event TICK hinzu.

Schritt #17: Neue Transition hinzufügen

Um unsere Statemachine zu vervollständigen fehlt noch eine Transition, die von dem Event TICK ausgelöst werden soll.

Transitionen werden im Modell immer an die Modell-Elemente angefügt, die den Ausgangspunkt der Transition darstellen. In unserem Fall ist dies der State Alpha.

• Fügen Sie dem State Alpha eine neue Transition hinzu.

• Referenzieren Sie für diese Transition als Target den State Alpha.

• Referenzieren Sie für diese Transition als TriggerEvent den Event TICK.

Schritt #18: Statemachine Modellierung ist abgeschlossen

Die fehlende Transition wurde hinzugefügt. Die Modellierung unserer Statemachine ist nun abgeschlossen. Das vollständige Meta Genius Modell im Überblick:

Die Warnungs-Icons aus der letzten Generierung werden übrigens bei der nächsten Generierung verschwinden.

Schritt #19: Neue Codegenerierung starten

• Starten Sie eine neue Generierung.

Im Hintergrund ist zu erkennen, dass die Warnungs-Icons verschwunden sind. EmStaMaG meldet als Ergebnis „Generation successfully completed“. Sehr gut!

Höchste Zeit die generierten Dateien genauer zu betrachten:

Der generierte Source Code wird hier genauer besprochen.

Die restlichen Schritte dieses Tutorials beschäftigen sich mit dem generierten Zustandsdiagramm und wie dieses nach seinen eigenen Vorstellungen gestaltet werden kann.

Schritt #20: Generiertes Diagramm in yEd öffnen

Von EmStaMaG wurde eine Datei namens DemoSm.graphml generiert. Diese enthält bereits alle grafischen Elemente unseres Zustandsdiagramms und deren Verknüpfungen, allerdings ohne sinnvolles Layout. Das lässt sich aber nachträglich einfach erstellen und wird dann auch bei wiederholten Generierungen beibehalten.

• Starten Sie den Diagramm Editor yEd.
• Öffnen Sie damit die generierte Datei DemoSm.graphml.

Wie gesagt, ein Graph ohne Layout sieht natürlich nicht sehr ansprechend aus. Das lässt sich in yEd aber einfach ändern. Das Tool bietet hierzu verschiedene Varianten um die Elemente eines Graphen automatisch anzuordnen.

Schritt #21: Mit Auto Layouting Funktionen experimentieren

Hier experimentieren Sie in yEd am besten mal mit den verschiedenen Möglichkeiten, die das „Layout“ Menü so bietet. Vielversprechend waren daraus „Organisch“, „Orthogonal : UML-Stil“ oder „Flowchart“.

Schritt #22: Statemachine Diagramm manuell editieren

Auch wenn die Auto Layout Funktionen von yEd meist schnell etwas Übersicht in einen Graphen bringen, so hat man selber doch meist etwas andere Vorstellungen, wie sein Zustandsdiagramm genau aussehen soll.

In yEd kann man seine Zustandsdiagramme aber natürlich auch manuell editieren und seinen eigenen Vorstellungen entsprechend abändern.

Aber Achtung! Manuell gemachte Änderungen können beim wiederholten Generieren nur dann übernommen werden, wenn diese auch in yEd gespeichert wurden!

Schritt #23: Fertig!

An dieser Stelle haben Sie nun das Anfänger Tutorial erfolgreich abgeschlossen. Sie haben damit alle Grundlagen um Zustandsmaschinen zu modellieren und daraus Zustandsdiagramme und funktionalen C Code zu generieren.

Die Zustandsmaschine aus diesem Tutorial erfüllt natürlich keine sinnvolle Funktion. Aber es gibt ja auch das Tutorial für Fortgeschrittene, in dem mit Zustandsmaschinen ein Analog-Digital-Wandler gesteuert und damit eine Temperatur-Überwachung mit optischer Übertemperatur-Anzeige realisiert wird.

Fragen oder Anregungen?

Haben Sie Fragen? Oder Probleme?

Dann wenden Sie sich doch bitte an: support@papa-lima.de

Anregungen und Verbesserungsvorschläge werden natürlich auch gerne angenommen!