SCXML on an ATMega328

Table of Contents

• Hardware Platform
  • Sensors
  • Actuators
• Control Logic
• Resources

This page describes how to use SCXML to model the control flow for an embedded micro-controller. We will transform an SCXML state-chart onto ANSI-C, provide some scaffolding and deploy it onto the Arduino Nano. Regardless of the target platform, the approach is the same if you like to use the ANSI-C transformation for just any other platform.

Hardware Platform

For a project of mine, I used a solar-powered Arduino Nano to control four aquarium pumps to water my balcony plants when their soil is dry. There are some peculiarities that justify to use a state-chart to model the controller's behavior, namely:

1. There is only enough power for one pump at a time
2. Pumps should only run if there is sufficient sunlight
3. The pump related to the sensor with the driest soil below a given threshold should run
4. If a pump runs, it ought to run for a given minimum amount of time

The whole system is powered via a 5W solar module, which is connected via a 12V DCDC converter to another 12V5V DCDC converter, allowing to operate the actuators with 12V and the Arduino with 5V. On the 12V potential, there are some gold caps worth ~150mF to stabilize the potential and provide some kick-off current for a pump to start.

Sensors

In order to measure the soil's moisture, I originally bought those cheap moisture sensors that will measure conductivity between two zinc plated conductors. The problem with these is that they corrode pretty quickly. You can alleviate the problem somewhat by measuring only once every N minutes, but still I disliked the approach.

That's why I went for capacitive sensors with some nice aluminum plates that I can either drop into the water reservoir of my balcony's flower beds or bury at the edge of a bed. Moist soil will cause a higher capacity and we can measure it very easily with two digital pins on the ATMega328: Just set the first pin to HIGH and measure the time it takes for a second pin, connected to the same potential to read HIGH. The longer it took to achieve the HIGH potential on the second pin, the higher the capacity, the more moist the soil.

There is another sensor as a simple voltage divider with 1M Ohm and 100K Ohm to measure the voltage at the solar module. This will allow us only to water plants when the sun is actually shining and with sufficient strength.

Actuators

I connected four 3W aquarium pumps via relais that I supply with 12V from the solar module and control via analog outputs from the Arduino as most digital outputs are taken by the capacitive sensors for the soil's moisture. The pumps are submerged in a 60l tank of water that I have to refill occasionally.

Control Logic

Initially, I developed the system as a pet project but soon realized that I could utilize a state-chart to, more formally, adhere to the requirements above. Here is the SCXML document I wrote:

<scxml datamodel="native" initial="dark" version="1.0">
  <!-- we provide the datamodel inline in the scaffolding -->
  <script><![CDATA[
    pinMode(LED, OUTPUT);
    for (char i = 0; i < 4; ++i) {
      pinMode(pump[i], OUTPUT);
      digitalWrite(pump[i], PUMP_OFF);
      bed[i].set_CS_AutocaL_Millis(0xFFFFFFFF);
    }
  ]]></script>

  <!-- it is too dark to water flowers -->
  <state id="dark">
    <transition event="light" cond="_event->data.light > LIGHT_THRES" target="light" />
    <onentry>
      <script><![CDATA[
        for (char i = 0; i < 4; ++i) {
          digitalWrite(pump[i], PUMP_OFF);
        }
      ]]></script>
    </onentry>
  </state>

  <!-- start to take measurements and activate single pumps if too dry -->
  <state id="light">
    <transition event="light" cond="_event->data.light &lt; LIGHT_THRES" target="dark" />

    <!-- delivers events for all the capsense measurements -->
    <invoke type="capsense" id="cap" />

    <state id="idle">
      <transition event="pump" cond="soil[0] &lt; 0 &amp;&amp;
                                     soil[0] &lt;= soil[1] &amp;&amp;
                                     soil[0] &lt;= soil[2] &amp;&amp;
                                     soil[0] &lt;= soil[3]" target="pump1" />
      <transition event="pump" cond="soil[1] &lt; 0 &amp;&amp;
                                     soil[1] &lt;= soil[0] &amp;&amp;
                                     soil[1] &lt;= soil[2] &amp;&amp;
                                     soil[1] &lt;= soil[3]" target="pump2" />
      <transition event="pump" cond="soil[2] &lt; 0 &amp;&amp;
                                     soil[2] &lt;= soil[0] &amp;&amp;
                                     soil[2] &lt;= soil[1] &amp;&amp;
                                     soil[2] &lt;= soil[3]" target="pump3" />
      <transition event="pump" cond="soil[3] &lt; 0 &amp;&amp;
                                     soil[3] &lt;= soil[0] &amp;&amp;
                                     soil[3] &lt;= soil[1] &amp;&amp;
                                     soil[3] &lt;= soil[2]" target="pump4" />
    </state>
    
    <state id="pumping">
      <transition event="idle" target="idle" />
      <onentry>
        <send delay="8000ms" event="idle" />
      </onentry>

      <state id="pump1">
        <invoke type="pump" id="1" />
      </state>
      <state id="pump2">
        <invoke type="pump" id="2" />
      </state>
      <state id="pump3">
        <invoke type="pump" id="3" />
      </state>
      <state id="pump4">
        <invoke type="pump" id="4" />
      </state>
    </state>
  </state>
