C++ Statemachine-Framework

by ·Kommentare deaktiviert für C++ Statemachine-Framework

StateMachines sind das Brot und Butter eines (embedded) Softwareentwicklers. Die meisten StateMachine Frameworks für C++ sind aber sehr kompliziert und verwenden unglaublich viel Templates oder hängen von irgendwelchen Bibliotheken ab. Hab grad Urlaub und hab mir gedacht ich bau mir jetzt endlich ein eigenes Statemachine-Framework. Überraschenderweise war das recht schnell erledigt (ca. 2 Tage). So viel muss ein StateMachine-Framework ja eigentlich garned können hab ich gemerkt. Was mich sehr gewundert hat ist, dass sowas wie parallele States in vielen Frameworks garnicht möglich sind oder sehr aufwendig. Rausgekommen sind im ersten Schuss etwa 100 Zeilen Code in einer einzigen Headerdatei. Auch wenn ich beim Testen recht leicht auf 100% Coverage kam, bin ich nicht sicher, dass das Ding fehlerfrei ist. Also erstmal vorsichtig damit – Wenn du Fehler findest, bitte her damit. Ich hab bestimmt ein paar versteckt 🙂

Features

  • Eventbasiert
  • Einfache Initialisierung (alles an einer Stelle bzw. Methode)
  • SubStates und parallelle States
  • Single header mit nur etwa 130 LOC – reinkopieren und loslegen – keine Abhängigkeiten zu irgendwelchen Bibliotheken – STL only
  • Interface mit nur einer Methode die lediglich Events entgegennimmt
  • Fast keine Templates – C++11 – auch für alte Compiler
  • Geeignet für Embedded-Systeme (auch Bare-Metal mit wenig RAM, FreeRTOS, Arduino, mbed)
  • Verschachtelbar – mehrere StateMachines in einem System einfach möglich
  • Wenig Speicherbedarf – eine einfache StateMachine braucht ca. 1,4 kB (gemessen auf ESP32 mit Arduino)
  • Schnell – Stateübergang in 5 us auf PC. Auf ESP32 in 75 us (ohne Logging)
  • Initialisierung aller States, Transitions und Reactions in nur einer überschriebenen Methode
  • Einfach zu verbinden mit dem Rest des Systems – kleine Aktionen über Lambdas die mit dem „Rest“ verknüpfen
  • So einfach, dass durch das kleine Beispiel bereits getestet mit 100% LineCoverage (coverage als html liegt mit im Repo)
  • Update 2024-11-04: Hab einen Timer-Mechanismus eingebaut (ist zwar kein standard StateMachine-Feature, hab ich aber schon oft gebraucht)

Das Repo liegt hier: https://bitbucket.org/bobbery/mystatemachine hab qmake verwendet, damit mans leicht im QtCreator aufmachen und übersetzen kann. Braucht natürlich kein Qt – aber für ein Makefile für jede Plattform bin ich zu faul und qmake hab ich viel lieber als CMake

Das ist die StateMachine – ist einfach nur ein Header mit knapp über 100 LOC

/* Copyright 2024 stefan.box2code.de
 *            
 * Use of this source code is governed by an MIT-style
 * license that can be found in the LICENSE file or at
 * https://opensource.org/licenses/MIT.
 */
#ifndef STATEMACHINE_H
#define STATEMACHINE_H

#include <functional>
#include <iostream>
#include <map>
#include <set>
#include <string>
#include <vector>

#define LOG_EVENTS
#define LOG_STATES

template<class StateID, class EventID>
class StateMachine
{
public:
    StateMachine() {}

    void react(EventID e) { react_p(e); }
    void handleTimerTick() { handleTimerTick_p(); }

    virtual void init() = 0; // overwrite it to create your machine

    virtual ~StateMachine() {}

protected:
    void react_p(EventID e)
    {
#ifdef LOG_EVENTS
        if (m_eventNames.find(e) != m_eventNames.end()) {
            std::cout << "on" << m_eventNames.find(e)->second << "()" << std::endl;
        }
#endif
        bool transitOk = true;
        for (StateID sid : m_activeStates) {
            if (m_reactions.find(std::make_pair(sid, e)) != m_reactions.end()) {
                if (!m_reactions.find(std::make_pair(sid, e))->second()) {
                    transitOk = false;
                }
            }
        }
        if (transitOk) {
            transit(e);
        }
    }

