| name | rust-embedded-iot-guide |
| description | Use when building Rust embedded systems, IoT devices, or bare-metal firmware (ARM Cortex-M, RISC-V, ESP32). Covers no_std architecture, PAC/HAL layering, RTIC/Embassy async, linker script control, power management, and hardware debugging. Vertical deepening of rust-architecture-guide for microcontroller targets. |
| metadata | {"version":"1.0.0","philosophy":"Mechanical Sympathy, Determinism, Minimalism, Jeet Kune Do","domain":"embedded systems & IoT","relationship":"vertical-deepening-of:rust-architecture-guide","default_edition":"2024","supported_editions":["2021","2024"],"aligned_with":["embedded-hal traits","RTIC framework","Embassy async","Cortex-M RTFM"],"note":"ESP-IDF Rust (std + FreeRTOS) requires a separate vertical guide; this guide covers bare-metal no_std targets only."} |
Rust Embedded & IoT Guide V1.0.0
Vertical deepening of rust-architecture-guide for bare-metal and RTOS-based embedded systems. Assumes constrained hardware (KB of RAM, MHz of clock), no operating system, real-time deadlines.
Core Philosophy
| Principle | Description |
|---|
| Mechanical Sympathy | Code directly maps to MMIO registers — no kernel, no syscall, no page table |
| Determinism | Every instruction cycle is accounted for; interrupt latency is bounded and measured |
| Minimalism | no_std by default; alloc is a luxury decision; every byte of .bss is audited |
| Jeet Kune Do | One-strike power cycles; flash-friendly data structures; DMA as the ultimate zero-copy |
Action 1: no_std Architecture & Crate Layering
Embedded Rust code has no std. The architecture follows a strict five-layer abstraction:
Application → BSP (Board Support) → HAL → PAC → Cortex-M/RISC-V Core
- PAC (Peripheral Access Crate): Auto-generated from SVD via
svd2rust. Unsafe MMIO.
- HAL: Implements
embedded-hal traits. Safe API over PAC. Hardware-agnostic.
- BSP: Board-specific pin assignments, clock trees, peripheral configuration.
- Red Line: Application code must never directly touch PAC registers.
→ references/01-no-std-architecture.md
Action 2: Memory Layout & Linker Script Control
In bare-metal, there is no OS to set up .bss/.data. You must:
- Define
memory.x linker script: FLASH origin/length, RAM origin/length
- Implement
pre_init in assembly: copy .data to RAM, zero .bss
- Audit stack usage per function (
cargo-call-stack)
- Red Line: Stack overflow in embedded = undefined behavior. Must use
flip-link or MPU stack guard.
→ references/02-memory-layout.md
Action 3: Interrupt-Driven Concurrency
No threads. No std::sync. Concurrency is interrupt-driven.
- RTIC (Real-Time Interrupt-driven Concurrency): Static priority ceiling protocol, deadlock-free by construction
- Embassy: Async executor on bare-metal.
#[embassy_executor::task], await on DMA completion
- Red Line: Prohibit busy-waiting (
loop { if flag {} }). Use interrupt or WFI/WFE.
- Red Line: Unsynchronized shared mutable
static mut is UB. Use CriticalSection, RTIC resource locks, portable-atomic, or static_cell patterns.
→ references/03-concurrency.md
Action 4: Peripheral Driver Development
Every peripheral is a state machine with hardware-backed constraints.
- SPI/I2C/UART: Implement
embedded-hal traits. Use DMA for bulk transfers.
- GPIO: Input/Floating/PullUp/PullDown/Analog/AlternateFunction — typed state machine.
- ADC/DAC: Calibration, sampling rate, DMA double-buffering.
- Timer/PWM: Capture/compare, dead-time insertion for motor control.
- Red Line: Prohibit bypassing HAL to write raw registers outside PAC crate.
→ references/04-peripheral-drivers.md
Action 5: Power Management & Battery Life
Every µA matters for battery-powered devices.
- Sleep/Deep-Sleep/Standby state machine. Wake sources: RTC, external interrupt, WDT.
- Clock gating: disable unused peripheral clocks. Dynamic frequency scaling.
- Red Line: Must measure actual current draw with power profiler (not simulator). Define a product-specific sleep budget based on MCU/board/radio requirements; the <10µA figure is typical for ultra-low-power designs but varies by hardware.
→ references/05-power-management.md
Action 6: Hardware Debugging & Observability
No println! to console. Debugging requires hardware tools.
- probe-rs / OpenOCD + GDB: Flash, debug, RTT (Real-Time Transfer) channels
- defmt: Binary-efficient logging framework (strings are interned, not transmitted)
- ITM/SWO: ARM CoreSight trace for performance profiling
- Logic analyzer: Protocol-level debugging for SPI/I2C/UART timing violations
- Red Line: Release builds must strip debug symbols. Measure binary size after
objcopy.
→ references/06-debugging.md
Action 7: Build System & Toolchain
rust-toolchain.toml: Pin nightly/stable, target (thumbv7em-none-eabi, riscv32imac-unknown-none-elf)cargo-embed / cargo-flash for consistent flashingcargo-generate templates for project scaffolding- Red Line: Never compile embedded project without target-specific
rust-toolchain.toml
→ references/07-toolchain.md
Action 8: Testing on Hardware
Unit tests on host (cargo test --target x86_64), integration on target.
defmt-test: Test harness that runs on hardware- Hardware-in-the-loop (HIL): Automate flash → run → check RTT output
cargo-modules: Audit module graph for PAC leakage- Red Line: Critical safety paths (motor control, medical) must pass HIL tests on real hardware
→ references/08-testing.md
Prohibitions Quick List
| Category | Prohibited | Mandatory |
|---|
| Standard Library | use std::* | #![no_std] + optional extern crate alloc |
| Dynamic Allocation | Box, Vec without allocator | Static buffers, heapless collections |
| Main Function | fn main() | #[entry] or #[cortex_m_rt::entry] |
| Threading | std::thread, tokio::spawn | RTIC tasks or Embassy async |
| Shared State | static mut | CriticalSection, RTIC resource locks |
| Busy-Wait | loop { if flag {} } | WFI/WFE, interrupt-driven wake |
| Stack Overflow | Unaudited recursion/deep frames | flip-link, MPU stack guard, cargo-call-stack |
| Debug Logging | println!, log crate | defmt / RTT |
| Raw Registers | Direct write_volatile in app | PAC → HAL → BSP abstraction |
| Unmeasured Power | Guess-based optimization | Power profiler with µA measurement |
| Release Symbols | Debug info in release | strip = true, opt-level = "z" |
Document Relationship Map
flowchart TD
subgraph Foundation["rust-architecture-guide"]
P0[P0 Safety]
P1[P1 Maintainability]
end
subgraph Embedded["rust-embedded-iot-guide"]
NoStd[01-no-std-architecture.md]
Memory[02-memory-layout.md]
Concurrency[03-concurrency.md]
Periph[04-peripheral-drivers.md]
Power[05-power-management.md]
Debug[06-debugging.md]
Toolchain[07-toolchain.md]
Testing[08-testing.md]
end
P0 -->|hardens| NoStd
P0 -->|hardens| Memory
P1 -->|adapts| Periph
NoStd --> Concurrency
Periph --> Power
Memory --> Debug
Debug --> Testing
style NoStd fill:#d9534f,stroke:#c9302c,color:#fff
style Memory fill:#5cb85c,stroke:#4cae4c,color:#fff
style Concurrency fill:#f0ad4e,stroke:#ec971f,color:#000
Reference Files
| File | Topic | Key Directive |
|---|
| 01-no-std-architecture.md | no_std Architecture & Crate Layering | PAC→HAL→BSP→App five-layer model |
| 02-memory-layout.md | Memory Layout & Linker Scripts | memory.x, stack audit, flip-link |
| 03-concurrency.md | Interrupt-Driven Concurrency | RTIC priority ceiling, Embassy async |
| 04-peripheral-drivers.md | Peripheral Driver Development | SPI/I2C/UART/GPIO/ADC typed state machines |
| 05-power-management.md | Power Management | Sleep states, clock gating, battery budget |
| 06-debugging.md | Hardware Debugging | probe-rs, defmt, RTT, ITM/SWO |
| 07-toolchain.md | Build System & Toolchain | rust-toolchain.toml, cargo-embed, templates |
| 08-testing.md | Testing on Hardware | defmt-test, HIL, hardware-in-the-loop CI |
Changelog
V1.0.0
- Initial framework: no_std architecture, memory layout, RTIC/Embassy concurrency
- Peripheral driver development with
embedded-hal traits
- Power management, hardware debugging, toolchain, and HIL testing
- Aligned with rust-architecture-guide V9.1.0 as parent constitution
