cool Arduino Serial State Machine

A serial device driven state machine for all arduino boards: cool Arduino Serial State Machine (coolASSM).

Introduction

This is a state machine for any arduino board that can be driven via sending commands over a serial console connection. The commands are common to the know one's as: PING, PONG, ACKN, RUN, WAIT, STOP, DONE. .., and so. Arduino is going to switch between states then, like: IDLE, MODE1, MODE2, .., MODE7, or even ERROR.

The project itself shall be extended by including own code or methods to several call back methods that are cylic driven by each different state.

Building

For building the HEX file, the arduino Makefile is used. Clone or download / unzip this first to your system and configure the Makefile by your local path where you have cloned / unzipped. Change in Makefile to your arduino board and type: make && make upload.

Usage

After start up arduino has nine STATES available:

• ERROR - arduino swtches from all other states, turn permanently (predefined) LED 13 on, and processes code of method: error(),
• IDLNG - arduino switches from ERROR and all other MODEs, and is idling, does a heartbeat blinking on LED 13, and processes code of method: idle(),
• MODE1 - arduino switches from IDLE and all other MODEs, blinks rapidly, and processes code of method: runMODE1(),
• MODE2 - arduino switches from IDLE and all other MODEs, blinks rapidly, and processes code of method: runMODE2(),
• MODE3 - arduino switches from IDLE and all other MODEs, blinks rapidly, and processes code of method: runMODE3(),
• MODE4 - arduino switches from IDLE and all other MODEs, blinks rapidly, and processes code of method: runMODE4(),
• MODE5 - arduino switches from IDLE and all other MODEs, blinks rapidly, and processes code of method: runMODE5(),
• MODE6 - arduino switches from IDLE and all other MODEs, blinks rapidly, and processes code of method: runMODE6(),
• MODE7 - arduino switches from IDLE and all other MODEs, blinks rapidly, and processes code of method: runMODE7().

To switch between theses STATEs, COMMANDs are sent to arduino. Theses COMMANDs follow an XML like syntax: <CMD_ID>.

The COMMANDS are:

• <0> NULL - the null command is driven internally by arduino itself,
• <1> SNA - State Not Available; sent arduino in ERROR state,
• <2> PING - is replied by PONG and let arduino from ERROR to IDLE state,
• <3> PONG - is replied by PING and let arduino from ERROR to IDLE state,
• <4> AKNW - may be sent to arduino as an notifier; optionally,
• <5> RUN - may be sent to arduino to start any run MODE; optionally,
• <6> WAIT - may arduino reply while it is processing data in a loop; optionally,
• <7> EVENT - may be sent to arduino to request some data processing; optionally,
• <8> DONE - may be sent as notifier of finishing a data processing; optionally,
• <9> STOP - is sent to arduino to return from any run MODE to IDLE state,
• <10> STATUS - is always replied by the current state of arduino,
• <11> run MODE1 - go from ANY state to this run MODE1, if not in ERROR state,
• <12> run MODE2 - go from ANY state to this run MODE2, if not in ERROR state,
• <13> run MODE3 - go from ANY state to this run MODE3, if not in ERROR state,
• <14> run MODE4 - go from ANY state to this run MODE4, if not in ERROR state,
• <15> run MODE5 - go from ANY state to this run MODE5, if not in ERROR state,
• <16> run MODE6 - go from ANY state to this run MODE6, if not in ERROR state,
• <17> run MODE7 - go from ANY state to this run MODE7, if not in ERROR state,
• <18> CNCT - may be used to establish a connection; optionally,
• <19> DCNT - may be used to release a connection; optionally.

Theses COMMANDs are sent by their ID to arduino**. However, arduino will not reply by an ID, arduino will reply instead by an - regular - XML syntax:

• For single replys, arduino uses single / empty XML tags <CMD_STR/>,
• For data replys, arduino may use XML tags <CMD_STR>data</CMD_STR>; optionally.

The COMMANDS for talking to HARDWARE are:

• <40> A0 - may be used for analog input reading data,
• <41> A1 - may be used for analog input reading data,
• <42> A2 - may be used for analog input reading data,
• <43> A3 - may be used for analog input reading data,
• <44> A4 - may be used for analog input reading data,
• <45> A5 - may be used for analog input reading data.

and for reading digital pins:

• <60> GPIO0 - may be used for digital input reading data,
• <61> GPIO1 - may be used for digital input reading data,
• <62> GPIO2 - may be used for digital input reading data,
• <63> GPIO3 - may be used for digital input reading data,
• <64> GPIO4 - may be used for digital input reading data,
• <65> GPIO5 - may be used for digital input reading data,
• <66> GPIO6 - may be used for digital input reading data,
• <67> GPIO7 - may be used for digital input reading data,
• <68> GPIO8 - may be used for digital input reading data,
• <69> GPIO9 - may be used for digital input reading data,
• <70> GPIO10 - may be used for digital input reading data,
• <71> GPIO12 - may be used for digital input reading data,
• <72> GPIO12 - may be used for digital input reading data,
• <73> GPIO13 - may be used for digital input reading data,

All replies of arduino to your client can be directly processed as XML; e.g. in python.

Examples look like:

