libbno055-linux

A C++17 driver for the Bosch BNO055 9-axis IMU on Linux, with first-class ROS 2 integration.

Components

Quick Start

ROS 2 — IMU Driver Node

ros2 launch libbno055_linux bno055_launch.py

Published topics:

• /imu/data — sensor_msgs/Imu (quaternion, angular velocity, linear acceleration)
• /imu/mag — sensor_msgs/MagneticField
• /diagnostics — diagnostic_msgs/DiagnosticArray

For Nav2 Lifecycle Manager:

ros2 launch libbno055_linux bno055_launch.py node_type:=lifecycle

C++17

#include "libbno055-linux/bno055.hpp"

bno055lib::BNO055 imu(0x28, "/dev/i2c-1");
imu.begin(bno055lib::OpMode::NDOF);

auto quat = imu.getQuaternionNoexcept();
if (quat) {
    // quat->w, quat->x, quat->y, quat->z
}

Python

Note: The pip package name and the Python module name differ. Install: pip install libbno055-linux — Import: import libbno055

pip install libbno055-linux

import libbno055
imu = libbno055.BNO055(address=0x28, device="/dev/i2c-1")
imu.begin(libbno055.OpMode.NDOF)
q = imu.get_quaternion()

Rust

cargo add libbno055

Driver Features

Hardware Driver (C++17)

• I2C and UART transport backends with POSIX drivers
• Automatic transport recovery on bus errors and communication failures
• 18-byte sequential burst read for Accel + Mag + Gyro in a single transaction
• Stale Data Deduplication Filter — eliminates duplicate frame publishing in ROS 2
• Configurable sensor output data rates in AMG mode (up to Accel 1 kHz / Gyro 2 kHz ODR)
• Optional background polling thread for continuous non-blocking reads
• Calibration management — save and load sensor offsets to/from file

Empirical Benchmark (RDK X5 Hardware Validation)

Tested out-of-the-box on RDK X5 (Sunrise RDK) via standard Linux /dev/i2c-5 interface with zero tuning or custom OS setup:

File truncated at 100 lines see the full file

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.9.0] - 2026-07-30

Added

• Stale Data Deduplication Filter in ROS 2: Added raw 18-byte sequential burst read comparison (std::memcmp) to BNO055PublisherNode and BNO055LifecyclePublisherNode. Eliminates duplicate frame publishing when polling rate exceeds sensor output data rate.
• Empirical Hardware Benchmarks in README: Documented out-of-the-box performance metrics on RDK X5 (Sunrise RDK) (82.57 Hz sampling rate, 1.99 ms I/O latency, 0.73 ms stddev jitter).

Changed

• benchmark_imu Utility Improvements: Added support for selecting NDOF, IMUPlus, or AMG modes via command line arguments, and added automatic polling fallback when GPIO interrupt sysfs pin is unavailable.

[1.8.1] - 2026-07-29

Fixed

• ROS 2 Lifecycle component compilation: Fixed missing tf2_ros and geometry_msgs dependency links for bno055_ros2_lifecycle_components library in CMakeLists.txt.

[1.8.0] - 2026-07-29

Added

• getAllDataNoexcept() burst read API: New public method that reads all 8 sensor outputs (accel, mag, gyro, euler, quaternion, linear accel, gravity, temperature) in a single 45-byte I2C transaction (registers 0x08–0x34). Reduces I2C transactions by 87.5% vs individual reads.
• startAsyncReading() optimized: Background polling loop now uses getAllDataNoexcept() (1 burst) instead of 8 separate get*OrDefault() calls, dramatically reducing per-cycle latency.
• Python async bindings: Added start_async_reading, stop_async_reading, start_raw_async_reading, stop_raw_async_reading, start_interrupt_driven_reading, stop_interrupt_driven_reading, set_axis_remap, set_axis_sign, and get_all_data to Python. All async callbacks are GIL-safe (py::gil_scoped_acquire inside C++ thread lambdas).
• Python AllData, AxisMapConfig, AxisMapSign: New types exposed to Python.
• Rust wrapper parity: Added 10 missing safe wrapper methods to BNO055 struct: set_ext_crystal_use, get_linear_acceleration, get_gravity, get_temperature, is_fully_calibrated, save_calibration_file, load_calibration_file, enable_auto_calibration, disable_auto_calibration, enter_suspend_mode, enter_normal_mode.
• rust/cpp/ auto-sync: CMake POST_BUILD command on libbno055-linux target automatically syncs all 6 bundled C++ source/header files to rust/cpp/, preventing source drift.
• libgpiod v2 GPIO IRQ support: Migrated startInterruptDrivenReading() from deprecated /sys/class/gpio sysfs interface to modern libgpiod v2 character device API. Sysfs fallback retained via #else for systems without libgpiod.
• CI Arm64 matrix: Added ubuntu-24.04-arm runner to build-and-test job for native arm64 Python wheel and Rust crate testing.
• CI libgpiod-dev: All CI jobs (build, coverage, ROS 2) now install libgpiod-dev.