    void addInitialState(StateID sid, const std::string &name, StateID parent = StateID::NumStates)
    {
        m_stateNames[sid] = name;
        if (parent != StateID::NumStates) {
            m_childStates[parent].insert(sid);
        } else {
            m_activeStates.insert(sid);
        }
        m_initials[parent].insert(sid);
    }
    void addState(StateID sid, const std::string &name, StateID parent = StateID::NumStates)
    {
        m_stateNames[sid] = name;
        if (parent != StateID::NumStates) {
            m_childStates[parent].insert(sid);
        }
    }
    void addEventName(EventID eid, const std::string &name) { m_eventNames[eid] = name; }
    void addReaction(StateID sid, EventID eid, std::function<bool()> fun)
    {
        m_reactions.emplace(std::make_pair(sid, eid), fun);
    }
    void addEntry(StateID sid, std::function<bool()> fun) { m_entry.emplace(sid, fun); }
    void addExit(StateID sid, std::function<bool()> fun) { m_exit.emplace(sid, fun); }
    void addTransition(StateID sid, EventID eid, StateID target)
    {
        m_transitions.emplace(std::make_pair(sid, eid), target);
    }

    void transit(EventID e)
    {
        std::set<StateID> newActiveStates;
        for (StateID id : m_activeStates) {
            if (m_transitions.find(std::make_pair(id, e)) != m_transitions.end()) {
                StateID activated = m_transitions.find(std::make_pair(id, e))->second;
                newActiveStates.insert(activated);
                if (m_initials.find(activated) != m_initials.end()) {
                    for (StateID subInitial : m_initials.find(activated)->second) {
                        newActiveStates.insert(subInitial);
                    }
                }
            } else {
                newActiveStates.insert(id);
            }
        }

        std::set<StateID> deactivated;
        for (StateID id : m_activeStates) {
            if (newActiveStates.count(id) == 0) {
                deactivated.insert(id);
            }
        }

        for (StateID id : deactivated) {
            if (m_childStates.find(id) != m_childStates.end()) {
                for (StateID chId : m_childStates.at(id)) {
                    newActiveStates.erase(chId);
                    if (m_exit.find(chId) != m_exit.end()) {
                        m_exit.at(chId)();
                    }
                }
            }
            if (m_exit.find(id) != m_exit.end()) {
#ifdef LOG_STATES
                std::cout << "onExit() of " << m_stateNames.at(id) << std::endl;
#endif
                m_exit.at(id)();
            }
        }

        for (StateID id : newActiveStates) {
            if (m_activeStates.count(id) == 0) {
                if (m_entry.find(id) != m_entry.end()) {
#ifdef LOG_STATES
                    std::cout << "onEntry() of " << m_stateNames.at(id) << std::endl;
#endif
                    m_entry.at(id)();
                }
            }
        }

        m_activeStates = newActiveStates;
#ifdef LOG_STATES
        std::cout << "Current States: ";
        for (StateID id : m_activeStates) {
            if (m_stateNames.find(id) != m_stateNames.end()) {
                std::cout << m_stateNames.find(id)->second << " ";
            }
        }
        std::cout << std::endl;
#endif
    }

    void handleTimerTick_p()
    {
        bool timerExpired = false;
        for (auto timer : m_timers) {
            if (timer.second < 0) {
                continue;
            }
            m_timers[timer.first] = --timer.second;
            if (timer.second == 0) {        // timer is expired
                m_timers[timer.first] = -1; // timer is stopped
                timerExpired = true;
            }
        }
        if (timerExpired) {
            react_p(EventID::TimerExpired);
        }
    }

    bool isTimerExpired(size_t timerNum)
    {
        if (m_timers.find(timerNum) == m_timers.end()) {
            return false;
        }
        return m_timers.at(timerNum) < 0;
    }

    void startTimer(size_t timerNum, int timeInMs) { m_timers[timerNum] = timeInMs; }

    void stopTimer(size_t timerNum) { m_timers[timerNum] = -1; }

    std::map<StateID, std::string> m_stateNames;
    std::map<EventID, std::string> m_eventNames;
    std::map<StateID, std::set<StateID>> m_initials;
    std::map<std::pair<StateID, EventID>, StateID> m_transitions;
    std::set<StateID> m_activeStates;
    std::map<StateID, std::set<StateID>> m_childStates;
    typedef std::function<bool()> reactFun;
    std::map<std::pair<StateID, EventID>, reactFun> m_reactions;
    std::map<StateID, reactFun> m_entry;
    std::map<StateID, reactFun> m_exit;
    std::map<size_t, int> m_timers;
};

