connection_inspector

A lightweight C++ GUI that lists every live ROS 2 node and, on selecting one, shows its direct connections (publishers/subscribers it talks to) in two interchangeable views — a table and an ego graph — each connection carrying a single status icon:

Click any status icon for a plain-language explanation of the fault, e.g. “/map: publisher node_a offers TRANSIENT_LOCAL, subscriber node_b requests VOLATILE → durability incompatible”.

Built with Dear ImGui (vendored) + GLFW + OpenGL3. Diagnoses a broken topic link in seconds instead of polling the CLI.

Build

This is a standard ament_cmake package. From the colcon workspace root (/home/ros/ws inside the devcontainer):

colcon build --packages-select connection_inspector --merge-install
source install/setup.bash

System build dependencies (already installed in the Docker images): libglfw3-dev, libgl1-mesa-dev, build-essential, cmake, git. Dear ImGui is vendored under third_party/imgui — no extra fetch step.

Run

The GUI is an X11 app. On a Linux host, just launch it:

ros2 run connection_inspector connection_inspector

No xhost +local: is needed: docker-compose.yml bind-mounts your host’s X cookie ($XAUTHORITY, default ~/.Xauthority) to /tmp/.docker.xauth and sets XAUTHORITY to it. Because the container user is UID 1000 (matching the host) and uses host networking, that cookie authenticates directly. If you start the container with docker compose from a shell that lacks a valid DISPLAY / Xauthority (e.g. over plain SSH), pass them through or fall back to xhost +local:. A missing display shows X11: Failed to open display and the app exits cleanly with code 1.

Pick a node from the dropdown; switch between Table and Graph with the tab toggle.

Controls (Graph view)

• Drag empty canvas — pan.
• Mouse wheel — zoom about the cursor.
• Click a peer node box — recenter the graph on that node.
• Click a status icon — open the fault popup (works in both views).

The dropdown shows per-node counts ✓N ?N ✗N aggregating each node’s connections. Counts cover type + QoS only — liveness (dead/Hz) is shown only for the selected node, because we never subscribe to unselected nodes.

Try it

A ready-made demo graph (demo/) brings up three named pairs — one healthy and two with deliberate QoS faults — so every status icon shows up at once:

ros2 launch connection_inspector qos_demo.launch.py
# or straight from source, no install needed:
ros2 launch ./demo/qos_demo.launch.py

Select e.g. /talker_2 and click its status icon: “/demo_reliability: publisher /talker_2 offers BEST_EFFORT, subscriber /listener_2 requests RELIABLE → reliability incompatible”. Ctrl-C in the launch terminal tears the graph down.

demo/qos_demo_node.py is a small parametrized rclpy node (role + topic + QoS from parameters); the launch file just spawns six of them with distinct node names. Tweak it to add type-mismatch or dead-link cases.

Distro matrix

The devcontainer attaches to Humble. Jazzy is build-verified non-interactively (no daily-dev surface):

File truncated at 100 lines see the full file

Changelog for package connection_inspector

1.0.0 (2026-06-15)

• Refinements
• docs: add GPLv3 license and update package.xml
• feat: complete UI tasks and add GitHub Actions for release
• M1: backend & diagnostics (graph model, QoS RxO, status, liveness) Scaffold the ament_cmake package and the non-GUI core: - qos_compat: Request-vs-Offered compatibility -> QosVerdict (first failing policy + offered/requested values) - graph_model: build NodeView from the live rclcpp graph (by-node listers via NodeGraphInterface); pure type/QoS count aggregation for the dropdown
  • status: EdgeStatus precedence (type>qos>dead>ok>unknown) + popup text

  - liveness_probe: generic-subscription Hz sampler over a trailing window; normalises probe QoS history (TopicEndpointInfo reports UNKNOWN/depth 0, which rcl rejects as "invalid allocator"); history is not part of RxO - inspect_cli: manual harness verifying graph_model + liveness against talker/listener Gate: 28 gtests green on Humble; clean build. Jazzy compile still to be run on the host (docker unavailable inside the Humble devcontainer). Co-Authored-By: Claude Opus 4.8 <<noreply@anthropic.com>>