BNO08X Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Public Member Functions | Static Public Attributes | List of all members
bno08x::Bno08x< Port, Limits > Class Template Reference

Driver for one BNO080, BNO085 or BNO086. More...

#include <bno08x.hpp>

Public Member Functions

 Bno08x (Port &port) noexcept
 Bind the driver to a port. No I/O, cannot fail.
 
Result< void > Begin (const Config &cfg) noexcept
 Start a session: validate cfg, bring the bus up, reset the hub and begin waiting for its advertisement. Returns at once; Poll() does the rest and Ready() turns true. Called again, it ends every waiting operation with NotInitialized and starts a new session.
 
void Poll (uint32_t now_us) noexcept
 Advance the session: read what the hub offers, send the next request, check the time limits. Never waits on the hub; bounded work per call.
 
State GetState () const noexcept
 
bool Ready () const noexcept
 
Result< void > HardReset () noexcept
 Pulse NRST (needs the SetReset hook) and restart the session; pending operations complete with HubReset.
 
Result< OpId > Reset () noexcept
 Reset the hub with the executable-channel command (DS p23).
 
Result< OpId > HubOn () noexcept
 Executable channel "on": leave sleep, enable the configured sensors.
 
Result< OpId > HubSleep () noexcept
 Executable channel "sleep": only always-on and wake sensors keep running.
 
