¶ Firmware / Embedded
Operating systems, firmware architecture, OTA update mechanism, and security design across all eCozy devices.
¶ At a Glance
| Device | OS / RTOS | SDK / Version | Languages |
|---|---|---|---|
| Thermostat | Zephyr RTOS | nRF Connect SDK 2.9.0 | C++ 17, C, Python |
| Climate Sensor | Zephyr RTOS | nRF Connect SDK 2.9.0 | C++ 17, C |
| Central Unit | Yocto Linux (Kirkstone) | Custom BSP for RPi CM4 | C++ 17, C |
See also: OTA Updates · Security
¶ Thermostat
The thermostat firmware follows a modular architecture built on top of Zephyr RTOS with the nRF Connect SDK.
| Module | Responsibility |
|---|---|
| SensorManager | Temperature & humidity reading (Sensirion SHT40) |
| MotorController | Valve actuation — PWM-driven stepper motor control |
| PID Controller | Closed-loop heating regulation — calculates valve position from ΔT |
| MatterHandler | Matter-over-Thread stack — clusters, attributes, events, commissioning |
| DisplayManager | LCD rendering — current temp, setpoint, status icons |
| ButtonHandler | Physical button input — manual setpoint, reset, commissioning trigger |
| AudioAI | Edge AI sound recognition (fire alarm) via TensorFlow Lite on-device |
| OTA Module | Dual-bank firmware update over Thread network |
| Power Manager | Sleep mode orchestration — deep sleep, idle, wake-on-event |
¶ Climate Sensor
The Climate Sensor runs Zephyr RTOS with nRF Connect SDK. It provides high-precision room readings independently from the thermostat, optimized for multi-year coin-cell operation.
| Module | Responsibility |
|---|---|
| SHT40 Driver | I²C interface to Sensirion SHT40 — temperature & humidity readout |
| MatterHandler | Matter-over-Thread — Temperature & Humidity clusters |
| BLE Commissioning | Bluetooth LE for initial device setup onto Thread network |
| OTA Module | Dual-bank OTA via external MX25R16 flash (QSPI) |
| Power Manager | Deep sleep between measurement intervals; power switch for SHT40 |
| LED / Button | Status indication and factory reset |
| Battery Monitor | ADC-based coin cell voltage measurement |
¶ Central Unit
The Central Unit runs a custom Yocto Kirkstone Linux image on the Raspberry Pi CM4. The software is organized as a set of independent system services that communicate over D-Bus (session bus). The central orchestrator — Business Logic (cubl) — coordinates all services via an event-driven state machine (Startup → Commissioning → Connection → Operational).
| Service | D-Bus Name | Responsibility |
|---|---|---|
| Business Logic (cubl) | — (orchestrator) | State machine, event routing, data flow between all services. SQLite persistence. |
| BLE | org.freedesktop.ble |
BLE commissioning interface — advertises CU, receives Wi-Fi credentials and device config from the app |
| Wi-Fi | org.freedesktop.wifi |
Network manager — AP / Client / Disabled modes, SSID/PSK, IPv4/IPv6 configuration |
| OTC (OpenThread Controller) | org.freedesktop.otc |
Thread mesh configuration — PAN ID, channel, network key, TX power; provides active dataset for Matter |
| Matter Controller | org.freedesktop.matter_controller |
Thermostat/sensor lifecycle — pairing, attribute reads/writes, subscriptions, OTA provider, binding |
| REST Client | org.freedesktop.rest_client |
Cloud sync — login, polling, telemetry upload, room/device config pull, heating predictions |
| Scheduler | org.freedesktop.scheduler |
Heating schedule engine — weekly time-temperature programs, emits target temperature events |
| Heating Predictor | org.freedesktop.heating_predictor |
ML-based pre-heating optimization — computes start times from scenarios and outdoor temperature |
| Indicator | org.freedesktop.indicator |
LED & display — RGB LED patterns, OLED/TFT text rendering, backlight control |
| Buttons | org.freedesktop.buttons |
Physical button input — triggers state transitions (factory reset, pairing mode) |
| Temp Sensor | org.freedesktop.temp_sensor |
On-board SHT40 — local temperature & humidity readings for the CU itself |
Base image: Yocto Kirkstone LTS · Init: systemd · IPC: D-Bus (dbus-c++) · Networking: NetworkManager + wpa_supplicant
¶ OTA Update Mechanism
| Aspect | Edge Devices (Thermostat / Climate Sensor) | Central Unit |
|---|---|---|
| OTA framework | Matter OTA Provider (on Central Unit) | SWUpdate + Eclipse hawkBit |
| Transport | Matter OTA over Thread network | hawkBit DDI API (HTTPS polling) |
| Flash strategy | Dual-bank (A/B) — via external MX25R16 (QSPI, 2 Mbit) | A/B root filesystem partitions (eMMC) via SWUpdate |
| Trigger | Central Unit pushes OTA image to edge devices | hawkBit server assigns deployment → SWUpdate agent pulls SWU image |
| Rollback | Automatic — boots previous bank on validation failure | Automatic — U-Boot bootcount mechanism; falls back to previous partition |
| Integrity | SHA-256 hash + Matter OTA signature | SWU image signed (RSA / ECDSA); verified by SWUpdate before install |
| Downtime | < 30 s (reboot into new bank) | < 60 s (reboot into new rootfs) |
| User notification | LED blink pattern during update | Mobile app status notification via hawkBit feedback channel |
¶ Security Architecture
¶ Device-Level Security
| Layer | Mechanism | Details |
|---|---|---|
| Secure Boot | Hardware root of trust | nRF5340 / nRF52840: Immutable bootloader verifies firmware signature at every boot |
| Firmware Signing | Asymmetric keys (ECDSA) | All OTA images signed; rejected if signature invalid |
| Secure Storage | ARM TrustZone (nRF5340) / KMU | Cryptographic keys stored in hardware key management unit |
| TLS | TLS 1.2+ (Zephyr mbedTLS) | All cloud communication encrypted; certificate pinning on CU |
| Matter Security | CASE / PASE sessions | Device attestation, encrypted sessions, per-fabric credentials |
| Thread Security | Network-layer encryption | AES-128-CCM at MAC layer; Thread Commissioner controls network join |
¶ Central Unit Security
| Layer | Mechanism | Details |
|---|---|---|
| OS Hardening | Read-only rootfs | Yocto image with read-only root partition; writable overlay for config/data |
| Secure Boot | U-Boot verified boot | Signed kernel + device tree; boot aborts if tampered |
| Key Storage | Linux Kernel Keyring / TPM (optional) | Cloud API tokens and device certificates stored securely |
| Network | Firewall (nftables) | Only outbound HTTPS (443) and Thread-local traffic allowed |
| Updates | SWUpdate + hawkBit | RSA/ECDSA-signed SWU images; verified by SWUpdate before flashing |
| Monitoring | Watchdog + health daemon | Automatic reboot on unresponsive state; health metrics to cloud |
¶ Communication Security Summary
| Path | Protocol | Encryption | Auth |
|---|---|---|---|
| Edge ↔ Central Unit | Matter-over-Thread | AES-128-CCM (Thread) + CASE session | Device attestation certificates |
| Central Unit ↔ Cloud | HTTPS / REST | TLS 1.2+ | JWT + device certificate |
| App ↔ Cloud | HTTPS / REST | TLS 1.2+ | JWT (OAuth2) |
| OTA — Edge | Matter OTA over Thread | AES-128-CCM + signed image | Matter OTA signature verification |
| OTA — Central Unit | hawkBit DDI API (HTTPS) | TLS 1.2+ | SWUpdate RSA/ECDSA image signature |
¶ Related Pages
| 🏠 End-to-end System Overview | High-level view of all system layers and how they interconnect. |
| 🔩 Hardware Layer | Device inventory, chipsets, connectivity, and power design. |
| 🧠 Edge AI Layer | On-device machine learning — models, pipeline, and compute constraints. |
| ☁️ Cloud Layer | Backend infrastructure, application architecture, and data storage. |
| 📱 Application Layer | Mobile apps, dashboards, and API integrations. |