SimpleFSM

Arduino/ESP library to simplify setting up and running a state machine.

Author: Lennart Hennigs (https://www.lennarthennigs.de)
Copyright (C) 2023 Lennart Hennigs.
Released under the MIT license.

Description

This library allows you to quickly setup a State Machine. Read here what a state machine is and why a state machine is neat for hardware projects.

It has been tested with Arduino, ESP8266 and ESP32 devices.

⚠️ To see the latest changes to the library please take a look at the Changelog.

If you find this library helpful please consider giving it a ⭐️ at GitHub and/or buy me a ☕️. Thanks!

Features

Easy state definition
Allows for none, one or multiple final states
Event triggered transitions and (automatic) timed transitions
Possibility to define guard conditions for your transitions
Callback functions for...
- State entry, staying, exit
- Transition execution
- Final state reached
- the run interval of the state machine
Definition of an in_state interval
Functions for tracking the behavior and progress of the state machine
Creation of a Graphviz source file of your state machine definition
TBD: Storage of the current state on files with LittleFS or SD card storage (TBD)

⚠️ To see the latest changes to the library please take a look at the Changelog.

How To Use

You first need to define a set of states for your state machine
Then, define transitions (regular or timed) for these state
Pass the transitions to your state machine
Define an initial state
...and add the run() function in your loop
See SimpleTransitions.ino for a basic example

Defining States

A finite state machine has a defined set of states
A state must have a name...
...and can have callback functions for different events (when a state is entered, exited, or stays in a state)

  State(
    String name, 
    CallbackFunction on_enter, 
    CallbackFunction on_state = NULL, 
    CallbackFunction on_exit = NULL, 
    bool is_final = false
  );

Most states will have the entry handler

The easiest way to define states is creating using an array, e.g. as shown in MixedTransitions.ino:

State s[] = {
  State("red",        on_red),
  State("green",      on_green),
  State("BTN",        on_button_press)
};

The inital state must of the state machine must be defined – either via the constructor or the setup() function or via the setInitialState() function
None, one, or multiple states can be defined as an end state via setAsFinal()
For the full State class definition see State.h

Transitions

This library offers two types of Transitions, regular and timed ones
All transitions must have a from and and a to state
Transitions can have a callback function for when the transition is executed, a name, and a guard condition
You can add both types to a state machine, see MixedTransitions.ino for an example
See Transitions.h for the class definitions of Transition and TimedTransition.
Note: Both classes are based of an abstract class which is not to be used in your code.

Regular Transitions

  Transition(
    State* from, 
    State* to, 
    int event_id, 
    CallbackFunction on_run = NULL, 
    String name = "", 
    GuardCondition guard = NULL
  );

Regular transitions must have a a set of states and a trigger (ID):

Transition transitions[] = {
  Transition(&s[0], &s[1], light_switch_flipped),
  Transition(&s[1], &s[0], light_switch_flipped)
};

Define the triggers for your state machine in an enum (and set the first enum value to 1, to be safe):
```
enum triggers {
  light_switch_flipped = 1  
};
```
To call a trigger use the trigger()function:
```
fsm.trigger(light_switch_flipped);
```
See SimpleTransitions.ino and SimpleTransitionWithButtons.ino for more details

Timed Transitions

  TimedTransition(
    State* from, 
    State* to, 
    int interval, 
    CallbackFunction on_run = NULL, 
    String name = "", 
    GuardCondition guard = NULL
  );

Timed transitions are automatically executed after a certain amount of time has passed

The interval is defined in milliseconds:

TimedTransition timedTransitions[] = {
  TimedTransition(&s[0], &s[1], 6000),
  TimedTransition(&s[1], &s[0], 4000),
  TimedTransition(&s[2], &s[1], 2000)
};

See TimedTransitions.ino for more details

Guard Conditions

Guard conditions are evaluated before a transition takes places
Only if the guard condition is true the transition will be executed
Both regular and timed transitions can have guard conditions

You define guard conditions as functions:

TimedTransition timedTransitions[] = {
  TimedTransition(&s[0], &s[1], 1000, NULL, "", zero_yet),
  TimedTransition(&s[0], &s[0], 1000, NULL, "", not_zero_yet)
};  

bool not_zero_yet() {
  return countdown != 0;
}

bool zero_yet() {
  return countdown == 0;
}

See Guards.ino for a complete example

In-State Interval

States can have up to three events...
- when they enter a state
- while they are in a state
- ...and when they leave the state

  State(String name, CallbackFunction on_enter, CallbackFunction on_state = NULL, CallbackFunction on_exit = NULL, bool is_final = false);

To define how frequent the on_state event is called, pass an interval (in ms) to the run() function in your main loop():
```
void run(int interval = 1000, CallbackFunction tick_cb = NULL);
```
After this interval has passed the on_state function of the active state will be called (if it defined)
Also the tick_cbcallback function will be called (if defined) in the run() call

Helper functions

SimpleFSM provides a few functions to check on the state of the machine:

  State* getState() const;
  State* getPreviousState() const;
  bool isInState(State* state) const;
  int lastTransitionedAt() const;
  bool isFinished() const;

GraphViz Generation

Use the function getDotDefinition() to get your state machine definition in the GraphViz dot format

Here the output for the MixedTransitions.ino example:

  digraph G {
    rankdir=LR; pad=0.5
    node [shape=circle fixedsize=true width=1.5];
    "red light" -> "green light" [label=" (6000ms)"];
    "green light" -> "red light" [label=" (4000ms)"];
    "button pressed" -> "green light" [label=" (2000ms)"];
    "red light" -> "button pressed" [label=" (ID=1)"];
    "red light" [style=filled fontcolor=white fillcolor=black];
  }

You can use this visualize your state machine:
If the machine is running, the current state will be highlighted
Currently guard functions and end states are not shown in the graph
See MixedTransitionsBrowser.ino to learn how to run a webserver to show the Graphviz diagram of your state machine

Class Definitions

State.h
Transitions.h for the class definition of both transitions
SimpleFSM

Examples

SimpleTransitions.ino - only regular transitions and showcasing the different events
SimpleTransitionWithButtons.ino - event is now triggered via a hardware button
TimedTransitions.ino - showcasing timed transitions
MixedTransitions.ino - regular and timed transitions
MixedTransitionsBrowser.ino - creates a webserver to show the Graphviz diagram of the state machine
Guards.ino - showing how to define guard functions

Notes

This libary is heavily inspiried by the Arduino-fsm library created by Jon Black. I initally used some of his as a base. Without Jon's work this library would not exist.
To see the latest changes to the library please take a look at the Changelog.
And if you find this library helpful, please consider giving it a star at GitHub. Thanks!

How To Install

Open the Arduino IDE choose "Sketch > Include Library" and search for "SimpleFSM". Or download the ZIP archive (https://github.com/lennarthennigs/SimpleFSM/zipball/master), and choose "Sketch > Include Library > Add .ZIP Library..." and select the downloaded file.

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

LennartHennigs/SimpleFSM