More › tutorial-board

More

Tutorial: a greenhouse on a real board

This tutorial takes one small product from its requirements to its measured behaviour on a real board. The product is a greenhouse thermostat: a sensor reads the air, and a fan runs when the air is too hot. The board is an ST NUCLEO-F446RE. You will write nothing by hand: the model gives the firmware, the tests and the measurements.

The whole example is in examples/greenhouse. Plan under an hour, most of it for the wiring and the first build.

What has been run, and where: the model's tests in the simulator, and the firmware in Renode, an emulator of the board's chip. The run on a real board is yours: board.sh is ready for it, but it has not been run on hardware yet.

1. What to buy#

Part Why About
ST NUCLEO-F446RE the board: an STM32F446RE with its programmer (ST-LINK) on the same USB cable 15 €
A BME280 breakout, 3.3 V the sensor: temperature (and humidity, pressure) on I²C 5 €
A 1-channel 5 V relay module, "high level trigger" switches the fan. Many modules have an H/L jumper: set it to H 3 €
A small 5 V fan (under 200 mA) what the relay runs 3 €
A USB cable (mini-B on most NUCLEO-64 boards), jumper wires

A relay module that closes on a low level ("low level trigger") also works, but the fan then runs when it should not: set its jumper to H, or buy one with a high-level input.

2. Wiring#

The NUCLEO-F446RE has an Arduino header. The model says where each part is wired, so the firmware and the wiring agree.

Board pin STM32 pin Part pin
3V3 — BME280 VIN (or VCC)
GND — BME280 GND
D15 (SCL) PB8 BME280 SCL
D14 (SDA) PB9 BME280 SDA
5V — relay VCC
GND — relay GND
D7 PA8 relay IN
5V — relay COM
— — relay NO → fan red (+)
GND — fan black (−)

Power the BME280 from 3V3, not 5V. The board's 5 V comes from its USB cable: plug the USB into the ST-LINK side of the board (the top, with the USB socket).

3. Install#

You need archec (this repository, or npm install -g arche-lang), Rust, and probe-rs to flash the board.

curl https://sh.rustup.rs -sSf | sh            # Rust, if you have not got it
rustup target add thumbv7em-none-eabihf         # the board's Cortex-M4F
brew install probe-rs-tools                     # macOS; elsewhere: https://probe.rs

On Linux, probe-rs needs a udev rule to reach the ST-LINK without root (its site has the file). Renode is optional, to run the firmware without the board: take its portable package from renode.io.

4. The model, piece by piece#

Open examples/greenhouse/main.arche. It is about 130 lines, in five parts.

What it must do#

Three requirements, written plainly. REQ-SAFE also has a formal property, so the model checker can prove it and archec replay can check it on a trace.

requirement REQ-FAN "Fan on when hot" {
  text "The fan shall start within 1 s when the air is above 28 °C."
}
requirement REQ-STOP "Fan off when cool" {
  text "The fan shall stop within 1 s when the air is below 26 °C, once it has run 10 s."
}
requirement REQ-SAFE "No short cycling" {
  text "Once started, the fan shall run at least 10 s."
  formal "ctl in Starting leads to ctl in Cooling within 11s"
}

The gap between 26 °C and 28 °C is the hysteresis: near one threshold, the fan does not switch on and off at every reading.

What it does#

Two parts. The sampler reads the air every 500 ms and sends it on. It reads a TemperatureSensor, not a BME280: what the sensor does, from arche-hw-store/sensors.arche. Changing the sensor is then one line.

message AIR "Air reading" {
  period 500ms
  temperature: Temperature
}

component AirSampler "Air sampler" {
  out sensor: requires TemperatureSensor
  out air:    data sends AIR
  fn sample "Read the air" {
    ```arche
    send air AIR { temperature: sensor.temperature() }
    ```
    wcet 60ms
  }
}

The controller is a state machine. Each reading may move it: above 28 °C the fan starts, below 26 °C it stops. Starting lasts 10 s whatever the air does, which is REQ-SAFE.

