Spaces:
Running
Running
| # 🤖 lerobot.js | |
| **State-of-the-art AI for real-world robotics in JavaScript/TypeScript** | |
| A faithful TypeScript/JavaScript port of [Hugging Face's lerobot](https://github.com/huggingface/lerobot), bringing cutting-edge robotics AI to the JavaScript ecosystem with **zero Python dependencies**. | |
| ## 🚀 **[Complete SO-100 Setup Guide →](docs/getting_started_nodejs.md)** | |
| **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 | |
| ```bash | |
| # 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 | |
| ```bash | |
| # 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 | |
| ```bash | |
| # 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**: | |
| ```bash | |
| 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 | |
| ```bash | |
| $ 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 | |
| ```bash | |
| $ 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 | |
| ```bash | |
| $ 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](https://web.dev/serial/): | |
| - ✅ **Chrome/Edge 89+** (Desktop) | |
| - ✅ **Chrome Android 105+** (Mobile) | |
| - ✅ **HTTPS** or localhost required | |
| - ❌ Firefox/Safari (WebSerial not supported) | |
| ## 🛠️ Development | |
| ### Setup | |
| ```bash | |
| git clone https://github.com/timpietrusky/lerobot.js | |
| cd lerobot.js | |
| pnpm install | |
| ``` | |
| ### Scripts | |
| ```bash | |
| # 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: | |
| ```typescript | |
| // 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: | |
| ```typescript | |
| import { SerialPort } from "serialport"; | |
| // Cross-platform port detection | |
| const ports = await SerialPort.list(); | |
| ``` | |
| ## 🗺️ Roadmap | |
| - [x] **Phase 1**: USB port detection (CLI + Browser) | |
| - [ ] **Phase 2**: Motor communication and setup | |
| - [x] **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 | |
| ```bash | |
| # 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 | |
| - [Hugging Face lerobot team](https://github.com/huggingface/lerobot) for the original Python implementation | |
| - [WebSerial API](https://web.dev/serial/) for browser-native hardware access | |
| - [serialport](https://github.com/serialport/node-serialport) for Node.js cross-platform support | |
| --- | |
| **Built with ❤️ for the robotics community** | |