Skip to content

Commit 0fbcbf4

Browse files
committed
docs: sharpen the fault wedge; add "vs observability" positioning
Drop the feature-list tagline and slim "Beyond faults" to a one-line teaser so structured faults stay the single hook, with the rest behind the docs. Add a Foxglove/Rerun/PlotJuggler section framed as complement, not compete: the automotive scan-tool precedent, the fleet-scale O(1) argument, alerting vs a confirmed/persisted fault, and read-only visualization vs acting on it.
1 parent 42b3308 commit 0fbcbf4

1 file changed

Lines changed: 31 additions & 11 deletions

File tree

README.md

Lines changed: 31 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,6 @@
1818
tree, with lifecycle, history, and the state captured at the moment it happened.
1919
</p>
2020

21-
<p align="center">
22-
Structured fault codes · SOVD entity tree · Fault lifecycle · Freeze-frame + black-box capture · <a href="https://github.com/selfpatch/ros2_medkit_mcp">AI via MCP</a>
23-
</p>
24-
2521
## Drop it into the stack you already run
2622

2723
### Nav2: a navigation goal that quietly aborts
@@ -87,6 +83,33 @@ not a rip-and-replace.
8783
| Scope | ROS only | ROS today; PLC / ECU on one API |
8884
| Agent access | none | MCP adapter |
8985

86+
## "I already have Foxglove. Why do I need this?"
87+
88+
Foxglove, Rerun and PlotJuggler are how you *look* at robot data - plots, 3D, logs, live or
89+
from a bag - and they're great at it. ros2_medkit does the job they leave undone: it turns a
90+
failure into a **structured fault**.
91+
92+
> Every mature machine industry already draws this line: in a car, an oscilloscope is not a
93+
> scan tool. UDS / DTC diagnostics sit *above* the signal layer, as structured, queryable
94+
> state. Robotics just hasn't drawn it yet.
95+
96+
- **"I'll just set an alert."** A threshold alert fires on a raw signal and is gone - no
97+
entity, no lifecycle, no history, and it means something different on every robot. A fault is
98+
confirmed, persisted, entity-attributed state you can query later - and, being SOVD, it means
99+
the same thing across robots and vendors. Alerting pages a human; diagnostics gives a machine
100+
an answer.
101+
- **It has to survive a fleet.** Visualization is O(humans) - one operator, one timeline, and
102+
nobody scrubs 400 of them. A structured fault is O(1): the same code and lifecycle aggregate
103+
across the fleet, so *"which 12 of 400 robots have a confirmed navigation fault right now?"*
104+
is a query, not a person.
105+
- **You can't act on a plot.** Observability is read-only by design. A structured fault is the
106+
precondition for doing something about it - gating an OTA on robot health, triggering
107+
remediation. You can't safely patch what you haven't first diagnosed as a fault.
108+
109+
So it is not a replacement for your observability stack - it is the **diagnosis layer
110+
underneath it**. medkit flags and persists the fault (readable by dashboards, fleet managers
111+
and agents, not just people) and captures the black-box rosbag you then open in Foxglove.
112+
90113
## Run it in 5 minutes
91114

92115
**Install** from the ROS 2 distribution (source build and Pixi in the
@@ -160,13 +183,10 @@ For a guided walkthrough, see the
160183

161184
## Beyond faults
162185

163-
Faults are the front door; the same REST surface exposes the whole ROS 2 graph - discovery,
164-
live topic data, service/action calls, parameters, bulk data, SSE subscriptions, triggers,
165-
locking, scripts, software updates and JWT/RBAC auth (OpenAPI 3.1.0 + Swagger UI at
166-
`/api/v1/docs`). It models your robot as a SOVD **entity tree** (areas -> components -> apps,
167-
with cross-cutting functions) so the same concepts carry across robots, vehicles and embedded
168-
systems. See the [full documentation](https://selfpatch.github.io/ros2_medkit/) and the
169-
[roadmap](https://selfpatch.github.io/ros2_medkit/roadmap.html).
186+
Faults are the wedge. Once medkit is in, the same REST surface is a full SOVD diagnostic
187+
gateway - your whole robot as an entity tree, live data, service and action calls, bulk data,
188+
software updates and JWT/RBAC auth. The fault gets you in the door;
189+
[the docs](https://selfpatch.github.io/ros2_medkit/) have the rest.
170190

171191
## Documentation & community
172192

0 commit comments

Comments
 (0)