</scxml>

There are a few noteworthy things in the SCXML document above:

• Datamodel attribute is `native and no datamodel element is given
  • This will cause the transpilation process to include all datamodel statements and expressions as is in the generated source, without passing them to a user-supplied callback for interpretation.
  • Using this approach, it is no longer possible to interpret the document with the browser.
• We can use identifiers and functions available on the Arduino platform
  • As all expressions and statements will be inserted verbatim into the generated ANSI-C file, and will merely compile it as any other file when we deploy on the Arduino.
• Content of script elements is in CDATA sections while expressions in conditions are escaped
  • We are using the DOMLSSerializer to create a textual representation of the XML DOM and I could not convince it to unescape XML entities when writing the stream.
• We assume a pump and a capsense invoker
  • Indeed, we will not write proper invokers but just mock them in the scaffolding. The important thing is that we get the lifetime management from the SCXML semantics.

When we transform this document via uscxml-transform -tc -i WaterPump.scxml -o stateMachine.c we will arrive at a stateMachine.c file which conforms to the control flow modeled in the SCXML file. Now, we will need to write the scaffolding that connects the callbacks and starts the machine. The complete scaffolding for the generated state machine is given below:

// Resources:
// https://www.avrprogrammers.com/howto/atmega328-power
// https://github.com/PaulStoffregen/CapacitiveSensor
// https://de.wikipedia.org/wiki/Faustformelverfahren_%28Automatisierungstechnik%29
// http://brettbeauregard.com/blog/2011/04/improving-the-beginners-pid-introduction/
// google://SCC3 for conformal coating

#include <LowPower.h> 
#include <CapacitiveSensor.h> 


#define USCXML_NO_HISTORY

#define LED 13                     // LED pin on the Arduino Nano
#define LIGHT A7                   // 1:10 voltage divider soldered into the solar panel
#define LIGHT_THRES 300            // do not actuate beneath this brightness
#define MEASURE_INTERVAL SLEEP_1S  // time between cycles
#define DARK_SLEEP_CYCLES 1

#define PUMP_ON LOW                // Setting an output to LOW will trigger the relais
#define PUMP_OFF HIGH

#define ROLLOFF 0.8                // exponential smoothing for sensor readings

float soil[4] = { 0, 0, 0, 0 };    // smoothed sensor readings from the capacitive sensors
int pump[4] = { A0, A1, A2, A3 };  // we abuse analog pins as digital output
int activePump = -1;

int thrs[4] = { 1400, 1400, 1400, 1400 }; // start pumping below these values

CapacitiveSensor bed[4] = {        // Pins where the capacitive sensors are connected
  CapacitiveSensor(3, 2),
  CapacitiveSensor(5, 4),
  CapacitiveSensor(7, 6),
  CapacitiveSensor(9, 8)
};
char readCapSense = 0;             // Whether the capsense invoker is active

struct data_t {
  int light;
};
struct event_t {
  const char* name;
  struct data_t data;
};

// the various events
long pumpRemain = 0;
struct event_t _eventIdle = {
  name: "idle"
};
struct event_t _eventLight = {
  name: "light"
};
struct event_t _eventPump = {
  name: "pump"
};
struct event_t* _event;

#include "stateMachine.c"

uscxml_ctx ctx;

/* state chart is invoking something */
static int invoke(const uscxml_ctx* ctx,
                  const uscxml_state* s,
                  const uscxml_elem_invoke* invocation,
                  unsigned char uninvoke) {
  if (strcmp(invocation->type, "pump") == 0) {
    int pumpId = atoi(invocation->id);
    digitalWrite(pump[pumpId], uninvoke == 0 ? PUMP_ON : PUMP_OFF);
  } else if (strcmp(invocation->type, "capsense") == 0) {
    readCapSense = uninvoke;
  }
}

/* is the event matching */
static int matched(const uscxml_ctx* ctx,
                   const uscxml_transition* transition,
                   const void* event) {
  // we ignore most event name matching rules here
  return strcmp(transition->event, ((const struct event_t*)event)->name) == 0;
}

static int send(const uscxml_ctx* ctx, const uscxml_elem_send* send) {
  if (send->delay > 0)
    pumpRemain = send->delay;
  return USCXML_ERR_OK;
}

static void* dequeueExternal(const uscxml_ctx* ctx) {
  // we will only call step when we have an event
  void* tmp = _event;
  _event = NULL;
  return tmp;
}

static bool isInState(const char* stateId) {
  for (size_t i = 0; i < ctx.machine->nr_states; i++) {
    if (ctx.machine->states[i].name &&
            strcmp(ctx.machine->states[i].name, stateId) == 0 &&
            BIT_HAS(i, ctx.config)) {
      return true;
    }
  }

  return false;
}

void setup() {
  // initilize the state chart
  memset(&ctx, 0, sizeof(uscxml_ctx));
  ctx.machine = &USCXML_MACHINE;
  ctx.invoke = invoke;
  ctx.is_matched = matched;
  ctx.dequeue_external = dequeueExternal;
  ctx.exec_content_send = send;

  int err = USCXML_ERR_OK;

  // run until first stable config
  while((err = uscxml_step(&ctx)) != USCXML_ERR_IDLE) {}
}


void loop() {
  digitalWrite(LED, HIGH);

  int err = USCXML_ERR_OK;

  if (readCapSense) {
    // capsense invoker is active
    for (int i = 0; i < 4; ++i) {
      int cap = bed[i].capacitiveSensor(50);
      if (cap > 0) {
        soil[i] = ROLLOFF * soil[i] + (1 - ROLLOFF) * (cap - thrs[i]);
      }
    }
  }

  _eventLight.data.light = analogRead(LIGHT);
  _event = &_eventLight;
  while((err = uscxml_step(&ctx)) != USCXML_ERR_IDLE) {}

  if (isInState("dark")) {
    LowPower.powerDown(MEASURE_INTERVAL, ADC_OFF, BOD_OFF);
    return;
  }

  if (isInState("light")) {
    if (false) {
    } else if (isInState("pumping")) {
      // is time elapsed already?
      if (pumpRemain == 0) {
        _event = &_eventIdle;
        while((err = uscxml_step(&ctx)) != USCXML_ERR_IDLE) {}
      }
    } else if (isInState("idle")) {
      // check is we need to pump
      _event = &_eventPump;
      while((err = uscxml_step(&ctx)) != USCXML_ERR_IDLE) {}
    }
  }

  pumpRemain = (pumpRemain >= 8000) ? pumpRemain - 8000 : 0;

  digitalWrite(LED, LOW);
  LowPower.powerDown(MEASURE_INTERVAL, ADC_OFF, BOD_OFF);

}

To integrate the scaffolding and the control logic from the state-chart, the generated stateMachine.c is merely included into the compilation unit. To compile it all, I am using PlatformIO IDE as it is more convenient to work with multifile projects as apposed to the Arduino IDE, but both will work. It is important, not to compile stateMachine.c as a distinct compilation unit, but only as part of the scaffolding. If you have any problems to exclude it from the build process, you may always rename it into something without a .c extension.

The scaffolding is rather minimal and somewhat unorthodox as I tried to get away without using malloc for dynamic memory allocations, but keep everything on the stack. Let's walk through the individual lines:

• First we include the header files for LowPower and CapacitiveSensor. With PlatformIO, you will have to copy them into your lib directory along with their respective implementations.
• Then we declare some macros that define constant values. Noteworthy is the USCXML_NO_HISTORY macro which causes the generated ANSI-C to drop a block of code for processing history elements, which we do not use.
• Afterwards, we declare and define variables. We could have them as part of a datamodel element in the original SCXML document, but in my opinion, defining them here makes their existence more explicit.
• It is noteworthy that we do enumerate all the events we are going to pass and will not implement an actual queue of events. A proper queue would require malloc and there will never be more than one event to consider per microstep.
• In line 62, we include the generated ANSI-C stateMachine and define a context, as it is required to represent the state of a state-chart.
• Then we define the callbacks that we later connect to the state-chart's context:
  • invoke will be called whenever an invocation is to be started or stopped at the end of a macro-step. This is where we merely remember whether we are supposed to start a pump (type pump) or deliver sensor readings from the capacitive sensors (type capsense).
  • matched is called to determine whether a given transition's event descriptor is matched by a given event and a concept explained in more detail in the SCXML recommendation. In this implementation, we ignore the finer points of event descriptor matching and only match, when the event's name is a literal match for the transition's event. attribute
  • send: When we start a pump, we are sending a delayed event to ourselves which we will have to deliver back into the state-chart after the given time in milliseconds passed. We just remember the current delay in pumpRemain and, subsequently, decrease it until we reach the timeout and have to deliver it.
  • dequeueExternal: Whenever the interpreter is in a stable configuration, it makes an attempt to dequeue an external event, which will cause this callback to be triggered. If we return an event, it will be processed by triggering transitions and a change in the configuration, if we return NULL, the state-chart will IDLE.
  • isInState is not formally a callback to be registered by the context but very useful to dispatch upon the configuration of the state chart later.
• In setup, we initialize the state of the platform after the reset button is pressed or the power came back on. I.e. we connect the callbacks and initialize the state chart by proceeding to the first IDLE interpreter state.
• In loop we process one cycle of the controller. We turn the LED on to indicate that we are processing and read the capacitive sensors if the invoker is active. Then we read the amount of light that arrives at the solar module via the voltage divider connected to LIGHT and transition accordingly. Afterwards we check if it is time to send the eventual idle event to turn of the pumps or check if we ought to activate a pump.

One thing that helped me when developing the scaffolding was to thing about the configuration the state chart would eventually be in and observe the various events it would react to. Then to make sure that these events would be delivered when they are relevant.

Resources

The resources required when deploying this program on the ATMega328 are given as follows:

Program:   10534 bytes (32.1% Full)
(.text + .data + .bootloader)

Data:       1636 bytes (79.9% Full)
(.data + .bss + .noinit)

There are still quite some possibilities to reduce these resources some more if we are pressed on space:

• Event and invoker names can be enumerated
• We can drop some unused callbacks from the uscxm_ctx struct
• We can remove most fields of the uscxml_elem_send struct