• Single / empty XML reply: a sent <10> to arduino, will be replied by its state, e.g. <IDLNG/>, <MODE1/>, or <MODE2/>
• and content / data XML replys may be implemented like:
  • standard: <A0> 23.72 </A0>,
  • standard: <GPIO7> 1 </GPIO7>,
  • individual: <DATA> 1.2;3.4;5.6 </DATA>,
  • individual: <INFO> sensor A0: is broke </INFO>,
  • individual: <LOG> system voltage: 5.783 </LOG>,
  • individual: <MSG> 0700 - good morning </MSG>.

Theses content / data based replies are held fully independent; those are not predefined. You can individually implemented such by extending the class ASSM, overloading the virtual methods up to all STATEs.

However, in current version only reading from arduino is available.

Example

For an example, run_MODE7() is generating and sending some dummy data after processing. You can challenge arduino to process and responded - try:

• flash / boot arduino out of the box with coolASSM.ino,
• start arduino IDE and press: SHFT + CTRL + m to open serial monitor,
  • be sure you have the right port and the correct baudrate.
• Type into the serial monitor:
  • <17>, to tell arduino to go to STATE: run MODE7:
    • arduino will start processing and reply with an: <AKNW/>.
  • <7>, to sent an EVNT (event) to arduino:
    • arduino will reply with an: <AKNW/>, and start processing:
      • sents each second for three times a: <WAIT/> to you,
      • and afterwards the result: <DATA> 1.2;3.4;5.6 </DATA>.
  • <9>, to tell arduino to go back to state IDLNG and blinks a heartbeat:
    • arduino will start processing and reply with an: <AKNW/>.

Retrieving data & individual commands

For retrieving data / content / logs / messages / .. /, you can use the following predefined methods on arduino, while extending class ASSM:

• writeData( String, tag, String data, int digits, int, precision )
• arduino sends: <tag/>data</tag>; ready XML.

For retrieving individual COMMANDs for adapting those on your client side, you can use the following predefiend method:

• writeCommand( Str str ),
• arduino sends: <str/>; ready XML.

Releases

The following stable releases of coolASSM are available:

• V1.2 - added defines for analog & digital pins, optimized COMMANDS, STATEs, and writeData methods.
• v1.1 - cleaned and better readable code; no DEBUG_DISPLAY messages.
• v1 - keeping configurable DEBUG_DISPLAY messages,

Try cloning (git checkout <SHA>) or download and unzip from release page.

Remarks

I use this project as a basis for sensor applications; e.g. see: ASSTCP.

On client side I use the mirrow project: cool Python Serial State Machine (coolPSSM) to implement the processing of retrieved data / content / logs / messages / .. / from arduino; the project is still ongoing.

Everything was coded using:

• atom editor,
• arduino Makefile for automated building,
• arduino IDE for serial monitor,
• Gnome as window manager,
• and debian GNU/Linux.

have fun :-)

ChangeLog

20230518

• updating the copyright by year ..

20200404

• added defines for hardware:
  • all analog pins; are named: ASSM_HARD_ANLG{ 0, 1, .., 5 }:
    • IDs are: { 40, 41, .., 45 }; doin' leetspeak,
    • STRINGs are: { A0, A1, .., A5 }; doin' leetspeak,
  • all digital pins; are named: ASSM_HARD_GPIO{ 0, 1, .., 13 }
  • IDs are: { 60, 61, .., 73 }; doin' leetspeak,
  • STRINGs are: { GPIO0, GPIO1, .., GPIO13 }; doin' leetspeak,
• optimzed STATEs - always five letters for STATEs:
  • IDLE is renamed to IDLNG
  • RNMDx are renamed to RMD{ 0, 1, .., 7 }
• optimzed COMMANDs - always less than five lettes:
  • EVENT is renamed to EVNT
  • STATUS are renamed to STAT
• optimized writeData methods:
  • available for all data types: bool, int, float, double, String,
  • always sending full XML TAGs like:
    • as standard: <A0>23.72</A0>,
    • or as standard: <GPIO7>23.72</GPIO7>,
    • as individual: <DATA>1.2;3.4;5.6</DATA>.
• cleaned and commented code ..

20200403

• extending the README,
• added version v0.9, v1.0, v1.1 and linked release page.

20200402

• add light up and flashing of arduino's built in LED on PIN 13:
  • in ERROR state it will light up permanently,
  • in IDLE state it will do a heartbeat:
    • with a duration of 60 bpm,
    • that let arduino do a general delay of a full second.
  • in ALL run MODE states:
    • it will flash rapidly by 10 milliseconds,
    • that let arduino do a general delay of 20 milliseonds in total.
• added COMMANDs:
  • RNMD1, RNMD2, RNMD3, RNMD4, RNMD5, RNMD6, RNMD7,
  • equivalent IDs are: 11, 12, 13, 14, 15, 15, 16, 17.
• added STATEs:
  • MODE1, MODE2, MODE3, MODE4, MODE5, MODE6, MODE7,
  • equivalent IDs are: 11, 12, 13, 14, 15, 15, 16, 17.
• STATE running with ID 3 is deprecated,
• changed COMMAND CONNECT:
  • to name CNCT,
  • and ID to 18.
• changed COMMAND DISCONNECT:
  • to DCNT,
  • and ID tp 19.

20200331

• reset the public and private methods,
• renamed files to coolASSM_config.*,
• adding MIT License to all files.

20200330

• adding class ASSM_CALLBACK for having virtual methods to be overloaded

20200329:

• removing and cleaning OLED display code,
• adding the README.md for explanation,
• setting up reository on github.com.