lembed / awesome-arduino Goto Github PK

Hello!

I have just created awesome-ws2812, a curated list of awesome resources for ws2812 LED strips and matrices controlled using Arduino.

Just wanted to let you know so you can add it to your list if you think it's appropriate.

Cheers!

state machines generators

the state machine is generated on compiletime

• SCXML format ("statechart XML format") (wikipedia) (w3c) - hierarchical state machines, parallel state machines, ... should be feature-complete for most use cases. the state machines are declared in XML, which can be compiled to efficient C or C++ code
  • https://github.com/shuvalov-mdb/xstate-cpp-generator - generate C++ code from scxml spec, implemented in javascript (hackable!)
  • https://doc.qt.io/qt-5/qscxmlc.html - Qt SCXML Compiler - generate C++ code from scxml spec
  • https://github.com/jp-embedded/scxmlcc - generate C++ code from scxml spec
    • more-or-less abandoned (or stable) since year 2019
  • https://github.com/tklab-tud/uscxml#for-transformations - generate C++ code from scxml spec
    • last push in year 2019 = abandoned project with serious bugs, for example tklab-tud/uscxml#179 (fixed in alexzhornyak's fork)
    • http://tklab-tud.github.io/uscxml/embedded.html SCXML on an ATMega328
• statechart format. based on protobuf (the "protocol buffers" binary protocol), not XML. ancestor of scxml
  • https://github.com/google/statechart in c++
  • https://github.com/AlexandreDecan/sismic - Statechart Model Interpreter and Checker
  • https://github.com/cmars/statechart - statecharts in rust
• https://github.com/jonasblixt/ufsm - generate C code from xml spec (custom format, not scxml)

state machine interpreters

the state machine is generated on runtime

• https://doc.qt.io/qt-5/qtscxml-index.html - both interpreter and compiler
• https://github.com/zen747/scm - scxml in C++. only runtime interpreter, no code generator
• https://github.com/BehaviorTree/BehaviorTree.CPP - custom XML format

state machine theory

• https://stackoverflow.com/questions/133214/is-there-a-typical-state-machine-implementation-pattern

event driven programming

aka: reactive programming, non-blocking code, parallel computing, async code, embedded operating systems, parallel state machines

• https://github.com/igormiktor/arduino-EventManager [already listed in Awesome-arduino] EventManager is a single C++ class that provides an event handling system for Arduino. With EventManager you can register functions that "listen" for particular events and when things happen you can "post" events to EventManager. You then use the loop() function to regularly tell EventManager to process events and the appropriate listeners will be called.
• https://github.com/mikaelpatel/Cosa - Cosa is an object-oriented platform for Arduino. It replaces the Arduino and Wiring library with a large set of integrated classes that support the full range of AVR/ATmega/ATtiny internal hardware modules ... Cosa supports several programming paradigms including Multi-Tasking, Event Driven Programming and UML Capsules/Actors.
• https://github.com/tinkerspy/Automaton/wiki - Reactive State Machine Framework for Arduino. The Automaton framework allows you to create Arduino applications that consist entirely of concurrently running components (finite state machines) interacting with one another. Changes are automatically propagated through the application like changes in a spreadsheet. Encourages modular design and separation of concerns
• https://github.com/johnnyb/Eventually - make a more event-oriented environment for Arduino programming. To make it actually easy to use to build worthwhile projects.
• https://github.com/kmilo17pet/QuarkTS - operating system that provides a modern environment to build stable and predictable event-driven multitasking embedded software. Due to its size and features, is intended to play in the space between RTOSes and bare-metal. QuarkTS was written for embedded developers who want more functionality than what existing task schedulers offer, but want to avoid the space and complexity of a full RTOS, keeping the taste of a robust and safe one.
• https://github.com/QuantumLeaps/qpc - "quantum leap" real-time embedded framework/RTOS for embedded systems based on active objects (actors) and hierarchical state machines
  • https://github.com/QuantumLeaps/qpcpp
  • Event-Driven Arduino Programming with QP™-nano and QM™ - "Luckily, generations of programmers before you have discovered an effective way of solving the “spaghetti” code problem. The solution is based on the concept of a state machine, or actually a set of collaborating state machines that preserve the context from one event to the next using the concept of state. This QP™-nano framework described in the next section allows you to combine the event-driven programming paradigm with modern state machines."
  • event-driven arduino programming
