Architecture¶
How the driver is built: three layers, one call through them and the choices behind them.
Figure description and sources
Top to bottom, each arrow is a call. Your application calls one object, whose public calls are listed from the umbrella header in inc/. The core turns each call into register reads and writes and hands them to the port contract (the CRTP base in inc/*_interface.hpp), which forwards them, at compile time, to the hooks of the port class you write; your port moves the bytes on the bus. The notes on the right say which layers stay the same on every MCU and which one you write. A library without a port contract has only the first two layers.
Drawn from: inc/fdo2.hpp public calls; inc/fdo2_uart_interface.hpp UartInterface; figure module docs/diagrams/figures/driver-layers.py.
Layers¶
| Layer | Files | Owns |
|---|---|---|
| Core | inc/fdo2.hpp, src/fdo2.ipp |
Lifecycle, the state machine, measurements, calibration, settings, retries, errors |
| Protocol | inc/fdo2_protocol.hpp |
CRC-16, command encoding, the line assembler and the reply parser |
| Types | inc/fdo2_types.hpp, inc/fdo2_detail.hpp |
Error, Result<T>, Config, Status, conversions, compile-time helpers |
| Port contract | inc/fdo2_uart_interface.hpp |
The CRTP base, CtrlPin, GpioSignal, the UartPort concept |
| Platform port | Your class | The UART, and optionally the clock, delay, baud rate, supply switch and log |
| Kconfig layer | inc/fdo2_kconfig.hpp |
Optional: a Config from ESP-IDF menuconfig |
The protocol layer has no state and no port: the tests drive it alone.
One call through the layers¶
Figure description and sources
Participants, left to right: Your code, FDO2
Drawn from: docs/model/one-call-through-the-layers.seq.yml.
Design choices¶
- CRTP, not virtual functions. The port is a template parameter constrained by a concept, so every call is resolved at compile time and a missing hook is a compile error that names it.
- One state machine, two ways to drive it. The blocking calls are the start call plus a loop over
Poll()with the port's delay, so both paths run the same code (Non-blocking use). - A parser that only reads. It returns a value or a reason; the core decides what to do about it.
- Flash writes are guarded. Opt-in, a budget, never repeated (Calibration).
- One error type.
Result<T>carries a value and anError; nothing throws. - No heap, no exceptions, no RTTI, no
std::function, noprintf. The driver is a header-only template with no mutable static state.
Source map¶
| You want | Read |
|---|---|
| The public API | inc/fdo2.hpp |
| How a call is implemented | src/fdo2.ipp |
| The command and reply grammar | inc/fdo2_protocol.hpp |
| The port contract | inc/fdo2_uart_interface.hpp |
Next: Contract.