Result< OpId > SetFeature (SensorId id, const FeatureConfig &fc) noexcept
 Configure a sensor (Set Feature, RM S6.5.4). Completes when the request is written (or on the hub's reply with Config::set_feature_confirm).
 
Result< OpId > GetFeature (SensorId id) noexcept
 Ask the hub for a sensor's feature report (RM S6.5.3); the answer updates the shadow.
 
Result< FeatureConfig > Feature (SensorId id) const noexcept
 The driver's shadow of a sensor's feature report (what the hub was last told or said).
 
Result< OpId > Flush (SensorId id) noexcept
 Force a sensor to flush its batch (RM S6.5.6); completes on the Flush Completed report.
 
Result< OpId > ReadProductId () noexcept
 Request the product ID (RM S6.3.1).
 
const ProductId & Product () const noexcept
 
std::span< const ProductId > ProductEntries () const noexcept
 
Result< OpId > ReadMetadata (SensorId id) noexcept
 Read a sensor's metadata record (RM S5.1); the result is available from GetMetadata().
 
const Metadata * GetMetadata (SensorId id) const noexcept
 
Result< OpId > ReadFrs (uint16_t record, FrsBuffer &out) noexcept
 Read an FRS record into out (RM S6.3.6).
 
Result< OpId > WriteFrs (uint16_t record, std::span< const uint32_t > words) noexcept
 Write an FRS record (RM S6.3.3 to S6.3.5), then read it back and compare unless Config::frs_verify is false.
 
Result< OpId > EraseFrs (uint16_t record) noexcept
 Erase an FRS record (a write of length 0).
 
Result< OpId > Tare (AxisMask axes, TareBasis basis) noexcept
 Tare now (RM S6.4.3.1).
 
Result< OpId > PersistTare () noexcept
 Persist the last tare to flash (RM S6.4.3.2).
 
Result< OpId > SetReorientation (const Quat14 &q) noexcept
 Set the run-time reorientation (RM S6.4.3.3).
 
Result< OpId > ClearReorientation () noexcept
 Clear the run-time reorientation (all-zero quaternion).
 
Result< OpId > ConfigureMeCal (const MeCal &cal) noexcept
 Configure the motion engine's calibration (RM S6.4.6.1).
 
Result< OpId > GetMeCal () noexcept
 Read the calibration enables (RM S6.4.6.2); they come back in the OpDone values.
 
Result< OpId > SaveDcd () noexcept
 Save the dynamic calibration data (RM S6.4.5).
 
Result< OpId > SetPeriodicDcd (bool enable) noexcept
 Turn the periodic DCD save on or off (RM S6.4.7).
 
Result< OpId > ClearDcdAndReset () noexcept
 Clear the DCD and reset the hub (RM S6.4.9).
 
Result< OpId > GetOscillator () noexcept
 Ask for the oscillator type (RM S6.4.8): 0 internal, 1 crystal, 2 external clock.
 
Result< OpId > Initialize () noexcept
 Re-initialise the sensor hub (RM S6.4.4).
 
Result< OpId > GetCounts (SensorId id) noexcept
 Read a sensor's counters (RM S6.4.2.1); four counts in the OpDone values.
 
Result< OpId > ClearCounts (SensorId id) noexcept
 Clear a sensor's counters (RM S6.4.2.2).
 
Result< OpId > ReportErrors (uint8_t severity) noexcept
 Ask for the SH-2 error queue (RM S6.4.1).
 
Result< OpId > StartSimpleCal (uint32_t interval_us) noexcept
 Start the simple calibration (RM S6.4.10).
 
Result< OpId > FinishSimpleCal () noexcept
 Finish the simple calibration; the status is in OpDone.detail.
 
Result< OpId > SetMotionIntent (MotionIntent intent) noexcept
 Tell the interactive calibration the motion intent (BNO086, RM S6.4.12).
 
Result< OpId > SendWheel (const WheelSample &s) noexcept
 Report a wheel measurement for dead reckoning (RM S6.4.13).
 
Result< void > RvcSend (std::span< const uint8_t > text) noexcept
 UART-RVC host input, guarded (ambiguity A8): the $MIB commands of RM S3.1.2 are not verified. Unsupported unless Config::rvc_inputs_experimental is set.
 
bool PopEvent (Event &out) noexcept
 Take the oldest event.
 
const Stats & GetStats () const noexcept
 
Result< Event > Latest (SensorId id) const noexcept
 The most recent sample of a sensor.
 
uint32_t AgeUs (const Event &ev) const noexcept
 The age of a sample.
 
std::size_t TraceLastTransfer (std::span< uint8_t > out) const noexcept
 Copy the first bytes of the most recent SHTP transfer the hub sent (the 4-byte header first), for bring-up and fault finding. No I/O: the driver never reads the bus on its own account, because a raw read would race the framing engine (handbook KB-CPP-129).
 
std::size_t GetLastTransferLength () const noexcept
 
const detail::Advert & Advertised () const noexcept
 

Static Public Attributes

static constexpr Transport kTransport = Port::kTransport
 The transport of this port.
 
static constexpr std::size_t kTraceBytes = 32
 Bytes of the last transfer that TraceLastTransfer() keeps.
 

Detailed Description

template<HubPort Port, LimitsLike Limits = DefaultLimits>
class bno08x::Bno08x< Port, Limits >

Driver for one BNO080, BNO085 or BNO086.

Lifecycle: construct with the port (no I/O), Begin(Config) to start a session, call Poll(now_us) from your loop or task (at least once per tenth of the fastest report period, DS p19), and PopEvent() to take what arrived. Every call that touches the hub returns Error::NotInitialized until Begin() has succeeded; no call starts the hub as a side effect.

Optional port hooks, found at compile time:

Hook Used for Without it
bool SetReset(bool) NRST: hardware reset in Begin() and HardReset() HardReset() returns Unsupported; Begin() joins a running hub
bool SetBootn(bool) BOOTN held high around a reset, so a stray low level cannot start the bootloader Not driven
bool TakeIntTimestamp(uint32_t&) The time of the H_INTN edge, for exact sample times The time of the Poll() that saw H_INTN
bool IntAsserted() (UART transports) The H_INTN level The first received byte is the time reference
void Log(LogLevel, const char*) One line per lifecycle event or failure Nothing is logged

A hook declared with the wrong signature is a compile error.

Template Parameters
PortYour class derived from HubInterface<Port> that names its kTransport.
LimitsThe sizes of the fixed buffers; DefaultLimits unless you tune them.

Constructor & Destructor Documentation

◆ Bno08x()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
bno08x::Bno08x< Port, Limits >::Bno08x ( Port &  port)
inlineexplicitnoexcept

Bind the driver to a port. No I/O, cannot fail.

Parameters
portThe port; it must outlive the driver.

Member Function Documentation

◆ Advertised()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
const detail::Advert & bno08x::Bno08x< Port, Limits >::Advertised ( ) const
inlinenoexcept
Returns
The limits the hub advertised (zero for a field it did not advertise).

◆ AgeUs()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
uint32_t bno08x::Bno08x< Port, Limits >::AgeUs ( const Event &  ev) const
inlinenoexcept

The age of a sample.

Parameters
evA sample.
Returns
Microseconds between the sample and the last Poll() time, modulo 2^32: an age above 71.6 minutes reads short.

◆ Begin()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< void > bno08x::Bno08x< Port, Limits >::Begin ( const Config &  cfg)
noexcept

Start a session: validate cfg, bring the bus up, reset the hub and begin waiting for its advertisement. Returns at once; Poll() does the rest and Ready() turns true. Called again, it ends every waiting operation with NotInitialized and starts a new session.

Parameters
cfgThe configuration; InvalidArgument (and nothing sent) when cfg.Valid() is false.
Returns
Bus when the port could not start; InvalidArgument for a bad configuration.

◆ ClearCounts()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::ClearCounts ( SensorId  id)
noexcept

Clear a sensor's counters (RM S6.4.2.2).

Parameters
idThe sensor.
Returns
The operation.

◆ ClearDcdAndReset()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::ClearDcdAndReset ( )
noexcept

Clear the DCD and reset the hub (RM S6.4.9).

Returns
The operation.

◆ ClearReorientation()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::ClearReorientation ( )
noexcept

Clear the run-time reorientation (all-zero quaternion).

Returns
The operation.

◆ ConfigureMeCal()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::ConfigureMeCal ( const MeCal &  cal)
noexcept

Configure the motion engine's calibration (RM S6.4.6.1).

Parameters
calThe enables.
Returns
The operation.

◆ EraseFrs()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::EraseFrs ( uint16_t  record)
noexcept

Erase an FRS record (a write of length 0).

Parameters
recordThe record type.
Returns
The operation.

◆ Feature()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< FeatureConfig > bno08x::Bno08x< Port, Limits >::Feature ( SensorId  id) const
noexcept

The driver's shadow of a sensor's feature report (what the hub was last told or said).

Parameters
idThe sensor.
Returns
The shadow, or InvalidArgument for an ID the driver does not know.

◆ FinishSimpleCal()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::FinishSimpleCal ( )
noexcept

Finish the simple calibration; the status is in OpDone.detail.

Returns
The operation.

◆ Flush()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::Flush ( SensorId  id)
noexcept

Force a sensor to flush its batch (RM S6.5.6); completes on the Flush Completed report.

Parameters
idThe sensor.
Returns
The operation.

◆ GetCounts()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::GetCounts ( SensorId  id)
noexcept

Read a sensor's counters (RM S6.4.2.1); four counts in the OpDone values.

Parameters
idThe sensor.
Returns
The operation.

◆ GetFeature()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::GetFeature ( SensorId  id)
noexcept

Ask the hub for a sensor's feature report (RM S6.5.3); the answer updates the shadow.

Parameters
idThe sensor.
Returns
The operation, or an error as for SetFeature().

◆ GetLastTransferLength()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
std::size_t bno08x::Bno08x< Port, Limits >::GetLastTransferLength ( ) const
inlinenoexcept
Returns
The full length of the most recent transfer in bytes (it may exceed kTraceBytes); 0 before the first.

◆ GetMeCal()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::GetMeCal ( )
noexcept

Read the calibration enables (RM S6.4.6.2); they come back in the OpDone values.

Returns
The operation.

◆ GetMetadata()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
const Metadata * bno08x::Bno08x< Port, Limits >::GetMetadata ( SensorId  id) const
noexcept
Parameters
idThe sensor.
Returns
The cached metadata of a sensor, or nullptr when it was not read (or has none).

◆ GetOscillator()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::GetOscillator ( )
noexcept

Ask for the oscillator type (RM S6.4.8): 0 internal, 1 crystal, 2 external clock.

Returns
The operation.

◆ GetState()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
State bno08x::Bno08x< Port, Limits >::GetState ( ) const
inlinenoexcept
Returns
The state of the session.

◆ GetStats()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
const Stats & bno08x::Bno08x< Port, Limits >::GetStats ( ) const
inlinenoexcept
Returns
The counters.

◆ HardReset()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< void > bno08x::Bno08x< Port, Limits >::HardReset ( )
noexcept

Pulse NRST (needs the SetReset hook) and restart the session; pending operations complete with HubReset.

Returns
Unsupported without the hook, NotInitialized before Begin(), Bus on a pin failure.

◆ HubOn()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::HubOn ( )
noexcept

Executable channel "on": leave sleep, enable the configured sensors.

Returns
The operation.

◆ HubSleep()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::HubSleep ( )
noexcept

Executable channel "sleep": only always-on and wake sensors keep running.

Returns
The operation.

◆ Initialize()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::Initialize ( )
noexcept

Re-initialise the sensor hub (RM S6.4.4).

Returns
The operation.

◆ Latest()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< Event > bno08x::Bno08x< Port, Limits >::Latest ( SensorId  id) const
noexcept

The most recent sample of a sensor.

Parameters
idThe sensor.
Returns
The sample, or NotAdvertised when the sensor never reported.

◆ PersistTare()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::PersistTare ( )
noexcept

Persist the last tare to flash (RM S6.4.3.2).

Returns
The operation.

◆ Poll()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
void bno08x::Bno08x< Port, Limits >::Poll ( uint32_t  now_us)
noexcept

Advance the session: read what the hub offers, send the next request, check the time limits. Never waits on the hub; bounded work per call.

Parameters
now_usThe current time of the port's NowUs() counter.

◆ PopEvent()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
bool bno08x::Bno08x< Port, Limits >::PopEvent ( Event &  out)
noexcept

Take the oldest event.

Parameters
[out]outThe event.
Returns
true when one was available.

◆ Product()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
const ProductId & bno08x::Bno08x< Port, Limits >::Product ( ) const
inlinenoexcept
Returns
Entry 0 of the last Product ID request (the first response, RM S6.3.2); valid is false before one arrived. Later entries of the same request are in ProductEntries().

◆ ProductEntries()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
std::span< const ProductId > bno08x::Bno08x< Port, Limits >::ProductEntries ( ) const
inlinenoexcept
Returns
The entries of the last Product ID request, in the order they arrived: at most Config::product_id_entries (ambiguity A33). A response that arrives while no request waits is counted in Stats::product_id_extra and dropped.

◆ ReadFrs()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::ReadFrs ( uint16_t  record,
FrsBuffer &  out 
)
noexcept

Read an FRS record into out (RM S6.3.6).

Parameters
recordThe record type (reg::kFrs*).
outReceives the words; it must outlive the operation.
Returns
The operation.

◆ ReadMetadata()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::ReadMetadata ( SensorId  id)
noexcept

Read a sensor's metadata record (RM S5.1); the result is available from GetMetadata().

Parameters
idThe sensor.
Returns
The operation; Unsupported for a sensor that has no record.

◆ ReadProductId()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::ReadProductId ( )
noexcept

Request the product ID (RM S6.3.1).

Returns
The operation.

◆ Ready()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
bool bno08x::Bno08x< Port, Limits >::Ready ( ) const
inlinenoexcept
Returns
true when operations and events flow (state Ready).

◆ ReportErrors()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::ReportErrors ( uint8_t  severity)
noexcept

Ask for the SH-2 error queue (RM S6.4.1).

Parameters
severityErrors of this severity and higher.
Returns
The operation.

◆ Reset()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::Reset ( )
noexcept

Reset the hub with the executable-channel command (DS p23).

Returns
The operation.

◆ RvcSend()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< void > bno08x::Bno08x< Port, Limits >::RvcSend ( std::span< const uint8_t >  text)
noexcept

UART-RVC host input, guarded (ambiguity A8): the $MIB commands of RM S3.1.2 are not verified. Unsupported unless Config::rvc_inputs_experimental is set.

Parameters
textThe ASCII command including its checksum, for example "$MIB,RESET*87".
Returns
Unsupported, or Bus when the port refused a byte.

◆ SaveDcd()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::SaveDcd ( )
noexcept

Save the dynamic calibration data (RM S6.4.5).

Returns
The operation.

◆ SendWheel()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::SendWheel ( const WheelSample &  s)
noexcept

Report a wheel measurement for dead reckoning (RM S6.4.13).

Parameters
sThe sample.
Returns
The operation.

◆ SetFeature()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::SetFeature ( SensorId  id,
const FeatureConfig &  fc 
)
noexcept

Configure a sensor (Set Feature, RM S6.5.4). Completes when the request is written (or on the hub's reply with Config::set_feature_confirm).

Parameters
idThe sensor.
fcThe common feature report; interval_us 0 turns the sensor off.
Returns
The operation, or Variant, Unsupported, InvalidArgument, Refused, NotInitialized, Busy.

◆ SetMotionIntent()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::SetMotionIntent ( MotionIntent  intent)
noexcept

Tell the interactive calibration the motion intent (BNO086, RM S6.4.12).

Parameters
intentThe intent.
Returns
The operation, or Variant on another chip when Config::strict_variant is set.

◆ SetPeriodicDcd()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::SetPeriodicDcd ( bool  enable)
noexcept

Turn the periodic DCD save on or off (RM S6.4.7).

Parameters
enabletrue to enable.
Returns
The operation.

◆ SetReorientation()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::SetReorientation ( const Quat14 &  q)
noexcept

Set the run-time reorientation (RM S6.4.3.3).

Parameters
qThe quaternion, Q14.
Returns
The operation.

◆ StartSimpleCal()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::StartSimpleCal ( uint32_t  interval_us)
noexcept

Start the simple calibration (RM S6.4.10).

Parameters
interval_usSample interval in microseconds; 0 means the default 10000.
Returns
The operation.

◆ Tare()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::Tare ( AxisMask  axes,
TareBasis  basis 
)
noexcept

Tare now (RM S6.4.3.1).

Parameters
axesThe axes.
basisThe rotation vector it is based on.
Returns
The operation, or InvalidArgument for a mask other than All and ZOnly (see Config::tare_any_mask).

◆ TraceLastTransfer()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
std::size_t bno08x::Bno08x< Port, Limits >::TraceLastTransfer ( std::span< uint8_t >  out) const
inlinenoexcept

Copy the first bytes of the most recent SHTP transfer the hub sent (the 4-byte header first), for bring-up and fault finding. No I/O: the driver never reads the bus on its own account, because a raw read would race the framing engine (handbook KB-CPP-129).

Parameters
[out]outReceives at most kTraceBytes bytes.
Returns
The number of bytes copied; 0 before the first transfer.

◆ WriteFrs()

template<HubPort Port, LimitsLike Limits = DefaultLimits>
Result< OpId > bno08x::Bno08x< Port, Limits >::WriteFrs ( uint16_t  record,
std::span< const uint32_t >  words 
)
noexcept

Write an FRS record (RM S6.3.3 to S6.3.5), then read it back and compare unless Config::frs_verify is false.

Parameters
recordThe record type.
wordsThe record; at most kFrsMaxWords. The driver copies it.
Returns
The operation; the OpDone carries Refused and the hub's status in detail on failure.

The documentation for this class was generated from the following file: