A ROS2 data-recording system for robot teaching — record topics from ROS2-compatible robots and persist them as MCAP, all driven from a web UI.
Release status — pre-1.0 (v0.1.0, beta). APIs, data formats, and the CLI/UI may change without notice. Pin a specific version for any production use.
Quickstart · Documentation · Issues · Security
OpenLUTRA records ROS2 topics from ROS2-compatible robots and persists them as MCAP files, with a web UI for starting/stopping recordings, monitoring live topic quality, and reviewing recorded data. It targets robot teaching and teleoperation workflows where reliable, observable data collection matters.
Robot ──ROS2 Topics──▶ FastAPI
/robot_slave/states (100Hz) ├── subprocess: ros2 bag record → MCAP
/robot_master/cmd (100Hz) ├── rclpy: frequency monitor + gap detection
/*_depth_cam/.../compressed └── SSE: real-time stream → Web UI
A hybrid architecture is used:
| Function | Technology | Reason |
|---|---|---|
| Recording | subprocess (ros2 bag record) |
Memory isolation; safe for long sessions |
| Monitoring | rclpy (lightweight) |
Real-time alerts; keeps only the latest N messages |
| Quality analysis | mcap Python library |
Accurate post-hoc metrics |
See docs/ARCHITECTURE.md for details.
- One-click recording from a web UI — start/stop
ros2 bag record -s mcapwithout touching a terminal. - Live topic monitoring — per-topic Hz, miss rate, and gap detection over SSE.
- MCAP-first storage — explicit
-s mcap(not the default sqlite3); no Python-side buffering for memory safety. - Automatic quality analysis — IQR-based loss detection (
Q3 + 1.5×IQR), per-topic status, persistent quality reports. - Recording browser — search, filter, and inspect recordings; per-topic timeline heatmap, loss events, and video/joint previews.
- MCAP → MP4 preview — per-camera MP4s generated on demand from MCAP, streamed frame-by-frame through ffmpeg.
- Pluggable validation — built-in validators plus a
@register_validatorextension point for custom per-recording rules. See docs/domain/custom_validators.md. - Robot config as YAML — topics, expected Hz, and
ROS_DOMAIN_IDswitched via theROBOT_CONFIGenvironment variable.
make setup # one-time: install dependencies + copy .env
make up # start dev environment (simulator + backend + frontend)| Service | URL |
|---|---|
| Frontend | http://localhost:5173 |
| Backend API | http://localhost:8000 |
| API docs | http://localhost:8000/docs |
cp .env.example .env # set ROS_DOMAIN_ID to match your robot
make prod-up # production start (network_mode: host)See docs/SETUP.md for prerequisites, environment variables, and deployment notes.
| Command | Description |
|---|---|
make up |
Start dev environment (with simulator) |
make down |
Stop |
make build |
Build Docker images |
make prod-up |
Production start (host network) |
make prod-down |
Production stop |
See the Makefile for the full list (lint, test, format, generate, etc.).
See docs/ARCHITECTURE.md for the full data flow.
Set the task name (for example pick-and-place) from the inline editor in the header. The task name becomes the prefix of the recording directory ({task}_{timestamp}). If left unset, the recording directory is the timestamp alone.
- Select topics — check the topics you want to record in the left panel (ROS2 topics are auto-discovered).
- Start recording — press the record button.
- Monitor live — watch per-topic Hz and miss% in the left panel; the bottom Missing Rate graph shows the time series.
- Stop recording — press the record button again. Quality analysis runs automatically.
- Review — open the recordings page or the MCAP detail page to inspect per-topic metrics (loss rate, continuity score).
| Document | Contents |
|---|---|
| docs/TECH_STACK.md | Tech stack (versions, tooling) |
| docs/STRUCTURE.md | Directory layout (backend / frontend / tests) |
| docs/SETUP.md | Setup guide (prerequisites, dev, prod, env vars) |
| docs/ARCHITECTURE.md | Architecture (system, data flow, Docker) |
| docs/DEVELOPMENT.md | Development guide (style, branching, tests) |
| docs/domain/ | Domain notes (ROS2, MCAP, LeRobot, quality analysis) |
| examples/ | Reference snippets (e.g. plugging in custom ROS2 message types) |
OpenLUTRA is currently v0.1.0 (beta) and follows the SemVer 0.y.z convention: minor versions may include breaking changes until v1.0.0. Only the latest main is eligible for security fixes (see SECURITY.md).
Docker images are not published at this stage; the project is distributed as source.
Nothing on this list is committed — these are directions we are currently exploring.
- LeRobot-format export — conversion and output of recordings to the LeRobot dataset format.
- Richer validation and quality analysis — expand the set of built-in validators and quality metrics, and surface more actionable diagnostics in the UI.
- Recording labeling — attach labels, tags, and review status to recordings to organize datasets for downstream training.
- Seamless storage integrations — first-class support for shipping recorded files to various storage backends (object stores, dataset platforms, etc.).
- etc. — feedback via issues is welcome.
- File an issue at https://github.com/fastlabel/open-lutra/issues. Bug reports, feature requests, and questions are welcome in English or Japanese.
- For security reports, see SECURITY.md — please do not open a public issue.
External pull requests are not accepted at this stage. Issues are welcome — see CONTRIBUTING.md.
- Repository root: Apache License 2.0
/examplesdirectory: BSD Zero Clause License (0BSD)
See NOTICE for required attributions, including third-party components redistributed under their original licenses.
See TRADEMARKS.md for the policy on use of the "OpenLUTRA" and "FastLabel" names and logos.
OpenLUTRA builds on the work of many upstream projects, including ROS2, the MCAP format, FastAPI, and React.
Maintained by FastLabel, Inc.