Hugging Face's logo

Spaces:
NERDDISCO
/
LeRobot.js
Running

App Files Community
LeRobot.js / README.md
NERDDISCO's picture
NERDDISCO
feat: added calibrate
ec936d5
preview code
|
raw
history blame
9.23 kB

🤖 lerobot.js

State-of-the-art AI for real-world robotics in JavaScript/TypeScript

A faithful TypeScript/JavaScript port of Hugging Face's lerobot, bringing cutting-edge robotics AI to the JavaScript ecosystem with zero Python dependencies.

🚀 Complete SO-100 Setup Guide →

Get your SO-100 robot arms working in 10 minutes with lerobot.js!
Step-by-step guide covering port detection, motor setup, calibration, and teleoperation.

✨ Features

  • 🔌 USB Port Detection: Find robot arm serial ports in Node.js CLI and browser
  • 🎛️ Robot Calibration: Complete SO-100 follower/leader calibration system
  • 🌐 Universal: Works in Node.js, browsers, and Edge devices
  • 🎯 Python Faithful: Identical UX and messaging to original lerobot
  • 📱 WebSerial: Browser-native serial port access (Chrome/Edge 89+)
  • 🚀 Zero Dependencies: No Python runtime required
  • 📦 Lightweight: Pure TypeScript implementation

🚀 Quick Start

Installation & Setup 

# Option 1: Install globally (recommended)
npm install -g lerobot

# Option 2: Use directly with npx (no installation)
npx lerobot --help

# Verify installation
lerobot --help

Essential Commands 

# 1. Find USB ports for your robot arms
lerobot find-port

# 2. Calibrate follower robot
lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm

# 3. Calibrate leader teleoperator
lerobot calibrate --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm

# Show command help
lerobot calibrate --help

Alternative Usage Methods 

# Method 1: Global CLI (after installation)
lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_robot

# Method 2: Direct with npx (no installation needed)
npx lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_robot

# Method 3: Development setup (if you cloned the repo)
git clone https://github.com/timpietrusky/lerobot.js
cd lerobot.js && pnpm install && pnpm run install-global

Browser Usage

  1. Development:

    git clone https://github.com/timpietrusky/lerobot.js
cd lerobot.js
pnpm install
pnpm run dev

  2. Visit: http://localhost:5173

  3. Use the interface:

    • Click "Show Available Ports" to see connected devices
    • Click "Find MotorsBus Port" for guided port detection

📖 Documentation

Find USB Ports

Identify which USB ports your robot arms are connected to - essential for SO-100 setup.

CLI Example 

$ lerobot find-port

Finding all available ports for the MotorsBus.
Ports before disconnecting: ['COM3', 'COM4']
Remove the USB cable from your MotorsBus and press Enter when done.

The port of this MotorsBus is 'COM3'
Reconnect the USB cable.

Robot Calibration

Calibrate SO-100 robot arms for precise control and teleoperation.

Calibrate Follower Robot 

$ lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm

Calibrating device...
Device type: so100_follower
Port: COM4
ID: my_follower_arm

Connecting to so100_follower on port COM4...
Connected successfully.
Starting calibration procedure...
[... calibration steps ...]
Calibration completed successfully.
Configuration saved to: ~/.cache/huggingface/lerobot/calibration/robots/so100_follower/my_follower_arm.json
Disconnecting from robot...

Calibrate Leader Teleoperator 

$ lerobot calibrate --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm

Calibrating teleoperator...
[... guided calibration process ...]
Configuration saved to: ~/.cache/huggingface/lerobot/calibration/teleoperators/so100_leader/my_leader_arm.json

Browser Interface

  1. Visit: Built-in web interface with calibration controls
  2. Port Selection: Browser dialog for device selection
  3. Interactive Calibration: Step-by-step guided process
  4. File Download: Automatic calibration file download

Platform Support

Platform Method Requirements
Node.js lerobot find-port, calibrate Node.js 18+, Windows/macOS/Linux
Browser Web interface + calibration Chrome/Edge 89+, HTTPS or localhost
Mobile Browser Chrome Android 105+

Browser Compatibility

The browser version uses the WebSerial API:

  • ✅ Chrome/Edge 89+ (Desktop)
  • ✅ Chrome Android 105+ (Mobile)
  • ✅ HTTPS or localhost required
  • ❌ Firefox/Safari (WebSerial not supported)

🛠️ Development

Setup 

git clone https://github.com/timpietrusky/lerobot.js
cd lerobot.js
pnpm install

Scripts 

# Development server (browser)
pnpm run dev

# Build CLI for Node.js
pnpm run build:cli

# Build web interface
pnpm run build:web

# Test CLI locally
pnpm run cli:find-port

# Build everything
pnpm run build

Project Structure 

src/
├── lerobot/
│   ├── node/
│   │   └── find_port.ts     # Node.js implementation
│   └── web/
│       └── find_port.ts     # Browser implementation (WebSerial)
├── cli/
│   └── index.ts             # CLI interface
├── main.ts                  # Web interface
└── web_interface.css        # UI styles

🎯 Design Principles

1. Python lerobot Faithfulness

  • Identical commands: npx lerobot find-port ↔ python -m lerobot.find_port
  • Same terminology: "MotorsBus", not "robot arms"
  • Matching output: Error messages and workflows identical
  • Familiar UX: Python lerobot users feel immediately at home

2. Platform Abstraction

  • Universal core: Shared robotics logic
  • Adaptive UX: CLI prompts vs. browser modals
  • Progressive enhancement: Works everywhere, enhanced on capable platforms

3. Zero Dependencies

  • Node.js: Only uses built-in modules + lightweight serialport
  • Browser: Native WebSerial API, no external libraries
  • Deployment: Single package, no Python runtime needed

🔧 Technical Details

WebSerial API

The browser implementation leverages modern web APIs:

// Request permission to access serial ports
await navigator.serial.requestPort();

// List granted ports
const ports = await navigator.serial.getPorts();

// Detect disconnected devices
const removedPorts = portsBefore.filter(/* ... */);

CLI Implementation

Node.js version uses the serialport library for cross-platform compatibility:

import { SerialPort } from "serialport";

// Cross-platform port detection
const ports = await SerialPort.list();

🗺️ Roadmap

  • Phase 1: USB port detection (CLI + Browser)
  • Phase 2: Motor communication and setup
  • Phase 3: Robot calibration tools ✅ COMPLETE!
  • Phase 4: Dataset management and visualization
  • Phase 5: Policy inference (ONNX.js)
  • Phase 6: Training infrastructure

✅ Recently Completed

Phase 3 - Robot Calibration (December 2024)

  • Complete SO-100 follower/leader calibration system
  • CLI commands identical to Python lerobot
  • Web browser calibration interface
  • HF-compatible configuration storage
  • Comprehensive error handling and validation

📋 CLI Command Reference

Available Commands 

# Show all commands
lerobot --help

# Find USB ports
lerobot find-port

# Calibrate robot
lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=ROBOT_ID

# Calibrate teleoperator
lerobot calibrate --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=TELEOP_ID

# Show calibration help
lerobot calibrate --help

Configuration Files

Calibration data follows Hugging Face directory structure:

~/.cache/huggingface/lerobot/calibration/
├── robots/
│   └── so100_follower/
│       └── ROBOT_ID.json
└── teleoperators/
    └── so100_leader/
        └── TELEOP_ID.json

Environment Variables:

  • HF_HOME: Override Hugging Face home directory
  • HF_LEROBOT_CALIBRATION: Override calibration directory

🤝 Contributing

We welcome contributions! This project follows the principle of Python lerobot faithfulness - all features should maintain identical UX to the original.

Guidelines

  1. Check Python lerobot implementation first
  2. Maintain identical command structure and messaging
  3. Follow snake_case file naming convention
  4. Test on both Node.js and browser platforms

📄 License

Apache 2.0 - Same as original lerobot

🙏 Acknowledgments

Built with ❤️ for the robotics community