Architectuur van de toestandsmachine

De OSSM-firmware gebruikt een declaratieve toestandsmachine om het gedrag van het apparaat te beheren. Dit zorgt voor voorspelbare overgangen tussen bedieningsmodi en voorkomt ongeldige toestanden die onverwacht gedrag kunnen veroorzaken.

Toestandsdiagram

Het volgende diagram toont alle toestanden en overgangen in de OSSM-toestandsmachine:

Ontwerpoverzicht

De toestandsmachine wordt geïmplementeerd met Boost.SML (State Machine Language), een C++14-bibliotheek die alleen uit headers bestaat en een domeinspecifieke taal biedt voor het definiëren van toestandsmachines.

Waarom Boost.SML?

Boost.SML werd gekozen voor OSSM omdat het het volgende biedt:

• Verificatie tijdens compilatie - Ongeldige overgangen worden gedetecteerd tijdens het compileren, niet tijdens de runtime
• Geen runtime-overhead - Prestaties gelijkwaardig aan handgeschreven switch/case
• Declaratieve syntaxis - De transitietabel leest als documentatie
• Threadveiligheid - Ingebouwde ondersteuning voor gelijktijdige toegang via beleidsregels
• Kleine footprint - Eén header, ~2000 regels code, geen afhankelijkheden

Syntaxis van overgangstabel

Elke rij in de overgangstabel volgt dit patroon:

source_state + event [guard] / action = target_state

Bijvoorbeeld:

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

Dit betekent: wanneer de toestand menu.idle actief is en er een buttonPress-gebeurtenis optreedt, gaat de toestand over naar simplePenetration als de guard isOption(Menu::SimplePenetration) true retourneert.

Gebeurtenissen

Gebeurtenissen veroorzaken toestandsovergangen. Het zijn eenvoudige structuren die zijn gedefinieerd in Events.h en die vanuit elk deel van de codebase kunnen worden verzonden.

Gebeurtenissen dispatchen

Gebeurtenissen worden met behulp van de globale stateMachine-instantie gedispatcht:

#include "ossm/state/state.h"

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

De toestandsmachine wordt bij het opstarten geïnitialiseerd in state.cpp en als globale pointer beschikbaar gesteld.

Guards

Guards zijn voorwaardelijke controles die bepalen of een overgang moet plaatsvinden. Ze retourneren true om de overgang toe te staan of false om deze te blokkeren.

Implementatie van Guards

Guards worden gedefinieerd als constexpr-lambdas in de naamruimte guards. Ze roepen vooruit gedeclareerde implementatiefuncties aan om de header licht te houden:

// 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; };
    };
}

De feitelijke logica zit in guards.cpp, waardoor de compileertijden kort blijven en implementatiewijzigingen mogelijk zijn zonder de transitietabel opnieuw te compileren.

Acties

Acties zijn functies die tijdens toestandsovergangen worden uitgevoerd. Ze veroorzaken bijwerkingen zoals het bijwerken van het display, het starten van motoren of het resetten van instellingen.

Weergaveacties

Bewegingsacties

Instellingsacties

Systeemacties

Actie-implementatie

Acties worden gedefinieerd als constexpr-lambdas in de naamruimte actions. Net als Guards delegeren ze naar vooruit gedeclareerde implementatiefuncties:

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

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

De implementatiefuncties in actions.cpp roepen de juiste functiemodules op:

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

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

Dit patroon houdt de toestandsmachine losgekoppeld van specifieke implementaties en maakt het mogelijk dat functiemodules onafhankelijk worden ontwikkeld.

Threadveiligheid

De OSSM-toestandsmachine is geconfigureerd met threadveilige beleidsregels om gebeurtenissen van meerdere FreeRTOS-taken af te handelen:

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

Hierbij wordt een recursieve mutex gebruikt om toestandsovergangen te beschermen, zodat gebeurtenissen veilig vanuit de volgende contexten kunnen worden gedispatcht:

• De hoofdlus
• Knop-interrupt-handlers
• BLE-opdrachthandlers
• Achtergrondtaken

De toestandsmachine wordt geïnitialiseerd in state.cpp:

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

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

Toestandslogging

De firmware bevat een StateLogger die alle toestandsovergangen registreert voor foutopsporing:

sml::logger<StateLogger>

Dit geeft transitie-informatie door via ESP-IDF-logging, waardoor het gedrag van de toestandsmachine tijdens de ontwikkeling eenvoudig kan worden gevolgd.

Architectuurnotities

De toestandsmachine volgt een ontkoppelde modulaire architectuur:

• Definitie van de toestandsmachine (machine.h) bevat alleen de overgangstabel
• Acties en Guards zijn constexpr-lambda's die delegeren aan implementatiefuncties
• Functiemodules (zoals pages::, simple_penetration::, stroke_engine::) bevatten de daadwerkelijke logica
• Globale toestandsstructuren beheren de applicatietoestand in plaats van klasseleden

Zie Mappenstructuur voor een compleet overzicht van de broncodeorganisatie.

Verder lezen