Architektur der Zustandsmaschine

Die OSSM-Firmware verwendet eine deklarative Zustandsmaschine, um das Geräteverhalten zu verwalten. Dies gewährleistet vorhersehbare Übergänge zwischen den Betriebsmodi und verhindert ungültige Zustände, die zu unerwartetem Verhalten führen könnten.

Zustandsdiagramm

Das folgende Diagramm zeigt alle Zustände und Übergänge in der OSSM-Zustandsmaschine:

Designübersicht

Die Zustandsmaschine wird mithilfe von Boost.SML (State Machine Language) implementiert, einer C++14-Bibliothek, die ausschließlich aus Headern besteht und eine domänenspezifische Sprache zum Definieren von Zustandsmaschinen bereitstellt.

Warum Boost.SML?

Boost.SML wurde für OSSM ausgewählt, weil es Folgendes bietet:

• Überprüfung zur Kompilierungszeit – Ungültige Übergänge werden zur Kompilierungszeit und nicht zur Laufzeit abgefangen
• Kein Laufzeit-Overhead – Leistung entspricht handgeschriebener switch/case-Logik
• Deklarative Syntax – Die Übergangstabelle liest sich wie eine Dokumentation
• Thread-Sicherheit – Integrierte Unterstützung für gleichzeitigen Zugriff über Richtlinien
• Geringer Platzbedarf – Einzelner Header, ca. 2000 Codezeilen, keine Abhängigkeiten

Syntax der Übergangstabelle

Jede Zeile in der Übergangstabelle folgt diesem Muster:

source_state + event [guard] / action = target_state

Zum Beispiel:

"menu.idle"_s + buttonPress[(isOption(Menu::SimplePenetration))] = "simplePenetration"_s

Dies bedeutet: Wenn im Zustand menu.idle ein buttonPress-Ereignis auftritt und der Guard isOption(Menu::SimplePenetration) true zurückgibt, wird in den Zustand simplePenetration gewechselt.

Ereignisse

Ereignisse lösen Zustandsübergänge aus. Es handelt sich um einfache Strukturen, die in Events.h definiert sind und von überall in der Codebasis ausgelöst werden können.

Ereignisse auslösen

Ereignisse werden mithilfe der globalen stateMachine-Instanz ausgelöst:

#include "ossm/state/state.h"

// From anywhere in the codebase
stateMachine->process_event(ButtonPress{});
stateMachine->process_event(Done{});

Die Zustandsmaschine wird beim Start in state.cpp initialisiert und als globaler Zeiger bereitgestellt.

Guards

Guards sind bedingte Prüfungen, die bestimmen, ob ein Übergang stattfinden soll. Sie geben true zurück, um den Übergang zuzulassen, oder false, um ihn zu blockieren.

Implementierung von Guards

Guards werden als constexpr-Lambdas im guards-Namespace definiert. Sie rufen vorwärts deklarierte Implementierungsfunktionen auf, um den Header schlank zu halten:

// In guards.h - forward declaration
bool ossmIsPreflightSafe();

namespace guards {
    // Constexpr lambda wraps the implementation
    constexpr auto isPreflightSafe = []() {
        return ossmIsPreflightSafe();
    };

    // Parameterized guard using nested lambda
    constexpr auto isOption = [](Menu option) {
        return [option]() { return ossmGetMenuOption() == option; };
    };
}

Die eigentliche Logik befindet sich in guards.cpp, wodurch die Kompilierungszeiten kurz bleiben und Implementierungsänderungen möglich sind, ohne dass die Übergangstabelle neu kompiliert werden muss.

Aktionen

Aktionen sind Funktionen, die bei Zustandsübergängen ausgeführt werden. Sie führen zu Nebeneffekten wie der Aktualisierung der Anzeige, dem Starten von Motoren oder dem Zurücksetzen von Einstellungen.

Anzeigeaktionen

Bewegungsaktionen

Einstellungen-Aktionen

Systemaktionen

Implementierung von Aktionen

Aktionen werden als constexpr-Lambdas im actions-Namespace definiert. Wie Guards delegieren sie an vorwärts deklarierte Implementierungsfunktionen:

// In actions.h - forward declarations
void ossmDrawHello();
void ossmEmergencyStop();

namespace actions {
    constexpr auto drawHello = []() { ossmDrawHello(); };
    constexpr auto emergencyStop = []() { ossmEmergencyStop(); };
}

Die Implementierungsfunktionen in actions.cpp rufen die entsprechenden Funktionsmodule auf:

// In actions.cpp
void ossmEmergencyStop() {
    stepper->forceStop();
    stepper->disableOutputs();
}

void ossmDrawHello() {
    pages::drawHello();  // Delegates to pages namespace
}

Dieses Muster hält die Zustandsmaschine von bestimmten Implementierungen entkoppelt und ermöglicht die unabhängige Entwicklung von Funktionsmodulen.

Thread-Sicherheit

Die OSSM-Zustandsmaschine ist mit Thread-Sicherheitsrichtlinien konfiguriert, um Ereignisse aus mehreren FreeRTOS-Aufgaben zu verarbeiten:

sml::sm<OSSMStateMachine, sml::thread_safe<ESP32RecursiveMutex>, sml::logger<StateLogger>>

Dabei wird ein rekursiver Mutex verwendet, um Zustandsübergänge zu schützen und eine sichere Ereignisverteilung aus folgenden Kontexten zu ermöglichen:

• Hauptschleife
• Tasten-Interrupt-Handler
• BLE-Befehlshandler
• Hintergrundaufgaben

Die Zustandsmaschine wird in state.cpp initialisiert:

// Global state machine instance
StateMachine* stateMachine = nullptr;

void initStateMachine() {
    stateMachine = new StateMachine{};
    stateMachine->process_event(Done{});  // Trigger initial transition
}

Zustandsprotokollierung

Die Firmware enthält einen StateLogger, der alle Zustandsübergänge zum Debuggen protokolliert:

sml::logger<StateLogger>

Dadurch werden Übergangsinformationen über die ESP-IDF-Protokollierung ausgegeben, sodass das Verhalten der Zustandsmaschine während der Entwicklung leicht verfolgt werden kann.

Architekturnotizen

Die Zustandsmaschine folgt einer entkoppelten modularen Architektur:

• Zustandsmaschinendefinition (machine.h) enthält nur die Übergangstabelle
• Aktionen und Guards sind constexpr-Lambdas, die an Implementierungsfunktionen delegieren
• Funktionsmodule (wie pages::, simple_penetration::, stroke_engine::) enthalten die eigentliche Logik
• Globale Zustandsstrukturen verwalten den Anwendungsstatus anstelle von Klassenmitgliedern

Eine vollständige Übersicht über die Quellcodeorganisation finden Sie unter Ordnerstruktur.

Weiterführende Literatur