component FanControl "Fan control" {
  in air:  data receives AIR { depth 4 }
  out fan: requires Relay
  states {
    state Idle "Fan off" {
      on-enter ```arche
        fan.off()
      ```
    }
    state Starting "Fan on, its first 10 s" {
      on-enter ```arche
        fan.on()
      ```
    }
    state Cooling "Fan on"
    Idle -> Starting on AIR [temperature > 28.0]
    Starting -> Cooling on "after 10s"
    Cooling -> Idle on AIR [temperature < 26.0]
  }
}

A guard reads the message's fields by name: temperature is the reading's.

What it is made of#

One system holds the board, the two devices of the store and the two parts. Its links are the wiring of section 2: the BME280 on the board's I2C1, the relay on PA8. They also say which device each part uses.

system Greenhouse "Greenhouse" {
  part board:   NucleoF446RE
  part sensor:  Bme280 { in temperature_sensor: provides TemperatureSensor { noise 0.05°C } }
  part relay:   GpioRelay { in pin { pins { pin PA8 } } }
  part sampler: AirSampler
  part ctl:     FanControl
  board.i2c1 -> sensor.i2c
  sampler.sensor -> sensor.temperature_sensor
  sampler.air -> ctl.air
  ctl.fan -> relay.relay
}
Diagram: Greenhouse
What archec draws from this code: Greenhouse

Most breakouts answer at 0x77, as the store says. Some cheap ones answer at 0x76: write part sensor: Bme280 { inout i2c { address 0x76 } … } for those.

Where it runs#

The deployment puts both parts in one firmware on the board. The sampler's thread is the more urgent one. The chain gives REQ-FAN's 1 s to the path from a reading to the fan.

deployment OnBoard "On the NUCLEO" {
  system Greenhouse
  platform Greenhouse
  binary firmware on board {
    thread sense "Sense" { runs sampler; period 500ms; step sample; priority 2 }
    thread control "Control" { runs ctl; priority 1; queue 4; wcet 1ms }
  }
  chain reaction "From a reading to the fan" { through sampler, ctl; budget 1s }
}
Diagram: On the NUCLEO
What archec draws from this code: On the NUCLEO

How it is checked#

Four test cases set the sensor's reading and look at the relay. The simulator runs them; Renode runs the same cases on the real firmware.

test-plan TP-GREENHOUSE "Greenhouse" {
  case TC-FAN "Hot air starts the fan within 1 s" {
    verifies REQ-FAN
    at 1s expect not relay.closed
    at 2s do sensor.temperature = 31
    within 1s expect relay.closed
  }
}

5. Simulate#

cd examples/greenhouse
archec check main.arche
archec test main.arche --sim web
archec analyze main.arche

archec test --sim web runs the four cases in the simulator, where the BME280 reads 21 °C until a case warms it. All four pass. archec analyze adds up the worst case of the reaction: up to 500 ms before the next reading sees the heat, then 60 ms to read, then the controller. That is 621 ms, inside the 1 s budget.

archec verify main.arche proves REQ-SAFE with NuSMV, when it is installed. Without it, it says "not checked", and archec verify --conflicts still checks the requirements can hold together.

6. Emulate in Renode#

./board.sh --renode

This builds the firmware and runs it in Renode, on its model of the STM32F4, with its model of the BME280. The air is 21 °C, then 31 °C at 5 s, then 22 °C at 25 s. What the firmware writes on its UART is recorded, then measured. The firmware's first line says which build it is, and board.sh checks it before it measures anything:

✓ build 79bbe5250c9e, commit 3f2a1c9b0d: the firmware is this model's

This is what a run printed:

Threads              n      period (jitter)        response min / avg / p99 / max
  sense              79     500ms (0ns)            42.115ms / 42.118ms / 42.178ms / 42.178ms
  control            80     493.67ms (499.462ms)   37us / 54.788us / 73us / 73us
Chain reaction "From a reading to the fan": 79 × min 42.151ms avg 42.157ms max 42.215ms
  predicted worst case 621ms, budget 1s  ok

  ✓ REQ-FAN   the fan started 1 time(s), the first at +5.0 s, 104 µs after a reading of 31.0 °C. archec timing: reading → fan 42 ms at most (79 readings), budget 1 s ✓. simulator ✓ (TC-FAN, TC-BAND)
  ✓ REQ-STOP  the fan stopped at +25.0 s, 106 µs after a reading of 22.0 °C. simulator ✓ (TC-STOP, TC-BAND)
  ✓ REQ-SAFE  the fan ran 20.0 s (at least 10 s). archec replay: ✓. simulator ✓ (TC-SAFE)