• https://en.wikipedia.org/wiki/Event-driven_finite-state_machine
• https://arduino.stackexchange.com/questions/18072/event-driven-programming
  • http://blog.ardublock.com/2013/10/29/evaluating-of-event-driven-libraries-on-arduino/

visual simulators

edit the state machine as text file, and get a graphical simulation

• SCXML format
  • https://github.com/statelyai/xstate-viz (live demo) - state machine visualizer / simulator, runs in the browser
  • https://github.com/statelyai/xstate#hierarchical-nested-state-machines in javascript
    • useful to implement graphical state machine editors (visual programming)
    • can be used to implement C++ code generators
      • https://github.com/shuvalov-mdb/xstate-cpp-generator
    • https://github.com/darrylhebbes/awesome_xstate

visual editors

• https://github.com/fmorbini/scxmlgui
• visual editor in Qt Creator
• QM™ Graphical Modeling Tool - QM™ (Quantum Modeler) is a free, cross-platform, graphical modeling tool for designing and implementing real-time embedded applications based on the QP™ state machine frameworks. ... QM™ eliminates coding errors by automatic generation of compact C or C++ code that is 100% traceable from your design.

specify state machines in c++

these solutions are rather verbose = more work

• https://github.com/tinkerspy/Automaton - focus on arduino [already listed in Awesome-arduino]
• https://github.com/kiprasmel/xstate-cpp - "scxml" in C++. new project. not-yet import from scxml
• https://github.com/boost-ext/sml
• https://github.com/digint/tinyfsm
• https://github.com/andrew-gresyk/HFSM2 High-Performance Hierarchical Finite State Machine
• https://github.com/kiishor/UML-State-Machine-in-C
• https://github.com/tinverse/tsm

related

• https://stackoverflow.com/questions/1793511/is-there-a-programming-language-with-built-in-state-machine-construct
• https://github.com/topics/hierarchical-state-machine

motivation: why string parsing?
in some cases, we want a custom text-based protocol,
which is easy for both humans and machines

as human, i do not want to type

{"cmd":"some_command","args":["arg1","arg2"]}

instead, i want to say

some_command arg1 arg2

challenges on arduino:

• low memory usage
• reading from serial port should be non-blocking

sample code can be run on a normal computer (no arduino)

single character parsers

as seen in many discussions on "arduino remote control via serial port"

// parse-char.cpp
// gcc parse-char.cpp -o parse-char && ./parse-char

#include <stdio.h> // printf, fgetc

int main() {
  char rc;
  while (true) {
    // arduino: read char with Serial.read()
    rc = fgetc(stdin); // read char from stdin (terminal)
    switch (rc) {
      case 'x':
        printf("received x -> exit\n");
        return 0;
        break;
      case '\n':
        printf("received \\n -> ignore\n");
        break;
      default:
        printf("received %c -> unknown command\n", rc);
    }
  }
}

as seen in

• https://arduining.com/2015/05/04/serial-control-of-arduino-led/
• ...

simple string parsers

use strcmp or strncmp to compare strings

as seen in

• kroimon/Arduino-SerialCommand
  • https://awtfy.com/2011/05/23/a-minimal-arduino-library-for-processing-serial-commands/
• https://forum.arduino.cc/t/parsing-serial-commands-programs-string-stuff/176213

// parse-string.cpp
// gcc parse-string.cpp -o parse-string && ./parse-string

#include <stdio.h>
#include <string.h>

const char* expectedString = "hello";

int main() {

  // arduino: get actualString with Serial.read()
  const char* actualString = "hello";

  printf("actualString = %s\n", actualString);
  printf("expectedString = %s\n", expectedString);

  if (strcmp(actualString, expectedString) == 0) {
    printf("found expected string\n");
  }

}

parsing variable strings

commands are constant strings, but we also want to parse variables

sample input:

set some_key 1234

https://forum.arduino.cc/t/how-to-parse-multiple-variables-in-one-string/582456 - strtok, atoi, atof

