elkanamol/console — STM32U585 Multi-Threaded Sensor Console

Short project summary

Manual-control Zephyr RTOS console for STM32U585 (BlackPill), featuring Zbus message bus, supervisor FSM, SSD1306 OLED display thread, and diagnostic sensor monitoring. See docs/DESIGN_DES.md for full architecture and task roadmap.

---

Overview

Phase 1: Manual button/shell control (OFF ↔ ACTIVE ↔ SLEEP)

• Zbus message bus for thread coordination
• Supervisor FSM for state transitions
• SSD1306 OLED display thread: updates automatically in ACTIVE, manual override via shell
• Internal/external sensor reads (BME280, MPU6050, ADC)
• All state transitions are user-initiated (button/shell)

See docs/DESIGN_DES.md for details.

Features

This project is a Zephyr RTOS application for STM32U585 that provides:

• USB CDC ACM shell console
• Interrupt-driven button handling with software debounce
• LED auto-blink timer that runs independently of shell activity
• Internal sensor reads via Zephyr sensor API (temperature, VREF, VBAT)
• External I2C sensor reads (BME280, MPU6050)
• Periodic sensor sampling via a dedicated work queue

Code organization (key directories):

• src/app: application state + pure app logic
• src/sensors: internal/external sensor modules
• src/shell: shell commands + shell parsing logic
• src/hal: Zephyr HAL wrappers used for host-side unit testing

Requirements

• STM32U585 board (BlackPill STM32U585CI or compatible)
• Zephyr SDK/toolchain for firmware build + flash
• Python virtual environment at ../.venv
• Ruby + Ceedling for host-side unit tests
• gcovr (Python package) for coverage reports

Building and Running

Firmware build / flash (example):

source ../.venv/bin/activate
# Build
west build -p always -b blackpill_u585ci -d build/console
# Flash (after successful build)
west flash -d build/console

Shell connection (example):

minicom -D /dev/ttyACM0 -b 115200

VS Code tasks are available for common workflows (build/flash/monitor/test).

Shell Commands

Display commands

• display on — turn the SSD1306 OLED on (ACTIVE only)
• display off — turn the display off
• display write "text" — write a single line to the display
• display status — show display state

LED commands

• led on
• led off
• led toggle

Button commands

• button info — show button stats
• button reset — reset button counters

Sensor commands

• sensor temp — read internal temperature
• sensor vref — read internal VREF
• sensor vbat — read VBAT
• sensor all — show latest environmental data
• sensor bme280 — read external BME280
• sensor mpu6050 — read external MPU6050

Notes on display behavior

• The display thread subscribes to sensor data and display commands.
• In ACTIVE mode the display updates automatically on new sensor data (data-driven).
• In OFF and SLEEP the display remains off; display on can force it on for diagnostics.
• Manual display commands override rendering but do not change the system FSM state.

TDD Methodology (Current)

Development follows Red → Green → Refactor with Ceedling + Unity + CMock:

1. Add failing unit test(s)
2. Implement smallest production change
3. Refactor while tests remain green
4. Run ceedling test:all
5. Run Zephyr firmware build to prevent regressions

Unit Testing and Coverage

Run unit tests (host-side Ceedling):

source ../.venv/bin/activate
export PATH="$HOME/.local/share/gem/ruby/3.2.0/bin:$PATH"
ceedling test:all

Generate coverage (clean run recommended):

source ../.venv/bin/activate
export PATH="$HOME/.local/share/gem/ruby/3.2.0/bin:$PATH"
ceedling clobber
ceedling gcov:all

Optional: produce full HTML/XML report:

ceedling gcov:all report:gcov

Note: coverage generation can take several minutes; results are printed to the runner console.

CI

GitHub Actions workflow: .github/workflows/ceedling-ci.yml

• Runs ceedling test:all
• Runs ceedling gcov:all
• Coverage is emitted to runner logs (no CI artifact upload)

Project Status

Phase 1 is focused on manual control (OFF ↔ ACTIVE ↔ SLEEP). Current highlights:

• Zbus and message definitions: ✅
• Central sensor thread (BME280 + MPU6050) and I2C mutex: ✅
• Supervisor FSM (button-driven): ✅
• Display thread (SSD1306): ✅ (data-driven updates in ACTIVE; manual override via shell)
• Internal ADC sensors (temp, VREF, VBAT): partial — next task (TG 4.4)

See docs/DESIGN_DES.md for full task order and future Phase 2/3 work (IMU interrupts, GPS).

Project Notes

• Internal sensor readings are intended for diagnostics, not precision calibration.
• LED auto-blink starts at boot (500 ms period).
• Button debounce window is 50 ms.
• Periodic sampling runs through Zephyr work queue infrastructure.