Skip to content

Architecture

How the driver is built: three layers, one of them yours, and what happens in each when you read a channel.

Datasheet sections this page relies on

From Texas Instruments SLAS605 C:

  • Frame, reply word, GPIO refresh and alarm timing: 8.1 Overview, p. 28
  • Manual mode and the two-frame read latency: 8.4.4 Operating in Manual Mode, Figures 50 and 51, Table 1, p. 31
  • Auto-1 mode and its program register: 8.4.5 Operating in Auto-1 Mode, Figures 52 to 54, Tables 2 to 4, p. 34
  • The "continue" word: 8.4.7 Continued Operation in a Selected Mode, Table 7, p. 41

All of them, with the driver API for each: Datasheet map.

Layer diagram: your application calls the ADS7952 core, which sends register reads and writes through the SPI 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 ADS7952 core, which sends register reads and writes through the SPI 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/ads7952.hpp public calls; inc/ads7952_spi_interface.hpp SpiInterface; figure module docs/diagrams/figures/driver-layers.py.

Layers

Layer Files Owns
Core inc/ads7952.hpp, src/ads7952.ipp Lifecycle, reset and identity check, the frame pipeline (mode, selected channel, replies in flight), address checks, program sequences and their repair, errors
Types and frame format inc/ads7952_types.hpp, inc/ads7952_registers.hpp Error, Result<T>, Variant, Package, Range, Verify, GpioConfig, AlarmThreshold, Bank, Config; the command words and the reply fields
Port contract inc/ads7952_spi_interface.hpp The CRTP base, the SpiPort concept, detail::FrameBus (one 16-bit frame per transfer, MSB first)
Platform port Your class Bus bring-up, transfers and a delay; optionally logging
Kconfig layer inc/ads7952_kconfig.hpp Optional: a Config from ESP-IDF menuconfig

The pipeline the core tracks

Two timing grids of 16-bit frames. Manual: a Manual word selects channel 4 in frame N, the multiplexer acquires it in frame N + 1 and its result comes back in frame N + 2. Auto-1: the Auto-1 word restarts the sequence 2, 5, 6 in frame N, and from frame N + 2 on every Auto-1 word returns the next channel.Two timing grids of 16-bit frames. Manual: a Manual word selects channel 4 in frame N, the multiplexer acquires it in frame N + 1 and its result comes back in frame N + 2. Auto-1: the Auto-1 word restarts the sequence 2, 5, 6 in frame N, and from frame N + 2 on every Auto-1 word returns the next channel.
A result comes back two frames after its channel
Figure description and sources

Each column is one 16-bit frame, CS low for 16 SCLK cycles, left to right in time. In each panel the top row is the word the driver sends on SDI, the middle row the channel the multiplexer acquires during that frame, and the bottom row the reply on SDO: the conversion of the channel acquired in the frame before, sampled at this frame's CS falling edge, tagged with its address in DO15:12. In Manual mode (top) ReadChannel(4) selects channel 4 with a Manual word, sends a "continue" word and then the Manual word for channel 4 again (it carries the range once more), and keeps the third reply, whose address must be 4; the two replies before it still belong to the previous channel. In Auto-1 (bottom), entering the mode restarts the sequence at its first channel: with channels 2, 5 and 6 programmed, the first result arrives two frames after the Auto-1 word, and from then on every Auto-1 word without restart (DI11 = 1, the range again) returns the next channel of the sequence, so a pass costs one frame per channel. The timing is the datasheet's Figures 51 and 53; the frame counts come from ReadChannel(), readSelected(), scan() and collect() in src/ads7952.ipp.

Drawn from: src/ads7952.ipp select(); src/ads7952.ipp selectChecked(); src/ads7952.ipp readSelected(); src/ads7952.ipp scan(); inc/ads7952_registers.hpp kContinue; figure module docs/diagrams/figures/frame-pipeline.py.

The chip answers each frame with the result of the channel the frame before last chose (Figures 51 and 53). The core keeps three facts so that each call sends the fewest frames and returns only results that belong to it: the mode the chip is in (Manual, Auto-1, Auto-2, or unknown after a failure), the Manual channel, and how many replies still in flight were acquired before its last change (a select, an Auto entry, a new range or sequence). A read that does not need to choose the channel lets those replies pass; any other read chooses it again, which also sends the range. A reply's address is always checked against the channel it must carry.

One read through the layers

sequenceDiagram
    participant App as Your code
    participant Core as ADS7952<Port>
    participant Port as Your port
    App->>Core: ReadChannel(4)
    Core->>Port: Transfer(0x1A00: Manual, DI11, channel 4)
    Port-->>Core: true, reply of an earlier channel
    Core->>Port: Transfer(0x0000: continue)
    Port-->>Core: true, reply acquired before the select
    Core->>Port: Transfer(0x0000: continue)
    Port-->>Core: true, 0x4xxx: address 4, the result
    Core-->>App: Result<uint16_t>{code, Ok}
    App->>Core: ReadChannel(4)
    Core->>Port: Transfer(0x0000: continue)
    Port-->>Core: true, 0x4xxx
    Core-->>App: Result<uint16_t>{code, Ok}

A scan is drawn on the API guide: after the entry, one Auto-1 word (DI11 = 1, no restart) per channel.

Design choices

  • CRTP, not virtual functions. The port is a template parameter constrained by the SpiPort concept, so every call is resolved at compile time and a missing hook is a compile error that names it.
  • Optional hooks by named concepts. DelayUs and Log are detected by HasDelayUs and HasLog in one place, which match the hook's address against exactly one noexcept signature (detail::ExactHook). A missing DelayUs() fails to compile, and so does a hook declared with another signature; a missing Log() logs nothing.
  • No I/O in the constructor. Construction cannot fail and clocks nothing, so the driver can be a static or a member of a handler built at boot, before the board is plugged in.
  • Key every result on its address. The chip tags each reply with its channel; the driver never infers a channel from frame counting alone. A lost frame, a reset chip or a deaf SDI line becomes an error, not a wrong value.
  • Minimum frames, extra checks per call. The hot path sends one mode word per result; the read-backs the chip allows (GPIO levels, the scanned sequence) are asked for per call with Verify::ReadBack.
  • No mode calls. The driver enters Manual, Auto-1 or Auto-2 when a read needs it; the caller never has to keep the chip's mode and the driver's view in step.
  • One error type. Result<T> carries a value and an Error; nothing throws and nothing returns a bare bool.
  • 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/ads7952.hpp
How a call is implemented src/ads7952.ipp
Command words and reply fields inc/ads7952_registers.hpp
The port contract and the frame inc/ads7952_spi_interface.hpp

Next: Contract.