https://forum.arduino.cc/t/serial-input-basics-updated/382007/3

void parseData() {      // split the data into its parts

    char * strtokIndx; // this is used by strtok() as an index

    strtokIndx = strtok(tempChars,",");      // get the first part - the string
    strcpy(messageFromPC, strtokIndx); // copy it to messageFromPC
 
    strtokIndx = strtok(NULL, ","); // this continues where the previous call left off
    integerFromPC = atoi(strtokIndx);     // convert this part to an integer

    strtokIndx = strtok(NULL, ",");
    floatFromPC = atof(strtokIndx);     // convert this part to a float

}

runtime-generated string parsers

the commands are declared at runtime, in the arduino setup() function

as seen in

• billroy/bitlash with strcmp - a programmable command shell for arduino
• ppedro74/Arduino-SerialCommands with strcmp
• miko007/SerialTerminal with strcmp in c++

concept:

void handleCommandHello(char** argv, int argc) {
  // process arguments ...
  // sample input: "hello world"
  // -> argc == 2
  // -> argv[0] == "hello"
  // -> argv[1] == "world"
}

// global variable
Parser* parser;

void setup() {
  parser = new Parser();
  parser->addCommand("hello", &handleCommandHello);
}

the lookup from command name to handler function can be realized in different ways:

• strcmp, strncmp → simple string parsers
• search trees
• hashtables

compiletime-generated string parsers

• write custom grammar
• generate lexer
• generate parser

a "lexer" reads an input string and generates a list of tokens
a "parser" reads a list of tokens and generates a structure / syntax tree

with compiletime-generated string parsers,
commands and handlers are declared at compile time,
so the runtime can be optimized for lower memory usage

in most cases, this is a micro-optimization, aka "a waste of time" (lets do it anyway!)

as seen in

• Using byacc+Ragel for memory efficient parsers
• Parsing mathematical expressions with Ragel and Lemon
  • lemon is a modern version of byacc, maintained as a part of SQLite
  • slideshow: Generating parsers using Ragel and Lemon
  • https://github.com/tristanpenman/microcalc - A parser for simple arithmetic expressions, implemented in C++ using Lemon and Ragel

tree parsers

aka: lisp, scheme, ...

Greenspun's Tenth Rule of Programming:

any sufficiently complicated C or Fortran program
contains an ad hoc informally-specified bug-ridden slow implementation
of half of Common Lisp.

trees are encoded as lists of strings

• http://www.ulisp.com/ - uLisp® is a version of the Lisp programming language specifically designed to run on microcontrollers with a limited amount of RAM
• https://github.com/geekscape/aiko_engine#lisp_repl

note: in the context of lisp interpreters,
"embedded" usually means "a lisp interpreter, embedded into a non-lisp programming language"

sample input:

(addTimer PERIOD COUNT)
(debug)
(load)
(save)
(wifi (SSID PASSWORD))

related

ThingML plugins

thingML allows us to write plugins to parse (and serialize) custom text-based protocols

https://heads-project.github.io/methodology/heads_methodology/thingml_plugins.html

Proprietary systems:

In many cases, a ThingML component will have to communicate
with external closed-source components,
whose implementation cannot be modified.

In this case, the only option is to adapt the ThingML end,
both in terms of encoding and transport.

Serialization plugins are in charge of generating
both the serialization and parsing of a set of ThingML messages.

Note that serialization and parsing are not necessarily perfect mirrors,
as ports can be asymmetrical.

ThingML provides a default binary and string-based (JSON) serialization and deserialization,
available and interoperable in C, JavaScript and Java.

• ThingML: A Language and Code Generation Framework for Heterogeneous Targets → page 7, 4.3 Serialization Plugins / Encoding
• ArduinoSensor.thingml = example with binary protocol, similar to "single character parsers"

document parser versus stream parser

• document parsers: produce one large syntax-tree
• stream parsers: produce many small events

finite state machines

FSM are usually

• hand-made for simple machines
• generated for complex machines

FSM can be used for string lexing and parsing,
but FSM can also be used to implement full arduino programs (manage state, handle events)