#endif // STATEMACHINE_H

Und ein Besispiel

Das Beispiel ist bewusst einfach und hoffentlich leicht verständlich. Eigentlich wollt ich nur was was mit dem man gut parallelle States demonstrieren kann. Das Diagramm ist mit dem QtCreator gezeichnet:

/* Copyright 2024 stefan.box2code.de
 *            
 * Use of this source code is governed by an MIT-style
 * license that can be found in the LICENSE file or at
 * https://opensource.org/licenses/MIT.
 */

#include "statemachine.h"

#define MEASURE_TIME

#ifdef MEASURE_TIME
#include <chrono>
#endif

enum class MyStateID {
    Startup,
    Running,
    Lampe1An,
    Lampe1Aus,
    Lampe2An,
    Lampe2Aus,
    NumStates
}; // you should always add NumStates on end
enum class MyEventID {
    TimerExpired, // must always be there
    On,
    Off,
    Toggle,
    NumEvents
}; // you should always add NumEvents on end

class MyApi // The Interface to the Rest of your Application
{
public:
    virtual bool checkBatteryFull()
    {
        std::cout << "Implement battery check" << std::endl;
        return false;
    }
    virtual void turnOnLed() { std::cout << "Implement turn on LED" << std::endl; }
    virtual void playAudio() { std::cout << "Implement playing audio" << std::endl; }
    virtual void sendEventToAnotherSm(MyEventID)
    {
        std::cout << "Send event to another state machine in your system" << std::endl;
        // anotherStateMachine.react(e);
    }
    virtual ~MyApi() {}
};

class MyStateMachine : public virtual StateMachine<MyStateID, MyEventID>
{
public:
    MyStateMachine(MyApi &api)
        : m_api(api)
    {
        init();
    }

    void init() override
    {
        addInitialState(MyStateID::Startup, "Startup");
        addReaction(MyStateID::Startup, MyEventID::Off, [&]() {
            std::cout << "Hey a Off-Event in Startup" << std::endl;
            if (m_api.checkBatteryFull()) { // this is the easy way to call the rest of your system
                return true;                // must return true to do corresponding transition
            }
            return false;
        });
        addTransition(MyStateID::Startup,
                      MyEventID::Off,
                      MyStateID::Running); // this one will be forbidden by reaction above
        addTransition(MyStateID::Startup, MyEventID::On, MyStateID::Running);

        addState(MyStateID::Running, "Running");
        addEntry(MyStateID::Running, [&]() {
            std::cout << "Entry() of Running" << std::endl;
            startTimer(42, 500); // start timer 42 with 500 ms
            m_api.turnOnLed();   // this is the easy way to call the rest of your system
            return true;         // return what ever you want - doesnt matter
        });
        addExit(MyStateID::Running, [&]() {
            std::cout << "Exit() of Running" << std::endl;
            stopTimer(42); // timer 42 is now stopped
            return false;  // return what ever you want - doesnt matter
        });
        addTransition(MyStateID::Running, MyEventID::Off, MyStateID::Startup);
        addTransition(MyStateID::Running, MyEventID::TimerExpired, MyStateID::Startup);
        addReaction(MyStateID::Running, MyEventID::TimerExpired, [&]() {
            if (isTimerExpired(42)) {
                std::cout << "Timer 42 has expired" << std::endl;
                return true;
            }
            return false;
        });

        addInitialState(MyStateID::Lampe1An, "Lampe1An", MyStateID::Running);
        addTransition(MyStateID::Lampe1An, MyEventID::Toggle, MyStateID::Lampe1Aus);

        addState(MyStateID::Lampe1Aus, "Lampe1Aus", MyStateID::Running);
        addTransition(MyStateID::Lampe1Aus, MyEventID::Toggle, MyStateID::Lampe1An);
        addEntry(MyStateID::Lampe1Aus, []() {
            std::cout << "Entry() of Lampe1Aus" << std::endl;
            return true; // return what ever you want - doesnt matter
        });
        addExit(MyStateID::Lampe1Aus, []() {
            std::cout << "Exit() of Lampe1Aus" << std::endl;
            return false; // return what ever you want - doesnt matter
        });

        addState(MyStateID::Lampe2An, "Lampe2An", MyStateID::Running);
        addTransition(MyStateID::Lampe2An, MyEventID::Toggle, MyStateID::Lampe2Aus);
        addTransition(MyStateID::Lampe2An, MyEventID::Off, MyStateID::Startup);
        addReaction(MyStateID::Lampe2An, MyEventID::Off, []() {
            std::cout << "Hey a Off-Event in Lampe2An" << std::endl;
            return false; // returns false so the transition is skipped
        });

        addInitialState(MyStateID::Lampe2Aus, "Lampe2Aus", MyStateID::Running);
        addTransition(MyStateID::Lampe2Aus, MyEventID::Toggle, MyStateID::Lampe2An);

        addEventName(MyEventID::On, "On");
        addEventName(MyEventID::Off, "Off");
        addEventName(MyEventID::Toggle, "Toggle");
    }

private:
    MyApi &m_api;
};

