libbno055-linux

View the Official Web Documentation (API, Architecture, Integration Guides)

C++17 BNO055 library and ROS 2 nodes for Linux.

Features

• Standalone C++17 library: Link natively via CMake without ROS dependencies.
• Native I2C & UART Support: Fully implements the BNO055 binary protocol for both I2C (/dev/i2c-*) and USB-to-UART (/dev/ttyUSB*) using fast, low-level POSIX APIs.
• Full Telemetry Parity: Publishes standard IMU data, raw unfiltered data (imu/raw), gravity vectors (imu/gravity), and calibration status via JSON (~/calib_status) and diagnostic_msgs::msg::DiagnosticStatus (~/status).
• Hardware Reset & Calibration Services: Provides ~/reset for software-triggered hardware resets and ~/calibration_request for dynamic calibration state queries.
• ROS 2 nodes: Provides high-performance standard and lifecycle node interfaces.
• Automatic Recovery: Implements automatic recovery for EIO faults, clock stretching issues, and UART BUS_OVER_RUN errors.
• No heap allocations: Avoids dynamic memory allocation in hot sensor readout paths.
• Zero-copy publishers: Implements zero-copy memory transport (std::unique_ptr) for ROS 2 publishers.
• Built-in I2C mocking: Provides built-in I2C mocking for compilation and testing on macOS/Windows.
• High-Performance EKF Burst Read (New): Sequentially reads 18 bytes of raw sensor outputs (Accel, Mag, Gyro) in a single transaction, reducing bus latency by 3x.
• Linux GPIO Interrupt (IRQ) Driven Mode (New): Bypasses polling loops. Detects rising edge events on the physical INT pin using Linux poll(), triggering callbacks at sub-millisecond latency.
• Single-Precision float Optimizations (New): Swapped double-precision floats to 32-bit floats across all vectors and quaternion math to unlock hardware FPU speeds on ARM processors (e.g., Raspberry Pi).

High-Performance & State Estimation (EKF) Features

If you are developing a custom state estimator (Extended Kalman Filter / Complementary Filter) or using robot_localization, raw sensor throughput and latency determinism are critical.

libbno055-linux provides:

1. 18-Byte Burst Read: Reads Accelerometer, Magnetometer, and Gyroscope raw variables in a single sequential bus transaction (~450µs at 400kHz I2C).
2. High-Frequency Polling: Low-jitter background polling threads up to 200Hz.
3. GPIO Interrupt (IRQ) Driven Mode: POSIX poll() edge event detection on the physical INT pin for sub-millisecond response.

[!TIP] Complete C++ code examples for these APIs, EKF configuration files (ekf.yaml) for ROS 2 robot_localization, and kernel real-time scheduling setup are located in the Advanced Integration & Kernel Tuning Guide. For function signatures and types, see the API Reference.

Quick Start

A. Standalone C++ (No-ROS)

1. Build and Install:

   sudo apt update && sudo apt install -y build-essential cmake
   git clone https://github.com/lazytatzv/libbno055-linux.git
   cd libbno055-linux && mkdir build && cd build
   cmake .. -DBUILD_TESTING=OFF -DBUILD_EXAMPLES=ON
   make -j$(nproc) && sudo make install
   

1. Write your code (main.cpp):

