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

Contributing to libbno055-linux

First off, thank you for considering contributing to libbno055-linux!

Setting up your Development Environment

1. Clone the repository:

   git clone https://github.com/lazytatzv/libbno055-linux.git
   cd libbno055-linux
   

1. Install CMake and a C++17 compiler:
   • On Ubuntu: sudo apt install build-essential cmake
2. Build the project:

   mkdir build && cd build
   cmake -DBUILD_TESTING=ON -DENABLE_CLANG_TIDY=ON ..
   make
   

1. Run tests:

   ctest --output-on-failure
   

Pull Request Process

1. Update the README.md or docs with details of changes to the interface if applicable.
2. Make sure all tests pass locally. If you add new functionality, please add a test for it!
3. Format your code using clang-format and check with clang-tidy (configs are provided in the repo).
4. Create a Pull Request against the main branch.

Reporting Bugs

Please use the provided Bug Report template in the Issues tab. Ensure you include:

• OS Version
• BNO055 wiring / hardware setup
• Library version (or git commit)
• Minimal reproducible example

Suggesting Enhancements

Please use the Feature Request template in the Issues tab and provide as much detail as possible about why the feature is needed and how it should work.