Architecture¶
How the driver is built: three layers, one of them yours, and what happens in each when a sample arrives.
Datasheet sections this page relies on
- SHTP header, channels and cargo reads: CEVA 1000-3927 1.17, 1.3.1 SHTP, p. 22
- Report structure, product ID, executable commands: CEVA 1000-3927 1.17, 1.3.2 Report Structure, p. 23
- Getting started: establishing contact and reading: CEVA 1000-3927 1.17, 5 Getting started with BNO08X, p. 43
- Start-up timing: CEVA 1000-3927 1.17, 6.5.3 Startup timing, p. 47
- Command request and response: CEVA 1000-3625 1.9, 6.3.8 Command Request (0xF2), p. 43
- Header, channels and the rules of a cargo: CEVA 1000-3535 1.10, 2.2.1 SHTP Header, p. 4
- Channel advertisement: CEVA 1000-3535 1.10, 5.2 Channel Advertisement, p. 15
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/bno08x.hpp public calls; inc/bno08x_interface.hpp HubInterface; figure module docs/diagrams/figures/driver-layers.py.
Layers¶
| Layer | Files | Owns |
|---|---|---|
| Core | inc/bno08x.hpp, src/bno08x.ipp |
The session state machine, the operation queue, the event queue, timing, errors |
| Protocol | inc/bno08x_shtp.hpp, inc/bno08x_rvc.hpp |
SHTP framing and reassembly, the UART framing, the advertisement, the UART-RVC frames |
| Definitions | inc/bno08x_types.hpp, inc/bno08x_registers.hpp, inc/bno08x_reports.hpp, inc/bno08x_records.hpp |
Error, Result, Config, Event, the SH-2 constants, the table of report layouts, the FRS records |
| Port contract | inc/bno08x_interface.hpp |
The CRTP base, the HubPort concept and its transport variants |
| Platform port | Your class | The bus or UART, a clock, H_INTN and optionally NRST, BOOTN, WAKE and logging |
| Helpers | inc/bno08x_euler.hpp, inc/bno08x_kconfig.hpp |
Integer quaternion to Euler; an optional Config from ESP-IDF menuconfig |
Never blocking¶
The hub is asynchronous: it sends reports when it likes, answers requests later, and batches. The driver is therefore a state machine that you run from your loop.
Figure description and sources
Six states. The session starts in Idle. Begin() leaves Idle for Resetting when NRST is wired, for WaitAdvert when it is not, and for Ready on UART-RVC. Resetting goes to WaitAdvert when the reset wait is over. WaitAdvert goes to WaitReady once the advertisement is parsed, and WaitReady goes to Ready when the reset is complete. Ready goes back to WaitReady when the hub restarts. Resetting is also entered by HardReset() and by framing faults. Faulted is reached from Resetting when NRST cannot be released and from WaitAdvert or WaitReady on a start-up timeout, and Begin() or HardReset() lead from Faulted back to Resetting.
Drawn from: docs/model/session-states.state.yml.
Not drawn, to keep the picture readable: Begin() starts again from any state, like from Idle. Without NRST,
too many framing faults queue the reset command instead, and the session stays where it is until the hub's
restart arrives (Ready to WaitReady). A HardReset() or framing-fault reset whose pins cannot be driven
leaves the session Faulted. In Faulted only stop requests are written and nothing read is used.
Poll(now_us) reads what the hub has waiting (a transfer per H_INTN on I2C and SPI, the bytes in the UART
receiver), reassembles cargoes, decodes reports into events, writes the next queued request and checks the
timeouts. It never waits on the hub: a port hook that needs time (a stretching bus) is the only thing that can.
One sample through the layers¶
Figure description and sources
Participants, left to right: Your code, Bno08x, Your port and BNO08x. The steps run from top to bottom. Your code sends SetFeature(RotationVector, 10 ms) to Bno08x. Bno08x returns OpId to Your code. Bno08x sends I2cWrite(set feature cargo) to Your port. BNO08x returns H_INTN low to Your port. Your code sends Poll(now) to Bno08x. Bno08x sends IntAsserted(), I2cRead(header, rest) to Your port. A note over Bno08x says: reassemble, timestamp, decode. Bno08x returns Event Sensor on PopEvent() to Your code.
Drawn from: docs/model/one-sample-through-the-layers.seq.yml.
Design choices¶
- CRTP and concepts, not virtual functions. The port is a template parameter checked by the
HubPortconcept: every call resolves at compile time, and a missing or misdeclared hook is a compile error that names it. - One class, four transports.
Port::kTransportselects the read and write path at compile time; the code of a transport you do not use is not instantiated. - No I/O in the constructor, no blocking in
Begin(). Construction cannot fail, so the driver can be a static. - Operations return ids, results arrive as events. One queue of events carries samples, operation results, resets and errors, so the application has one place to look. A full queue drops and counts.
- Tables, not code, for reports. Every sensor's layout is one row of a table, checked at compile time; adding a report adds a row.
- Independent model for tests. The tests run the driver against a model of the hub written separately from the driver (Testing and CI), so a bug cannot hide behind a copied assumption.
- No heap, no exceptions, no RTTI, no
std::function, noprintf. A header-only template with no mutable static state.
Source map¶
| You want | Read |
|---|---|
| The public API | inc/bno08x.hpp |
| How a call is implemented | src/bno08x.ipp |
| Framing and reassembly | inc/bno08x_shtp.hpp |
| Report layouts and Q points | inc/bno08x_reports.hpp |
| The port contract | inc/bno08x_interface.hpp |
Next: Contract.