libbno055-linux API Reference

Table of Contents

Namespaces & Types

namespace bno055lib {
    // 3D coordinate vector (used for accelerometer, gyroscope, magnetometer, euler, gravity, linear accel)
    struct Vector3 {
        float x;
        float y;
        float z;
    };

    // 3D orientation quaternion representation
    struct Quaternion {
        float w; // Real part
        float x; // Imaginary X
        float y; // Imaginary Y
        float z; // Imaginary Z
    };

    // Transport interface representing I/O connection to the BNO055 hardware
    class Transport {
    public:
        virtual ~Transport() = default;
        virtual bool open() = 0;
        virtual void close() = 0;
        virtual bool isOpen() const = 0;
        virtual bool write8(uint8_t reg, uint8_t value) = 0;
        virtual bool writeLen(uint8_t reg, const uint8_t* buffer, uint8_t len) = 0;
        virtual bool read8(uint8_t reg, uint8_t& value) = 0;
        virtual bool readLen(uint8_t reg, uint8_t* buffer, uint8_t len) = 0;
    };

    // Mock implementation of Transport for hardware-independent verification
    class MockTransport : public Transport {
    public:
        MockTransport();
        void setRegister(uint8_t reg, uint8_t value);
        void setRegister16LE(uint8_t reg, int16_t value);
        void setFailOpen(bool fail);
        void setFailReads(bool fail);
        void setFailWrites(bool fail);
        uint32_t getWriteCount() const;
        uint32_t getReadCount() const;
        void reset();
    };

    // Bundled structure representing all sensor physical data
    struct AllData {
        Vector3 accel;
        Vector3 mag;
        Vector3 gyro;
        Vector3 euler;
        Vector3 linear_accel;
        Vector3 gravity;
        Quaternion quat;
        int8_t temp;
    };
    using AsyncDataCallback = std::function<void(const AllData& data)>;
    
    // Binary calibration offsets (22 bytes total) for saving/restoring sensor profile
    struct Offsets {
        int16_t accel_offset_x, accel_offset_y, accel_offset_z;
        int16_t mag_offset_x, mag_offset_y, mag_offset_z;
        int16_t gyro_offset_x, gyro_offset_y, gyro_offset_z;
        int16_t accel_radius, mag_radius;
    };

    // Dynamic calibration status of the sensor (0 = uncalibrated, 3 = fully calibrated)
    struct CalibrationStatus {
        uint8_t sys;   // Overall system calibration status [0-3]
        uint8_t gyro;  // Gyroscope calibration status [0-3]
        uint8_t accel; // Accelerometer calibration status [0-3]
        uint8_t mag;   // Magnetometer calibration status [0-3]
        
        // Returns true if gyro, accel, and mag are fully calibrated (status == 3)
        bool isFullyCalibrated() const;
    };

    // Cumulative telemetry diagnostics tracking error rates for health monitoring
    struct Diagnostics {
        uint32_t write_failures;      // Number of failed register write transactions
        uint32_t read_failures;       // Number of failed register read transactions
        uint32_t reconnect_attempts;  // Number of I2C bus auto-reconnect triggers
    };

    // Operating mode configuration
    enum class OpMode : uint8_t {
        Config = 0X00,          // Configuration mode (required to write map/sign/crystal settings)
        AccOnly = 0X01,         // Non-fusion Accelerometer only
        MagOnly = 0X02,         // Non-fusion Magnetometer only
        GyroOnly = 0X03,        // Non-fusion Gyroscope only
        AccMag = 0X04,          // Non-fusion Accelerometer + Magnetometer
        AccGyro = 0X05,         // Non-fusion Accelerometer + Gyroscope
        MagGyro = 0X06,         // Non-fusion Magnetometer + Gyroscope
        AMG = 0X07,             // Non-fusion Accelerometer + Magnetometer + Gyroscope (raw outputs)
        IMUPlus = 0X08,         // 6-axis Fusion (Acc + Gyro). Yaw relative to boot position. Recommended indoors.
        Compass = 0X09,         // 6-axis Fusion (Acc + Mag). Absolute Yaw.
        M4G = 0X0A,             // 6-axis Fusion (Mag + Gyro).
        NDOF_FMC_Off = 0X0B,    // 9-axis Fusion (Acc + Mag + Gyro) with Fast Magnetometer Calibration disabled
        NDOF = 0X0C             // 9-axis Fusion (Acc + Mag + Gyro) with FMC enabled. Absolute Yaw (North-referenced).
    };

    enum class LogLevel { Debug, Info, Warning, Error };
    using LoggerCallback = std::function<void(LogLevel level, std::string_view message)>;
}

Class BNO055

All functions in the BNO055 class are thread-safe and protect access to the underlying I2C bus using internal mutexes.

Lifecycle

  • explicit BNO055(uint8_t i2c_address = 0x28, std::string_view i2c_device = “/dev/i2c-1”)

    • Parameters:

      • i2c_address: uint8_t. The I2C slave address of the BNO055 (typically 0x28 or 0x29).

      • i2c_device: std::string_view. The Linux file path to the I2C adapter (e.g., /dev/i2c-1).

    • Returns: None (Constructor).

    • Description: Creates a BNO055 handler. If compiled on macOS/Windows, it falls back to the mock mode and accepts any mock device name.

  • explicit BNO055(std::unique_ptr transport)

    • Parameters:

      • transport: std::unique_ptr<Transport>. Custom transport implementation (e.g., a MockTransport instance).

    • Returns: None (Constructor).

    • Description: Creates a BNO055 handler using a custom transport layer. Extremely useful for unit testing (dependency injection) and porting.

  • bool begin(OpMode mode = OpMode::NDOF)

    • Parameters:

      • mode: OpMode. The target operation mode to start in.

    • Returns: bool. true if initialization, self-test verification, and mode transition succeeded; false on boot timeouts or I2C failures.

    • Description: Power-cycles the sensor, verifies the Chip ID, configures default Axis Maps and Unit settings, and spawns the background auto-recovery thread.

  • bool reset()

    • Parameters: None.

    • Returns: bool. true if reset and mode restoration succeeded; false on failure.

    • Description: Triggers a software hardware-reset using the SYS_TRIGGER register and completely re-initializes the device into the previously active operating mode. Useful for recovery from external hardware lockups.

Configuration

  • void setMode(OpMode mode)

    • Parameters:

      • mode: OpMode. The target operation mode to switch into.

    • Returns: void.

    • Exceptions: Throws bno055lib::IMUError on permanent I2C communication failures.

    • Description: Switches the operating mode of the sensor. Handles transition delay requirements automatically.

  • OpMode getMode()

    • Parameters: None.

    • Returns: OpMode. The active operation mode currently registered on the sensor.

    • Exceptions: Throws bno055lib::IMUError on I2C failure.

  • void setAxisRemap(AxisMapConfig config)

    • Parameters:

      • config: AxisMapConfig. The remap configuration matching the sensor’s mounting orientation.

    • Returns: void.

    • Exceptions: Throws bno055lib::IMUError on I2C failure.

  • void setAxisSign(AxisMapSign sign)

    • Parameters:

      • sign: AxisMapSign. The axis sign configuration to adjust rotation/acceleration directions.

    • Returns: void.

    • Exceptions: Throws bno055lib::IMUError on I2C failure.

  • void setExtCrystalUse(bool use_xtal)

    • Parameters:

      • use_xtal: bool. Set to true to use the external 32.768kHz crystal oscillator for enhanced fusion stability.

    • Returns: void.

    • Exceptions: Throws bno055lib::IMUError on I2C failure.

Sensor Data (Throwing APIs)

