Decisions › D01
Drivers bring their own diagnostics, as small programs that answer three verbs
Context
Round 1 compared five ways to show plugged-in hardware in the top bar, against six weighted requirements that were frozen before any variant existed. Zach added two directions while the round was running, and the second one changed what a plugin is.
Each sensor already has a driver, a Python SDK and a digital model. The question was whether the diagnostics tool should carry its own knowledge of every device, or ask the drivers.
The decision
A plugin is the device's own driver package. It ships one small program and one small config file. RobotDx only discovers devices and calls the program; it never imports it and never speaks a device protocol itself.
The next day the build plan fixed the boundary: a plugin is an executable that prints JSON lines. describe says what it is and which utilities it registers, diagnose runs the checks for one device, and act runs a utility. Later verbs (follow, probe, stop) were added the same way, one at a time and optional.
Why
“For each of our sensors we are already building associated digital models, drivers, Python SDKs, etc. We can just leverage the exact same code.”
Zach Yamaoka, 21 Oct 2026
“It should be easy to extend with any new sensors from any manufacturer in the future, so it should likely follow a plugin-like system.”
Zach Yamaoka, 21 Oct 2026
“I want something always within reach and small.”
Zach Yamaoka, 21 Oct 2026
The build plan gives the reason for a separate process: the driver's own dependencies stay in the driver's environment, a crashing driver cannot take the host down, any language works, and the diagnostics code is the exact code the driver already has.
“The plugins are doing all of the heavy lifting this is basically a light UI shell that reads the information”
Zach Yamaoka, notes, 22 Oct 2026
Options considered
Round 1 scored five ways for a driver to bind to the host. This column is the “drivers bring their own diagnostics” requirement (25 of 100 points), scored out of 5. The scores are for the round-1 prototypes, before the contract existed.
| Driver binding | Direction | Score | What the score said |
|---|---|---|---|
| A manifest in the driver | Quick Settings device list | 4 | A six-line manifest repeats the USB matcher the driver already has. |
| A module naming convention | Plug Journal tray | 5 | One file in the driver, no metadata. A test drops the file and the device turns unrecognised; restore it and it is diagnosed. |
| A command line with exit codes | Hub row | 4 | Language-agnostic; vendor tools can be wrapped. |
| Packaging entry points | Registry contract | 4 | One environment must hold every driver's dependencies. |
| A station file that declares slots | Station board | 3 | Every physical device also needs a slot in a file before it means anything. |
The build plan then took a subprocess that speaks JSON lines: the language-agnostic idea of the command line, with the one-file simplicity of the naming convention.
Consequences
- Adding a manufacturer means adding one program and one TOML file. There are no host or UI edits, and no parallel per-device code to keep in step with the driver.
- The host's job is small: discover, schedule, build the tree, show it. Every device-specific word on screen comes from a driver.
- The first two plugins were the moteus motor-controller driver and the RealSense camera driver; the computer's own checks followed as a third.
Evidence
- Babble and prune, round 1: five top-bar directionsReport, 2026-10-21. Evidence for this decision.
- IO diagnostics: the converged designReport, 2026-10-22. Evidence for this decision.
- 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.
- IO diagnostics: converged designContract doc, 2026-10-22. Scope, layout, the two planes, port ownership, the contract and the open question about reusing Lichtblick.
Commits in the app's repository (private):
da93cb52026-10-21 Criteria amendment A2: drivers bring their own diagnostics0fdb2fb2026-10-21 Driver-owned diagnostics contract3283bcf2026-10-22 Build plan v1: the plugin boundary