Fixed

• ACC_CONFIG overclocking bug: Corrected register value from 0x0F (62.5 Hz BW + ±16g, wrong) to 0x1D (1000 Hz BW + ±4g) in AMG mode. Bit layout documented per datasheet Tables 4-3 and 4-4.
• Software reset timing: Post-reset wait corrected from 50 ms to 600 ms pre-poll + 500 ms poll budget, matching the BNO055 datasheet-specified ~650 ms POR boot time (Section 3.4).
• setMode() transition timing: Replaced hardcoded 30 ms with datasheet-precise values: 19 ms (any mode → CONFIGMODE) and 7 ms (CONFIGMODE → any mode), per Section 3.6.1.
• Redundant delays removed: Eliminated unnecessary extra sleep_for calls from setAxisRemap(), setAxisSign(), and setExtCrystalUse().
• Register enum completeness: Added missing INT_MSK (0x0F) and INT_EN (0x10) Page 1 interrupt configuration registers with full bit-layout documentation.
• GYR_CONFIG_0 comment: Corrected misleading “ODR=2000Hz” to “Range=2000dps, Bandwidth=523Hz”.
• CI clang-format auto-commit scope: Restricted to ubuntu-latest only to prevent duplicate commits across the now-expanded OS matrix.

[1.7.2] - 2026-07-27

Fixed

• ROS 2 Distro Compatibility: Fixed service QoS profile setup to be compatible with ROS 2 Humble, Jazzy, Kilted, and Lyrical using compile-time version checks.
• CMake Modernization: Replaced deprecated ament_target_dependencies with standard CMake target_link_libraries to resolve build errors on ROS 2 Lyrical.
• Python Bindings: Corrected source file compilation paths in setup.py to fix macOS wheel build failures.

[1.7.1] - 2026-07-22

Added & Performance

• ROS 2 CallbackGroup Isolation: Fully isolated high-frequency control/sensor callbacks from 1Hz diagnostics and services using dedicated MutuallyExclusive CallbackGroups across all driver and controller nodes.
• MultiThreadedExecutor: Upgraded all standalone Node main() entrypoints to rclcpp::executors::MultiThreadedExecutor for non-blocking parallel execution.
• Slew-Rate Limiter: Added max_slew_rate parameter to HeadingController to constrain angular acceleration, protecting motor gears and preventing wheel slip shock.
• Outlier Validation: Added isValidQuat helper to reject corrupted or NaN/Inf IMU orientation data before PID calculation.
• Real-time Priority Elevation: Added trySetRealtimePriority helper to gracefully elevate Linux thread scheduling to SCHED_FIFO (Priority 80-85).

[1.7.0] - 2026-07-22

Added

• Heading PID Controller (bno055lib::HeadingController): Production-grade, zero-allocation C++17 heading controller for mobile robot straight-line driving and orientation lock.
• Theoretical Optimal Control Architecture: Upgraded with Trapezoidal (Tustin) Rule Integration, 1st-order Low-Pass Filtered Gyro Rate D-term, Kinematic Feedforward (FF) coupling, and Micro-Deadband smoothing.
• Production ROS 2 Nodes:
  • bno055_heading_control_node: Standard Composable Component node with Zero-Copy transport.
  • bno055_lifecycle_heading_control_node: Managed Lifecycle node for Nav2 lifecycle_manager integration.
• Safety Watchdog Timeout: Automatic Zero Velocity command generation when input velocity (cmd_vel_in) is lost to prevent runaway accidents.
• IMU Fail-Safe Passthrough: Automatic 100% velocity passthrough when IMU data is offline or disconnected, ensuring robot movement never stops.
• Direct Quaternion Update: Overloaded API allowing callers to pass Quat directly without manual Euler conversion.
• Dedicated Parameter YAML: Added config/heading_control_params.yaml and simplified 1-command startup.

[1.6.2] - 2026-07-22

Fixed

• Rust crates.io Publish: Fixed a dirty git tree issue in GitHub Actions by explicitly updating Cargo.lock alongside Cargo.toml version bumps.

[1.6.1] - 2026-07-22

Fixed

File truncated at 100 lines see the full file