Ambiguities and decisions¶
The CEVA documents disagree with each other in places, are silent in others, and describe chips that differ in
small ways. This page lists every case the driver had to decide, what it decided, and the switch that changes it.
Nothing here is verified on hardware: the driver is tested against an independent model of the hub whose
Knobs reproduce each reading (Testing and CI), so a hub that behaves differently is a bench result to
report, not a surprise in the field.
Datasheet sections this page relies on
- Features, variants and what differs: CEVA 1000-3927 1.17, Features (front page), p. 1
- Motion, orientation and environmental outputs: CEVA 1000-3927 1.17, 2 Sensor data processing, p. 30
- Interactive calibration (BNO086 only): CEVA 1000-3927 1.17, 3.3 Interactive Calibration (BNO086 only), p. 39
- Version history: BNO080 removed, polling note: CEVA 1000-3927 1.17, 8 Version history, p. 56
- UART inputs of the RVC mode: CEVA 1000-3625 1.9, 3.1.2 UART Inputs, p. 12
- Pin and interface differences from the BNO070: CEVA (Hillcrest Labs) none printed 1.6, 2.1 Pinout Comparisons, p. 7
All of them, with the driver API for each: Datasheet map.
Document codes: DS is the data sheet (revision 1.17 unless named), RM the SH-2 reference manual, SHTP the transport
protocol document, TARE and CAL the tare and calibration guides, MIG the older migration guide. LIB is CEVA's
reference C library, read only as a non-normative cross-check. Page numbers are printed pages
(Datasheet map). "Model" names a knob of the test model, not of the driver; a driver setting is a
Config field.
Variants¶
Config::variant selects the chip. It is never detected: no document maps the product ID part numbers to the three
names (A1), and the response is recorded in Product() but not used to choose behaviour.
| Behaviour | BNO080 | BNO085 | BNO086 |
|---|---|---|---|
| Interactive calibration, motion request 0x2B, command 0x0E | refused with Variant |
refused with Variant |
allowed |
| UART-RVC MI and MR bytes decoded | no | no | yes |
| I2C read when no data is waiting | not used: reads follow H_INTN | clock stretch | zero-length packet |
| Everything else | same driver paths | same | same |
With strict_variant = false the driver sends the request and lets the hub answer (A3, A4).
The decisions¶
| Id | What the documents say | Decision and knob |
|---|---|---|
| A1 | No document maps product ID part numbers to BNO080, BNO085 or BNO086 | Config::variant required (default Bno085); model product_part_number; the Product ID response is recorded, never used to choose behaviour |
| A2 | I2C read with no data: DS 1.17 says BNO085 stretches the clock, BNO086 sends zero-length packets; history p56: rev 1.15 "BNO086 does not support I2C polling", rev 1.17 "polling behavior for BNO086" | gate reads on H_INTN; accept zero-length headers; port documents its stretch timeout; model i2c_empty_poll in {stretch, zero_length, nack}; poll_without_int guarded |
| A3 | DS p1: BNO086 has an "identical ... software feature set" and also interactive calibration | strict_variant (default true) refuses 0x2B and command 0x0E on non-BNO086 with Variant; false sends and lets the hub decide; model bno086_features_on_085 |
| A4 | SH-2 manual S5.6 and S6.4.12 describe interactive calibration generally; datasheets say BNO086 only | as A3 |
| A5 | RVC tail: DS p21 "one (BNO086) or three (otherwise) reserved bytes" after MI and MR | same 19-byte frame; mi/mr decoded only for Bno086; model rvc_mi_mr |
| A6 | RVC checksum list omits MI and MR (RM S3.1.1 "sequence number, yaw, pitch, roll, acceleration and reserved bytes") while DS says "Index, yaw, pitch, roll, acceleration and reserved data bytes"; the example has MI = MR = 0 and cannot decide | accept the sum over bytes 2 to 17 (MI/MR included) first, else over bytes 2 to 14 plus byte 17; count which matched in Stats; model rvc_csum_includes_mi_mr |
| A7 | RVC angle ranges differ per axis (yaw ±180, pitch ±90, roll ±180) and there is no valid or status field | range check counted (rvc_out_of_range), not an error; model rvc_angle_noise |
| A8 | RM S3.1.2 lists $MIB,RESET*87, $MIB,INTENT*0n, $MIB,DYNCAL*nn, $MIB,CLRDCD*00; "*87" is not the XOR of the text (0x3F, recomputed here; INTENT 0x66, CLRDCD 0x74, DYNCAL 0x77) and the datasheet documents no RVC input |
guarded, default Unsupported; model implements $MIB with rvc_input_cs in |
| A9 | RVC start prints an ASCII banner before frames (DS p43) | scanner skips non-0xAA bytes; a false 0xAA 0xAA inside a frame is rejected by checksum and index continuity; model rvc_banner |
| A10 | RVC and UART-SHTP need a 32.768 kHz crystal or clock; internal clock "not accurate enough" (DS p15, p20, rev 1.8 note) | documented in hardware, not a code knob; model flags a UART error rate when clock_internal |
| A11 | Start-up order: advertisement, then executable reset-complete, then SH-2 initialise (DS p43); SHTP only requires the advertisement first | any order after the advertisement within startup_timeout_ms; require_init_response; an initialise response in Ready is a restart only when the session already had one; model startup_order, omit_init_response |
| A12 | The Max* advertisement values of the BNO08x are not documented (SHTP S5.2 shows an example only) | use advertised values; absent tags fall back to kMaxTxCargo/kMaxRxCargo; model advert_limits, advert_without_limits |
| A13 | SHTP allows fragmented host writes, the BNO08x does not (DS p22; SHTP errors 5, 6) | never fragment; Oversize; model accept_fragmented_writes off |
| A14 | Continuation reads: header with MSB set, length = remaining + 4 (SHTP S2.3.1); the BNO08x behaviour on a header-only first read is described only by the datasheet's "partial reads" sentence (DS p22) | strict_cont_len default true; model cont_header_style in {spec, no_header} (the second fails the engine into resync) |
| A15 | Sequence numbers after reset or at the first cargo on a channel are not specified | baseline from the first observed value after (re)start; gaps counted; model seq_start, seq_skip_rate |
| A16 | SH-2 per-report sequence "increments once for each report sent" (RM S6.5.1): per sensor or global is not stated | tracked per report ID; gaps counted only; model report_seq_scope |
| A17 | Base timestamp 0x7FFFFFFF means overflow (RM S7.2.1) and rebase accumulates (S7.2.2); nothing says what a host does on overflow | overflow disables the base for that cargo (time = t_int - delay) and counts base_overflow; model base_overflow |
| A18 | Step counter steps: RM Figure 102 shows a 16-bit field (bytes 8 to 9, two reserved), LIB reads a 32-bit value at bytes 8 to 11 | decode 16-bit (document normative); model step_counter_upper_bytes nonzero to show the difference; recorded in docs |
| A19 | Event payload widths: RM shows "LSB" for sigmotion, shake, flip, pickup, stability detector, tilt, pocket, circle (uint16) and single bytes for tap, stability classifier, sleep; LIB agrees | decode as the manual shows; upper byte nonzero counted payload_upper_nonzero |
| A20 | Environmental sensors depend on parts on the secondary I2C bus (BME280/BMP280, CM36686, DS p33) and may be absent | enabling a report the hub cannot serve times out; reported as Timeout with HubError detail when present; model env_sensors mask |
| A21 | Pin 10 is CLKSEL0 in DS 1.3 and later, EXTSYNC "future feature" in MIG 1.6 | DS wins; MIG kept for BNO070 history only |
| A22 | MIG notes "32 kHz crystal required" (22 pF); DS allows internal oscillator, crystal 12.5 pF | DS wins; hardware docs list both |
| A23 | VDDIO 1.65 V (pin table, DS p10) vs 1.7 V (operating conditions DS p45) | 1.7 V used as the specification; note on the chip card |
| A24 | ENV_SCL and ENV_SDA are pins 15 and 16 in DS 1.17 (corrected in rev 1.2) and swapped in MIG Figure 3 | DS 1.17 |
| A25 | RM Figure 32 summary table lists direction "W" for responses (0xFC, 0xF5) and the product ID section titles say "FSP3xx"; BNO08x byte layouts are the same as DS Figures 1-28 to 1-30 | layouts per the byte tables; directions per DS Figure 1-30 |
| A26 | RM Figure 37 lists status 12 twice ("unable to write record. FRS memory is full" and "12-255 reserved") | 12 treated as full; others above 12 as unknown failure; model frs_status_ge12 |
| A27 | FRS write completion: statuses 8 (valid) and 3 (completed) both appear | success = 3; 8 is recorded as an intermediate; 9, 5, 7, 11, 12, 10 fail; model frs_final_status in |
| A28 | FRS read requests: bytes after the type are "reserved"; block reads were removed in RM 1.3 | send zero; model rejects non-zero reserved |
| A29 | FRS read busy: "responded to with a Read Response indicating BUSY and then it completes the in-progress read" | one operation at a time in the driver; model frs_busy_interleave |
| A30 | Metadata revision 3 vs 4 (word 9) and the unknown vendor ID length alignment | parse both; model metadata_revision per sensor |
| A31 | The BNO08x supports only a subset of the SH-2 reports | datasheet-listed set is "D" in 1.8; the rest "M" (manual only): allowed, timeout means unsupported; Capabilities() says which are D; model sensor_mask |
| A32 | Datasheet metadata example (Figure 1-32) shows rotation vector revision 4 with Q point 3 = 13; RM S6.5.18 says change sensitivity Q13 | consistent; metadata wins when present |
| A33 | Product ID: DS 1.3.2 (p23) and RM S6.3.2 show one response layout and do not say how many come; the vendor library expects 4 (5 for three part numbers) | a request completes after product_id_entries responses (default 1); Product() is entry 0, ProductEntries() holds the entries of the request; later entries are counted in Stats::product_id_extra and dropped; the model sends 4 with different part numbers (product_id_entries) |
| A34 | RM S6.5.29 says the step counter wakes the host before the steps field wraps; DS p35 says the 16-bit counter | 16-bit; nothing to do in the driver beyond the wake flag |
| A35 | Periodic DCD save parameter: 0 enables, 1 disables (RM S6.4.7; LIB enabled ? 0 : 1) |
the API is a bool; model verifies both polarities |
| A36 | TARE cites RM S6.4.4.1 and S6.4.4.2 for tare now and persist; RM 1.9 numbers them S6.4.3.1, S6.4.3.2 | RM 1.9 numbers used |
| A37 | Tare Now supports axes 0x07 and 0x04 (RM S6.4.3.1 prose) although P1 is a bitmap | allowed masks 0x07 and 0x04; other masks InvalidArgument (knob tare_any_mask in the model) |
| A38 | DS p18: H_INTN should be handled within 1/10 of the fastest sensor period; hub times out after about 10 ms | Poll guidance in docs; model hint_host_timeout_ms retries H_INTN |
| A39 | DS 1.2.2.1 says I2C "up to 400 kb/s"; the SPI limit is 3 MHz; UART 3 Mbit/s; no minimum host SPI clock is given | constants only |
| A40 | CEVA's tare guide is titled for BNO085/BNO086; the calibration guide 1.3 for BNO080/BNO085 | recorded, no behaviour |
| A41 | Pickup detector 0x1B: RM Figure 107 (p79) shows 6 bytes, the vendor library's length table 8 | built-in length 6; an advertised ReportLengths entry wins; model pickup_report_len, advertise_report_lengths |
| A42 | Wheel encoder 0x2E: the RM has no report layout, the vendor library's length table says 12 | no layout, SetFeature returns Unsupported; with an advertised length a report is skipped and counted in unknown_report, without one the rest of its cargo is skipped; model wheel_encoder_len |
Not exposed: command 0x10 (dead-reckoning calibration save, sh2_saveDeadReckoningCalNow in the vendor library) is
not in the RM command list (Figure 42, p44 and p45, IDs 1 to 14, plus 0x0F in S6.4.13), so the driver does not send it.
Corrections found while checking the references¶
Thirty-odd page and section references were compared with the PDFs when the driver was written. These are the ones
that were wrong or imprecise in the working notes; the driver and docs/datasheets.yml use the corrected values.
| Reference as first noted | Corrected |
|---|---|
| Reports 0x13 and 0x1F are 5 bytes long | 6 bytes (RM report-length table) |
| One metadata record ID "0xE300" for all sensors | One per sensor, 0xE301 to 0xE325; 0x2C and 0x2D have none |
| 36 sensor input report IDs | 39 (40 counting the reserved 0x17) |
| DS p40, DS p18 | DS p41, DS p19 |
| RM section 6.5.2 p34, section 6.5 p42, Figure 75 p41 | RM p63, p62, p62 to 63 |
| RM section 7 p11, section 6.4.12.1 p12, Figure 111 p70 | RM p91, p60, p81 to 82 |
| SHTP Figure 16 p11, Figure 17 p12 | SHTP p15, p17 |
| DS section 1.4 p2 | DS p1 to p2 |
| One page offset for all documents | PDF page = printed page + 1 for RM, SHTP, the SH-2 update guide and the calibration |
| guides 1.3 and later; 0 for the data sheet, the tare guide and the migration guide | |
| "Accuracy under 10 degrees" from the data sheet | The tare guide, page 2 |
| Pin 1 marker described as the package feature | The marker belongs to the land pattern drawing |
The tare and calibration guides carry typos the driver does not copy: the update guide's command byte 0xF2 where
0xFC is meant, and a tag number 8 where 9 is meant. The driver's sensor-to-report-ID table is internal; it is
checked against the manual's figures, not against a library.
Accuracy of the Euler helper¶
ToEulerCentiDeg() converts a Q14 quaternion with integer arithmetic only. It is accurate to a few centidegrees in
general; very close to a pitch of plus or minus 90 degrees yaw and roll are ill-defined and the error reaches about
80 centidegrees (the tests bound it there). Use the quaternion itself for control and Euler angles for display.
Open questions for the vendor¶
A2 (I2C polling by variant), A3 (BNO086 features), A6 (the RVC checksum range), A8 (the RVC inputs), A12 (the advertised limits), A14 (continuation reads), A15 (sequence numbers after reset), A17 (timestamp overflow), A27 (the FRS completion status), and whether any chip implements the manual-only sensors. Firmware update (the DFU protocol is not public, DS p29) is not supported.