int main()
{
    MyApi myApi;
    MyStateMachine m(myApi);
#ifdef MEASURE_TIME
    auto start = std::chrono::steady_clock::now();
#endif
    m.react(MyEventID::Off);
    m.react(MyEventID::On);
    m.react(MyEventID::Toggle);
    m.react(MyEventID::Toggle);
    m.react(MyEventID::Toggle);
    m.react(MyEventID::Toggle);
    m.react(MyEventID::Off);
    m.react(MyEventID::Off);
    m.react(MyEventID::On);
    m.react(MyEventID::Toggle);
    m.react(MyEventID::Toggle);
    m.react(MyEventID::Toggle);
    m.react(MyEventID::Toggle);
    m.react(MyEventID::Off);
    m.react(MyEventID::On);
    m.react(MyEventID::Off);
    m.react(MyEventID::On);

#ifdef MEASURE_TIME
    std::cout << "Elapsed(us)="
              << std::chrono::duration_cast<std::chrono::microseconds>(
                     std::chrono::steady_clock::now() - start)
                     .count()
              << std::endl;
#endif

    for (int ms = 0; ms < 1000; ms++) {
        // of course you should call this in your SysTick-Handler
        m.handleTimerTick();
    }
}

Du siehst schon – Templates brauchst du nur in einer Zeile um deine eigenen Listen für States und Events einbinden zu können.

Die Anbindung an dein restliches System hab ich nur skizziert.

Ich hoffe der Code ist ansonsten selbsterklärend – Viel Spaß damit

Ach ja, noch die Ausgabe des Programms:


onOff()
Hey a Off-Event in Startup
Implement battery check
onOn()
onEntry() of Running
Entry() of Running
Implement turn on LED
Current States: Running Lampe1An Lampe2Aus 
onToggle()
onEntry() of Lampe1Aus
Entry() of Lampe1Aus
Current States: Running Lampe1Aus Lampe2An 
onToggle()
onExit() of Lampe1Aus
Exit() of Lampe1Aus
Current States: Running Lampe1An Lampe2Aus 
onToggle()
onEntry() of Lampe1Aus
Entry() of Lampe1Aus
Current States: Running Lampe1Aus Lampe2An 
onToggle()
onExit() of Lampe1Aus
Exit() of Lampe1Aus
Current States: Running Lampe1An Lampe2Aus 
onOff()
Exit() of Lampe1Aus
onExit() of Running
Exit() of Running
Current States: Startup 
onOff()
Hey a Off-Event in Startup
Implement battery check
onOn()
onEntry() of Running
Entry() of Running
Implement turn on LED
Current States: Running Lampe1An Lampe2Aus 
onToggle()
onEntry() of Lampe1Aus
Entry() of Lampe1Aus
Current States: Running Lampe1Aus Lampe2An 
onToggle()
onExit() of Lampe1Aus
Exit() of Lampe1Aus
Current States: Running Lampe1An Lampe2Aus 
onToggle()
onEntry() of Lampe1Aus
Entry() of Lampe1Aus
Current States: Running Lampe1Aus Lampe2An 
onToggle()
onExit() of Lampe1Aus
Exit() of Lampe1Aus
Current States: Running Lampe1An Lampe2Aus 
onOff()
Exit() of Lampe1Aus
onExit() of Running
Exit() of Running
Current States: Startup 
onOn()
onEntry() of Running
Entry() of Running
Implement turn on LED
Current States: Running Lampe1An Lampe2Aus 
onOff()
Exit() of Lampe1Aus
onExit() of Running
Exit() of Running
Current States: Startup 
onOn()
onEntry() of Running
Entry() of Running
Implement turn on LED
Current States: Running Lampe1An Lampe2Aus 
Elapsed(us)=123
Timer 42 has expired
Exit() of Lampe1Aus
onExit() of Running
Exit() of Running
Current States: Startup