✓ Renode: everything the run showed held

The 42 ms is the BME280 measuring: it takes about 40 ms each time it is asked. Renode's times are the emulator's, not the board's: the board's own numbers come in the next section.

archec gen main.arche --target renode also writes a Robot suite of the four test cases, for renode-test.

7. Flash and measure on the board#

Plug the board in, then:

./board.sh

It checks that the board's ST-LINK answers, and stops at once if it does not. Then it builds the firmware and flashes it with probe-rs. It records what the firmware writes on the ST-LINK's virtual COM port for 60 s. ./board.sh 120 records for longer.

Two seconds after the reset, it reads the first line the board wrote: the build the firmware is (arche-trace 0 build <fingerprint> <commit>). When it is not this model's, the flash did not take, or another firmware started: board.sh stops there with the board runs an older build: rebuild and flash, before you warm anything. archec status main.arche --build build/board/firmware.trace asks the same question of any trace.

When it says so, warm the BME280 with your hand or a hair dryer until it passes 28 °C. The fan starts. Then let it cool below 26 °C: once the fan has run 10 s, it stops. The line under the prompt shows each reading and the fan as they come.

8. Read the verdict#

At the end, board.sh runs archec timing and archec replay on the trace and prints one line per requirement:

  • ✓: the run showed it, and it held. REQ-FAN gives how long after the hot reading the fan started, and the reaction's worst case measured by archec timing against its 1 s budget.
  • –: the run did not show it. For example, the air never passed 28 °C: warm the sensor more and run again.
  • ✗: it did not hold, and the line says when. A SENSOR line means the BME280 did not answer: check its four wires and its address.

Everything is kept in build/board/ (build/renode/ for Renode): the trace (firmware.trace), the timing and replay results in JSON and JUnit, and the verdict. archec timing and archec replay also record their results in the project, with where they ran (ARCHE_BOARD, ARCHE_EVIDENCE_PLACE), the build the firmware said it was, and the firmware's hash. archec status main.arche shows them per requirement, with the highest rung each one reached:

REQ-SAFE  No short cycling
  highest rung  renode (sim ✓, renode ✓, board –)

The three rungs in one command#

Sections 5, 6 and 7 are the rungs of a ladder. One command climbs it and stops at the first rung that fails:

archec test main.arche --ladder                     # the simulator, then Renode
archec test main.arche --ladder --board 0483:374b   # then the board, flashed
  ✓ sim     4 case(s) passed on the browser simulator
  ✓ renode  board.sh --renode held (212 s)
  – board   skipped: no --board <probe> (this rung flashes the board: it runs only when asked)
✓ ladder: held up to renode

It runs board.sh for the two upper rungs. The board rung runs only with --board: its value is the probe as probe-rs list names it (VID:PID[:serial]), or any name when one board is plugged in. A tool that is not installed is a rung skipped, not failed. See the test ladder.

When you fix a bug#

Write the test that shows the bug, fix the model, then prove the test catches it. It must fail on the build before the fix and pass on yours:

archec test main.arche --against HEAD

See a test that proves a fix.

9. What each piece became#

  • archec gen --target embassy --trace wrote a Rust crate (Embassy). sensor.temperature() calls the BME280's driver, and fan.on() the relay's. The state machine runs as the model writes it: guards, on-enter, the 10 s timer.
  • With --trace, the firmware writes arche-trace lines on USART2 at 115200 baud: each thread's start and end, each message, each state entered, each reading (in thousandths: value sensor.temperature 28410 is 28.41 °C). Its first line is the build: the model's fingerprint and the git commit. It is about 60 KB of flash with the trace, 29 KB without.
  • archec timing compares the measured times with the model's wcet, periods and budget. archec replay checks the requirements' formal properties and the message periods on the same trace.

From here, change the model and run board.sh again. For example, try 30 °C instead of 28 °C, or a DS18B20 instead of the BME280 (one part line, once the store has its Rust driver).