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.1.1 (2026-06-21)

• DDS @key members now contribute to the field path in position: the key value is rendered as a bracket immediately after the struct that owns it (e.g. topic[ArmID:0]/State) instead of being appended at the end of the path. For a sequence of keyed structs the key replaces the numeric array index (e.g. Moves[J1]/..., Moves[J2]/...), so elements are identified by key rather than by unstable position.
• Fix key brackets accumulating across sequence elements (e.g. Moves[1]/...[J1][J2]) by rolling them back per element.
• Key bracket formats: integral [field:value], enum [EnumName], string [value].
• Tests: added the IDLKeyConvergence suite asserting exact key paths.
• Contributors: Davide Faconti

3.1.0 (2026-05-30)

• Upstream DDS-correctness fixes that previously existed only in the PlotJuggler-vendored copy of this library:
• Bounded sequences: parse the ROS2 T[<=N] syntax as a length-prefixed sequence and expose the declared bound via ROSField::isUpperBound() / maxSize().
• DDS enum @value() compatibility: a @value(N) annotation sets the display value while the CDR wire value stays the sequential ordinal (EnumValue::ddsCompatValue()); enum name resolution now matches the wire ordinal.
• PL_CDR optional alignment: 4-byte align the optional member header relative to the CDR origin and bounds-check its size, fixing corruption of two or more consecutive unset optional members.
• Multiple @key fields now all contribute to the field path (the suffixes accumulate instead of overwriting), preventing path collisions between samples that differ only in an earlier key.
• Tests: added BoundedSequence, DDSEnumCompatValue, DDSEnumKeyValueAnnotation, TwoConsecutiveUnsetOptionals and MultipleKeyFields.
• Contributors: Davide Faconti

3.0.1 (2026-05-29)

• Fix a crash (out-of-bounds tree access) when deserializing a DDS union whose active case is a struct. The field tree models a union as a single leaf node, so walking the resolved case struct indexed a non-existent child node. The case struct is now walked safely to keep the CDR cursor aligned.
• Add regression test IDLDeserialize.UnionWithStructCase
• Contributors: Davide Faconti

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

File truncated at 100 lines see the full file