ROS X Introspection

A runtime message parser and introspection library for ROS. It can deserialize any ROS message into key/value pairs without compile-time type knowledge.

Supported schema formats

• ROS .msg (ROS1 and ROS2 message definitions)
• DDS IDL (OMG IDL 4.2 subset)

The subset the OMG IDL currently supported are:

• enums
• unions
• @key and @optional
• multi-dimensional arrays
• struct inheritance

Build modes

The library compiles in two modes:

• ROS2 (colcon/ament)
• Standalone (vanilla CMake, no ROS dependency)

ROS1 .msg schemas and the ROS1 serialization format (ROS_Deserializer) are still supported at runtime, but the catkin build system is no longer maintained.

How it works

To parse a message at runtime, you need:

1. The type name (e.g. sensor_msgs/JointState or my_pkg::MyIdlMessage)
2. The schema definition (a .msg file or IDL text)
3. A raw memory buffer containing the serialized message

The raw buffer is typically obtained from:

• rosbag::MessageInstance or topic_tools::ShapeShifter in ROS1.
• GenericSubscription or rosbag2_storage::SerializedBagMessage in ROS2.
• MCAP files (works without ROS).

Output writers

The MessageWriter interface allows different output formats from the same deserialization walk:

Custom writers can be implemented by subclassing MessageWriter.

Building and testing

# Standalone build (no ROS)
cmake -S. -B build -DBUILD_TESTING=ON
cmake --build build
ctest --test-dir build

Benchmarks

The MCAP benchmark measures deserialization throughput on real bag files:

cmake -S. -B build -DBUILD_BENCHMARKS=ON
cmake --build build

# Run with different output writers
./build/mcap_benchmark path/to/file.mcap --writer flat
./build/mcap_benchmark path/to/file.mcap --writer msgpack
./build/mcap_benchmark path/to/file.mcap --writer json

The IDL benchmark measures CDR deserialization performance:

./build/idl_benchmark

Python binding

cmake -S. -B build_python -DROSX_PYTHON_BINDINGS=ON
cmake --build build_python

PYTHONPATH=build_python/python python3 python/mcap_ros_parser.py path_to_your_rosbag.mcap

Changelog for package rosx_introspection

3.0.0 (2026-05-26)

• Add IDL schema support and message-writer based deserialization
• Mark the breaking API update with a major version bump
• Contributors: Davide Faconti

2.3.0 (2026-04-06)

• Add Ubuntu CI workflow for non-ROS builds
• Use ament_cmake_gtest for tests in ROS2 builds
• Fix review issues: throw on bracket overflow, fix reserve, use num_brackets for estimate
• Split CI into per-distro workflows and add badges to README
• Add Rolling to CI matrix
• Add Kilted to CI matrix and bump checkout to v4
• Optimize toStr with precomputed path templates and segment table
• Make MCAP benchmark ROS-independent and add enable_testing()
• Contributors: Davide Faconti

2.2.1 (2026-04-06)

• Merge pull request #39 from gasmith/fix-test-deps
• cmake: Don't export test dependencies to downstream consumers
• Update variant.hpp
• Contributors: Davide Faconti, Greg Smith

2.1.0 (2026-02-21)

• Fix multiple bugs in serialization, deserialization, and JSON handling

  • Fix missing throw in ROS_Deserializer::deserialize for unsupported types
  • Fix NanoCDR_Deserializer::deserializeByteSequence crash on empty sequences
  • Fix ROS_Serializer buffer resize logic and UB (const-cast, type-punning)
  • Fix Tree::find using &_root instead of _root.get() on unique_ptr
  • Fix msgpack pointer invalidation after vector resize for large messages
  • Fix blob detection in deserialize() (was restricted to OTHER type only)
  • Fix deserializeIntoJson blob skip not advancing the deserializer

  - Fix serializeFromJson: add JSON parse error checking, type-safe value reading with range validation, proper null handling for missing fields

  • Add complete ROS_Serializer implementation (serialize, serializeString, etc.)

  - Add comprehensive test coverage for all fixes Co-Authored-By: Claude Opus 4.6 <<noreply@anthropic.com>>

• Merge pull request #29 from agxeed/fix/time-duration-nsec-serialization fix: correct nsecs duration serialization

• Merge pull request #22 from amarburg/bugfix_ament_export_testing_dependencies Add sensor_msgs, geometry_msgs as ament dependencies when BUILD_TESTING is true

• Merge pull request #27 from jorritolthuis/msgpack_cpp Make convertToMsgPack() available in C++

• Merge pull request #30 from agxeed/fix/compiler-warnings fix: compiler warnings

• Merge pull request #32 from konsim83/feature/replace_rosbag2_cpp_with_rclcpp Use rclcpp type support instead of rosbag2_cpp

• fix: compiler warnings

• fix: correct nsecs duration serialization

• Make convertToMsgPack() available in C++

• Add sensor_msgs, geometry_msgs as ament dependencies when BUILD_TESTING

• remove ament_target_dependencies

• Contributors: Davide Faconti, Jorrit Olthuis, Konrad Simon, Rein Appeldoorn, admin

2.0.1 (2025-10-01)

File truncated at 100 lines see the full file