Architecture¶
How the driver is built: three layers, one of them yours, and what happens in each when you move the motor.
Datasheet sections this page relies on
From Analog Devices (Trinamic) TMC5160A-DS 1.18:
- Features, control interfaces and key concepts: 1 Principles of Operation, p. 5
- Initialization examples: 23.1 Initialization Examples, p. 116
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/tmc5160.hpp public calls; inc/tmc5160_spi_interface.hpp SpiInterface; figure module docs/diagrams/figures/driver-layers.py.
Layers¶
| Layer | Files | Owns |
|---|---|---|
| Core | inc/tmc5160.hpp, src/tmc5160.ipp |
Lifecycle, guards, motion, status, framing of both buses, errors |
| Types and registers | inc/tmc5160_types.hpp, inc/tmc5160_registers.hpp, inc/tmc5160_status.hpp |
Error, Result<T>, Config and its parts; the register table; decoded status |
| Units | inc/tmc5160_units.hpp |
Pure integer helpers: the current plan, ramp conversions, the encoder scale |
| Helpers | inc/tmc5160_detail.hpp |
Typed integer literals, the exact hook probes, CRC-8, field packing |
| Port contracts | inc/tmc5160_spi_interface.hpp, inc/tmc5160_uart_interface.hpp |
The CRTP bases, the concepts, the bus requirements |
| Platform port | Your class | Bus bring-up and byte transfers, optionally delays, GPIO, the clock and logging |
| Kconfig layer | inc/tmc5160_kconfig.hpp |
Optional: a Config from ESP-IDF menuconfig |
One call through the layers¶
Figure description and sources
Participants, left to right: Your code, TMC5160
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 the
SpiPortorUartPortconcept, so every call is resolved at compile time and a missing hook is a compile error that names it. - One bus per object. The base class decides the bus; the framing code is
if constexpron it, so a UART port carries no SPI code. - A shadow of the write-only registers. Most TMC5160 registers cannot be read. The driver writes whole 32-bit words
from a write-through shadow and never reads them back; this also makes
UnexpectedResetdetectable and recoverable. - The configuration is the source of truth. Every setter builds the next
Config, validates it, writes the affected registers and only then stores it, so a failed call leaves the stored configuration as it was. - Guards in one place. Every dangerous write goes through one guard function that knows the acknowledgements.
- Optional hooks by
requires.DelayUs,GpioSet,GpioGet,SckHzandLogare detected in one place. - No I/O in the constructor. Construction cannot fail, so the driver can be a static or a member of a handler.
- 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/tmc5160.hpp |
| How a call is implemented | src/tmc5160.ipp |
| Register addresses and bits | inc/tmc5160_registers.hpp |
| The current arithmetic | inc/tmc5160_units.hpp |
| The port contracts | inc/tmc5160_spi_interface.hpp, inc/tmc5160_uart_interface.hpp |
Next: Contract.