These functions query raw data registers and convert them to SI units. They throw bno055lib::IMUError on permanent I2C communication loss.

  • Vector3 getAccelerometer()

    • Parameters: None.

    • Returns: Vector3. 3-axis acceleration in meters per second squared (m/s^2).

    • Exceptions: Throws bno055lib::IMUError.

  • Vector3 getMagnetometer()

    • Parameters: None.

    • Returns: Vector3. 3-axis magnetic field strength in microteslas (uT).

    • Exceptions: Throws bno055lib::IMUError.

  • Vector3 getGyroscope()

    • Parameters: None.

    • Returns: Vector3. 3-axis angular velocity in radians per second (rad/s).

    • Exceptions: Throws bno055lib::IMUError.

  • Vector3 getEulerAngles()

    • Parameters: None.

    • Returns: Vector3. Roll, Pitch, Yaw in radians (rad). Mapping: x = Roll, y = Pitch, z = Yaw.

    • Exceptions: Throws bno055lib::IMUError.

  • Vector3 getLinearAcceleration()

    • Parameters: None.

    • Returns: Vector3. 3-axis linear acceleration (accelerometer excluding gravity) in m/s^2.

    • Exceptions: Throws bno055lib::IMUError.

  • Vector3 getGravity()

    • Parameters: None.

    • Returns: Vector3. 3-axis gravity vector in m/s^2.

    • Exceptions: Throws bno055lib::IMUError.

  • Quaternion getQuaternion()

    • Parameters: None.

    • Returns: Quaternion. Normalized 3D orientation unit quaternion (w, x, y, z).

    • Exceptions: Throws bno055lib::IMUError.

  • int8_t getTemperature()

    • Parameters: None.

    • Returns: int8_t. Chip temperature in degrees Celsius (C).

    • Exceptions: Throws bno055lib::IMUError.

  • RawSensorData getRawSensorData()

    • Parameters: None.

    • Returns: RawSensorData. Struct containing converted raw accelerometer, magnetometer, and gyroscope vectors.

    • Exceptions: Throws bno055lib::IMUError.

    • Description: Sequentially reads 18 bytes of raw sensor data in a single burst I2C transaction, minimizing bus occupancy.

Sensor Data (Exception-free / noexcept APIs)

These companion APIs perform the exact same register queries and conversions but never throw exceptions.

  • std::optional<Vector3> getAccelerometerNoexcept() noexcept

  • std::optional<Vector3> getMagnetometerNoexcept() noexcept

  • std::optional<Vector3> getGyroscopeNoexcept() noexcept

  • std::optional<Vector3> getEulerAnglesNoexcept() noexcept

  • std::optional<Vector3> getLinearAccelerationNoexcept() noexcept

  • std::optional<Vector3> getGravityNoexcept() noexcept

  • std::optional<Quaternion> getQuaternionNoexcept() noexcept

  • std::optional<int8_t> getTemperatureNoexcept() noexcept

  • std::optional<RawSensorData> getRawSensorDataNoexcept() noexcept

    • Parameters: None.

    • Returns: std::optional<T>. Contains the requested struct on success; std::nullopt on communication failure.

    • Description: Safety-hardened read path that increments I2C diagnostic counters upon failure without generating CPU exceptions.

    • Parameters: None.

    • Returns: The requested struct directly (Vector3, Quaternion, or int8_t). On temporary bus drops, returns the last cached valid frame (or zero/identity).

Diagnostics & Calibration

  • Diagnostics getDiagnostics() const noexcept

    • Parameters: None.

    • Returns: Diagnostics. The telemetry diagnostic struct containing I2C read/write error counts and reconnection attempts.

  • CalibrationStatus getCalibrationStatus()

    • Parameters: None.

    • Returns: CalibrationStatus. Current calibration state values (0 to 3) for the system, gyro, accelerometer, and magnetometer.

    • Exceptions: Throws bno055lib::IMUError on I2C failure.

  • bool getSensorOffsets(Offsets& offsets)

    • Parameters:

      • offsets: Offsets& (output). Structure to store the retrieved calibration offsets.

    • Returns: bool. true if offsets were read and stored successfully; false on I2C failure.

  • bool getSensorOffsets(std::array<uint8_t, 22>& calib_data)

    • Parameters:

      • calib_data: std::array<uint8_t, 22>& (output). Raw byte array to store the 22 bytes of offsets.

    • Returns: bool. true if read succeeded; false on failure.

  • void setSensorOffsets(const Offsets& offsets)

    • Parameters:

      • offsets: const Offsets&. Calibration offset parameters to load into the sensor registers.

    • Returns: void.

    • Exceptions: Throws bno055lib::IMUError on failure.

    • Description: Writes offsets using a single-batch sequential I2C write transaction to minimize bus occupation.

  • void setSensorOffsets(const std::array<uint8_t, 22>& calib_data)

    • Parameters:

      • calib_data: const std::array<uint8_t, 22>&. Raw 22-byte array containing calibration offsets.

    • Returns: void.

    • Exceptions: Throws bno055lib::IMUError on failure.

  • bool saveCalibrationFile(std::string_view filepath)

    • Parameters:

      • filepath: std::string_view. Destination file path to save the 22-byte profile (e.g., calib.bin).

    • Returns: bool. true if offsets were read and successfully written to disk; false on I2C or file I/O errors.

  • bool loadCalibrationFile(std::string_view filepath)

    • Parameters:

      • filepath: std::string_view. Source path of the 22-byte binary profile.

    • Returns: bool. true if file read, register upload, and cache storage succeeded; false on file I/O or I2C errors.

    • Description: Uploads calibration to the sensor and caches it locally so it can be automatically restored during an I2C hot-reconnect recovery.

