IO diagnostics: the converged design

Your Oct 22 feedback on round 1, set against ~50 tools that already do part of this, turned into one design. Read the verdict, then go as deep as you want.^1,2

What you picked

Your own screenshots from the Oct 22 note, grouped by what each one added. Quotes are verbatim.²

V4’s window: a list on the left, detail on the right

“a nice simple layout... basically a bar on the left”

What it contributed: The window’s shape: a left column of devices, a search box on top, click a row for detail on the right. Round 1’s V4 dashboard became the frame for everything below.²

Clearpath “All Diagnostics”: a tree with icon, status and name

“You have a left side hand.. that is essentially a tree.”

What it contributed: The tree row (status icon · name · path underneath) and the detail drawer’s fields: Path, Hardware ID, Level, Message, Values. You called it “the rockwell dash board”: Clearpath has been part of Rockwell Automation since Oct 2023.^2,14,31

V1’s rows: name, id, count and status in one line, but not in Quick Settings

“I like how we see the kinda top level name, and ID”

What it contributed: The row grammar (icon · name · id or count · status), and one firm “no”: not inside Ubuntu’s built-in menu (“I wouldn’t put it on the built in ubunut thing”). The entry point is a chip of its own.²

V3’s button placeholder, and “how do printers do it?”

“I think we can have place holders for buttons”

What it contributed: The action plane. A printer driver registers its utilities and the OS dialog only shows them; here each driver registers its buttons and executes them itself.²

V2’s chip and Recent list: an activity log

“interesting idea here with like a activity log”

What it contributed: The activity log (plugged, unplugged, re-enumerated, fault in and out), and the idea you liked most: the computer should be “monitoring the wires” itself.²

ros2_medkit: an Entity Tree, and Operations

“child parent relations you can do drop down”

What it contributed: Parent/child nesting for many nodes on one bus (“Ok they call it an Entiy Tree”), and the Operations tab: named actions with a Run button, which is the action plane already built.^2,15,16

Greenwave Monitor: a table with measured vs expected frequency

“turn it into more of like a table view for fast high level overview”

What it contributed: Table mode: Clearpath’s nested first column with aligned columns to the right, which should carry more than Message, “stuff like Frequency”: rate measured vs expected, last seen, firmware, errors.^2,17

rqt_robot_monitor: roll-up and a timeline strip

“Yes the roll up view I think important”

What it contributed: Worst-child-wins roll-up, with counts on the parent (“(E: 1, W: 0) Computers”), and the colored history strip that keeps a one-off red tick visible.^2,33

RealSense Viewer: the level of ambition

“this is kinda at the level of like realsense viewer”

What it contributed: The scope line: plug it in, see what it is and how it is connected, a few “simple command controls”, and no robot control. Link speed sits beside the name (USB 3.2 vs USB 2.0).^2,24

Ten examples worth stealing from

Picked from about 50 tools across three survey lanes: four ROS-native, four vendor tools, two general device managers^3,4,5. Each card: the pattern, and exactly what IO diagnostics takes from it.

1. Clearpath Cockpit ROS 2 DiagnosticsROS-native

github.com · LGPL-2.1 · Linux (Cockpit plugin; needs ROS 2 + foxglove_bridge)

• One page of cards: a Timeline of status dots with Pause, then Errors and Warnings cards that read “No Errors” with a green check when clean, then All Diagnostics.
• All Diagnostics is one expandable tree (name above its path, Message column); selecting a row opens a details drawer with the key/values. “Generate Capture” zips a support bundle (admin only).
• IO diagnostics takes: The tree row and drawer fields as they are, positive empty states, and the capture button as our “copy diagnostics for support” action.^3,14

2. ros2_medkit web UIROS-native

github.com · Apache-2.0 · Linux (ROS 2 gateway; web UI in Docker, “early prototype”)

• Left Entity Tree (server › area › component › app) with type pills, ⌘K search and a Logical/Functional toggle; breadcrumb across the top.
• Each entity gets tabs with counts: Overview · Data 13 · Operations 7 · Config 35 · Faults. Its bridge maps STALE to CRITICAL: a device that stopped talking outranks one reporting an error.
• IO diagnostics takes: The detail panel’s skeleton (values, actions, read-only config, faults, each with a count) and STALE treated as worse than ERROR for hardware.^3,15

3. ROS diagnostics stack + rqt_robot_monitorROS-native

github.com · BSD-3 · Linux (needs a ROS 2 install)

