{"id":18824651,"url":"https://github.com/lennarthennigs/simplefsm","last_synced_at":"2025-04-07T13:04:37.596Z","repository":{"id":90173696,"uuid":"485017079","full_name":"LennartHennigs/SimpleFSM","owner":"LennartHennigs","description":"Arduino/ESP library to simplify setting up and running a state machine.","archived":false,"fork":false,"pushed_at":"2025-01-28T20:10:52.000Z","size":73,"stargazers_count":79,"open_issues_count":4,"forks_count":19,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-31T12:03:43.033Z","etag":null,"topics":["arduino","arduino-library","cplusplus","embedded","esp","esp32","esp8266","finite-state-machine","fsm","fsm-library","state-machine"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LennartHennigs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"lennart0815"}},"created_at":"2022-04-24T12:08:44.000Z","updated_at":"2025-03-02T17:03:41.000Z","dependencies_parsed_at":"2024-10-27T08:37:46.314Z","dependency_job_id":"dadfa477-e427-486b-b35c-0bc42967be19","html_url":"https://github.com/LennartHennigs/SimpleFSM","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LennartHennigs%2FSimpleFSM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LennartHennigs%2FSimpleFSM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LennartHennigs%2FSimpleFSM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LennartHennigs%2FSimpleFSM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LennartHennigs","download_url":"https://codeload.github.com/LennartHennigs/SimpleFSM/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247657276,"owners_count":20974344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","arduino-library","cplusplus","embedded","esp","esp32","esp8266","finite-state-machine","fsm","fsm-library","state-machine"],"created_at":"2024-11-08T00:57:04.318Z","updated_at":"2025-04-07T13:04:37.574Z","avatar_url":"https://github.com/LennartHennigs.png","language":"C++","funding_links":["https://ko-fi.com/lennart0815"],"categories":[],"sub_categories":[],"readme":"# SimpleFSM\n\nArduino/ESP library to simplify setting up and running a state machine.\n\n* Author: Lennart Hennigs (\u003chttps://www.lennarthennigs.de\u003e)\n* Copyright (C) 2023 Lennart Hennigs.\n* Released under the MIT license.\n\n## Description\n\nThis library allows you to quickly setup a State Machine. Read here [what a state machine is](https://majenko.co.uk/blog/our-blog-1/the-finite-state-machine-26) and [why a state machine is neat for hardware projects](https://barrgroup.com/embedded-systems/how-to/state-machines-event-driven-systems?utm_source=pocket_mylist).\n\nIt has been tested with Arduino, ESP8266 and ESP32 devices.\n\n⚠️ To see the latest changes to the library please take a look at the [Changelog](https://github.com/LennartHennigs/SimpleFSM/blob/master/CHANGELOG.md).\n\nIf you find this library helpful please consider giving it a ⭐️ at [GitHub](https://github.com/LennartHennigs/SimpleFSM) and/or [buy me a ☕️](https://ko-fi.com/lennart0815). Thanks!\n\n### Features\n\n* Easy state definition\n* Allows for none, one or multiple final states\n* Event triggered transitions and (automatic) timed transitions\n* Possibility to define guard conditions for your transitions\n* Callback functions for...\n  * State entry, staying, exit\n  * Transition execution\n  * Final state reached\n  * the run interval of the state machine\n* Definition of an in_state interval\n* Functions for tracking the behavior and progress of the state machine\n* Creation of a `Graphviz` source file of your state machine definition\n* TBD: Storage of the current state on files with `LittleFS` or SD card storage (TBD)\n  \n⚠️ To see the latest changes to the library please take a look at the [Changelog](https://github.com/LennartHennigs/SimpleFSM/blob/master/CHANGELOG.md).\n\n## How To Use\n\n* You first need to define a set of states for your state machine\n* Then, define transitions (regular or timed) for these state\n* Pass the transitions to your state machine\n* Define an initial state\n* ...and add the `run()` function in your loop\n* See [SimpleTransitions.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/MixedTransitions/MixedTransitions.ino) for a basic example\n\n### Defining States\n\n* A finite state machine has a defined set of states\n* A state must have a name...\n* ...and can have callback functions for different events (when a state is entered, exited, or stays in a state)\n\n```c++\n  State(\n    String name, \n    CallbackFunction on_enter, \n    CallbackFunction on_state = NULL, \n    CallbackFunction on_exit = NULL, \n    bool is_final = false\n  );\n```\n\n* Most states will have the entry handler\n* The easiest way to define states is creating using an array, e.g. as shown in [MixedTransitions.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/MixedTransitions/MixedTransitions.ino):\n  \n  ```c++\n  State s[] = {\n    State(\"red\",        on_red),\n    State(\"green\",      on_green),\n    State(\"BTN\",        on_button_press)\n  };\n  ```\n\n* The inital state **must** of the state machine must be defined – either via the constructor or the `setup()` function or via the `setInitialState()` function\n* None, one, or multiple states can be defined as an end state via `setAsFinal()`\n* For the full `State` class definition see [State.h](https://github.com/LennartHennigs/SimpleFSM/blob/master/src/State.h)\n\n### Transitions\n\n* This library offers two types of Transitions, regular and timed ones\n* All transitions must have a from and and a to state\n* Transitions can have a callback function for when the transition is executed, a name, and a [guard condition](#guard-conditions)\n* You can add both types to a state machine, see [MixedTransitions.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/MixedTransitions/MixedTransitions.ino) for an example\n* See [Transitions.h](https://github.com/LennartHennigs/SimpleFSM/blob/master/src/Transitions.h) for the class definitions of `Transition` and `TimedTransition`.\n* Note: Both classes are based of an abstract class which is not to be used in your code.\n\n### Regular Transitions\n\n```c++\n  Transition(\n    State* from, \n    State* to, \n    int event_id, \n    CallbackFunction on_run = NULL, \n    String name = \"\", \n    GuardCondition guard = NULL\n  );\n```\n\n* Regular transitions must have a a set of states and a trigger (ID):\n\n  ```c++\n  Transition transitions[] = {\n    Transition(\u0026s[0], \u0026s[1], light_switch_flipped),\n    Transition(\u0026s[1], \u0026s[0], light_switch_flipped)\n  };\n  ```\n\n* Define the triggers for your state machine in an enum (and set the first enum value to 1, to be safe):\n\n  ```c++\n  enum triggers {\n    light_switch_flipped = 1  \n  };\n  ```\n\n* To call a trigger use the `trigger()`function:\n\n  ```c++\n  fsm.trigger(light_switch_flipped);\n  ```\n\n* See [SimpleTransitions.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/SimpleTransitions/SimpleTransitions.ino) and [SimpleTransitionWithButtons.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/SimpleTransitionWithButton/SimpleTransitionWithButton.ino) for more details\n\n### Timed Transitions\n\n```c++\n  TimedTransition(\n    State* from, \n    State* to, \n    int interval, \n    CallbackFunction on_run = NULL, \n    String name = \"\", \n    GuardCondition guard = NULL\n  );\n```\n\n* Timed transitions are automatically executed after a certain amount of time has passed\n* The interval is defined in milliseconds:\n\n  ```c++\n  TimedTransition timedTransitions[] = {\n    TimedTransition(\u0026s[0], \u0026s[1], 6000),\n    TimedTransition(\u0026s[1], \u0026s[0], 4000),\n    TimedTransition(\u0026s[2], \u0026s[1], 2000)\n  };\n  ```\n\n* See [TimedTransitions.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/TimedTransitions/TimedTransitions.ino) for more details\n\n### Guard Conditions\n\n* Guard conditions are evaluated before a transition takes places\n* Only if the guard condition is true the transition will be executed\n* Both regular and timed transitions can have guard conditions\n* You define guard conditions as functions:\n\n  ```c++\n  TimedTransition timedTransitions[] = {\n    TimedTransition(\u0026s[0], \u0026s[1], 1000, NULL, \"\", zero_yet),\n    TimedTransition(\u0026s[0], \u0026s[0], 1000, NULL, \"\", not_zero_yet)\n  };  \n\n  bool not_zero_yet() {\n    return countdown != 0;\n  }\n\n  bool zero_yet() {\n    return countdown == 0;\n  }\n  ```\n\n* See [Guards.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/Guards/Guards.ino) for a complete example\n\n### In-State Interval\n\n* States can have up to three events...\n  * when they enter a state\n  * while they are in a state\n  * ...and when they leave the state\n\n```c++\n  State(String name, CallbackFunction on_enter, CallbackFunction on_state = NULL, CallbackFunction on_exit = NULL, bool is_final = false);\n```\n\n* To define how frequent the `on_state` event is called, pass an interval (in ms) to the `run()` function in your main `loop()`:\n\n  ```c++\n  void run(int interval = 1000, CallbackFunction tick_cb = NULL);\n  ```\n\n* After this interval has passed the `on_state` function of the active state will be called (if it defined)\n* Also the `tick_cb`callback function will be called (if defined) in the `run()` call\n\n### Helper functions\n\n* SimpleFSM provides a few functions to check on the state of the machine:\n\n  ```c++\n    State* getState() const;\n    State* getPreviousState() const;\n    bool isInState(State* state) const;\n    int lastTransitionedAt() const;\n    bool isFinished() const;\n\n  ```\n\n### GraphViz Generation\n\n* Use the function `getDotDefinition()` to get your state machine definition in the GraphViz [dot format](https://www.graphviz.org/doc/info/lang.html)\n* Here the output for the [MixedTransitions.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/MixedTransitions/MixedTransitions.ino) example:\n  \n  ```c++\n    digraph G {\n      rankdir=LR; pad=0.5\n      node [shape=circle fixedsize=true width=1.5];\n      \"red light\" -\u003e \"green light\" [label=\" (6000ms)\"];\n      \"green light\" -\u003e \"red light\" [label=\" (4000ms)\"];\n      \"button pressed\" -\u003e \"green light\" [label=\" (2000ms)\"];\n      \"red light\" -\u003e \"button pressed\" [label=\" (ID=1)\"];\n      \"red light\" [style=filled fontcolor=white fillcolor=black];\n    }\n  ```\n\n* You can use this visualize your state machine:\\\n  ![MixedTransitions.ino example](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/MixedTransitions/MixedTransitions.svg?raw=true)\n\n* If the machine is running, the current state will be highlighted\n* Currently guard functions and end states are not shown in the graph\n* See [MixedTransitionsBrowser.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/MixedTransitionsBrowser/MixedTransitionsBrowser.ino) to learn how to run a webserver to show the Graphviz diagram of your state machine\n\n## Class Definitions\n\n* [State.h](https://github.com/LennartHennigs/SimpleFSM/blob/master/src/State.h)\n* [Transitions.h](https://github.com/LennartHennigs/SimpleFSM/blob/master/src/Transitions.h) for the class definition of both transitions\n* [SimpleFSM](https://github.com/LennartHennigs/SimpleFSM/blob/master/src/SimpleFSM.h)\n\n## Examples\n\n* [SimpleTransitions.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/SimpleTransitions/SimpleTransitions.ino) - only regular transitions and showcasing the different events\n* [SimpleTransitionWithButtons.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/SimpleTransitionWithButton/SimpleTransitionWithButton.ino) - event is now triggered via a hardware button\n* [TimedTransitions.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/TimedTransitions/TimedTransitions.ino) - showcasing timed transitions\n* [MixedTransitions.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/MixedTransitions/MixedTransitions.ino) - regular and timed transitions\n* [MixedTransitionsBrowser.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/MixedTransitionsBrowser/MixedTransitionsBrowser.ino) - creates a webserver to show the Graphviz diagram of the state machine\n* [Guards.ino](https://github.com/LennartHennigs/SimpleFSM/blob/master/examples/Guards/Guards.ino) - showing how to define guard functions\n\n## Notes\n\n* This libary is heavily inspiried by the [Arduino-fsm](https://github.com/jonblack/arduino-fsm) library created by [Jon Black](https://github.com/jonblack). I initally used some of his as a base. Without Jon's work this library would not exist.\n* To see the latest changes to the library please take a look at the [Changelog](https://github.com/LennartHennigs/SimpleFSM/blob/master/CHANGELOG.md).\n* And if you find this library helpful, please consider giving it a star at [GitHub](https://github.com/LennartHennigs/SimpleFSM). Thanks!\n\n## How To Install\n\nOpen the Arduino IDE choose \"Sketch \u003e Include Library\" and search for \"SimpleFSM\".\nOr download the ZIP archive (\u003chttps://github.com/lennarthennigs/SimpleFSM/zipball/master\u003e), and choose \"Sketch \u003e Include Library \u003e Add .ZIP Library...\" and select the downloaded file.\n\n## License\n\nMIT License\n\nCopyright (c) 2023 Lennart Hennigs\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flennarthennigs%2Fsimplefsm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flennarthennigs%2Fsimplefsm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flennarthennigs%2Fsimplefsm/lists"}