Skip to content

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.

Layer diagram: your application calls the Bno08x core, which sends register reads and writes through the I2C, SPI or 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 Bno08x core, which sends register reads and writes through the I2C, SPI or 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/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.

State machine of the BNO08x session with the states Idle, Resetting, WaitAdvert, WaitReady, Ready and Faulted, and the calls and events that move it between them.State machine of the BNO08x session with the states Idle, Resetting, WaitAdvert, WaitReady, Ready and Faulted, and the calls and events that move it between them.
Session states of the driver
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

One sensor sample: your code enables a feature, the core writes it through your port, the hub pulls its interrupt line low when data is ready, and the next Poll reads, reassembles and decodes the report into an event.One sensor sample: your code enables a feature, the core writes it through your port, the hub pulls its interrupt line low when data is ready, and the next Poll reads, reassembles and decodes the report into an event.
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 HubPort concept: every call resolves at compile time, and a missing or misdeclared hook is a compile error that names it.
  • One class, four transports. Port::kTransport selects 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, no printf. 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.