feat(docs): Add comprehensive README for STM32U585 console project

Author: elkanamol

README.md

@@ -0,0 +1,165 @@
+# 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](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](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):
+
+```bash
+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):
+
+```bash
+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):
+
+```bash
+source ../.venv/bin/activate
+export PATH="$HOME/.local/share/gem/ruby/3.2.0/bin:$PATH"
+ceedling test:all
+```
+
+Generate coverage (clean run recommended):
+
+```bash
+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:
+
+```bash
+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](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.