Decisions › D06
One action vocabulary across every driver
Context
The goal for the day was a basic one: plug the rack in and have it run. The moteus controllers already had a set of shell aliases for the common jobs (find boards, triage the bus, calibrate, stop all, open tview, restore a config, change an id), and the RealSense camera had its own tools. The model Zach pointed at was a printer driver's utilities window: an icon, a title and one line per utility.
The decision
A driver offers its actions under standard machine names. The same name means the same thing, with the same label, on every driver: check_comms, check_firmware, update_firmware, calibrate, update_config, clear_faults, reboot, stop_all, set_id, open_console and, a day later, identify.
The label belongs to the host: a driver's title for a standard name must equal it, and the validator checks. A driver may add an action of its own; it is shown under “More” and may not reuse a standard name for another meaning. Two names carry their way in brackets so a person reads what will happen first: “Identify (wiggle)”, “Open console (tview)”.
Why
“And also accross different drivers, etc we can use the same commands so we forget about theimnplentatino details behind.”
Zach Yamaoka, notes, 22 Oct 2026
“how do printers do it? I guess you do register esseitatally like a prototcol of utilities buttons..”
Zach Yamaoka, notes, 22 Oct 2026
“tview should be supported on a particular board, but also on a bus”
Zach Yamaoka, 24 Oct 2026
Options considered
| Option | Verdict | Reason |
|---|---|---|
| Each driver names its own utilities | Rejected | The person would need to remember what each vendor's tool is called and how it differs. |
| Standard names with one label, extras under “More” | Chosen | Same name, same meaning, same label everywhere; a non-standard action still has a place. |
| Skip the host's buttons and open each vendor's console | Kept as one action | open_console opens the vendor's own tool (tview, realsense-viewer) for what the vocabulary does not cover. |
Consequences
- The danger of an action is per driver, not per name: the same name can be a read on one device and make hardware move on another. See dry run first.
open_consoleworks at both scopes: on the adapter it opens tview for every board found on that bus, on a board it opens tview for that board's id only, after the board answers a query.- A device's identity carries a
model_id, the part id from the RobotParts catalogue, as a plain string. RobotDx never imports the catalogue.
Evidence
- Round 2: the panel on the real rackReport, 2026-10-22. Evidence for this decision.
- One action vocabulary across drivers (record v0.1)Contract doc, 2026-10-22. The standard action names, their one label each, the four danger classes, the dry run and the model_id identity key.
- Diagnostics record v0Contract doc, 2026-10-22. ROS DiagnosticStatus kept whole, plus Entity, Event, Fault and Action. Eight lessons from the field, the rules, and the evidence re-checked.
Commits in the app's repository (private):
95ee3742026-10-22 Round 2 integration: printer-style Utilities cardabcb41a2026-10-23 Vocabulary: identify51415342026-10-24 open_console at both scopes