Hi everyone,
I’ve been working on an open-source project called ROS 2 Inspector, aimed at making it easier to understand the architecture of an unfamiliar or large ROS 2 workspace before running it.
The idea came from a problem I’ve repeatedly found interesting in ROS 2 projects:
When documentation is incomplete or outdated, understanding a workspace often means combining source-code inspection, launch-file analysis, grep/search, runtime tools such as rqt_graph, and a lot of manual exploration.
ROS 2 Inspector tries to automate part of that first architectural pass.
For example:
ros2inspector scan .
This scans the workspace from source and produces a compact summary of the discovered ROS 2 packages together with health signals that can help identify areas worth reviewing more closely.
The output can be exported as:
- table
- JSON
- YAML
For a more visual exploration:
ros2inspector viz
This generates a self-contained interactive visualization of the discovered ROS 2 architecture, allowing you to explore nodes, topics, services, actions, and their relationships.
There are also commands for inspecting nodes and connections, generating dependency and communication graphs, auditing connectivity, and validating architectural policies.
Some examples:
ros2inspector nodes --show-connections
ros2inspector graph comms --format mermaid
ros2inspector audit
ros2inspector validate --policy ros2inspector_policy.yaml
The analyzer currently handles supported patterns in Python, C++, ROS interfaces, and launch files.
One important point: ROS 2 Inspector is based on static analysis.
It is not intended to replace runtime tools.
Dynamic names, plugins, conditional behavior, runtime remappings, DDS/network behavior, and other aspects of the effective ROS 2 topology can only be fully understood with runtime evidence.
I see the two approaches as complementary:
Static analysis:
What architecture can we infer from the workspace before launching it?
Runtime inspection:
What architecture actually exists when the system is running?
The project is still in its early releases, so there is a lot of room for improvement, optimization, and broader ROS 2 pattern support.
That is also why I’d really like feedback from people working with real ROS 2 systems.
In particular:
What information would you want to see when opening an unfamiliar ROS 2 workspace for the first time?
And for the visualization:
What would make an architecture graph genuinely useful on a large ROS 2 system rather than just becoming another unreadable graph?
If you have a non-confidential ROS 2 workspace, I’d also be very interested in cases where the analyzer misses something, interprets something incorrectly, or where you think runtime/static information should be connected differently.
GitHub:
Website / documentation:
LinkedIn post:
Thanks, and I’d be very interested to hear how others approach this problem.