Skip to content

How diagnosis works

Step 1 Collect env · RMW · network read-only probes Step 2 Compare two hosts or containers optional peer Step 3 Evaluate rule engine evidence per finding Step 4 Explain next step + docs optional AI Step 5 Verify live sample delivery, not guesses

1. Collect

The collector records facts about the environment it runs in:

  • ROS environment variables: ROS_DISTRO, ROS_DOMAIN_ID, RMW_IMPLEMENTATION, discovery settings, DDS XML paths (and whether those files exist). RMW_MISMATCH compares RMW_IMPLEMENTATION (unset means the Fast DDS default); the snapshot doesn't run ros2 doctor. The dashboard overview additionally detects the effective RMW with ros2 doctor --report.
  • Network interfaces with multicast flags (ip -j addr).
  • Container detection and the network, IPC and PID namespaces.
  • Nodes and topics visible in the ROS graph. Queries wait AUTODIAG_DISCOVERY_SECONDS (default 2) for DDS discovery, because without waiting the graph often looks incomplete.

2. Compare

Many problems involve two parties. With a second snapshot (another host or container), cross-host rules run too: domain, discovery range, RMW, distro, multicast and IPC namespace.

3. Evaluate

Each rule is a small, testable function that produces a finding:

{
  "code": "DOMAIN_MISMATCH",
  "severity": "error",
  "confidence": "high",
  "summary": "Different ROS_DOMAIN_ID values",
  "evidence": {"host_a": "0", "host_b": "7"},
  "recommended_action": "Use a consistent ROS_DOMAIN_ID across intended peers, then restart managed processes.",
  "documentation": [{"label": "ROS 2 domain IDs", "url": "https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Domain-ID.html"}]
}
Severity Meaning
error (problem) A confirmed configuration that prevents communication
warning Likely to cause problems, or unsupported
info (note) Worth knowing; not a fault

dds-autodiag selftest (dashboard Tool check) runs every rule against its synthetic faults (27 fixtures covering all 23 rules), so you can verify the installation. That is not a live test of your robot. Dashboard Live rule check (POST /api/live-rules) runs the same rules on this host, the loaded peer and this host’s live graph: each rule is fault, pass or skipped.

4. Explain

Findings link to official documentation where one applies. On request, the AI assistant explains the findings in context; see RAG & AI pipeline.

5. Verify

Configuration can be correct while data still doesn't flow, so the last step is always a real message: Read one sample in the dashboard, or dds-autodiag sample /topic.

Debugging "topic visible, no data"

This is the most common ROS 2 complaint. AutoDiag follows the same path an expert would:

flowchart TD
    A["Topic visible,<br/>but no data"] --> B{"Same ROS_DOMAIN_ID<br/>everywhere?"}
    B -- no --> B1["DOMAIN_MISMATCH<br/>align the IDs"]
    B -- yes --> C{"Publisher and subscriber<br/>QoS compatible?"}
    C -- no --> C1["RELIABILITY / DURABILITY_MISMATCH<br/>match the QoS"]
    C -- yes --> D{"Same message type?"}
    D -- no --> D1["TYPE_MISMATCH"]
    D -- yes --> E{"Same RMW family?"}
    E -- "Zenoh vs DDS" --> E1["RMW_MISMATCH<br/>use one RMW"]
    E -- yes --> F{"Across hosts: discovery<br/>range allows it?"}
    F -- no --> F1["DISCOVERY_RANGE_RESTRICTED<br/>LOCALHOST_ONLY"]
    F -- yes --> G{"Containers on one host<br/>using shared memory?"}
    G -- "different IPC namespaces" --> G1["SHM_IPC_NAMESPACE_DIFFERENCE<br/>--ipc=host or UDP"]
    G -- ok --> H["Read one sample<br/>to confirm delivery"]

What AutoDiag can't see

It says so instead of guessing:

  • A snapshot describes the collector's own environment. A node can set its own RMW or domain in its launch file.
  • The transport DDS actually selected at runtime (shared memory vs UDP) isn't measured.
  • Packet-level reachability between hosts isn't tested.