Decisions › D14
A driver registers what to check when its device is plugged in
Context
Until then the host ran a plain diagnose when a device connected, and the host decided what that meant for each device. On 23 October Zach asked for the opposite: the drivers say what should run on connection, so that diagnostics does not hold that information itself.
The decision
A plugin opts in by declaring a probe verb. The host runs it once per connection (when a device is first matched, on every re-enumeration) in place of that connection's first diagnose, and again if it ended blocked: about a second after the last holder exits, with a 10, 20, 40 second backoff meanwhile. It never runs on a schedule.
A probe is query-only. It prints the same records as diagnose, and the driver says what it found in three standard events with one meaning on every driver: Found, Probed (one summary, always last) and ProbeBlocked. The host derives no device-specific events of its own.
Why
“perhaps the drivers should like register a autorun on connect command”
Zach Yamaoka, 23 Oct 2026
“that way instead of diagnostics having to hold that information its each device that tells diagnostics what to do”
Zach Yamaoka, 23 Oct 2026
The stock model is the Linux driver model: when a bus matches a device to a driver the kernel calls the driver's probe() once. The host here is the bus, and the plugin's verb is the driver's probe.
Options considered
| Option | Verdict | Reason |
|---|---|---|
| Diagnostics holds what to check for each device | Rejected | The information belongs to the device's driver. Zach: each device tells diagnostics what to do. |
| A plain diagnose on connect, then on a schedule | Still supported | A plugin that declares no probe keeps this behaviour. |
| A probe verb once per connection, results as standard events | Chosen | Matches the stock model and keeps the host free of device knowledge. |
Consequences
- For the moteus driver a probe scans the expected ids first, checks identity and firmware against the latest release, checks the configuration against the inventory's safety keys, and checks the 5 Mbit/s CAN-FD link, with a 1 Mbit/s pass that tells wiring from a controller when the fast link loses frames.
- There is no “Lost” event. A board that later goes silent is the driver's not-answering status, and its fault lifecycle is the log of it.
- When a tview that RobotDx launched closes, the host probes the device again by itself.
Evidence
- On-connect probeContract doc, 2026-10-23. The driver says what to check when a device is plugged in: the verb, when the host runs it, the three standard events, and the query-only rule.
- IO diagnostics v1: build planContract doc, 2026-10-22. The decisions, the plugin boundary (a subprocess speaking JSON lines), the lanes, and the interfaces frozen between them.
Commits in the app's repository (private):
a7db4532026-10-23 Contract: the on-connect probecbd10902026-10-23 Host side of the on-connect probec32fc4c2026-10-23 Record: Found, Probed and ProbeBlocked as standard event codeseb80d2162026-10-24 Moteus and RealSense probe verbs