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.2 (2026-09-12)

• Fix: a CDR sequence length was read as unsigned but stored in int32_t; a length with the high bit set wrapped negative, bypassed the max-array guard, parsed the sequence as empty and let following fields be read from element bytes while deserialize() still reported success. The length is now unsigned and rejected when it exceeds the remaining bytes, at both walk sites (#47).
• Convert package share paths to strings for RoboStack/rolling (#45, Tobias Fischer).
• CI: add Lyrical to the matrix (#44).
• Contributors: Davide Faconti, Tobias Fischer

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

File truncated at 100 lines see the full file