• thingML - Code Generation Framework
  • https://github.com/ffleurey/ThingMLArduinoDemo - ThingML is a high-level language based on components, asynchronous messaging and finate state machines. Despite a high level of abstraction, ThingML includes a code generator which is suitable for Arduino as well as other flavors of 8 bits microcontrollers.
  • https://github.com/ffleurey/ThingML-PressureLogger
• ragel
  • example: params.rl
  • https://www.avrfreaks.net/forum/codec-parsing-strings-flexiblyefficiently-ragel
  • https://www.avrfreaks.net/forum/codec-parsing-json-based-config-file-using-micro-memory-ragel - json parser in ragel
  • https://knzl.at/parser-generators-embedded/
  • https://www.slideshare.net/tristanpenman/generating-parsers-using-ragel-and-lemon
  • http://thingsaaronmade.com/blog/a-simple-intro-to-writing-a-lexer-with-ragel.html
  • https://github.com/sebknzl/byacc-ragel - using ragel with cmake
  • https://github.com/gsauthof/cmake-ragel - using ragel with cmake
  • https://github.com/maikeru/tag_parser - sample input:
    • tag.1=value1 tag.2="value with spaces" a_different_tag=stuff tag
  • https://github.com/cHemingway/CommandParser - sample input:
    • fish = "haddock"
    • crabs = 12
    • SET CHANNEL NAME='CHN 1'
    • GET CHANNEL NAME
• smc
• stateforge
• tinyfsm
• ... and many more

G-code parser

tgolla/GCodeParser - a hand-written parser (not generated from grammar) → category: compiletime-generated string parsers

what is G-code?

A typical piece of G-code as sent to a RepRap machine might look like this:

N3 T0*57
N4 G92 E0*67
N5 G28*22
N6 G1 F1500.0*82
N7 G1 X2.0 Y2.0 F3000.0*85
N8 G1 X3.0 Y3.0*33

full access to arduino via serial port

useful in development, not in production
in production, we want to give only limited access to the microcontroller

https://github.com/monsonite/SIMPL - category: single character parsers

serial-port-json-server

expose the arduino's serial port on a web server, to allow acces from a web browser
https://github.com/chilipeppr/serial-port-json-server

Locoduino/Commanders

string parser. obscure. what is the actual protocol?

https://github.com/Locoduino/Commanders/blob/master/examples/SerialCommander/SerialCommander.ino

binary protocols

firmata binary protocol

https://github.com/firmata/protocol
https://github.com/firmata/arduino

Firmata [protocol] is based on the midi message format in that
commands bytes are 8 bits and data bytes are 7 bits.

For example the midi Channel Pressure (Command: 0xD0) message is 2 bytes long,
in Firmata the Command 0xD0 is used to enable reporting for a digital port (collection of 8 pins).
Both the midi and Firmata versions are 2 bytes long

string libraries

• https://www.best-microcontroller-projects.com/arduino-string.html - a safe, robust and debuggable replacement for string processing in Arduino

non-blocking serial communication

https://arduino.stackexchange.com/a/22516/80923 Nick Gammon - reading serial without blocking

https://www.forward.com.au/pfod/ArduinoProgramming/Serial_IO/index.html

ALL output methods, i.e. the Serial.print and Serial.write methods,
will stop the rest of you sketch from running once the Serial Tx buffer fills up.

The size of the Tx buffer varies between different Arduino boards.
Uno/Meg2560 has a 63 byte Tx buffer. The NanoBLE has none.

So if you want the rest of your sketch to keep running
while you output results or debugging messages,
you should not use any of the Serial print/write methods in your loop() code.

This tutorial will show you how to use the BufferedOuput class
to avoid blocking, add extra buffering.

automatic compiletime-generated string parsers

http://swig.org/ - SWIG is typically used to parse C/C++ interfaces and generate the 'glue code' required for the above target languages to call into the C/C++ code.

problem: swig can not generate purely text-based interfaces, aka "shell code"

related: string parsing on web servers

in the context of web servers, this problem is known as "routing"
the web client requests a "route" like /somedir/index.php?q=somequery
and the web server will lookup the request handler

https://github.com/julienschmidt/httprouter