ros2_medkit gives your ROS 2 robot a diagnostics REST API. It finds every node, topic, service and action by itself, and turns failures - error logs, failed actions, /diagnostics - into clear faults: what broke, where, how bad, with a snapshot and a rosbag of the moment it happened. No changes to your code.

Quick start

1. Get Docker, if you don't have it yet.

2. While your robot is running, start ros2_medkit on its computer:

   docker run --rm --network host --ipc host \
     -e ROS_DOMAIN_ID="${ROS_DOMAIN_ID:-0}" \
     -e RMW_IMPLEMENTATION="${RMW_IMPLEMENTATION:-rmw_fastrtps_cpp}" \
     ghcr.io/selfpatch/ros2_medkit-jazzy:latest \
     ros2 launch ros2_medkit_gateway bringup.launch.py

   On Humble or Lyrical, change jazzy to humble or lyrical.

3. See what it found:

   curl localhost:8080/api/v1/apps     # every node on your robot
   curl localhost:8080/api/v1/faults   # everything that has failed

   Or browse the whole API at localhost:8080/api/v1/docs.

Tip

That's it. ros2_medkit is now watching your robot, and every new failure shows up as a fault.

No robot at hand? The sensor demo runs on any laptop and lets you break things on purpose (it needs curl and jq):

git clone https://github.com/selfpatch/selfpatch_demos.git
cd selfpatch_demos/demos/sensor_diagnostics
./run-demo.sh     # web UI on http://localhost:3000
./inject-nan.sh   # break a sensor, then watch the fault appear

What a fault looks like

After a Nav2 goal is aborted:

// GET /api/v1/faults
{
  "items": [
    { "fault_code": "ACTION_NAVIGATE_TO_POSE_ABORTED",
      "severity_label": "ERROR", "status": "CONFIRMED",
      "reporting_sources": ["/bt_navigator"] }
  ],
  "x-medkit": { "count": 1 }
}

Each fault also keeps a snapshot of the moment it happened and a rosbag of the seconds around it:

curl localhost:8080/api/v1/apps/bt_navigator/faults/ACTION_NAVIGATE_TO_POSE_ABORTED
curl -O -J localhost:8080/api/v1/apps/bt_navigator/bulk-data/rosbags/ACTION_NAVIGATE_TO_POSE_ABORTED

Watch faults live, or add the web UI

# Faults as they happen
curl -N localhost:8080/api/v1/faults/stream

# A dashboard in the browser: open http://localhost:3000, click Connect, enter http://localhost:8080
docker run -p 3000:80 ghcr.io/selfpatch/ros2_medkit_web_ui:latest

See the web UI tutorial and the Postman collection.

Install without Docker

ros2_medkit is on its way into the official ROS packages. Once it reaches your distro:

sudo apt install ros-jazzy-ros2-medkit-gateway   # or ros-humble- / ros-lyrical-
ros2 launch ros2_medkit_gateway bringup.launch.py

To build from source or use Pixi, follow the installation guide.

Troubleshooting

• Robot missing? Run ros2_medkit on the robot's computer, or one on the same network, from a terminal where your ROS 2 setup works.
• Opening it from another computer? Add server_host:=0.0.0.0 to the end of the command in step 2, on a network you trust, and use the robot's IP address instead of localhost.
• No faults from /diagnostics? Add enable_diagnostic_bridge:=true to the end of the command in step 2.
• Still stuck? See troubleshooting or ask on Discord.

How it works

ros2_medkit listens to what your robot already publishes, so it works without code changes. For more control, report faults from your own nodes with the FaultReporter client, see the integration tutorial. The API follows SOVD (ISO 17978), the diagnostics standard from the automotive world.

Features

• Finds every node, topic, service and action, with no config
• Turns error logs, failed actions and /diagnostics into faults
• Confirms each fault, keeps its history and clears it once it's fixed
• Saves a snapshot and a rosbag of the moment each fault happened
• Reads any topic as JSON, calls services and actions, and reads and sets parameters
• Streams faults as they happen
• Software updates through a plugin, and sign-in with per-user permissions
• Rosbags open in whatever tool you already use to browse robot data

Compared with standard ROS 2 diagnostics

ros2_medkit builds on them. It reads /diagnostics too, so keep your diagnostic_updater code.

	Standard ROS 2 diagnostics	ros2_medkit
Where you see it	A desktop app next to the robot	A REST API, from anywhere
Code changes	Each node reports its own health	None needed
What you get	OK, WARN, ERROR or STALE, right now	A fault that is confirmed, tracked and cleared once fixed
When it breaks	Nothing is saved	A snapshot and a rosbag
History	None	Saved, so you can look back
Covers	ROS only	ROS today, PLCs and vehicle controllers through the same API
AI assistants	No	Yes, through MCP

Ecosystem

• ros2_medkit_web_ui - see your robot and its faults in the browser
• ros2_medkit_mcp - let an AI assistant look into your robot
• ros2_medkit_clients - Python and TypeScript clients
• selfpatch_demos - ready-made demo robots, from a mobile robot to an arm

Documentation

• Documentation and the step-by-step tutorial
• REST API reference and the Postman collection

Contributing

Contributions are welcome. Read CONTRIBUTING.md, pick a good first issue, or ask on Discord and in Discussions. Report security issues privately, see SECURITY.md.

License

Apache License 2.0, see LICENSE. ros2_medkit is built and maintained by selfpatch.ai.