LibRobotBagFix

简体中文

Commercial-grade rosbag2 repair and lightweight cross-platform parsing SDK for robot black-box data.

LibRobotBagFix is built for commercial robots such as autonomous delivery vehicles, lawn-mowing robots, and inspection robots. It inspects, repairs, and reads rosbag2 black-box data without requiring a ROS 2 runtime. Its first priority is the hardest class of post-incident recovery problems: after a collision, fall, emergency stop, or sudden power loss, the underlying MCAP / SQLite3 files may not have been closed cleanly, so official tools cannot open the logs and the last seconds or milliseconds of critical data become inaccessible.

Why This Project Exists

Commercial robots often record cameras, IMU, odometry, localization, control commands, and diagnostics at high frequency into ROS 2 rosbag2 data. After an incident, algorithm, hardware, operations, and support teams all rely on this black-box data to identify responsibility, locate root causes, and replay what happened on site.

In practice, robot incidents often involve power loss or abnormal process termination. The SQLite3 .db3 or MCAP files underneath rosbag2 may have only partially written tail structures, indexes, or metadata. The result is:

• Official rosbag2 tools cannot open the file, or can read only a small amount of information.
• The data closest to the incident is truncated at the end of the file and is hard to recover through normal workflows.
• Field teams want to inspect data on macOS, Windows, tablets, or mobile devices, but a full ROS 2 environment is too heavy.
• SDK integrators only need black-box reading and repair, and do not want to ship ROS 2, DDS, or the full rosbag2 dependency stack inside their products.

LibRobotBagFix turns this capability into an embeddable, packageable, cross-platform C++ SDK and command-line tool.

Architecture

The project is organized into three layers. Each layer can be validated independently or combined into a complete toolchain:

Low-level repair engine
  MCAP record scanning, tail-structure rebuild, SQLite3 WAL recovery, page-level salvage

Middle lightweight SDK
  Zero ROS runtime dependency C++ API, stable C ABI, CDR helpers, CMake install/export

Top-level demo tool
  Qt desktop demo for opening, inspecting, repairing, and previewing rosbag2 data in the field

Source layout:

apps/qt_demo/          Optional Qt desktop demo
include/robotbagfix/   Public C++ SDK and C ABI
src/                   Repair engine, inspector, readers, CDR helpers
tools/                 robotbagfix CLI
bindings/              JNI and Swift-friendly binding examples
fuzz/                  Minimal fuzz harnesses
docs/                  Design docs, development workflow, release notes, roadmap

Current Capabilities

• robotbagfix inspect <path> [--json]
  • Detects rosbag2 directories, .mcap, and .db3 files.
  • Reports topics, message counts, time ranges, WAL sidecars, incomplete MCAP offsets, warnings, and errors.
• robotbagfix repair <input> -o <output> [--json]
  • MCAP: keeps complete records and rebuilds the required Summary / Footer / trailing magic.
  • SQLite3: prefers SQLite recovery, then falls back to page-level salvage when needed.
• C++ SDK
  • BagReader::open, topic enumeration, message iteration, and raw serialized payload access.
  • inspect_bag_json and repair_bag_json facade APIs.
• C ABI
  • Stable opaque handles for FFI layers, covering bags, iterators, and reports.
• CDR helper
  • Reads primitive values, strings, byte sequences, and lightweight views for common Pose / Odometry / Imu / Image fields.
• Qt demo
  • Opens MCAP, SQLite3, or rosbag2 directories.
  • Runs inspect / repair and previews topics and messages.

Quick Start

Build the default SDK / CLI path and run tests:

scripts/build.sh
./build/robotbagfix --version
ctest --test-dir build --output-on-failure

Inspect a rosbag2 directory or a single data file:

./build/robotbagfix inspect path/to/bag_or_file --json

Repair MCAP or SQLite3 input:

./build/robotbagfix repair damaged.mcap -o repaired.mcap --json
./build/robotbagfix repair damaged.db3 -o repaired.db3 --json

Read repaired output through the SDK examples:

./build/rbf_read_bag_cpp repaired.db3
./build/rbf_read_bag_c repaired.db3

SDK Integration

The project can install into the repository-local install/ directory so downstream projects can consume it as an SDK. install/ is a local build artifact and is not committed to Git.

scripts/build.sh --type Release --install

The install tree contains:

install/bin/                         CLI
install/include/robotbagfix/          C++ / C headers
install/lib/                         Shared library
install/lib/cmake/LibRobotBagFix/     CMake package files
install/share/LibRobotBagFix/examples Example code

Downstream CMake projects can use it like this:

cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/LibRobotBagFix/install

find_package(LibRobotBagFix CONFIG REQUIRED)
target_link_libraries(your_app PRIVATE robotbagfix::robotbagfix)

Qt Demo

Qt is not a core dependency and is not built by default. On macOS with Homebrew, enable it with:

brew install qt
cmake -S . -B build-qt \
  -DRBF_BUILD_QT_DEMO=ON \
  -DCMAKE_PREFIX_PATH="$(brew --prefix qt)"
cmake --build build-qt --target robotbagfix_qt_demo --parallel
./build-qt/apps/qt_demo/robotbagfix_qt_demo

You can also point CMake directly at a verified local Qt6 path:

cmake -S . -B build-qt \
  -DRBF_BUILD_QT_DEMO=ON \
  -DCMAKE_PREFIX_PATH=/opt/homebrew/opt/qt

Fuzzing

Fuzz targets are disabled by default and require Clang or AppleClang:

scripts/build.sh --build-dir build-fuzz --fuzzers --no-tests --no-cli --no-examples
./build-fuzz/rbf_fuzz_mcap build/cli-smoke -runs=1000
./build-fuzz/rbf_fuzz_sqlite build/cli-smoke -runs=1000

Release Artifacts

The release workflow builds staged install trees for Linux and macOS and packages:

• CLI binary.
• Shared library.
• Headers.
• CMake package files.
• Example code.
• README and LICENSE.

After creating a v* tag, GitHub Actions attaches the tarballs to the GitHub Release.

Documentation

• Roadmap
• Design Document Index
• Low Level: MCAP / SQLite3 Binary Repair Engine
• Middle Layer: Zero-ROS-Dependency C++ Parsing SDK
• Top Layer: Cross-Platform Demo Tool
• Fixtures and Local Development
• Quality, Release and Fuzzing

Current Boundaries

• Damaged bags are never modified in place; repair always writes a new file.
• The core SDK does not depend on the ROS 2 runtime.
• The project does not provide DDS publish / subscribe and does not implement a rosbag player.
• It does not promise recovery of images, point clouds, or custom large messages whose payloads were only partially written.
• Qt, Android, iOS, and other UI or platform layers are not dependencies of the core SDK.