Quickstart¶
Run the driver on your PC first, with no hardware; then read the rotation vector from your MCU: wire the chip,
write a small port class, call Begin() and Poll().
Datasheet sections this page relies on
From CEVA 1000-3927 1.17:
- Getting started: establishing contact and reading: 5 Getting started with BNO08X, p. 43
All of them, with the driver API for each: Datasheet map.
Try it on your PC¶
examples/host/ runs the real driver against a model of the hub, on every
transport. From the repository root, with CMake and a C++20 compiler:
cmake -S examples/host -B build-example
cmake --build build-example
./build-example/bno08x_example_i2c_quickstart
The model produces arbitrary data, so your angles differ. The calls are the ones below; only the port differs on an MCU. CI builds and runs every example.
1. Wire it¶
For I2C at address 0x4A, with the hub as a slave on your MCU's I2C bus:
| MCU | BNO08x pin | Notes |
|---|---|---|
| I2C SCL | 19 H_SCL | Pull-up to VDDIO |
| I2C SDA | 20 H_SDA | Pull-up to VDDIO |
| GPIO input | 14 H_INTN | Active low: a message is waiting. Required for I2C and SPI |
| GPIO output | 11 NRST | Optional but recommended: the driver resets the hub with it |
| GND | 5 PS1, 6 PS0, 17 SA0 | Strap pins, sampled at reset: I2C, address 0x4A |
| 3.3 V | 3 VDD, 28 VDDIO | 100 nF each; 100 nF on pin 9 (CAP) to GND |
| 3.3 V through 10 k | 4 BOOTN | A low level at reset starts the bootloader |
The Hardware page has the full pin list, the other three transports and the reference circuits.
2. Add the driver¶
Add the repository as a submodule and link the bno08x::bno08x CMake target. Installation
covers CMake on any MCU, the installed package and ESP-IDF.
3. Write the port¶
The port is the only platform code: it brings the bus up, moves bytes, reads H_INTN and gives the time. Replace the
platform_* calls with your SDK's.
class MyPort : public bno08x::HubInterface<MyPort> {
public:
static constexpr bno08x::Transport kTransport = bno08x::Transport::I2c;
// Bring the bus and the pins up once; later calls return true at once.
bool EnsureInitialized() noexcept {
if (!ready_) {
ready_ = platform_i2c_init();
}
return ready_;
}
// A free-running microsecond counter. The driver only subtracts times, so a wrap is fine.
uint32_t NowUs() noexcept {
return platform_micros();
}
// One write transaction: START, address + W, the bytes, STOP.
bool I2cWrite(uint8_t addr, const uint8_t* data, std::size_t len) noexcept {
return platform_i2c_write(addr, data, len);
}
// One read transaction: START, address + R, `len` bytes, STOP. Never blocks on a clock stretch
// you can avoid: the driver reads only after H_INTN went low.
bool I2cRead(uint8_t addr, uint8_t* data, std::size_t len) noexcept {
return platform_i2c_read(addr, data, len);
}
// true while H_INTN is low: the hub has a cargo waiting.
bool IntAsserted() noexcept {
return platform_int_low();
}
// Optional: the driver resets the hub with this pin when you provide it.
bool SetReset(bool level) noexcept {
platform_nrst(level);
return true;
}
private:
bool ready_ = false;
};
Porting explains each hook, the optional ones and the other transports.
4. Run it¶
void RunSensor() {
static MyPort port;
static bno08x::Bno08x<MyPort> hub(port); // no I/O yet
const bno08x::Config cfg{}; // BNO085 on I2C 0x4A
if (const auto r = hub.Begin(cfg); !r.ok()) {
std::printf("Begin: %s\n", bno08x::ToString(r.error));
return;
}
bool requested = false;
for (;;) {
hub.Poll(port.NowUs()); // every few milliseconds: reads, writes and time-outs all happen here
if (hub.Ready() && !requested) {
bno08x::FeatureConfig fc{};
fc.interval_us = 20000; // 50 Hz
requested = hub.SetFeature(bno08x::SensorId::RotationVector, fc).ok();
}
bno08x::Event e{};
while (hub.PopEvent(e)) {
if (e.kind == bno08x::EventKind::Sensor) {
const auto eu = bno08x::ToEulerCentiDeg(e.v[0], e.v[1], e.v[2], e.v[3]);
std::printf("yaw %" PRId32 " pitch %" PRId32 " roll %" PRId32 " (centi-degrees)\n",
static_cast<int32_t>(eu.yaw), static_cast<int32_t>(eu.pitch),
static_cast<int32_t>(eu.roll));
}
}
}
}
What happens:
Begin()checks the configuration and starts the session. It returns at once.- Each
Poll()does a little: it pulses NRST, waits for the hub's advertisement and its start-up messages, and then reads whatever the hub has queued.Ready()turns true when the hub is up. SetFeature()asks for a report; the hub then sends it at the interval you gave.- Reports arrive as
EventKind::Sensorevents with the values in the report's own units, a timestamp and the accuracy.ToEulerCentiDeg()turns a rotation vector into angles with integer arithmetic.
If it does not work¶
| Symptom | First thing to check |
|---|---|
Ready() never turns true; state Faulted |
NRST, power and H_INTN (Troubleshooting) |
Begin() returns InvalidArgument |
A Config field is out of range; Config::Valid() says |
SetFeature() returns Variant |
You asked for a feature the configured chip lacks |
| No sensor events | The interval, and that you call Poll() often enough |
Next¶
- API guide: operations, events, errors.
- Sensors: every report and its units.
- Configuration: every
Configfield, buffer limits, Kconfig. - Examples: the host examples and the MCU example.