Skip to content

Architecture

How the driver is built: three layers, one call through them and the choices behind them.

Layer diagram: your application calls the FDO2 core, which sends register reads and writes through the UART port contract to the port class you write, which drives the chip; the core and the contract are the same on every MCU.Layer diagram: your application calls the FDO2 core, which sends register reads and writes through the UART port contract to the port class you write, which drives the chip; the core and the contract are the same on every MCU.
The layers, one of them yours
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

One call through the layers: your code calls MeasureOxygen(), the core exchanges frames with the chip through your port and returns the result to your code.One call through the layers: your code calls MeasureOxygen(), the core exchanges frames with the chip through your port and returns the result to your code.
One call through the layers
Figure description and sources

Participants, left to right: Your code, FDO2 and Your port. The steps run from top to bottom. Your code sends MeasureOxygen() to FDO2. FDO2 sends FlushInput() to Your port. FDO2 sends Write("#MOXY") to Your port. A note over FDO2 and Your port says: Repeat until CR or deadline. FDO2 sends Read(buffer, max, timeout) to Your port. Your port returns n bytes to FDO2. A note over FDO2 and Your port says: End of the repeated steps. A note over FDO2 says: assemble the line, check CRC, parse. A note over FDO2 says: status policy, plausibility windows. FDO2 returns Result to Your code.

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 an Error; nothing throws.
  • No heap, no exceptions, no RTTI, no std::function, no printf. 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.