```cpp #include <libbno055-linux/bno055.hpp> #include #include

int main() { // Initialize via I2C (Default) // bno055lib::BNO055 imu(0x28, “/dev/i2c-1”);

   // OR Initialize via UART
   bno055lib::BNO055::UARTConfig uart_cfg;
   uart_cfg.port = "/dev/ttyUSB0";
   uart_cfg.baudrate = 115200;
   bno055lib::BNO055 imu(uart_cfg);

   // Initialize in NDOF fusion mode
   if (!imu.begin(bno055lib::OpMode::NDOF)) {
       std::cerr << "Sensor initialization failed!\n";
       return 1;
   }

   // Configure automatic calibration loading & saving
   imu.enableAutoCalibration("/etc/robot_config/bno055_offsets.bin");

   for (int i = 0; i < 10; ++i) {
       // Orientation (Euler Angles converted from Quaternion)
       if (auto q = imu.getQuaternionNoexcept()) {
           auto euler = bno055lib::toEulerDegrees(*q);
           std::cout << "Euler (deg): Roll=" << euler.x << " Pitch=" << euler.y << " Yaw=" << euler.z << "\n";
       }

       // Acceleration
       if (auto acc = imu.getAccelerometerNoexcept()) {
           std::cout << "Accel (m/s^2): X=" << acc->x << " Y=" << acc->y << " Z=" << acc->z << "\n";
       }

       // Calibration Status
       auto calib = imu.getCalibrationStatus();
       std::cout << "Calibration: SYS=" << static_cast<int>(calib.sys) 
                 << " GYRO=" << static_cast<int>(calib.gyro) << "\n";

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.3.2] - 2026-07-16

Added

• Added ~/reset service to hardware-reset the IMU and auto-recover the state.
• Added ~/status (diagnostic_msgs/DiagnosticStatus) publisher for full compatibility with standard ROS 2 diagnostics systems.
• Added macOS and Windows build support for POSIX-based UART driver mock compilation.

[1.3.1] - 2026-07-16

Fixed

• Fixed duplicate variable declaration in publisher node causing compilation failure.
• Fixed clang-format style violations in C++ files.

[1.3.0] - 2026-07-16

Added

• Added imu/raw (sensor_msgs/Imu) publisher for unfiltered accelerometer and gyroscope data.
• Added imu/gravity (geometry_msgs/Vector3) publisher for gravity vector.
• Added imu/calib_status (std_msgs/String) publisher to output calibration status as JSON.
• Added ~/calibration_request (std_srvs/Trigger) service to query calibration status dynamically.
• Implemented native C++ UART communication backend for USB-to-UART bridges.
• Added new ROS parameters for UART: connection_type, uart_port, uart_baudrate, uart_timeout.

[1.2.3] - 2026-07-16

Fixed

• Fixed missing member variable declarations for mag_publisher_ and temp_publisher_ in the lifecycle node.
• Removed stray python scripts that were accidentally committed.

[1.2.2] - 2026-07-16

Fixed

• Fixed CMake keyword signature mismatch (target_link_libraries vs ament_target_dependencies) for ROS 2 nodes.

[1.2.1] - 2026-07-16

Fixed

• Fixed ROS 2 CMake target linking by using ament_target_dependencies instead of target_link_libraries to prevent build failures on the ROS Buildfarm.

[1.2.0] - 2026-07-15

Added

• Complete Debian packaging support (CPack and debian/ directory) for standalone PPA release without ROS dependencies.
• Zero-copy intra-process communication enabled by default for ROS 2 nodes.

Changed

• Refactored core library to enforce deterministic, noexcept execution natively (removed *OrDefault APIs in favor of std::optional-returning *Noexcept APIs).
• Unified standard and high-performance ROS 2 nodes into a single, highly optimized node.
• Re-written documentation to focus strictly on factual, technical features rather than buzzwords.

[1.1.1] - 2026-07-10

Changed

• Updated maintainer email to GitHub no-reply address in package.xml.

[1.1.0] - 2026-07-10

Added

• Three ROS 2 publisher nodes (bno055_publisher_node, bno055_perf_publisher_node, and bno055_lifecycle_publisher_node) in src/ros2/.
• ROS 2 Python Launch file (launch/bno055_launch.py) and parameters configuration file (config/bno055_params.yaml) to dynamically configure and launch the nodes.
• Custom parameterization for QoS overrides (qos_reliability, qos_history_depth), EKF covariances, and startup calibration autoloading (calibration_file).
• Managed diagnostic telemetry publishing to /diagnostics using diagnostic_msgs for real-time monitoring of I2C health and calibration levels.
• Mock-based ROS 2 node integration tests using GoogleTest in tests/test_ros2_nodes.cpp.
• Formatter validation (clang-format) checks in the GitHub Actions CI pipeline.
• Flexible GTest offline fallback resolution in CMakeLists.txt for offline environments (e.g., ROS buildfarms).
• Comprehensive ROS 2 troubleshooting guides in docs/TROUBLESHOOTING.md.

Changed

• Refactored ROS 2 nodes to eliminate redundant logic (DRY principle) by extracting parameter declarations, logging, covariance filling, and diagnostics building into a shared header src/ros2/bno055_ros2_common.hpp.

[1.0.0] - 2026-07-10

Added

• Robust, thread-safe, and dependency-free BNO055 library for Linux.
• Simplified API for beginners and visual debugging features.
• vcpkg and Conan integration support.
• Comprehensive Sphinx-based documentation (using Furo theme) including architecture, integration, and troubleshooting guides.
• GitHub Actions CI workflows and contribution guidelines (CONTRIBUTING.md).

Changed

• Renamed the library and CMake target to libbno055-linux.

Optimized

• Eliminated heap allocations in burst write functions to improve sensor write performance.