Skip to content

Figures

Every figure on this site is drawn by a Python module from facts extracted from the code, so it is rebuilt, not redrawn, when the code changes. CI runs kokeb-docs figures --check and fails when a committed figure no longer matches the code. Each figure below lists the files it is drawn from.

Inside the FDO2

Block diagram of the FDO2: its function blocks, how they connect and which package pins reach each block.Block diagram of the FDO2: its function blocks, how they connect and which package pins reach each block.
Inside the FDO2
Figure description and sources

The FDO2's function blocks inside its outline. Arrows between blocks carry signals or data in the direction they point (both ways where they have two heads). The package pins stand on the left and right edges with their numbers, each wired to the block it reaches.

Drawn from: docs/hardware.yml; inc/fdo2_uart_interface.hpp.

Hardware description: docs/hardware.yml

Drawn from:

FDO2: Direct connection to a 3.3-volt controller

Schematic of the FDO2 direct connection to a 3.3-volt controller: the chip with U2 MCU (3.3 V), C1 capacitor 100 nF; the MCU wires carry the port hooks GpioSet(CtrlPin::Power), Read(), Write().Schematic of the FDO2 direct connection to a 3.3-volt controller: the chip with U2 MCU (3.3 V), C1 capacitor 100 nF; the MCU wires carry the port hooks GpioSet(CtrlPin::Power), Read(), Write().
FDO2: Direct connection to a 3.3-volt controller
Figure description and sources

A schematic. The MCU is on the left, each of its pins level with the chip pin it connects to; above each wire is the hook of the driver's port that drives or reads it. Supply pins point up to their supply and decoupling, ground pins down. Pins on the right carry the loads and the pins tied to a supply or ground; a cross marks a pin left open. A dot is a junction; wires that cross without a dot are not connected.

Drawn from: docs/hardware.yml; inc/fdo2_uart_interface.hpp.

Hardware description: docs/hardware.yml

Drawn from:

FDO2: Connection to a 5-volt controller through a divider

Schematic of the FDO2 connection to a 5-volt controller through a divider: the chip with U2 MCU (5 V), R1 resistor 10 kΩ, R2 resistor 12 kΩ, C1 capacitor 100 nF; the MCU wires carry the port hooks GpioSet(CtrlPin::Power), Read(), Write().Schematic of the FDO2 connection to a 5-volt controller through a divider: the chip with U2 MCU (5 V), R1 resistor 10 kΩ, R2 resistor 12 kΩ, C1 capacitor 100 nF; the MCU wires carry the port hooks GpioSet(CtrlPin::Power), Read(), Write().
FDO2: Connection to a 5-volt controller through a divider
Figure description and sources

A schematic. The MCU is on the left, each of its pins level with the chip pin it connects to; above each wire is the hook of the driver's port that drives or reads it. Supply pins point up to their supply and decoupling, ground pins down. Pins on the right carry the loads and the pins tied to a supply or ground; a cross marks a pin left open. A dot is a junction; wires that cross without a dot are not connected.

Drawn from: docs/hardware.yml; inc/fdo2_uart_interface.hpp.

Hardware description: docs/hardware.yml

Drawn from:

FDO2 package, Module, 4-pin

Outline of the FDO2 in Module, 4-pin drawn to scale from above: body 28.5 x 28.5 x 27.5 mm, 4 pins.Outline of the FDO2 in Module, 4-pin drawn to scale from above: body 28.5 x 28.5 x 27.5 mm, 4 pins.
FDO2 package, Module, 4-pin
Figure description and sources

The FDO2 package seen from the top and, when the height is known, from the side, drawn to scale: 28.5 x 28.5 x 27.5 mm. The arrows carry the datasheet's dimensions, the dot marks pin 1 and the pads are numbered counter-clockwise from it, coloured by the pin's electrical type (legend below). Pads sit centred on each side, evenly spaced; the datasheet's land pattern is the reference for a board.

Drawn from: docs/hardware.yml; inc/fdo2_uart_interface.hpp.

Hardware description: docs/hardware.yml

Drawn from:

FDO2 pinout, Module, 4-pin

Pinout of the FDO2 in Module, 4-pin, top view: 4 pins, each with its name, its electrical type as a colour and the driver hook that uses it.Pinout of the FDO2 in Module, 4-pin, top view: 4 pins, each with its name, its electrical type as a colour and the driver hook that uses it.
FDO2 pinout, Module, 4-pin
Figure description and sources

The FDO2 seen from the top, in its Module, 4-pin package. Pin 1 is marked by the dot; the numbers run counter-clockwise from it. Each pad is coloured by the pin's electrical type (legend below). Next to it is the pin's name and, in mono, the hook of the driver's port that drives or reads it; a pin without a hook is not used by the driver.

Drawn from: docs/hardware.yml; inc/fdo2_uart_interface.hpp.

Hardware description: docs/hardware.yml

Drawn from:

The layers, one of them yours

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.

Figure module: docs/diagrams/figures/driver-layers.py

Drawn from:

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.

Hardware description: docs/model/one-call-through-the-layers.seq.yml

Drawn from:

The driver's states

State diagram of fdo2::FDO2: Uninitialized, PoweringUp, Idle, Waiting, Streaming, Draining and StateUnknown, with the calls and events that move between them.State diagram of fdo2::FDO2: Uninitialized, PoweringUp, Idle, Waiting, Streaming, Draining and StateUnknown, with the calls and events that move between them.
The driver's states
Figure description and sources

Each box is a State of fdo2::FDO2, read from the enumeration in inc/fdo2_types.hpp; each arrow is a call or an event that moves it. Start-up goes through PoweringUp to Idle. An operation (Start* or a blocking call) puts the driver in Waiting; a good reply returns it to Idle. A timeout, a CRC error or a refused line sends it through Draining, where input is discarded until the line is quiet, so a late reply is never read as the next answer. A flash-writing command or a baud change that ended without a confirmed echo leaves StateUnknown, which only Resync() or a power cycle ends. While the module streams, Idle is reported as Streaming. The transitions are fixed in this figure and checked against the names used in src/fdo2.ipp.

Drawn from: inc/fdo2_types.hpp State; src/fdo2.ipp State transitions; figure module docs/diagrams/figures/state-machine.py.

Figure module: docs/diagrams/figures/state-machine.py

Drawn from:

One command and its reply

Five steps of a transaction: flush the receive buffer, write the command, wait for the module, read the echo and values, end at the carriage return; the allowance of each kind of command is listed under the wait.Five steps of a transaction: flush the receive buffer, write the command, wait for the module, read the echo and values, end at the carriage return; the allowance of each kind of command is listed under the wait.
One command and its reply
Figure description and sources

A transaction is five steps, left to right. The driver drops what is in the receive buffer, writes the command and its carriage return, then waits for the module: the module echoes the command, with its values, and ends the reply with one carriage return. The wait is the characters' airtime at the current baud rate, plus the module's processing allowance for the command (command_ms, measurement_ms, calibration_ms, flash_ms or logo_ms of the Config), plus margin_ms. The numbers shown are the Config defaults, read from inc/fdo2_types.hpp. A reply that does not end in time is a Timeout: the driver drains the line, and sends an idempotent read again when retries allow.

Drawn from: inc/fdo2_types.hpp Config; figure module docs/diagrams/figures/transaction-timing.py.

Figure module: docs/diagrams/figures/transaction-timing.py

Drawn from: