Content
# SO-101 ROS, MoveIt, LeLab, and MCP on Jetson
A self-contained, safety-gated integration for one SO-101 leader/follower pair on a Jetson Orin Nano:
official LeRobot and LeLab, ROS 2 Humble, RViz, MoveIt 2, deterministic robot skills, and semantic MCP.
Your local LeRobot checkout is treated as an external source and is not modified by this project.
> Default mode is fake. Real execution requires explicit `allow_real_execution=true` and the staged
> hardware checklist. No automatic recalibration. Emergency stop and faults preempt every command source.
## Quick start
```bash
git clone https://github.com/itsbharatj/so101_ros_mcp.git
cd so101_ros_mcp
cp .env.example .env
# Edit .env: set LEROBOT_SOURCE_DIR and optional calibration/port paths
./scripts/bootstrap.sh
./scripts/doctor.sh
./scripts/build_ros.sh
./scripts/with_ros_env.sh ros2 launch so101_bringup full_stack.launch.py \
mode:=fake rviz:=true mcp:=true \
skill_library_path:="$PWD/robot_skills"
```
In a second terminal, expose semantic MCP over local Streamable HTTP:
```bash
./scripts/run_mcp.sh --transport http --host 127.0.0.1 --port 8765
```
Headless LeLab is independent of ROS serial ownership:
```bash
./scripts/run_lelab_local.sh # Jetson only
./scripts/run_lelab_lan.sh # LAN bind; open http://<jetson-ip>:8000 from a laptop
```
## What each layer does
- LeRobot owns calibrated SO-101 motor/camera support and ML datasets.
- LeLab is the official browser UI for configuring, teleoperating, recording, replay, and training.
- ROS 2 provides standard state, action, service, TF, launch, diagnostics, and ownership interfaces.
- MoveIt computes FK/IK and collision-aware plans; it does not bypass the guarded controller.
- Robot skills are deterministic trajectories under `robot_skills/`; Codex skills under `skills/`
are maintenance instructions and never move the robot.
- MCP gives an LLM semantic tools, but all motion still passes ROS ownership, limits, MoveIt, and ESTOP.
## Safety gates
Never connect and move the arms directly from this quick start. Complete the staged
[hardware checklist](docs/testing/real_hardware_checklist.md), physically support the arm, verify
calibration and direction passively, and enable real execution only for the active test. The system
does not recalibrate automatically or disable torque automatically where the arm could collapse.
## Documentation
Start with [getting started](docs/getting_started.md), [architecture](docs/architecture/system_overview.md),
[environment setup](docs/environment/setup.md), [hardware safety](docs/hardware/safety.md),
[MoveIt operation](docs/moveit/planning_and_execution.md), [MCP tools](docs/mcp/tools.md), and the
[final engineering report](docs/final_report.md). Saved evidence lives under `artifacts/`; fake and
physical results are never mixed.
