Architecture¶
How the driver is built: three layers, one of them yours, and what happens in each when you change a pin.
Datasheet sections this page relies on
From NXP PCAL9555A Rev. 2:
- Register pairs, pointer toggling and burst transfers: 7 Bus transactions; 7.1 Writing to the port registers; 7.2 Reading the port registers, p. 14
All of them, with the driver API for each: Datasheet map.
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/pcal9555.hpp public calls; inc/pcal9555_i2c_interface.hpp I2cInterface; figure module docs/diagrams/figures/driver-layers.py.
Layers¶
| Layer | Files | Owns |
|---|---|---|
| Core | inc/pcal9555.hpp, src/pcal9555.ipp |
Lifecycle, the copy of the registers, presence and identity checks, write order, errors |
| Types and registers | inc/pcal9555_types.hpp, inc/pcal9555_registers.hpp |
Error, Result<T>, Config, Validate(), pin helpers; the register map |
| Port contract | inc/pcal9555_i2c_interface.hpp |
The CRTP base, the I2cPort concept, the register framing |
| Platform port | Your class | Bus bring-up and byte transfers, optionally logging |
| Kconfig layer | inc/pcal9555_kconfig.hpp |
Optional: a Config from ESP-IDF menuconfig |
One call through the layers¶
sequenceDiagram
participant App as Your code
participant Core as PCAL9555<Port>
participant Port as Your port
App->>Core: SetOutputs(PinMask(3), false)
Note over Core: initialised? mask not 0?
Note over Core: new output pair from the copy: 0xFFF7
Core->>Port: Write(0x20, [0x02, 0xF7, 0xFF])
Port-->>Core: true
Note over Core: copy updated
Core-->>App: Result<void>{Ok}
Design choices¶
- CRTP, not virtual functions. The port is a template parameter constrained by the
I2cPortconcept, so every call is resolved at compile time and a missing hook is a compile error that names it. - A copy of the registers. The driver writes every register it owns at start-up and keeps what it wrote in its
Config. A pin call computes the new pair from the copy and writes it once, instead of a read-modify-write; the copy is also whatEnsureInitialized()writes again afterDeinitialize(). - The variant is configured, not probed. The data sheets do not say how a PCA9555 answers the Agile I/O
command bytes, so writing to them on a guess could reach the wrong register.
Config::variantnames the part, and a start-up for a PCAL9555A reads before it writes. - No waits. The chip has no conversion or reset time, so the port has no delay hook and every call is a fixed number of transfers.
- One error type.
Result<T>carries a value and anError; nothing throws and nothing returns a barebool. - 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/pcal9555.hpp |
| How a call is implemented | src/pcal9555.ipp |
| Register addresses and bits | inc/pcal9555_registers.hpp |
| The port contract | inc/pcal9555_i2c_interface.hpp |
Next: Contract.