Transports¶
One class, four ways to reach the hub. The port you write names its transport; everything above it (operations,
events, calibration) is identical. The strap pins PS1 and PS0 choose the transport in the chip, so the port's
kTransport must match the wiring.
Datasheet sections this page relies on
- Protocol selection (PS1, PS0): CEVA 1000-3927 1.17, 1.2 BNO08X Connectivity, p. 9
- I2C: address, clock stretching, framing: CEVA 1000-3927 1.17, 1.2.2 I2C interface, p. 12
- UART-SHTP: baud rate, framing, byte gap: CEVA 1000-3927 1.17, 1.2.3 UART-SHTP interface, p. 15
- SPI: mode, WAKE, H_INTN handshake: CEVA 1000-3927 1.17, 1.2.4 SPI Interface, p. 17
- UART-RVC: the 19-byte frame: CEVA 1000-3927 1.17, 1.2.5 UART-RVC interface, p. 20
- SHTP header, channels and cargo reads: CEVA 1000-3927 1.17, 1.3.1 SHTP, p. 22
- SPI timing: CEVA 1000-3927 1.17, 6.5.2 SPI timing, p. 46
- Interrupt timing: host must answer H_INTN: CEVA 1000-3927 1.17, 6.5.4 Interrupt timing, p. 48
- UART inputs of the RVC mode: CEVA 1000-3625 1.9, 3.1.2 UART Inputs, p. 12
- Header, channels and the rules of a cargo: CEVA 1000-3535 1.10, 2.2.1 SHTP Header, p. 4
- Reading cargoes, continuations and interrupts: CEVA 1000-3535 1.10, 2.5 Reading Cargoes, p. 6
- Synchronous protocols: I2C and SPI handshake: CEVA 1000-3535 1.10, 3 Synchronous protocols (SPI/I2C), p. 7
- SHTP over UART: control characters, BSQ and BSN: CEVA 1000-3535 1.10, 4 SHTP over UART, p. 10
- Command channel and the error list: CEVA 1000-3535 1.10, 5.1 Command Channel, p. 13
- Channel advertisement: CEVA 1000-3535 1.10, 5.2 Channel Advertisement, p. 15
- SH-2 channel usage and report lengths: CEVA 1000-3600 1.6, 2.2 SH-2 Channel Usage, p. 4
All of them, with the driver API for each: Datasheet map.
| Transport | kTransport |
PS1 | PS0 | Speed | Hooks you write | Needs H_INTN |
|---|---|---|---|---|---|---|
| I2C (SHTP) | Transport::I2c |
0 | 0 | 100 or 400 kbit/s | I2cWrite, I2cRead, IntAsserted |
yes |
| SPI (SHTP) | Transport::Spi |
1 | 1 | up to 3 MHz | SpiTransfer, SetWake, IntAsserted |
yes |
| UART (SHTP) | Transport::UartShtp |
1 | 0 | 3 Mbit/s | UartRead, UartWrite or UartWriteByte |
optional |
| UART-RVC | Transport::UartRvc |
0 | 1 | 115200 baud | UartRead |
no |
Every port also provides EnsureInitialized() and NowUs(). Porting shows each one in code.
SHTP in one page¶
Every message is a cargo with a 4-byte header: a 15-bit length (the top bit continues a cargo), a channel and a
per-channel sequence number. The driver uses channel 0 (the advertisement and the error list), 1 (executable
commands), 2 (SH-2 control), 3 and 4 (input reports, normal and wake-up) and 5 (the gyro-integrated rotation
vector). Cargoes can be fragmented by the hub; the driver reassembles them and never fragments what it sends: a
request that does not fit one write is refused with Oversize. The advertisement at start-up carries the limits;
without a limit tag the driver uses its Limits sizes (A12).
The framing engine is strict. Every rule it enforces has a counter in Stats (short transfers, a length of 0xFFFF,
a null header, a length of 1 to 3, an oversize cargo, a bad channel, lost or orphaned continuations, wrong
continuation lengths, duplicate or skipped sequence numbers, unknown or cut-short reports). Config::resync_limit
violations within Config::resync_window_ms make the driver abandon the running operations with Framing, count
a resynchronisation and reset the hub, instead of guessing at the bytes.
I2C¶
The hub is a slave at 0x4A (SA0 low) or 0x4B (SA0 high). The driver reads only after H_INTN went low: first the
4-byte header, then exactly the rest of the cargo as a continuation, each as a separate transaction that ends with a
STOP (no repeated start). Reading without H_INTN is possible with Config::poll_without_int, which is guarded:
a BNO085 stretches the clock when it has nothing to say, a BNO086 answers with a zero-length packet (A2), so the port
documents its stretch timeout. Keep the bus at 400 kbit/s or less (A39).
SPI¶
Mode 3 (clock idles high, data sampled on the second edge), most significant bit first, at most 3 MHz, full duplex.
H_INTN tells the host a cargo is waiting; the host then does one duplex transfer, which may be longer than the
cargo (the hub pads with zeros and a null header). To write, the driver drives WAKE low if H_INTN is not already
asserted, waits for H_INTN up to Config::wake_timeout_us, does the transfer and releases WAKE. PS0 is both a strap
and the WAKE line, so it must be a GPIO that is high while NRST is released: the driver drives it high before every
NRST pulse and releases it on every exit (operation time-out, HardReset(), resync, hub restart), DS p18.
UART with SHTP¶
Frames start and end with 0x7E; inside a frame 0x7E and 0x7D are escaped (0x7D, then the byte XOR 0x20).
The byte after the start flag is the protocol ID: 1 for SHTP data, 0 for the hub's control frames (the buffer status
query, BSQ, and the buffer status notification, BSN, in which the hub says how many bytes it can take). The BSN is a
token: it holds until the next host write or until the advertised UART timeout (tag 0x81) expires, and the driver
sends only while it is valid and large enough. The SHTP gives no answer time for a BSQ, so a query whose BSN has not
arrived after Config::uart_bsq_retry_ms is sent again (Stats::bsq_retries) until the operation's own limit ends
it; a lost query or notification therefore costs one retry, never the link. A write that times out half-sent is
closed with a flag byte and never finished later, and a reset or resync drops a frame in progress. The hub needs at
least 100 microseconds between bytes it receives, so the port either sends byte by byte through UartWriteByte (the
driver paces it) or declares kPortPacesUartTx = true and implements UartWrite. Both UART modes need the
32.768 kHz clock on the board: the internal oscillator is not accurate enough at these rates (A10).
UART-RVC¶
The hub streams a 19-byte frame at 100 Hz and takes no commands: 0xAA 0xAA, an index that increases by one,
yaw, pitch and roll in 0.01 degree, acceleration in milli-g, the BNO086's MI and MR bytes, reserved bytes and a
checksum (the low byte of the sum of bytes 2 to 17, A6). Poll() delivers each valid frame as an EventKind::Rvc
event whose v holds index, yaw, pitch, roll, ax, ay, az, mi, mr, mi_mr_valid. An ASCII banner at power-up is
skipped (A9); a frame with a wrong checksum is counted and the scanner slides one byte. The $MIB text inputs
the manual describes (reset, intent, dynamic calibration) are refused with Unsupported unless
rvc_inputs_experimental is set, because the manual's own example checksum does not match its text (A8).
Next: Sensors.