Drop an MCAP. RobotScope explains why the robot stopped.
Open-source incident explanation for ROS 2 and Autoware — facts, inference, 3D scene, and decision timeline in one local-first view.
Quick start · 10-second showcase · MP4 · Architecture · Changelog · Contributing
RobotScope is not a robot viewer. It is an OSS observability platform that explains what the robot sensed, believed, planned, commanded, learned, and remembered — on the same timeline, coordinate frame, and causality graph.
MCAP · rosbag2 · live WebSocket | Autoware · Nav2 · MoveIt native panels | PlotJuggler-style time-series | cross-stack failure recipes | plugin-first SDK
Open the phantom-stop incident. RobotScope loads the MCAP, finds the incident, seeks to it, and separates the result into:
- Facts — observed trajectory length, perception count, thresholds, semantic entity paths, and source topics.
- Inference — a deterministic debugging lead, explicitly labeled as heuristic rather than proven root cause.
- Next checks — the exact Autoware panels to correlate at the same timestamp.
Copy the incident deep link or export a local Markdown report; no robot data is uploaded. Try localization drift or control tracking failure next.
RobotScope reconstructs the full decision loop of an embodied agent on one timeline:
| Stage | Example entities | Status |
|---|---|---|
| Sensed | LiDAR, camera, IMU, raw /sensing/* topics |
shipped |
| Believed | Localization pose, TF tree, occupancy grid, perception objects | shipped |
| Planned | Trajectories, Nav2 paths, MoveIt motion plans, lanelet routes | shipped |
| Commanded | /cmd_vel, action goals, service calls (opt-in command gateway) |
shipped |
| Learned | VLA policy state, world-model rollouts | schema-level |
| Remembered | Maps (Lanelet2 OSM / Boost bin), recorded MCAP, sidecar indexes | shipped |
Learned entities are defined in the RDM data model (/policy/*) but don't have dedicated panels yet.
Across the stack, failure recipes flag what went wrong (control tracking, phantom stop, localization drift, controller stuck, joint overspeed, scene collision) and pin them to the timeline.
| Tool | Strength | Gap RobotScope fills |
|---|---|---|
| Foxglove | MCAP replay, flexible panels | Physical AI trace, Autoware-native semantics, fully OSS core |
| Rerun | Multimodal ECS data layer | ROS2-native graph, Autoware/Nav2 daily workflow |
| RViz | ROS 3D standard | Web-native, dataset/replay, AI observability |
Winning wedge: ROS2-native + Autoware-native + Physical-AI-native + fully OSS + plugin-first.
We do not compete head-on with Foxglove on viewer polish, Rerun on generic data layers, or RViz display parity alone.
git clone https://github.com/rsasaki0109/RobotScope.git # or: git@github.com:rsasaki0109/RobotScope.git
cd RobotScope
npm install
npm run dev # → http://localhost:5173Open an MCAP file from the viewer (drag & drop) or click Connect Live for a WebSocket agent.
Incident demo (GitHub Pages): explain a phantom obstacle stop — the explainer auto-seeks to the incident and shows facts separately from inference. The same MCAP works with layout=nav2, layout=moveit, or layout=timeseries. Use demo=1 for normal playback or demo=rosbag2 for the bundled rosbag2 bag.
| Layout | Scrub to | Failure recipe |
|---|---|---|
autoware |
~0.9s / ~1.4s / end | Control tracking / phantom stop / localization drift |
nav2 |
~0.5s / ~1.8s | Controller stuck / localization uncertainty |
moveit |
~0.7s / ~1.8s | Joint overspeed / scene collision |
Each domain layout pins the stack's key panels to the timeline — Autoware (map, localization, GNSS pose, NDT, planning, perception, control), Nav2 (AMCL, costmap with a 2D occupancy preview, global/local plan, goal, controller), MoveIt (joint states, per-joint detail with overspeed flagging, planning scene, trajectory).
Nav2 demo (layout=nav2): controller-stuck recipe at ~0.5s with plan, goal, a 2D costmap preview, and cmd_vel context on the same timeline.
The timeseries layout turns any numeric ROS2 field into a live plot next to the 3D scene. Pick fields from the catalog (click or drag), overlay multiple series with per-series Y axes, or stack them one-per-plot. Add derived analysis channels — moving average, derivative (d/dt), or series math (A + - * / B) — computed live from the selected signals. Drag to zoom / wheel to pan with a shared time axis, click anywhere on a plot to seek the 3D scene and timeline, and export the visible series to CSV. Switch the time axis between elapsed seconds and wall-clock, or pin the Y axis to a fixed range. Zooming refetches just the visible window at full resolution, so it stays responsive on large recordings. Works on MCAP, rosbag2, and live agents.
Time-series demo (layout=timeseries): localization score and lateral / longitudinal error overlaid with per-series Y axes, plus a moving-average and a d/dt analysis channel computed from them; click a plot to seek the 3D scene, zoom for full-resolution detail, export to CSV.
rosbag2 demo: swap demo=1 for demo=rosbag2 to load a bundled rosbag2 (.db3) bag instead of MCAP — the same time-series tools work on std_msgs/Float64, geometry_msgs/Twist, and nav_msgs/Odometry fields decoded straight from the SQLite store. (You can also drag & drop your own .db3 or a rosbag2 folder.)
The timeline footer shows all stack recipes at the playhead (amber = Autoware, blue = Nav2, purple = MoveIt). Click colored ticks to jump. When recipes are active, the cross-layout banner below the command bar lists all stacks — click a chip to switch layout.
See docs/live-agent.md — pick preset Local demo :8765 in the command bar, or add ?live=1 to auto-connect.
Safety: the command / service / action gateways are opt-in and allowlisted — nothing is published unless you explicitly enable it. Use them against demo or controlled systems only.
# Generate demo recording (TF + odometry + Autoware topics)
node scripts/create-tf-demo.mjs # → sample_data/demo-scene.mcap
# Terminal 1 — live replay agent
npm run demo:live-agent
# Terminal 2 — viewer
npm run dev # Connect Live → ws://127.0.0.1:8765
# Domain layouts
npm run demo:autoware
npm run demo:nav2
npm run demo:moveit
npm run demo:example
# Native ROS2 agent (requires a sourced ROS distro)
npm run demo:ros2-agent -- --profile autoware
# Static GitHub Pages bundle (local preview)
npm run build:pages
npm run preview:pages # → http://127.0.0.1:4173/RobotScope/?layout=autoware&demo=1
npm run capture:showcase # → hero GIF + MP4 + social cardRobotScope/
├── docs/ Architecture & guides
├── packages/
│ ├── robotscope-core/ RDM schema, query API, MCAP ingest
│ └── robotscope-viewer/ React + Three.js web viewer
├── plugins/
│ ├── autoware/ Autoware-native panels
│ ├── nav2/ Nav2 stack panels
│ ├── moveit/ MoveIt panels
│ └── example/ Third-party plugin template (SDK)
├── schemas/ RDM & plugin manifest schemas
├── agent/ ROS2 live bridge (C++/Python)
├── examples/ Layouts & demo configs
└── sample_data/ Sample MCAP fetch scripts
Lanelet2 Boost binary parsing consolidated for daily map workflows. See the release notes and the full CHANGELOG.md.
Beta — viewer is usable daily, but the RDM schema and plugin contracts may still change before a v2 GA.
| Layer | Highlight |
|---|---|
| Map | Boost bin parse — heuristic boundary extraction + Map panel (Boost bin) badge |
| Live (v1.x) | Action gateway — goal send · feedback tracking · cancel · preempt · timeline panel |
| Live (v1.x) | Command gateway — 6-DOF Twist editor · service Trigger calls (allowlisted, opt-in) |
| Map (v0.x) | Lanelet2 OSM sidecar — relations + regulatory elements · RL2D 2D/3D preview |
| Ingest (v0.x) | MCAP + sidecar index · rosbag2 .db3 / folder bags · live WebSocket |
Docs: Lanelet2 Boost bin guide · Migration v1.7 alpha → beta · Known limitations
Out of scope (v1.7 beta): full lanelet topology · regulatory yield refs · cross-boost portability · cloud / fleet dashboard.
Release history: every alpha/beta/GA from v0.1 onward — with per-release shipped features, docs, and scope boundaries — lives in CHANGELOG.md.
See docs/architecture.md for the master design document.
Core data model — the Robot Data Model (RDM): Entity + Component + Archetype + Timeline + Frame + Causality.
Entity path examples:
/world/map/lanelet2
/robot/ego/localization/pose
/policy/main/vla_state
Raw logs stay in MCAP. Indexes live in .robotscope/ sidecar files.
| Layer | Choice |
|---|---|
| UI | React, TypeScript, Vite, Zustand |
| 3D | Three.js (WebGL2 primary, WebGPU experimental) |
| Core | TypeScript (Rust migration path for MCAP/index) |
| Agent | C++ rclcpp + WebSocket |
| Storage | MCAP + DuckDB/SQLite sidecar |
- Core, SDK, examples: Apache-2.0
- Schemas: CC0 or Apache-2.0 (see
schemas/) - Docs: CC-BY-4.0
See docs/contributing.md. Issues and PRs are welcome.
Try it first: open an MCAP and you immediately get a ROS2 + Autoware + policy trace on a fully open core — then bring your own renderer or plugin.