• The record: DiagnosticStatus = level (OK / WARN / ERROR / STALE) + name + message + hardware_id + string key/values, stable since ROS 1. The aggregator rolls it into a tree where the parent takes the worst child, and “expected” makes an absent device a warning, not silence.
• rqt_robot_monitor stacks Error and Warn panes (leaf items only) above the All devices tree, with a history strip: “Last message received N seconds ago”, Pause.
• IO diagnostics takes: The record shape unchanged, worst-child roll-up, “expected but absent”, and the history strip as the cheapest honest view of a flaky link.^3,12,13

4. Foxglove / Lichtblick Diagnostics panelsROS-native

github.com · Foxglove: proprietary, sign-in · Lichtblick fork: MPL-2.0, Linux desktop / web / Docker

• Summary feed on top (minimum-level dropdown, fuzzy “Filter hardware id”, sort by level, pin), Detail below: level-colored title and a zebra key/value table.
• A per-panel stale timeout (5 s default) rewrites old entries to STALE on the client. Lichtblick accepts any channel whose schema is diagnostic_msgs/msg/DiagnosticArray, JSON included.
• IO diagnostics takes: The zebra key/value table, hardware_id as the search key, and a free second view: emit the same records and Lichtblick renders them with zero UI code (unproven; a 30-minute spike).^3,18,19

5. CTRE Phoenix Tuner Xvendor

v6.docs.ctr-electronics.com · Proprietary freeware · no Linux build (Windows, macOS, Android, iOS)

• The first screen is “Devices (17)”, as cards or a table: Name | Model | ID | CAN Bus | FirmVer | Status. The border color is the firmware state and is always repeated as a sentence (“A new firmware version is available.”); a duplicate ID is its own red state.
• A bulb on every card blinks the device; the footer carries “Latency: 0ms – Jitter: 0ms”.
• IO diagnostics takes: Table-mode columns, color always repeated in words, duplicate-ID as a named state, identify on every row. Reference only: no Linux.^4,21

6. DroneCAN GUI Toolvendor

github.com · MIT · Linux, Windows, macOS (pip)

• Passive discovery: every node broadcasts a heartbeat, so it appears on its own. Table: Node ID | Name | Mode | Health | Uptime | vendor code.
• Double-click opens the node: software version + CRC, hardware version + unique ID, then Restart and Update firmware right under the identity, then config (Fetch / Store / Erase).
• IO diagnostics takes: Presence from a declared heartbeat (our expected_period_s), uptime that resets exposes brown-outs, and identity + actions in one detail panel.^4,22

7. REV Hardware Clientvendor

docs.revrobotics.com · Free (proprietary) · Linux in RHC2 (Ubuntu 24.04, Debian 12+)

• The left tree shows the USB-attached controller (“USB; CAN ID 1”) as the bridge, a “CAN Bus” node under it, and the other controllers on that bus as children.
• Out-of-date rows carry a red triangle; Update All and Check for Updates sit on top with “Last check: 10:55 am”; the Update tab shows Current 1.5.0, Latest 1.5.2, Out-of-Date.
• IO diagnostics takes: Exactly our fdcanusb › CAN bus › node shape, the Current / Latest block, and the last-check time beside the update button.^4,23

8. Intel RealSense Viewervendor

github.com · Apache-2.0 · Linux and Windows binaries

• Devices appear on plug-in; the card title carries the USB generation (“3.2”), then Record · Sync · Info · More.
• “Firmware Update Recommended!”: model, serial, Current vs Recommended version, one sentence on why, Install / Dismiss. Bottom bar counts errors, warnings, info.
• IO diagnostics takes: Link speed beside the name (it catches a D405 on USB 2), “recommended” rather than “latest”, and Install / Dismiss as the shape of the update action.^4,5,24

9. Home Assistant device page + registrygeneral

developers.home-assistant.io · Apache-2.0 · Linux (Python)

• A small Device info card (model, maker, “Connected via Zigbee Coordinator”), readings first, then a separate Diagnostic card with an Identify button; noisy diagnostics are off by default.
• Underneath: the device registry (manufacturer, model, serial_number, sw_version, hw_version, via_device) and the Update entity (installed_version, latest_version, release_url, install).
• IO diagnostics takes: The identity schema word for word, via_device as the tree edge, the update entity as the update record, and button entities as the shape of a registered action.^5,25,26

10. USB Device Tree Viewer (and Linux usbview)general

www.uwe-sieber.de · Windows freeware · Linux counterpart usbview, GPL-2.0, GTK

