Skip to content

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
enable rotation vector: ok
yaw 71.87 pitch 2.70 roll 22.56 deg (accuracy 3)

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.

git submodule add https://github.com/kokeb-labs-drivers/driver-bno08x.git external/driver-bno08x

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.

my_port.hpp
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

main.cpp
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:

  1. Begin() checks the configuration and starts the session. It returns at once.
  2. 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.
  3. SetFeature() asks for a report; the hub then sends it at the interval you gave.
  4. Reports arrive as EventKind::Sensor events 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 Config field, buffer limits, Kconfig.
  • Examples: the host examples and the MCU example.