Power Management

  • void enterSuspendMode()

    • Parameters: None.

    • Returns: void.

    • Exceptions: Throws bno055lib::IMUError on failure.

    • Description: Places the sensor into suspend mode to reduce power consumption. Suspends accelerometer, gyroscope, and magnetometer blocks.

  • void enterNormalMode()

    • Parameters: None.

    • Returns: void.

    • Exceptions: Throws bno055lib::IMUError on failure.

    • Description: Awakes the sensor from suspend mode back to active normal operation.

Logging

  • void setLogger(LoggerCallback callback)

    • Parameters:

      • callback: LoggerCallback. Callback function of signature void(LogLevel level, std::string_view message).

    • Returns: void.

    • Description: Hooks a custom logging function (such as std::cout or ROS 2 logging macros) to direct library diagnostics, warnings, and reconnect traces.

Asynchronous Reading

  • bool startAsyncReading(double rate_hz, AsyncDataCallback callback)

    • Parameters:

      • rate_hz: double. The target frequency in Hz to query the sensor data.

      • callback: AsyncDataCallback. Callback function executed on the background thread whenever new measurements are gathered.

    • Returns: bool. true if background polling thread successfully spawned; false if already running.

    • Description: Spawns a high-priority background polling thread that sleeps to minimize timing jitter. Calls callback with a thread-safe copy of AllData.

  • void stopAsyncReading()

    • Parameters: None.

    • Returns: void.

    • Description: Signals the background async thread to terminate and blocks until it joins.

  • bool startRawAsyncReading(double rate_hz, RawAsyncDataCallback callback)

    • Parameters:

      • rate_hz: double. Polling frequency.

      • callback: RawAsyncDataCallback. Callback executing with raw 3-axis readings.

    • Returns: bool.

    • Description: Spawns a lightweight async thread polling only raw IMU data via burst transaction.

  • void stopRawAsyncReading()

    • Parameters: None.

    • Returns: void.

    • Description: Stops the raw async polling thread.

Interrupt Driven Reading (IRQ)

  • bool startInterruptDrivenReading(int gpio_pin, RawAsyncDataCallback callback)

    • Parameters:

      • gpio_pin: int. Linux GPIO pin connected to the BNO055 INT pin.

      • callback: RawAsyncDataCallback. Handler triggered on interrupt.

    • Returns: bool. true if background IRQ waiting thread spawned.

    • Description: Registers a rising-edge trigger on the specified Linux GPIO pin. When BNO055 triggers INT, the kernel interrupt immediately unblocks POSIX poll() on the GPIO sysfs file descriptors, firing the callback with raw burst readings at sub-millisecond latency.

  • void stopInterruptDrivenReading()

    • Parameters: None.

    • Returns: void.

    • Description: Stops the interrupt-driven IRQ monitoring thread.

Automatic Calibration

  • void enableAutoCalibration(std::string_view filepath)

    • Parameters:

      • filepath: std::string_view. The binary calibration profile path to load from on begin() and save to.

    • Returns: void.

    • Description: Activates automated calibration loading on startup and writes offsets back to the disk target once fully calibrated status is reached.

  • void disableAutoCalibration()

    • Parameters: None.

    • Returns: void.

    • Description: Deactivates the automated calibration load/save helper logic.

Utilities (Class-External)

  • Vector3 toEulerDegrees(const Quaternion& q) noexcept

    • Parameters:

      • q: const Quaternion&. The normalized unit quaternion representation of orientation.

    • Returns: Vector3. Roll, Pitch, and Yaw in degrees (Mapping: x = Roll [-180, 180], y = Pitch [-90, 90], z = Yaw [0, 360)).

    • Description: Utility function to convert Quaternion orientation into human-readable Euler angles in degrees (now executing on single-precision float elements).