• My Computer › host controller › root hub › port › device, each node resolved to a human label (COM port, product name).
• A failed device gets a numbered problem badge (43) and a generic VID_0000&PID_0002; the detail pane shows the port chain, connection speed and a missing-serial warning.
• IO diagnostics takes: The OS half of our tree: USB topology from sysfs, the port chain as “where is it plugged in”, and link speed plus enumeration failures as wire diagnostics.^5,27,28

Layout: chip → tree + detail → table → activity log

Shape status two ways, never by color alone: a filled circle is OK, a triangle is WARN, a square is ERROR, a dashed ring is STALE or “no driver”. Tuner X repeats every color as a sentence; medkit uses disc, ring and square^3,4.

The two planes: read-only status, driver-owned actions

This answers “is this read only or do we also allow commanding?” with both, kept apart. Off-the-shelf twins already do this: Home Assistant button and update entities, ros2_medkit’s Operations tab, and DroneCAN’s Restart / Update firmware beside the node’s identity^1,4,5,15. Staleness is computed, not reported: each record declares its period, and one older than about 3× that period turns STALE, ROS diagnostics’ fourth level^1,3.

Ownership: whoever owns the port does the talking

Permissions reduce to a rule each driver already obeys: one owner per port, the same move as a single writer per piece of state. The holder check reads /proc/locks and never takes the lock itself, because a registry that test-acquires the rack lock makes an experiment refuse to start (measured in round 1)³⁶.

The contract

ROS DiagnosticStatus has been stable since ROS 1 and every viewer in the survey reads it^3,12. It lacks four things: a tree position, a staleness period, structured identity and update state. Three fields and one optional record add them, borrowed rather than invented^1,5,25,26.

{
  "level": "ERROR",
  "name": "comms",
  "message": "CAN 15 fault 33 on bridge enable",
  "hardware_id": "fdcanusb-272813EF/can/15",
  "path": "host/usb-1-3/fdcanusb-272813EF/can/15",
  "expected_period_s": 1.0,
  "identity": {
    "manufacturer": "mjbots", "model": "moteus",
    "serial_number": "<from moteus_tool --info>",
    "sw_version": "1.1.2",
    "via_device": "fdcanusb-272813EF/can"
  },
  "update": {"installed_version": "1.1.2", "latest_version": "1.1.2"},
  "values": [["fault", "33"], ["replies", "3 of 3"]]
}

Two sources build one tree

This is “which USB port is it plugged into”, answered by the OS (sysfs, /dev/serial/by-id, kernel log), the same skeleton USB Device Tree Viewer draws; REV’s tree shows the driver half, a USB bridge with a CAN bus and its nodes beneath^4,5,27. Two traps from round 1: a D405’s USB descriptor serial differs from its SDK serial (XXXXXXXXXXXX vs 2186222…), and with two adapters plugged the generic /dev/fdcanusb symlink can silently name the wrong one, so the tree keys adapters by serial^6,36.

The computer diagnoses its own wires

Your idea, made first-class: every edge in the tree carries its own health, from passive sources^1,2.

The kernel’s SocketCAN counters give the CAN vocabulary for free on any netdev adapter, but an fdcanusb is a USB-serial device with no kernel counters, so its bus health has to come from the moteus driver or round-trip checks^4,30. Kvaser CanKing’s Bus Statistics widget is close to the panel we want:^4,29

The activity log, seeded with Oct 21:

The six kernel-log rows and the 18:29 holder are read straight from out/snapshot-live.json³²; the coalescer folds XXXXXXXX’s five enumerations into one notice⁶. The four “reported” rows come from the rack session that evening^1,6, with times only where a time was recorded.

Why it is a stable sub-assembly

This is commitment 3 of your own DP - Diagonistics: “the diagnostic surface is stable”, the foundation tests, dashboards and the data flywheel build on^7,8. It is also the board-farm move: the station is permanent and its self-test is part of the station, separate from whatever device is under test³⁵. Software components can join later (out of scope now)^1,2.

Open question: reuse Lichtblick as the dashboard?

Recommendation: own the small chip, tree and actions; emit the standard records so Lichtblick, Foxglove and rqt work as second views, and prove the bridge with a ~30-minute spike^1,3,11,20. This matches the July decision to own the shell and treat any viewer as a replaceable lens¹¹.

Converged mock

Captured from the parallel builder’s clickable mock (prototypes/v6-converged/), replaying the real Oct 21 rack at 18:11, 18:25 and 19:02. Looked at for this report, not driven by it.

Decision surface

Settled

• Scope: a hardware IO diagnostics dashboard, RealSense-Viewer level, that works before any robot stack runs.^1,2
• Layout: chip with Recent → tree + detail → table mode → activity log; not in Quick Settings.^1,2
• Two planes; read-only by default; a button only when a driver registered it; every action confirmed; blocked while the port is held.¹
• Ownership rule: whoever owns the port does the talking.¹
• Contract: DiagnosticStatus + path + expected_period_s + identity; update as Home Assistant’s update entity.¹
• Stack default: V2’s single small Python process with a local web window; the plugin is each driver package’s own diagnostics.py, found by entry point.^1,6

Open, each with a recommendation and the default if you say nothing

1. 1. Exact STALE ruleRecommend STALE when a record is older than max(3 × expected_period_s, 5 s). 3× is the spec; the 5 s floor matches rqt, Lichtblick and the aggregator, so a fast record does not flicker.
   Default: that rule.
2. 2. Actions while the stack owns the portRecommend: show the button disabled with the owner named (“owned by pid …”) in v1; forward through the stack driver’s own service later.
   Default: disabled, owner named.
3. 3. Where “latest version” comes fromRecommend a per-model table shipped inside each driver package, no network; “unknown” is OK-level; update available is WARN, never ERROR.
   Default: local table.
4. 4. Active link checksRecommend passive signals and driver-reported counters, plus V2’s one gated comms check per newly settled adapter, only when the port and rack lock are free.
   Default: that.
5. 5. Lichtblick spike now or after v1Recommend after the mock is accepted; it changes nothing in v1 because the records are already in its shape.
   Default: after v1.

Out of scope

• Software components (nodes, planners, policies): later, with the same records.
• The CAD / 3D view that paints these statuses onto links in the model.
• Robot control or motion, fleet and cloud views, long-term history (that belongs in a time-series store).

Source index

1. Converged design spec, IO diagnostics (orchestrator, 2026-10-22)
2. Zach, Daily Note Oct 22 2026, “Feedback on Io Diagonistics” (14 screenshots)
3. Survey lane ROS: diagnostics dashboards in the ROS ecosystem (accessed 2026-10-22)
4. Survey lane vendor: actuator, sensor and field-bus tools (accessed 2026-10-22)
5. Survey lane general: device and health dashboards outside ROS (accessed 2026-10-22)
6. Babble round 1 gallery: five top-bar directions (2026-10-21)
7. DP - Diagonistics (Zach)
8. MOC - Diagnostics (Zach)
9. C - ROS Diagnostics Stack
10. IoT Software Tools That Robotics Should Steal (Deep Research, 2026-07-16)
11. Foxglove vs Rerun — Logging Boundary and Backend Decision (Deep Research, 2026-07-21)
12. ROS 2 DiagnosticStatus.msg (common_interfaces, BSD-3)
13. ros/diagnostics: diagnostic_updater + diagnostic_aggregator
14. Clearpath Cockpit ROS 2 Diagnostics docs
15. ros2_medkit (selfpatch)
16. Open Robotics Discourse: What’s missing from ROS 2 diagnostics, and what we built
17. NVIDIA Isaac ROS Greenwave Monitor (Apache-2.0)
18. Foxglove Diagnostics panels docs
19. Lichtblick (MPL-2.0)
20. foxglove-sdk on PyPI (MIT)
21. CTRE Phoenix Tuner X: Devices page
22. DroneCAN GUI Tool (MIT)
23. REV Hardware Client: SPARK MAX update
24. RealSense Viewer SW/FW update logic
25. Home Assistant device registry
26. Home Assistant update entity
27. USB Device Tree Viewer (Uwe Sieber)
28. usbview for Linux (GPL-2.0)
29. Kvaser CanKing
30. Linux SocketCAN documentation
31. Rockwell Automation completes acquisition of Clearpath Robotics (Oct 2, 2023)
32. io_facts live snapshot, rack PC, 2026-10-21 18:29 (real kernel log + holders)
33. rqt_robot_monitor
34. ros2 doctor (ros2cli)
35. C - Board Farm (Permanent Station, Swappable DUT)
36. io-diagnostics README: round-1 measured traps

Built by docs/build_design_report.py. Vault note: IO Diagnostics — Prior Art and Converged Design (2026-10-22). Repo: ~/io-diagnostics. Claude Code · Opus 5.5.