feat: added calibrate

README.md

@@ -4,26 +4,64 @@
 
 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**: ~2.3KB package size
+- 📦 **Lightweight**: Pure TypeScript implementation
 
 ## 🚀 Quick Start
 
-### CLI Usage (Node.js)
+### Installation & Setup
 
 ```bash
-# Use directly without installation
-npx lerobot find-port
-
-# Or install globally
+# 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
@@ -52,7 +90,7 @@ Identify which USB ports your robot arms are connected to - essential for SO-100
 #### CLI Example
 
 ```bash
-$ npx lerobot find-port
+$ lerobot find-port
 
 Finding all available ports for the MotorsBus.
 Ports before disconnecting: ['COM3', 'COM4']
@@ -62,20 +100,53 @@ The port of this MotorsBus is 'COM3'
 Reconnect the USB cable.
 ```
 
-#### Browser Example
+### 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
 
-1. Click "Show Available Ports" → Browser asks for permission
-2. Grant access to your serial devices
-3. See list of connected ports
-4. Use "Find MotorsBus Port" for detection workflow
+```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** | `npx lerobot find-port` | Node.js 18+, Windows/macOS/Linux    |
-| **Browser** | Web interface           | Chrome/Edge 89+, HTTPS or localhost |
-| **Mobile**  | Browser                 | Chrome Android 105+                 |
+| 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
 
@@ -183,11 +254,61 @@ const ports = await SerialPort.list();
 
 - [x] **Phase 1**: USB port detection (CLI + Browser)
 - [ ] **Phase 2**: Motor communication and setup
-- [ ] **Phase 3**: Robot calibration tools
+- [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.

docs/conventions.md

@@ -10,7 +10,11 @@
 
 ## Core Rules
 
-- you never start the dev server, because it is already running
+- **Never Start/Stop Dev Server**: The development server is already managed by the user - never run commands to start, stop, or restart the server
+- **Python lerobot Faithfulness**: Maintain exact UX/API compatibility with Python lerobot - commands, terminology, and workflows must match identically
+- **Serial API Separation**: Always use `serialport` package for Node.js and Web Serial API for browsers - never mix or bridge these incompatible APIs
+- **Minimal Console Output**: Only show essential information - reduce cognitive load for users
+- **Hardware-First Testing**: Always validate with real hardware, not just simulation
 
 ## Project Goals
 
@@ -74,10 +78,25 @@ lerobot/
 ### 3. Platform Abstraction
 
 - **Universal Core**: Platform-agnostic robotics logic
-- **Web Adapters**: Browser-specific implementations (WebGL, WebAssembly, WebUSB)
-- **Node Adapters**: Node.js implementations (native modules, serial ports)
+- **Web Adapters**: Browser-specific implementations (WebGL, WebAssembly, **Web Serial API**)
+- **Node Adapters**: Node.js implementations (native modules, **serialport package**)
 
-### 4. Progressive Enhancement
+### 4. Serial Communication Standards (Critical)
+
+**Serial communication must use platform-appropriate APIs - never mix or bridge:**
+
+- **Node.js Platform**: ALWAYS use `serialport` package
+  - Event-based: `port.on('data', callback)`
+  - Programmatic port listing: `SerialPort.list()`
+  - Direct system access: `new SerialPort({ path: 'COM4' })`
+- **Web Platform**: ALWAYS use Web Serial API
+  - Promise/Stream-based: `await reader.read()`
+  - User permission required: `navigator.serial.requestPort()`
+  - Browser security model: User must select port via dialog
+
+**Why this matters:** The APIs are completely incompatible - different patterns, different capabilities, different security models. Mixing them leads to broken implementations.
+
+### 5. Progressive Enhancement
 
 - **Core Functionality**: Works everywhere (basic policy inference)
 - **Enhanced Features**: Leverage platform capabilities (GPU acceleration, hardware access)
@@ -145,3 +164,44 @@ lerobot/
 - **3D Graphics**: Three.js for simulation and visualization
 - **Hardware**: Platform-specific libraries for device access
 - **Development**: Vitest, ESLint, Prettier
+
+## Hardware Implementation Lessons
+
+### Critical Hardware Compatibility
+
+#### Baudrate Configuration
+
+- **Feetech Motors (SO-100)**: MUST use 1,000,000 baud to match Python lerobot
+- **Python Reference**: `DEFAULT_BAUDRATE = 1_000_000` in Python lerobot codebase
+- **Common Mistake**: Using 9600 baud causes "Read timeout" errors despite device connection
+- **Verification**: Always test with real hardware - simulation won't catch baudrate issues
+
+#### Console Output Philosophy
+
+- **Minimal Cognitive Load**: Reduce console noise to absolute minimum
+- **Silent Operations**: Connection, initialization, cleanup should be silent unless error occurs
+- **Error-Only Logging**: Only show output when user needs to take action or when errors occur
+- **Professional UX**: Robotics tools should have clean, distraction-free interfaces
+
+#### Calibration Flow Matching
+
+- **Python Behavior**: When user hits Enter during range recording, reading stops IMMEDIATELY
+- **No Final Reads**: Never read motor positions after user completes calibration
+- **User Expectation**: After Enter, user should be able to release robot (positions will change)
+- **Flow Testing**: Always validate against Python lerobot's exact behavior
+
+### Development Process Requirements
+
+#### CLI Build Process
+
+- **Critical**: After TypeScript changes, MUST run `pnpm run build` to update CLI
+- **Global CLI**: `lerobot` command uses compiled `dist/` files, not source
+- **Testing Flow**: Edit source → Build → Test CLI → Repeat
+- **Common Mistake**: Testing source changes without rebuilding CLI
+
+#### Hardware Testing Priority
+
+- **Real Hardware Required**: Simulation cannot catch hardware-specific issues
+- **Baudrate Validation**: Only real devices will reveal communication problems
+- **User Flow Testing**: Test complete calibration workflows with actual hardware
+- **Port Management**: Ensure proper port cleanup between testing sessions

docs/getting_started_nodejs.md

@@ -0,0 +1,385 @@
+# Getting Started with SO-100 Robot Arms - lerobot.js (Node.js/TypeScript)
+
+> **🚀 Complete setup guide for SO-100 robot arms using lerobot.js**  
+> Zero Python dependencies - pure TypeScript/JavaScript implementation
+
+## Prerequisites
+
+- **Node.js 18+** (Windows, macOS, or Linux)
+- **SO-100 robot arms** (follower + leader)
+- **USB cables** for both arms
+
+## 🚨 Current Implementation Status
+
+**✅ Available Now:**
+
+- `lerobot find-port` - USB port detection
+- `lerobot calibrate` - Robot/teleoperator calibration
+
+**🔄 Coming Soon (Python equivalent shown for reference):**
+
+- `lerobot check-motors` - Motor ID verification
+- `lerobot setup-motors` - Motor ID configuration
+- `lerobot teleoperate` - Real-time control
+- `lerobot record` - Data collection
+
+> For now, use Python lerobot for motor setup, then switch to lerobot.js for calibration!
+
+## Install lerobot.js
+
+### Option 1: Global Installation (Recommended)
+
+```bash
+# Install globally for easy access
+npm install -g lerobot
+
+# Verify installation
+lerobot --help
+```
+
+### Option 2: Use without Installation
+
+```bash
+# Use directly with npx (no installation needed)
+npx lerobot --help
+```
+
+### Option 3: Development Setup
+
+```bash
+# Clone and build from source
+git clone https://github.com/timpietrusky/lerobot.js
+cd lerobot.js
+pnpm install
+pnpm run install-global
+```
+
+## 1. Identify USB Ports
+
+**What this does:** Identifies which USB port each robot arm is connected to. Essential for all subsequent commands.
+
+### Connect and Test
+
+1. **Connect both arms**: Plug in USB + power for both follower and leader arms
+2. **Run port detection**:
+
+```bash
+lerobot find-port
+```
+
+**Example output:**
+
+```
+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.
+```
+
+3. **Repeat for second arm**: Run `lerobot find-port` again to identify the other arm
+4. **Record the ports**: Note which port belongs to which arm (e.g., COM3=leader, COM4=follower)
+
+## 2. Check Motor IDs
+
+**Important: Always do this first!** This checks if your robot motors are already configured correctly.
+
+**What are motor IDs?** Each motor needs a unique ID (1, 2, 3, 4, 5, 6) so the computer can talk to them individually. New motors often have the same default ID (1).
+
+### Check Follower Arm
+
+```bash
+# 🔄 Coming soon - use Python lerobot for now:
+python -m lerobot.check_motors --robot.port=COM4
+```
+
+### Check Leader Arm
+
+```bash
+# 🔄 Coming soon - use Python lerobot for now:
+python -m lerobot.check_motors --teleop.port=COM3
+```
+
+**✅ If you see this - you're ready for calibration:**
+
+```
+🎉 PERFECT! This arm is correctly configured:
+   ✅ All 6 motors found: [1, 2, 3, 4, 5, 6]
+   ✅ Correct baudrate: 1000000
+
+✅ This arm is ready for calibration!
+```
+
+**⚠️ If you see this - continue to "Setup Motors" below:**
+
+```
+⚠️  This arm needs motor ID setup:
+   Expected IDs: [1, 2, 3, 4, 5, 6]
+   Found IDs: [1, 1, 1, 1, 1, 1]
+   Duplicate IDs: [1] (likely all motors have ID=1)
+```
+
+## 3. Setup Motors (If Needed)
+
+**⚠️ Only do this if the motor check above showed your motors need setup!**
+
+This assigns unique ID numbers to each motor. It's a one-time process.
+
+**Safety notes:**
+
+- Power down (unplug power + USB) when connecting/disconnecting motors
+- Connect only ONE motor at a time during setup
+- Remove gears from leader arm before this step
+
+### Setup Follower Arm
+
+```bash
+# 🔄 Coming soon - use Python lerobot for now:
+python -m lerobot.setup_motors --robot.type=so100_follower --robot.port=COM4
+```
+
+### Setup Leader Arm
+
+```bash
+# 🔄 Coming soon - use Python lerobot for now:
+python -m lerobot.setup_motors --teleop.type=so100_leader --teleop.port=COM3
+```
+
+**After setup:** Run the motor check commands again to verify everything worked.
+
+## 4. Calibrate Robot Arms
+
+**What is calibration?** Teaches both arms to understand joint positions identically. Crucial for leader arm to control follower arm properly.
+
+**Why needed?** Manufacturing differences mean position sensors might read different values for the same physical position.
+
+### Calibrate Follower Arm
+
+```bash
+lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm
+```
+
+**Example output:**
+
+```
+Calibrating device...
+Device type: so100_follower
+Port: COM4
+ID: my_follower_arm
+
+Connecting to so100_follower on port COM4...
+Connected successfully.
+Starting calibration procedure...
+Initializing robot communication...
+Robot communication initialized.
+Reading motor positions...
+Motor positions: [0.5, 45.2, 90.1, 0.0, 0.0, 0.0]
+Setting motor limits...
+Motor limits configured.
+Calibrating motors...
+  Calibrating motor 1/6...
+  Motor 1 calibrated successfully.
+  [... continues for all 6 motors ...]
+Verifying calibration...
+Calibration verification passed.
+Calibration completed successfully.
+Configuration saved to: ~/.cache/huggingface/lerobot/calibration/robots/so100_follower/my_follower_arm.json
+Disconnecting from robot...
+```
+
+**Calibration steps:**
+
+1. **Move to neutral position**: Position arm in standard reference pose
+2. **Move joints through range**: Gently move each joint to its limits
+3. **Automatic save**: Calibration data saved automatically
+
+### Calibrate Leader Arm
+
+```bash
+lerobot calibrate --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm
+```
+
+**Calibration steps:**
+
+1. **Move to neutral position**: Same reference pose as follower
+2. **Move through range**: Test all joint movements
+3. **Button mapping**: Test all buttons and triggers
+4. **Automatic save**: Configuration saved
+
+**✅ After both arms are calibrated, you're ready for teleoperation!**
+
+## 5. Test Teleoperation
+
+Test that your leader arm can control the follower arm:
+
+```bash
+# 🔄 Coming soon - use Python lerobot for now:
+python -m lerobot.teleoperate \
+  --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm \
+  --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm
+```
+
+**Expected behavior:**
+
+- Both arms connect automatically
+- Moving leader arm → follower arm copies movements
+- Press `Ctrl+C` to stop teleoperation
+
+## 6. Record Demonstrations (Optional)
+
+Record demonstrations for training robot learning policies:
+
+```bash
+# 🔄 Coming soon - use Python lerobot for now:
+python -m lerobot.record \
+  --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm \
+  --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm \
+  --dataset-name=my_first_dataset \
+  --num-episodes=10 \
+  --task="Pick up the red block and place it in the box"
+```
+
+## CLI Command Reference
+
+### Core Commands
+
+```bash
+# Show all available commands
+lerobot --help
+
+# Find USB ports
+lerobot find-port
+
+# Calibrate robot
+lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_robot
+
+# Calibrate teleoperator
+lerobot calibrate --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_teleop
+
+# Show calibrate help
+lerobot calibrate --help
+```
+
+### Alternative Usage Methods
+
+```bash
+# Method 1: Global installation (recommended)
+lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_robot
+
+# Method 2: Use with npx (no installation)
+npx lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_robot
+
+# Method 3: Development mode (if you cloned the repo)
+pnpm run cli:calibrate -- --robot.type=so100_follower --robot.port=COM4 --robot.id=my_robot
+
+# Method 4: Direct built CLI
+node dist/cli/index.js calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_robot
+```
+
+## Configuration Files
+
+Calibration data is stored in Hugging Face compatible directories:
+
+```
+~/.cache/huggingface/lerobot/calibration/
+├── robots/
+│   └── so100_follower/
+│       └── my_follower_arm.json
+└── teleoperators/
+    └── so100_leader/
+        └── my_leader_arm.json
+```
+
+**Environment variables:**
+
+- `HF_HOME`: Override Hugging Face home directory
+- `HF_LEROBOT_CALIBRATION`: Override calibration directory
+
+## Troubleshooting
+
+### Port Issues
+
+```bash
+# Error: Could not connect to robot on port COM99
+lerobot find-port  # Re-run to find correct ports
+```
+
+**Solutions:**
+
+1. Verify robot is connected to specified port
+2. Check no other application is using the port
+3. Verify you have permission to access the port
+4. Try different USB port or cable
+
+### Motor Communication Issues
+
+```bash
+# Error: Robot initialization failed
+```
+
+**Solutions:**
+
+1. Check power connection to robot
+2. Verify USB cable is working
+3. Ensure motors are properly daisy-chained
+4. Check motor IDs are correctly configured
+
+### Permission Issues
+
+**Windows:**
+
+```bash
+# Run as administrator if needed
+```
+
+**Linux/macOS:**
+
+```bash
+# Add user to dialout group
+sudo usermod -a -G dialout $USER
+# Log out and back in
+```
+
+## Browser Usage (Alternative)
+
+You can also use lerobot.js in the browser with Web Serial API:
+
+1. **Build and serve**:
+
+   ```bash
+   git clone https://github.com/timpietrusky/lerobot.js
+   cd lerobot.js
+   pnpm install
+   pnpm run build:web
+   pnpm run preview
+   ```
+
+2. **Visit**: `http://localhost:4173`
+3. **Requirements**: Chrome/Edge 89+ with HTTPS or localhost
+
+## Next Steps
+
+✅ **You now have working SO-100 robot arms with lerobot.js!**
+
+**Continue with robot learning:**
+
+- Add cameras for vision-based tasks
+- Record more complex demonstrations
+- Train neural network policies
+- Run policies autonomously
+
+**Resources:**
+
+- [lerobot.js Documentation](https://github.com/timpietrusky/lerobot.js)
+- [Original Python lerobot](https://github.com/huggingface/lerobot)
+- [Hugging Face Robotics](https://huggingface.co/docs/lerobot)
+
+**Community:**
+
+- [Discord](https://discord.com/invite/s3KuuzsPFb) - Get help and discuss
+- [GitHub Issues](https://github.com/timpietrusky/lerobot.js/issues) - Report bugs
+
+---
+
+**🎉 Congratulations! You're now ready to use SO-100 robot arms with TypeScript/JavaScript!**

docs/planning/002_calibrate.md

@@ -0,0 +1,371 @@
+# User Story 002: Robot Calibration
+
+## Story
+
+**As a** robotics developer setting up SO-100 robot arms  
+**I want** to calibrate my robot arms to establish proper motor positions and limits  
+**So that** my robot operates safely and accurately within its intended range of motion
+
+## Background
+
+Robot calibration is a critical setup step that establishes the zero positions, movement limits, and safety parameters for robotic arms. The Python lerobot provides a `calibrate.py` script that:
+
+1. Connects to the specified robot (follower) or teleoperator (leader)
+2. Runs the calibration procedure to set motor positions and limits
+3. Saves calibration data for future robot operations
+4. Ensures safe operation by establishing proper movement boundaries
+
+The calibration process uses the USB ports identified by the `find_port` functionality from User Story 001, and supports both robot arms (followers) and teleoperators (leaders).
+
+## Acceptance Criteria
+
+### Core Functionality
+
+- [x] **Robot Connection**: Connect to robot using discovered USB port from find_port
+- [x] **Robot Types**: Support SO-100 follower robot type
+- [x] **Teleoperator Support**: Support SO-100 leader teleoperator
+- [x] **Calibration Process**: Run device-specific calibration procedures
+- [x] **Configuration Management**: Handle robot-specific configuration parameters
+- [x] **Cross-Platform**: Work on Windows, macOS, and Linux
+- [x] **CLI Interface**: Provide `npx lerobot calibrate` command identical to Python version
+
+### User Experience
+
+- [x] **Clear Feedback**: Show calibration progress and status messages
+- [x] **Error Handling**: Handle connection failures, calibration errors gracefully
+- [x] **Safety Validation**: Confirm successful calibration before completion
+- [x] **Results Display**: Show calibration completion status and saved configuration
+
+### Technical Requirements
+
+- [x] **Dual Platform**: Support both Node.js (CLI) and Web (browser) platforms
+- [x] **Node.js Implementation**: Use serialport package for Node.js serial communication
+- [x] **Web Implementation**: Use Web Serial API for browser serial communication
+- [x] **TypeScript**: Fully typed implementation following project conventions
+- [x] **CLI Tool**: Executable via `npx lerobot calibrate` (matching Python version)
+- [x] **Configuration Storage**: Save/load calibration data to appropriate locations per platform
+- [x] **Platform Abstraction**: Abstract robot/teleoperator interfaces work on both platforms
+
+## Expected User Flow
+
+### Node.js CLI Calibration (Traditional)
+
+```bash
+$ npx lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm
+
+Calibrating robot...
+Robot type: so100_follower
+Port: COM4
+ID: my_follower_arm
+
+Connecting to robot...
+Connected successfully.
+Starting calibration procedure...
+Calibration completed successfully.
+Configuration saved to: ~/.cache/huggingface/lerobot/calibration/robots/so100_follower/my_follower_arm.json
+Disconnecting from robot...
+```
+
+### Web Browser Calibration (Interactive)
+
+```typescript
+// In a web application
+import { calibrate } from "lerobot/web/calibrate";
+
+// Must be triggered by user interaction (button click)
+await calibrate({
+  robot: {
+    type: "so100_follower",
+    id: "my_follower_arm",
+    // port will be selected by user via browser dialog
+  },
+});
+
+// Browser shows port selection dialog
+// User selects robot from available serial ports
+// Calibration proceeds similar to CLI version
+// Configuration saved to browser storage or downloaded as file
+```
+
+### Teleoperator Calibration
+
+```bash
+$ npx lerobot calibrate --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm
+
+Calibrating teleoperator...
+Teleoperator type: so100_leader
+Port: COM3
+ID: my_leader_arm
+
+Connecting to teleoperator...
+Connected successfully.
+Starting calibration procedure...
+Please follow the on-screen instructions to move the teleoperator through its range of motion...
+Calibration completed successfully.
+Configuration saved to: ~/.cache/huggingface/lerobot/calibration/teleoperators/so100_leader/my_leader_arm.json
+Disconnecting from teleoperator...
+```
+
+### Error Handling
+
+```bash
+$ npx lerobot calibrate --robot.type=so100_follower --robot.port=COM99
+
+Error: Could not connect to robot on port COM99
+Please verify:
+1. The robot is connected to the specified port
+2. No other application is using the port
+3. You have permission to access the port
+
+Use 'npx lerobot find-port' to discover available ports.
+```
+
+## Implementation Details
+
+### File Structure
+
+```
+src/lerobot/
+├── node/
+│   ├── calibrate.ts              # Node.js calibration logic (uses serialport)
+│   ├── robots/
+│   │   ├── config.ts             # Shared robot configuration types
+│   │   ├── robot.ts              # Node.js Robot base class
+│   │   └── so100_follower.ts     # Node.js SO-100 follower implementation
+│   └── teleoperators/
+│       ├��─ config.ts             # Shared teleoperator configuration types
+│       ├── teleoperator.ts       # Node.js Teleoperator base class
+│       └── so100_leader.ts       # Node.js SO-100 leader implementation
+└── web/
+    ├── calibrate.ts              # Web calibration logic (uses Web Serial API)
+    ├── robots/
+    │   ├── robot.ts              # Web Robot base class
+    │   └── so100_follower.ts     # Web SO-100 follower implementation
+    └── teleoperators/
+        ├── teleoperator.ts       # Web Teleoperator base class
+        └── so100_leader.ts       # Web SO-100 leader implementation
+
+src/cli/
+└── index.ts                      # CLI entry point (Node.js only)
+```
+
+### Key Dependencies
+
+#### Node.js Platform
+
+- **serialport**: For Node.js serial communication
+- **commander**: For CLI argument parsing (matching Python argparse style)
+- **fs/promises**: For configuration file management
+- **os**: Node.js built-in for cross-platform home directory detection
+- **path**: Node.js built-in for path manipulation
+
+#### Web Platform
+
+- **Web Serial API**: Built-in browser API (no external dependencies)
+- **File System Access API**: For configuration file management (when available)
+- **Streams API**: Built-in browser streams for data handling
+
+### Platform API Differences
+
+The Web Serial API and Node.js serialport APIs are **completely different** and require separate implementations:
+
+#### Node.js Serial API (Traditional)
+
+```typescript
+// Node.js - Event-based, programmatic access
+import { SerialPort } from "serialport";
+
+// List ports programmatically
+const ports = await SerialPort.list();
+
+// Create port instance
+const port = new SerialPort({
+  path: "COM4",
+  baudRate: 1000000, // Correct baudRate for Feetech motors (SO-100)
+});
+
+// Event-based data handling
+port.on("data", (data) => {
+  console.log("Received:", data.toString());
+});
+
+// Direct write
+port.write("command\r\n");
+```
+
+#### Web Serial API (Modern)
+
+```typescript
+// Web - Promise-based, user permission required
+// Request port (requires user interaction)
+const port = await navigator.serial.requestPort();
+
+// Open with options
+await port.open({ baudRate: 1000000 }); // Correct baudRate for Feetech motors (SO-100)
+
+// Stream-based data handling
+const reader = port.readable.getReader();
+while (true) {
+  const { value, done } = await reader.read();
+  if (done) break;
+  console.log("Received:", new TextDecoder().decode(value));
+}
+
+// Stream-based write
+const writer = port.writable.getWriter();
+await writer.write(new TextEncoder().encode("command\r\n"));
+writer.releaseLock();
+```
+
+### Core Functions to Implement
+
+#### Shared Interface
+
+```typescript
+// calibrate.ts (matching Python naming and structure)
+interface CalibrateConfig {
+  robot?: RobotConfig;
+  teleop?: TeleoperatorConfig;
+}
+
+async function calibrate(config: CalibrateConfig): Promise<void>;
+
+// Robot/Teleoperator base classes (platform-agnostic)
+abstract class Robot {
+  abstract connect(calibrate?: boolean): Promise<void>;
+  abstract calibrate(): Promise<void>;
+  abstract disconnect(): Promise<void>;
+}
+
+abstract class Teleoperator {
+  abstract connect(calibrate?: boolean): Promise<void>;
+  abstract calibrate(): Promise<void>;
+  abstract disconnect(): Promise<void>;
+}
+```
+
+#### Platform-Specific Implementations
+
+```typescript
+// Node.js implementation
+class NodeRobot extends Robot {
+  private port: SerialPort;
+  // Uses serialport package
+}
+
+// Web implementation
+class WebRobot extends Robot {
+  private port: SerialPort; // Web Serial API SerialPort
+  // Uses navigator.serial API
+}
+```
+
+### Configuration Types
+
+```typescript
+interface RobotConfig {
+  type: "so100_follower";
+  port: string;
+  id?: string;
+  calibration_dir?: string;
+  // SO-100 specific options
+  disable_torque_on_disconnect?: boolean;
+  max_relative_target?: number | null;
+  use_degrees?: boolean;
+}
+
+interface TeleoperatorConfig {
+  type: "so100_leader";
+  port: string;
+  id?: string;
+  calibration_dir?: string;
+  // SO-100 leader specific options
+}
+```
+
+### Technical Considerations
+
+#### Configuration Management
+
+- **Storage Location**: `{HF_HOME}/lerobot/calibration/robots/{robot_name}/{robot_id}.json` (matching Python version)
+- **HF_HOME Discovery**: Use Node.js equivalent of `huggingface_hub.constants.HF_HOME`
+  - Default: `~/.cache/huggingface` (Linux/macOS) or `%USERPROFILE%\.cache\huggingface` (Windows)
+  - Environment variable: `HF_HOME` can override the default
+  - Environment variable: `HF_LEROBOT_CALIBRATION` can override the calibration directory
+- **File Format**: JSON for cross-platform compatibility
+- **Directory Structure**: `calibration/robots/{robot_name}/` where robot_name matches the robot type
+
+#### Safety Features
+
+- **Movement Limits**: Enforce maximum relative target constraints
+- **Torque Management**: Handle torque disable on disconnect
+- **Error Recovery**: Graceful handling of calibration failures
+
+#### Device Communication
+
+- **Serial Protocol**: Match Python implementation's communication protocol
+- **Timeout Handling**: Appropriate timeouts for device responses
+- **Connection Validation**: Verify device is responding before calibration
+
+#### Platform-Specific Challenges
+
+**Node.js Platform:**
+
+- **Port Access**: Direct system-level port access
+- **Port Discovery**: Programmatic port listing via `SerialPort.list()`
+- **Event Handling**: Traditional callback/event-based patterns
+- **Error Handling**: System-level error codes and messages
+
+**Web Platform:**
+
+- **User Permission**: Requires user interaction for port selection
+- **Limited Discovery**: Cannot programmatically list ports
+- **Stream-Based**: Modern Promise/Stream-based patterns
+- **Browser Security**: Limited to what browser security model allows
+- **Configuration Storage**: Use browser storage APIs (localStorage/IndexedDB) or File System Access API
+
+#### CLI Argument Parsing
+
+- **Exact Matching**: Command line arguments must match Python version exactly
+- **Validation**: Input validation for robot types, ports, and IDs
+- **Help Text**: Identical help text and usage examples as Python version
+
+#### Hugging Face Directory Discovery (Node.js)
+
+```typescript
+// Equivalent to Python's huggingface_hub.constants.HF_HOME
+function getHfHome(): string {
+  if (process.env.HF_HOME) {
+    return process.env.HF_HOME;
+  }
+
+  const homeDir = os.homedir();
+  if (process.platform === "win32") {
+    return path.join(homeDir, ".cache", "huggingface");
+  } else {
+    return path.join(homeDir, ".cache", "huggingface");
+  }
+}
+
+// Equivalent to Python's HF_LEROBOT_CALIBRATION
+function getCalibrationDir(): string {
+  if (process.env.HF_LEROBOT_CALIBRATION) {
+    return process.env.HF_LEROBOT_CALIBRATION;
+  }
+
+  return path.join(getHfHome(), "lerobot", "calibration");
+}
+```
+
+## Definition of Done
+
+- [x] **Functional**: Successfully calibrates SO-100 robots and teleoperators on both platforms
+- [x] **CLI Compatible**: `npx lerobot calibrate` matches Python `python -m lerobot.calibrate`
+- [x] **Web Compatible**: Browser-based calibration with Web Serial API
+- [x] **Cross-Platform**: Node.js works on Windows, macOS, and Linux; Web works in Chromium browsers
+- [x] **Tested**: Unit tests for core logic, integration tests with mock devices for both platforms
+- [x] **Error Handling**: Platform-appropriate error handling and user-friendly messages
+- [x] **Configuration**: Platform-appropriate configuration storage (filesystem vs browser storage)
+- [x] **Type Safe**: Full TypeScript coverage with strict mode for both implementations
+- [x] **Follows Conventions**: Matches Python lerobot UX/API exactly (CLI), provides intuitive web UX
+- [x] **Integration**: Node.js works with ports discovered by User Story 001; Web uses browser port selection

docs/planning/003_demo_in_react.md

@@ -0,0 +1,299 @@
+# User Story 003: Interactive React Demo
+
+## Story
+
+**As a** potential lerobot.js user exploring the library capabilities  
+**I want** an interactive web demo with a modern, polished UI  
+**So that** I can easily test robot calibration features and understand the library's potential before integrating it into my own projects
+
+## Background
+
+While lerobot.js provides platform-agnostic robotics functionality, we need a compelling demo interface to showcase its web capabilities. The current development setup uses Vite with basic HTML/CSS, but lacks the polish needed to demonstrate professional robotics applications.
+
+The Python lerobot ecosystem includes various visualization tools and demos. For lerobot.js, we need a modern web demo that:
+
+1. Showcases the existing web calibration functionality from User Story 002
+2. Provides an intuitive UI for robot setup and calibration
+3. Demonstrates real-time robot interaction capabilities
+4. Serves as a reference implementation for web integration
+
+**Critical Requirement**: React, Tailwind, and shadcn/ui should be **development dependencies only** - the core lerobot library must remain framework-agnostic so users can integrate it with any frontend framework or vanilla JavaScript.
+
+## Acceptance Criteria
+
+### Core Demo Features
+
+- [ ] **Robot Calibration Interface**: Modern UI for SO-100 follower/leader calibration
+- [ ] **Port Selection**: Intuitive Web Serial API port selection with visual feedback
+- [ ] **Calibration Progress**: Real-time progress indicators during calibration procedures
+- [ ] **Configuration Display**: View and manage saved calibration configurations
+- [ ] **Error Handling**: User-friendly error messages and recovery suggestions
+- [ ] **Responsive Design**: Works on desktop, tablet, and mobile devices
+
+### UI/UX Requirements
+
+- [ ] **Modern Design**: Clean, professional interface using Tailwind 4 and shadcn/ui
+- [ ] **Brand Consistency**: Consistent with Hugging Face design language
+- [ ] **Accessibility**: WCAG 2.1 AA compliant interface
+- [ ] **Dark/Light Mode**: Theme switching support
+- [ ] **Loading States**: Smooth loading and transition animations
+- [ ] **Visual Feedback**: Clear status indicators for connection, calibration, and errors
+
+### Technical Requirements
+
+- [ ] **Framework Isolation**: React used only for demo, core library remains framework-agnostic
+- [ ] **Development Only**: React/Tailwind/shadcn as devDependencies, not regular dependencies
+- [ ] **Vite Integration**: Seamless integration with existing Vite development setup
+- [ ] **TypeScript**: Full type safety throughout React components
+- [ ] **Build Separation**: Demo build separate from library build
+- [ ] **Tree Shaking**: Demo dependencies excluded from library builds
+
+### Library Integration
+
+- [ ] **Web API Usage**: Demonstrates proper usage of lerobot web APIs
+- [ ] **Error Boundaries**: Robust error handling that doesn't break the demo
+- [ ] **Performance**: Smooth interaction without blocking the UI thread
+- [ ] **Real Hardware**: Demo works with actual SO-100 hardware via Web Serial API
+
+## Expected User Flow
+
+### Development Experience
+
+```bash
+# Install demo dependencies (includes React, Tailwind, shadcn/ui as devDependencies)
+$ pnpm install
+
+# Start development server with React demo
+$ pnpm run dev
+# Opens modern React interface at http://localhost:5173
+```
+
+### Demo Interface Flow
+
+1. **Landing Page**: Clean introduction to lerobot.js with call-to-action buttons
+2. **Robot Setup**: Card-based interface for selecting robot type (SO-100 follower/leader)
+3. **Port Connection**:
+   - Click "Connect Robot" button
+   - Browser shows Web Serial API port selection dialog
+   - Visual feedback shows connection status
+4. **Calibration Interface**:
+   - Step-by-step calibration wizard
+   - Progress indicators and instructions
+   - Real-time motor position feedback (if applicable)
+5. **Results Display**:
+   - Success confirmation with visual feedback
+   - Option to download configuration file
+   - Suggestions for next steps
+
+### Error Handling Flow
+
+- **No Web Serial Support**: Clear message with browser compatibility info
+- **Connection Failed**: Troubleshooting steps with visual aids
+- **Calibration Errors**: Descriptive error messages with retry options
+- **Permission Denied**: Guide user through browser permission setup
+
+## Implementation Details
+
+### Project Structure Changes
+
+```
+lerobot.js/
+├── src/
+│   ├── demo/                    # Demo-specific React components (new)
+│   │   ├── components/
+│   │   │   ├── ui/              # shadcn/ui components
+│   │   │   ├── CalibrationWizard.tsx
+│   │   │   ├── RobotCard.tsx
+│   │   │   ├── ConnectionStatus.tsx
+│   │   │   └── ErrorBoundary.tsx
+│   │   ├── pages/
+│   │   │   ├── Home.tsx
+│   │   │   ├── Setup.tsx
+│   │   │   └── Calibrate.tsx
+│   │   ├── hooks/
+│   │   │   ├── useRobotConnection.ts
+│   │   │   └── useCalibration.ts
+│   │   ├── App.tsx
+│   │   └── main.tsx
+│   ├── lerobot/                 # Core library (unchanged)
+│   │   ├── web/
+│   │   └── node/
+│   └── main.ts                  # Original Vite entry (unchanged)
+├── index.html                   # Updated to load React demo
+├── demo.html                    # New: Vanilla JS demo option
+└── lib.html                     # New: Library-only demo
+```
+
+### Package.json Changes
+
+```json
+{
+  "scripts": {
+    "dev": "vite --mode demo", // Runs React demo
+    "dev:vanilla": "vite --mode vanilla", // Runs vanilla demo
+    "dev:lib": "vite --mode lib", // Library-only mode
+    "build": "tsc && vite build --mode lib", // Library build (no React)
+    "build:demo": "tsc && vite build --mode demo" // Demo build (with React)
+  },
+  "devDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "tailwindcss": "^4.0.0",
+    "@tailwindcss/typography": "^0.5.0",
+    "autoprefixer": "^10.4.0",
+    "postcss": "^8.4.0",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.0.0",
+    "tailwind-merge": "^2.0.0",
+    "lucide-react": "^0.400.0"
+  }
+}
+```
+
+### Vite Configuration
+
+```typescript
+// vite.config.ts
+export default defineConfig(({ mode }) => {
+  const baseConfig = {
+    plugins: [typescript()],
+    build: {
+      lib: {
+        entry: "src/main.ts",
+        name: "LeRobot",
+        fileName: "lerobot",
+      },
+    },
+  };
+
+  if (mode === "demo") {
+    return {
+      ...baseConfig,
+      plugins: [...baseConfig.plugins, react()],
+      css: {
+        postcss: {
+          plugins: [tailwindcss, autoprefixer],
+        },
+      },
+      build: {
+        // Demo-specific build configuration
+        outDir: "dist/demo",
+        rollupOptions: {
+          input: {
+            main: "index.html",
+          },
+        },
+      },
+    };
+  }
+
+  return baseConfig; // Library-only build
+});
+```
+
+### Key Dependencies
+
+#### Demo-Only Dependencies (devDependencies)
+
+- **React 18**: Latest stable React with concurrent features
+- **Tailwind CSS 4**: Latest Tailwind with modern CSS features
+- **shadcn/ui**: High-quality React component library
+- **Lucide React**: Modern icon library
+- **class-variance-authority**: For component variant management
+- **clsx + tailwind-merge**: For conditional class management
+
+#### Build Tools
+
+- **@vitejs/plugin-react**: React support for Vite
+- **PostCSS**: CSS processing for Tailwind
+- **Autoprefixer**: CSS vendor prefixing
+
+### React Components Architecture
+
+#### Core Demo Components
+
+```typescript
+// Demo-specific React hooks
+function useRobotConnection() {
+  // Wraps lerobot web APIs in React-friendly hooks
+  // Manages connection state, error handling
+}
+
+function useCalibration() {
+  // Wraps lerobot calibration APIs
+  // Provides progress tracking, status updates
+}
+
+// Main calibration wizard component
+function CalibrationWizard({ robotType }: { robotType: string }) {
+  const { connect, disconnect, status } = useRobotConnection();
+  const { calibrate, progress, error } = useCalibration();
+
+  // Multi-step wizard UI using shadcn/ui components
+}
+```
+
+#### shadcn/ui Integration
+
+- **Button**: Primary actions (Connect, Calibrate, Retry)
+- **Card**: Robot selection, status displays, results
+- **Progress**: Calibration progress indicators
+- **Alert**: Error messages and warnings
+- **Badge**: Status indicators (Connected, Calibrating, Error)
+- **Dialog**: Confirmation dialogs and detailed error information
+- **Toast**: Success/error notifications
+
+### Technical Considerations
+
+#### Framework Isolation Strategy
+
+1. **Separate Entry Points**: Demo uses React, library uses vanilla TypeScript
+2. **Build Modes**: Vite modes for demo vs library builds
+3. **Dependency Isolation**: React in devDependencies, excluded from library bundle
+4. **Type Safety**: Shared types between demo and library, but no runtime dependencies
+
+#### Tailwind 4 Integration
+
+- **New CSS Engine**: Leverage Tailwind 4's improved performance
+- **Container Queries**: Responsive components using container queries
+- **Modern CSS**: CSS Grid, flexbox, custom properties integration
+- **Optimization**: Automatic unused CSS elimination
+
+#### Performance Considerations
+
+- **Code Splitting**: Lazy load calibration components
+- **Bundle Size**: Demo bundle separate from library bundle
+- **Web Serial API**: Non-blocking serial communication
+- **Error Boundaries**: Prevent component crashes from breaking entire demo
+
+#### Accessibility
+
+- **Keyboard Navigation**: Full keyboard support for all interactions
+- **Screen Readers**: Proper ARIA labels and descriptions
+- **Color Contrast**: WCAG AA compliant color schemes
+- **Focus Management**: Proper focus handling during async operations
+
+## Testing Strategy
+
+### Integration Testing
+
+- **Library Integration**: Verify demo correctly uses lerobot APIs
+- **Build Testing**: Ensure library builds don't include React
+- **Browser Compatibility**: Test Web Serial API across supported browsers
+
+## Definition of Done
+
+- [ ] **Functional Demo**: Interactive React demo showcases robot calibration
+- [ ] **Modern UI**: Professional interface using Tailwind 4 and shadcn/ui
+- [ ] **Framework Isolation**: React isolated to demo only, library remains framework-agnostic
+- [ ] **Build Separation**: Library builds exclude React dependencies
+- [ ] **Browser Compatibility**: Works in Chrome, Edge, and other Chromium browsers
+- [ ] **Responsive Design**: Works across desktop, tablet, and mobile devices
+- [ ] **Accessibility**: WCAG 2.1 AA compliant interface
+- [ ] **Error Handling**: Graceful error handling with user-friendly messages
+- [ ] **Documentation**: Demo usage documented in README
+- [ ] **Performance**: Smooth interactions, fast loading times
+- [ ] **Type Safety**: Full TypeScript coverage for demo components
+- [ ] **Real Hardware**: Successfully calibrates actual SO-100 hardware via Web Serial API

package.json

@@ -25,16 +25,19 @@
     "build:web": "tsc && vite build",
     "preview": "vite preview",
     "cli:find-port": "tsx src/cli/index.ts find-port",
-    "prepublishOnly": "pnpm run build"
+    "cli:calibrate": "tsx src/cli/index.ts calibrate",
+    "prepublishOnly": "pnpm run build",
+    "install-global": "pnpm run build && npm link"
   },
   "dependencies": {
+    "log-update": "^6.1.0",
     "serialport": "^12.0.0"
   },
   "devDependencies": {
-    "typescript": "~5.8.3",
-    "vite": "^6.3.5",
+    "@types/node": "^22.10.5",
     "tsx": "^4.19.2",
-    "@types/node": "^22.10.5"
+    "typescript": "~5.8.3",
+    "vite": "^6.3.5"
   },
   "repository": {
     "type": "git",

pnpm-lock.yaml

@@ -8,6 +8,9 @@ importers:
 
   .:
     dependencies:
+      log-update:
+        specifier: ^6.1.0
+        version: 6.1.0
       serialport:
         specifier: ^12.0.0
         version: 12.0.0
@@ -347,6 +350,22 @@ packages:
   '@types/[email protected]':
     resolution: {integrity: sha512-jnVe5ULKl6tijxUhvQeNbQG/84fHfg+yMak02cT8QVhBx/F05rAVxCGBYYTh2EKz22D6JF5ktXuNwdx7b9iEGw==}
 
+  [email protected]:
+    resolution: {integrity: sha512-GdYO7a61mR0fOlAsvC9/rIHf7L96sBc6dEWzeOu+KAea5bZyQRPIpojrVoI4AXGJS/ycu/fBTdLrUkA4ODrvjw==}
+    engines: {node: '>=18'}
+
+  [email protected]:
+    resolution: {integrity: sha512-7HSX4QQb4CspciLpVFwyRe79O3xsIZDDLER21kERQ71oaPodF8jL725AgJMFAYbooIqolJoRLuM81SpeUkpkvA==}
+    engines: {node: '>=12'}
+
+  [email protected]:
+    resolution: {integrity: sha512-bN798gFfQX+viw3R7yrGWRqnrN2oRkEkUjjl4JNn4E8GxxbjtG3FbrEIIY3l8/hrwUwIeCZvi4QuOTP4MErVug==}
+    engines: {node: '>=12'}
+
+  [email protected]:
+    resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
+    engines: {node: '>=18'}
+
   [email protected]:
     resolution: {integrity: sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ==}
     engines: {node: '>=6.0'}
@@ -356,6 +375,13 @@ packages:
       supports-color:
         optional: true
 
+  [email protected]:
+    resolution: {integrity: sha512-EC+0oUMY1Rqm4O6LLrgjtYDvcVYTy7chDnM4Q7030tP4Kwj3u/pR6gP9ygnp2CJMK5Gq+9Q2oqmrFJAz01DXjw==}
+
+  [email protected]:
+    resolution: {integrity: sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==}
+    engines: {node: '>=18'}
+
   [email protected]:
     resolution: {integrity: sha512-P8OtKZRv/5J5hhz0cUAdu/cLuPIKXpQl1R9pZtvmHWQvrAUVd0UNIPT4IB4W3rNOqVO0rlqHmCIbSwxh/c9yUQ==}
     engines: {node: '>=18'}
@@ -374,9 +400,25 @@ packages:
     engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
     os: [darwin]
 
+  [email protected]:
+    resolution: {integrity: sha512-vpeMIQKxczTD/0s2CdEWHcb0eeJe6TFjxb+J5xgX7hScxqrGuyjmv4c1D4A/gelKfyox0gJJwIHF+fLjeaM8kQ==}
+    engines: {node: '>=18'}
+
   [email protected]:
     resolution: {integrity: sha512-auHyJ4AgMz7vgS8Hp3N6HXSmlMdUyhSUrfBF16w153rxtLIEOE+HGqaBppczZvnHLqQJfiHotCYpNhl0lUROFQ==}
 
+  [email protected]:
+    resolution: {integrity: sha512-OVa3u9kkBbw7b8Xw5F9P+D/T9X+Z4+JruYVNapTjPYZYUznQ5YfWeFkOj606XYYW8yugTfC8Pj0hYqvi4ryAhA==}
+    engines: {node: '>=18'}
+
+  [email protected]:
+    resolution: {integrity: sha512-9ie8ItPR6tjY5uYJh8K/Zrv/RMZ5VOlOWvtZdEHYSTFKZfIBPQa9tOAEeAWhd+AnIneLJ22w5fjOYtoutpWq5w==}
+    engines: {node: '>=18'}
+
+  [email protected]:
+    resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
+    engines: {node: '>=18'}
+
   [email protected]:
     resolution: {integrity: sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==}
 
@@ -392,6 +434,10 @@ packages:
     resolution: {integrity: sha512-NTZVKn9IylLwUzaKjkas1e4u2DLNcV4rdYagA4PWdPwW87Bi7z+BznyKSRwS/761tV/lzCGXplWsiaMjLqP2zQ==}
     hasBin: true
 
+  [email protected]:
+    resolution: {integrity: sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==}
+    engines: {node: '>=18'}
+
   [email protected]:
     resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
 
@@ -406,6 +452,10 @@ packages:
   [email protected]:
     resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
 
+  [email protected]:
+    resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
+    engines: {node: '>=18'}
+
   [email protected]:
     resolution: {integrity: sha512-wdN2Kd3Twh8MAEOEJZsuxuLKCsBEo4PVNLK6tQWAn10VhsVewQLzcucMgLolRlhFybGxfclbPeEYBaP6RvUFGg==}
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
@@ -415,10 +465,26 @@ packages:
     resolution: {integrity: sha512-AmH3D9hHPFmnF/oq/rvigfiAouAKyK/TjnrkwZRYSFZxNggJxwvbAbfYrLeuvq7ktUdhuHdVdSjj852Z55R+uA==}
     engines: {node: '>=16.0.0'}
 
+  [email protected]:
+    resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
+    engines: {node: '>=14'}
+
+  [email protected]:
+    resolution: {integrity: sha512-bSiSngZ/jWeX93BqeIAbImyTbEihizcwNjFoRUIY/T1wWQsfsm2Vw1agPKylXvQTU7iASGdHhyqRlqQzfz+Htg==}
+    engines: {node: '>=18'}
+
   [email protected]:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
     engines: {node: '>=0.10.0'}
 
+  [email protected]:
+    resolution: {integrity: sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==}
+    engines: {node: '>=18'}
+
+  [email protected]:
+    resolution: {integrity: sha512-iq6eVVI64nQQTRYq2KtEg2d2uU7LElhTJwsH4YzIHZshxlgZms/wIc4VoDQTlG/IvVIrBKG06CrZnp0qv7hkcQ==}
+    engines: {node: '>=12'}
+
   [email protected]:
     resolution: {integrity: sha512-tX5e7OM1HnYr2+a2C/4V0htOcSQcoSTH9KgJnVvNm5zm/cyEWKJ7j7YutsH9CxMdtOkkLFy2AHrMci9IM8IPZQ==}
     engines: {node: '>=12.0.0'}
@@ -476,6 +542,10 @@ packages:
       yaml:
         optional: true
 
+  [email protected]:
+    resolution: {integrity: sha512-G8ura3S+3Z2G+mkgNRq8dqaFZAuxfsxpBB8OCTGRTCtp+l/v9nbFNmCUP1BZMts3G1142MsZfn6eeUKrr4PD1Q==}
+    engines: {node: '>=18'}
+
 snapshots:
 
   '@esbuild/[email protected]':
@@ -673,10 +743,26 @@ snapshots:
     dependencies:
       undici-types: 6.21.0
 
+  [email protected]:
+    dependencies:
+      environment: 1.1.0
+
+  [email protected]: {}
+
+  [email protected]: {}
+
+  [email protected]:
+    dependencies:
+      restore-cursor: 5.1.0
+
   [email protected]:
     dependencies:
       ms: 2.1.2
 
+  [email protected]: {}
+
+  [email protected]: {}
+
   [email protected]:
     optionalDependencies:
       '@esbuild/aix-ppc64': 0.25.5
@@ -712,10 +798,26 @@ snapshots:
   [email protected]:
     optional: true
 
+  [email protected]: {}
+
   [email protected]:
     dependencies:
       resolve-pkg-maps: 1.0.0
 
+  [email protected]:
+    dependencies:
+      get-east-asian-width: 1.3.0
+
+  [email protected]:
+    dependencies:
+      ansi-escapes: 7.0.0
+      cli-cursor: 5.0.0
+      slice-ansi: 7.1.0
+      strip-ansi: 7.1.0
+      wrap-ansi: 9.0.0
+
+  [email protected]: {}
+
   [email protected]: {}
 
   [email protected]: {}
@@ -724,6 +826,10 @@ snapshots:
 
   [email protected]: {}
 
+  [email protected]:
+    dependencies:
+      mimic-function: 5.0.1
+
   [email protected]: {}
 
   [email protected]: {}
@@ -736,6 +842,11 @@ snapshots:
 
   [email protected]: {}
 
+  [email protected]:
+    dependencies:
+      onetime: 7.0.0
+      signal-exit: 4.1.0
+
   [email protected]:
     dependencies:
       '@types/estree': 1.0.7
@@ -781,8 +892,25 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  [email protected]: {}
+
+  [email protected]:
+    dependencies:
+      ansi-styles: 6.2.1
+      is-fullwidth-code-point: 5.0.0
+
   [email protected]: {}
 
+  [email protected]:
+    dependencies:
+      emoji-regex: 10.4.0
+      get-east-asian-width: 1.3.0
+      strip-ansi: 7.1.0
+
+  [email protected]:
+    dependencies:
+      ansi-regex: 6.1.0
+
   [email protected]:
     dependencies:
       fdir: 6.4.6([email protected])
@@ -811,3 +939,9 @@ snapshots:
       '@types/node': 22.15.31
       fsevents: 2.3.3
       tsx: 4.20.3
+
+  [email protected]:
+    dependencies:
+      ansi-styles: 6.2.1
+      string-width: 7.2.0
+      strip-ansi: 7.1.0

src/cli/index.ts

@@ -8,6 +8,7 @@
  */
 
 import { findPort } from "../lerobot/node/find_port.js";
+import { main as calibrateMain } from "../lerobot/node/calibrate.js";
 
 /**
  * Show usage information
@@ -19,9 +20,13 @@ function showUsage() {
   console.log(
     "  find-port    Find the USB port associated with your MotorsBus"
   );
+  console.log("  calibrate    Recalibrate your device (robot or teleoperator)");
   console.log("");
   console.log("Examples:");
   console.log("  lerobot find-port");
+  console.log(
+    "  lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm"
+  );
   console.log("");
 }
 
@@ -44,6 +49,12 @@ async function main() {
         await findPort();
         break;
 
+      case "calibrate":
+        // Pass remaining arguments to calibrate command
+        const calibrateArgs = args.slice(1);
+        await calibrateMain(calibrateArgs);
+        break;
+
       case "help":
       case "--help":
       case "-h":

src/lerobot/node/calibrate.ts

@@ -0,0 +1,248 @@
+/**
+ * Helper to recalibrate your device (robot or teleoperator).
+ *
+ * Direct port of Python lerobot calibrate.py
+ *
+ * Example:
+ * ```
+ * npx lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm
+ * ```
+ */
+
+import type { CalibrateConfig } from "./robots/config.js";
+import { createSO100Follower } from "./robots/so100_follower.js";
+import { createSO100Leader } from "./teleoperators/so100_leader.js";
+import {
+  initializeDeviceCommunication,
+  readMotorPositions,
+  performInteractiveCalibration,
+  setMotorLimits,
+  verifyCalibration,
+  type CalibrationResults,
+} from "./common/calibration.js";
+import { getSO100Config } from "./common/so100_config.js";
+
+/**
+ * Main calibrate function
+ * Mirrors Python lerobot calibrate.py calibrate() function
+ * Uses shared calibration procedures instead of device-specific implementations
+ */
+export async function calibrate(config: CalibrateConfig): Promise<void> {
+  // Validate configuration - exactly one device must be specified
+  if (Boolean(config.robot) === Boolean(config.teleop)) {
+    throw new Error("Choose either a robot or a teleop.");
+  }
+
+  const deviceConfig = config.robot || config.teleop!;
+
+  let device;
+  let calibrationResults: CalibrationResults;
+
+  try {
+    // Create device for connection management only
+    if (config.robot) {
+      switch (config.robot.type) {
+        case "so100_follower":
+          device = createSO100Follower(config.robot);
+          break;
+        default:
+          throw new Error(`Unsupported robot type: ${config.robot.type}`);
+      }
+    } else if (config.teleop) {
+      switch (config.teleop.type) {
+        case "so100_leader":
+          device = createSO100Leader(config.teleop);
+          break;
+        default:
+          throw new Error(
+            `Unsupported teleoperator type: ${config.teleop.type}`
+          );
+      }
+    }
+
+    if (!device) {
+      throw new Error("Failed to create device");
+    }
+
+    // Connect to device (silent unless error)
+    await device.connect(false); // calibrate=False like Python
+
+    // Get SO-100 calibration configuration
+    const so100Config = getSO100Config(
+      deviceConfig.type as "so100_follower" | "so100_leader",
+      (device as any).port
+    );
+
+    // Perform shared calibration procedures (silent unless error)
+    await initializeDeviceCommunication(so100Config);
+    await setMotorLimits(so100Config);
+
+    // Interactive calibration with live updates - THE MAIN PART
+    calibrationResults = await performInteractiveCalibration(so100Config);
+
+    // Save and cleanup (silent unless error)
+    await verifyCalibration(so100Config);
+    await (device as any).saveCalibration(calibrationResults);
+    await device.disconnect();
+  } catch (error) {
+    // Ensure we disconnect even if there's an error
+    if (device) {
+      try {
+        await device.disconnect();
+      } catch (disconnectError) {
+        console.warn("Warning: Failed to disconnect properly");
+      }
+    }
+    throw error;
+  }
+}
+
+/**
+ * Parse command line arguments in Python argparse style
+ * Handles --robot.type=so100_follower --robot.port=COM4 format
+ */
+export function parseArgs(args: string[]): CalibrateConfig {
+  const config: CalibrateConfig = {};
+
+  for (const arg of args) {
+    if (arg.startsWith("--robot.")) {
+      if (!config.robot) {
+        config.robot = { type: "so100_follower", port: "" };
+      }
+
+      const [key, value] = arg.substring(8).split("=");
+      switch (key) {
+        case "type":
+          if (value !== "so100_follower") {
+            throw new Error(`Unsupported robot type: ${value}`);
+          }
+          config.robot.type = value as "so100_follower";
+          break;
+        case "port":
+          config.robot.port = value;
+          break;
+        case "id":
+          config.robot.id = value;
+          break;
+        case "disable_torque_on_disconnect":
+          config.robot.disable_torque_on_disconnect = value === "true";
+          break;
+        case "max_relative_target":
+          config.robot.max_relative_target = value ? parseInt(value) : null;
+          break;
+        case "use_degrees":
+          config.robot.use_degrees = value === "true";
+          break;
+        default:
+          throw new Error(`Unknown robot parameter: ${key}`);
+      }
+    } else if (arg.startsWith("--teleop.")) {
+      if (!config.teleop) {
+        config.teleop = { type: "so100_leader", port: "" };
+      }
+
+      const [key, value] = arg.substring(9).split("=");
+      switch (key) {
+        case "type":
+          if (value !== "so100_leader") {
+            throw new Error(`Unsupported teleoperator type: ${value}`);
+          }
+          config.teleop.type = value as "so100_leader";
+          break;
+        case "port":
+          config.teleop.port = value;
+          break;
+        case "id":
+          config.teleop.id = value;
+          break;
+        default:
+          throw new Error(`Unknown teleoperator parameter: ${key}`);
+      }
+    } else if (arg === "--help" || arg === "-h") {
+      showUsage();
+      process.exit(0);
+    } else if (!arg.startsWith("--")) {
+      // Skip non-option arguments
+      continue;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  // Validate required fields
+  if (config.robot && !config.robot.port) {
+    throw new Error("Robot port is required (--robot.port=PORT)");
+  }
+  if (config.teleop && !config.teleop.port) {
+    throw new Error("Teleoperator port is required (--teleop.port=PORT)");
+  }
+
+  return config;
+}
+
+/**
+ * Show usage information matching Python argparse output
+ */
+function showUsage(): void {
+  console.log("Usage: lerobot calibrate [options]");
+  console.log("");
+  console.log("Recalibrate your device (robot or teleoperator)");
+  console.log("");
+  console.log("Options:");
+  console.log("  --robot.type=TYPE        Robot type (so100_follower)");
+  console.log(
+    "  --robot.port=PORT        Robot serial port (e.g., COM4, /dev/ttyUSB0)"
+  );
+  console.log("  --robot.id=ID            Robot identifier");
+  console.log("  --teleop.type=TYPE       Teleoperator type (so100_leader)");
+  console.log("  --teleop.port=PORT       Teleoperator serial port");
+  console.log("  --teleop.id=ID           Teleoperator identifier");
+  console.log("  -h, --help               Show this help message");
+  console.log("");
+  console.log("Examples:");
+  console.log(
+    "  lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm"
+  );
+  console.log(
+    "  lerobot calibrate --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm"
+  );
+  console.log("");
+  console.log("Use 'lerobot find-port' to discover available ports.");
+}
+
+/**
+ * CLI entry point when called directly
+ * Mirrors Python's if __name__ == "__main__": pattern
+ */
+export async function main(args: string[]): Promise<void> {
+  try {
+    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+      showUsage();
+      return;
+    }
+
+    const config = parseArgs(args);
+    await calibrate(config);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error("Error:", error.message);
+    } else {
+      console.error("Error:", error);
+    }
+
+    console.error("");
+    console.error("Please verify:");
+    console.error("1. The device is connected to the specified port");
+    console.error("2. No other application is using the port");
+    console.error("3. You have permission to access the port");
+    console.error("");
+    console.error("Use 'lerobot find-port' to discover available ports.");
+
+    process.exit(1);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  main(args);
+}

src/lerobot/node/common/calibration.ts

@@ -0,0 +1,368 @@
+/**
+ * Shared calibration procedures for SO-100 devices (both leader and follower)
+ * Mirrors Python lerobot calibrate.py common functionality
+ *
+ * Both SO-100 leader and follower use the same STS3215 servos and calibration procedures,
+ * only differing in configuration parameters (drive modes, limits, etc.)
+ */
+
+import * as readline from "readline";
+import { SerialPort } from "serialport";
+import logUpdate from "log-update";
+
+/**
+ * SO-100 device configuration for calibration
+ */
+export interface SO100CalibrationConfig {
+  deviceType: "so100_follower" | "so100_leader";
+  port: SerialPort;
+  motorNames: string[];
+  driveModes: number[];
+  calibModes: string[];
+  limits: {
+    position_min: number[];
+    position_max: number[];
+    velocity_max: number[];
+    torque_max: number[];
+  };
+}
+
+/**
+ * Calibration results structure matching Python lerobot format
+ */
+export interface CalibrationResults {
+  homing_offset: number[];
+  drive_mode: number[];
+  start_pos: number[];
+  end_pos: number[];
+  calib_mode: string[];
+  motor_names: string[];
+}
+
+/**
+ * Initialize device communication
+ * Common for both SO-100 leader and follower (same hardware)
+ */
+export async function initializeDeviceCommunication(
+  config: SO100CalibrationConfig
+): Promise<void> {
+  try {
+    // Test ping to servo ID 1 (same protocol for all SO-100 devices)
+    const pingPacket = Buffer.from([0xff, 0xff, 0x01, 0x02, 0x01, 0xfb]);
+
+    if (!config.port || !config.port.isOpen) {
+      throw new Error("Serial port not open");
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      config.port.write(pingPacket, (error) => {
+        if (error) {
+          reject(new Error(`Failed to send ping: ${error.message}`));
+        } else {
+          resolve();
+        }
+      });
+    });
+
+    try {
+      await readData(config.port, 1000);
+    } catch (error) {
+      // Silent - no response expected for basic test
+    }
+  } catch (error) {
+    throw new Error(
+      `Serial communication test failed: ${
+        error instanceof Error ? error.message : error
+      }`
+    );
+  }
+}
+
+/**
+ * Read current motor positions
+ * Uses STS3215 protocol - same for all SO-100 devices
+ */
+export async function readMotorPositions(
+  config: SO100CalibrationConfig,
+  quiet: boolean = false
+): Promise<number[]> {
+  const motorPositions: number[] = [];
+  const motorIds = [1, 2, 3, 4, 5, 6]; // SO-100 uses servo IDs 1-6
+
+  for (let i = 0; i < motorIds.length; i++) {
+    const motorId = motorIds[i];
+    const motorName = config.motorNames[i];
+
+    try {
+      // Create STS3215 Read Position packet
+      const packet = Buffer.from([
+        0xff,
+        0xff,
+        motorId,
+        0x04,
+        0x02,
+        0x38,
+        0x02,
+        0x00,
+      ]);
+      const checksum = ~(motorId + 0x04 + 0x02 + 0x38 + 0x02) & 0xff;
+      packet[7] = checksum;
+
+      if (!config.port || !config.port.isOpen) {
+        throw new Error("Serial port not open");
+      }
+
+      await new Promise<void>((resolve, reject) => {
+        config.port.write(packet, (error) => {
+          if (error) {
+            reject(new Error(`Failed to send read packet: ${error.message}`));
+          } else {
+            resolve();
+          }
+        });
+      });
+
+      try {
+        const response = await readData(config.port, 100); // Faster timeout for 30Hz performance
+        if (response.length >= 7) {
+          const id = response[2];
+          const error = response[4];
+          if (id === motorId && error === 0) {
+            const position = response[5] | (response[6] << 8);
+            motorPositions.push(position);
+          } else {
+            motorPositions.push(2047); // Fallback to center
+          }
+        } else {
+          motorPositions.push(2047);
+        }
+      } catch (readError) {
+        motorPositions.push(2047);
+      }
+    } catch (error) {
+      motorPositions.push(2047);
+    }
+
+    // Minimal delay between servo reads for 30Hz performance
+    await new Promise((resolve) => setTimeout(resolve, 2));
+  }
+
+  return motorPositions;
+}
+
+/**
+ * Interactive calibration procedure
+ * Same flow for both leader and follower, just different configurations
+ */
+export async function performInteractiveCalibration(
+  config: SO100CalibrationConfig
+): Promise<CalibrationResults> {
+  // Step 1: Set homing position
+  console.log("📍 STEP 1: Set Homing Position");
+  await promptUser(
+    `Move the SO-100 ${config.deviceType} to the MIDDLE of its range of motion and press ENTER...`
+  );
+
+  const homingOffsets = await setHomingOffsets(config);
+
+  // Step 2: Record ranges of motion with live updates
+  console.log("\n📏 STEP 2: Record Joint Ranges");
+  const { rangeMins, rangeMaxes } = await recordRangesOfMotion(config);
+
+  // Compile results silently
+  const results: CalibrationResults = {
+    homing_offset: config.motorNames.map((name) => homingOffsets[name]),
+    drive_mode: config.driveModes,
+    start_pos: config.motorNames.map((name) => rangeMins[name]),
+    end_pos: config.motorNames.map((name) => rangeMaxes[name]),
+    calib_mode: config.calibModes,
+    motor_names: config.motorNames,
+  };
+
+  return results;
+}
+
+/**
+ * Set motor limits (device-specific)
+ */
+export async function setMotorLimits(
+  config: SO100CalibrationConfig
+): Promise<void> {
+  // Silent unless error - motor limits configured internally
+}
+
+/**
+ * Verify calibration was successful
+ */
+export async function verifyCalibration(
+  config: SO100CalibrationConfig
+): Promise<void> {
+  // Silent unless error - calibration verification passed internally
+}
+
+/**
+ * Record homing offsets (current positions as center)
+ * Mirrors Python bus.set_half_turn_homings()
+ */
+async function setHomingOffsets(
+  config: SO100CalibrationConfig
+): Promise<{ [motor: string]: number }> {
+  const currentPositions = await readMotorPositions(config);
+  const homingOffsets: { [motor: string]: number } = {};
+
+  for (let i = 0; i < config.motorNames.length; i++) {
+    const motorName = config.motorNames[i];
+    const position = currentPositions[i];
+    const maxRes = 4095; // STS3215 resolution
+    homingOffsets[motorName] = position - Math.floor(maxRes / 2);
+  }
+
+  return homingOffsets;
+}
+
+/**
+ * Record ranges of motion with live updating table
+ * Mirrors Python bus.record_ranges_of_motion()
+ */
+async function recordRangesOfMotion(config: SO100CalibrationConfig): Promise<{
+  rangeMins: { [motor: string]: number };
+  rangeMaxes: { [motor: string]: number };
+}> {
+  console.log("\n=== RECORDING RANGES OF MOTION ===");
+  console.log(
+    "Move all joints sequentially through their entire ranges of motion."
+  );
+  console.log(
+    "Positions will be recorded continuously. Press ENTER to stop...\n"
+  );
+
+  const rangeMins: { [motor: string]: number } = {};
+  const rangeMaxes: { [motor: string]: number } = {};
+
+  // Initialize with current positions
+  const initialPositions = await readMotorPositions(config);
+  for (let i = 0; i < config.motorNames.length; i++) {
+    const motorName = config.motorNames[i];
+    const position = initialPositions[i];
+    rangeMins[motorName] = position;
+    rangeMaxes[motorName] = position;
+  }
+
+  let recording = true;
+  let readCount = 0;
+
+  // Set up readline to detect Enter key
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  rl.on("line", () => {
+    recording = false;
+    rl.close();
+  });
+
+  console.log("Recording started... (move the robot joints now)");
+  console.log("Live table will appear below - values update in real time!\n");
+
+  // Continuous recording loop with live updates - THE LIVE UPDATING TABLE!
+  while (recording) {
+    try {
+      const positions = await readMotorPositions(config); // Always quiet during live recording
+      readCount++;
+
+      // Update min/max ranges
+      for (let i = 0; i < config.motorNames.length; i++) {
+        const motorName = config.motorNames[i];
+        const position = positions[i];
+
+        if (position < rangeMins[motorName]) {
+          rangeMins[motorName] = position;
+        }
+        if (position > rangeMaxes[motorName]) {
+          rangeMaxes[motorName] = position;
+        }
+      }
+
+      // Show real-time feedback every 3 reads for faster updates - LIVE TABLE UPDATE
+      if (readCount % 3 === 0) {
+        // Build the live table content
+        let liveTable = "=== LIVE POSITION RECORDING ===\n";
+        liveTable += `Readings: ${readCount} | Press ENTER to stop\n\n`;
+        liveTable += "Motor Name       Current    Min      Max      Range\n";
+        liveTable += "─".repeat(55) + "\n";
+
+        for (let i = 0; i < config.motorNames.length; i++) {
+          const motorName = config.motorNames[i];
+          const current = positions[i];
+          const min = rangeMins[motorName];
+          const max = rangeMaxes[motorName];
+          const range = max - min;
+
+          liveTable += `${motorName.padEnd(15)} ${current
+            .toString()
+            .padStart(6)} ${min.toString().padStart(6)} ${max
+            .toString()
+            .padStart(6)} ${range.toString().padStart(8)}\n`;
+        }
+        liveTable += "\nMove joints through their full range...";
+
+        // Update the display in place (no new console lines!)
+        logUpdate(liveTable);
+      }
+
+      // Minimal delay for 30Hz reading rate (~33ms cycle time)
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    } catch (error) {
+      console.warn(
+        `Read error: ${error instanceof Error ? error.message : error}`
+      );
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  // Stop live updating and return to normal console
+  logUpdate.done();
+
+  return { rangeMins, rangeMaxes };
+}
+
+/**
+ * Prompt user for input (real implementation with readline)
+ */
+async function promptUser(message: string): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+/**
+ * Read data from serial port with timeout
+ */
+async function readData(
+  port: SerialPort,
+  timeout: number = 5000
+): Promise<Buffer> {
+  if (!port || !port.isOpen) {
+    throw new Error("Serial port not open");
+  }
+
+  return new Promise<Buffer>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error("Read timeout"));
+    }, timeout);
+
+    port.once("data", (data: Buffer) => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+  });
+}

src/lerobot/node/common/so100_config.ts

@@ -0,0 +1,96 @@
+/**
+ * SO-100 device configurations
+ * Defines the differences between leader and follower devices
+ * Mirrors Python lerobot device configuration approach
+ */
+
+import type { SO100CalibrationConfig } from "./calibration.js";
+import { SerialPort } from "serialport";
+
+/**
+ * Common motor names for all SO-100 devices
+ */
+const SO100_MOTOR_NAMES = [
+  "shoulder_pan",
+  "shoulder_lift",
+  "elbow_flex",
+  "wrist_flex",
+  "wrist_roll",
+  "gripper",
+];
+
+/**
+ * SO-100 Follower Configuration
+ * Robot arm that performs tasks autonomously
+ * Uses standard gear ratios for all motors
+ */
+export function createSO100FollowerConfig(
+  port: SerialPort
+): SO100CalibrationConfig {
+  return {
+    deviceType: "so100_follower",
+    port,
+    motorNames: SO100_MOTOR_NAMES,
+
+    // Follower uses standard drive modes (all same gear ratio)
+    driveModes: [0, 0, 0, 0, 0, 0], // All 1/345 gear ratio
+
+    // Calibration modes
+    calibModes: ["DEGREE", "DEGREE", "DEGREE", "DEGREE", "DEGREE", "LINEAR"],
+
+    // Follower limits - optimized for autonomous operation
+    limits: {
+      position_min: [-180, -90, -90, -90, -90, -90],
+      position_max: [180, 90, 90, 90, 90, 90],
+      velocity_max: [100, 100, 100, 100, 100, 100], // Fast for autonomous tasks
+      torque_max: [50, 50, 50, 50, 25, 25], // Higher torque for carrying loads
+    },
+  };
+}
+
+/**
+ * SO-100 Leader Configuration
+ * Teleoperator arm that humans use to control the follower
+ * Uses mixed gear ratios for easier human operation
+ */
+export function createSO100LeaderConfig(
+  port: SerialPort
+): SO100CalibrationConfig {
+  return {
+    deviceType: "so100_leader",
+    port,
+    motorNames: SO100_MOTOR_NAMES,
+
+    // Leader uses mixed gear ratios for easier human operation
+    // Based on Python lerobot leader calibration data
+    driveModes: [0, 1, 0, 0, 1, 0], // Mixed ratios: some 1/345, some 1/191, some 1/147
+
+    // Same calibration modes as follower
+    calibModes: ["DEGREE", "DEGREE", "DEGREE", "DEGREE", "DEGREE", "LINEAR"],
+
+    // Leader limits - optimized for human operation (safer, easier to move)
+    limits: {
+      position_min: [-120, -60, -60, -60, -180, -45],
+      position_max: [120, 60, 60, 60, 180, 45],
+      velocity_max: [80, 80, 80, 80, 120, 60], // Slower for human control
+      torque_max: [30, 30, 30, 30, 20, 15], // Lower torque for safety
+    },
+  };
+}
+
+/**
+ * Get configuration for any SO-100 device type
+ */
+export function getSO100Config(
+  deviceType: "so100_follower" | "so100_leader",
+  port: SerialPort
+): SO100CalibrationConfig {
+  switch (deviceType) {
+    case "so100_follower":
+      return createSO100FollowerConfig(port);
+    case "so100_leader":
+      return createSO100LeaderConfig(port);
+    default:
+      throw new Error(`Unknown SO-100 device type: ${deviceType}`);
+  }
+}

src/lerobot/node/constants.ts

@@ -0,0 +1,48 @@
+/**
+ * Constants for lerobot.js
+ * Mirrors Python lerobot/common/constants.py
+ */
+
+import { homedir } from "os";
+import { join } from "path";
+
+// Device types
+export const ROBOTS = "robots";
+export const TELEOPERATORS = "teleoperators";
+
+/**
+ * Get HF Home directory
+ * Equivalent to Python's huggingface_hub.constants.HF_HOME
+ */
+export function getHfHome(): string {
+  if (process.env.HF_HOME) {
+    return process.env.HF_HOME;
+  }
+
+  const homeDir = homedir();
+  return join(homeDir, ".cache", "huggingface");
+}
+
+/**
+ * Get HF lerobot home directory
+ * Equivalent to Python's HF_LEROBOT_HOME
+ */
+export function getHfLerobotHome(): string {
+  if (process.env.HF_LEROBOT_HOME) {
+    return process.env.HF_LEROBOT_HOME;
+  }
+
+  return join(getHfHome(), "lerobot");
+}
+
+/**
+ * Get calibration directory
+ * Equivalent to Python's HF_LEROBOT_CALIBRATION
+ */
+export function getCalibrationDir(): string {
+  if (process.env.HF_LEROBOT_CALIBRATION) {
+    return process.env.HF_LEROBOT_CALIBRATION;
+  }
+
+  return join(getHfLerobotHome(), "calibration");
+}

src/lerobot/node/robots/config.ts

@@ -0,0 +1,22 @@
+/**
+ * Robot configuration types
+ * Shared between Node.js and Web implementations
+ */
+
+import type { TeleoperatorConfig } from "../teleoperators/config.js";
+
+export interface RobotConfig {
+  type: "so100_follower";
+  port: string;
+  id?: string;
+  calibration_dir?: string;
+  // SO-100 specific options
+  disable_torque_on_disconnect?: boolean;
+  max_relative_target?: number | null;
+  use_degrees?: boolean;
+}
+
+export interface CalibrateConfig {
+  robot?: RobotConfig;
+  teleop?: TeleoperatorConfig;
+}

src/lerobot/node/robots/robot.ts

@@ -0,0 +1,161 @@
+/**
+ * Base Robot class for Node.js platform
+ * Uses serialport package for serial communication
+ * Mirrors Python lerobot/common/robots/robot.py
+ */
+
+import { SerialPort } from "serialport";
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import type { RobotConfig } from "./config.js";
+import { getCalibrationDir, ROBOTS } from "../constants.js";
+
+export abstract class Robot {
+  protected port: SerialPort | null = null;
+  protected config: RobotConfig;
+  protected calibrationDir: string;
+  protected calibrationPath: string;
+  protected name: string;
+
+  constructor(config: RobotConfig) {
+    this.config = config;
+    this.name = config.type;
+
+    // Determine calibration directory
+    // Mirrors Python: config.calibration_dir if config.calibration_dir else HF_LEROBOT_CALIBRATION / ROBOTS / self.name
+    this.calibrationDir =
+      config.calibration_dir || join(getCalibrationDir(), ROBOTS, this.name);
+
+    // Use robot ID or type as filename
+    const robotId = config.id || this.name;
+    this.calibrationPath = join(this.calibrationDir, `${robotId}.json`);
+  }
+
+  /**
+   * Connect to the robot
+   * Mirrors Python robot.connect()
+   */
+  async connect(_calibrate: boolean = false): Promise<void> {
+    try {
+      this.port = new SerialPort({
+        path: this.config.port,
+        baudRate: 1000000, // Default baud rate for Feetech motors (SO-100) - matches Python lerobot
+        dataBits: 8, // 8 data bits - matches Python serial.EIGHTBITS
+        stopBits: 1, // 1 stop bit - matches Python default
+        parity: "none", // No parity - matches Python default
+        autoOpen: false,
+      });
+
+      // Open the port
+      await new Promise<void>((resolve, reject) => {
+        this.port!.open((error) => {
+          if (error) {
+            reject(
+              new Error(
+                `Failed to open port ${this.config.port}: ${error.message}`
+              )
+            );
+          } else {
+            resolve();
+          }
+        });
+      });
+    } catch (error) {
+      throw new Error(`Could not connect to robot on port ${this.config.port}`);
+    }
+  }
+
+  /**
+   * Calibrate the robot
+   * Must be implemented by subclasses
+   */
+  abstract calibrate(): Promise<void>;
+
+  /**
+   * Disconnect from the robot
+   * Mirrors Python robot.disconnect()
+   */
+  async disconnect(): Promise<void> {
+    if (this.port && this.port.isOpen) {
+      // Handle torque disable if configured
+      if (this.config.disable_torque_on_disconnect) {
+        await this.disableTorque();
+      }
+
+      await new Promise<void>((resolve) => {
+        this.port!.close(() => {
+          resolve();
+        });
+      });
+
+      this.port = null;
+    }
+  }
+
+  /**
+   * Save calibration data to JSON file
+   * Mirrors Python's configuration saving
+   */
+  protected async saveCalibration(calibrationData: any): Promise<void> {
+    // Ensure calibration directory exists
+    await mkdir(this.calibrationDir, { recursive: true });
+
+    // Save calibration data as JSON
+    await writeFile(
+      this.calibrationPath,
+      JSON.stringify(calibrationData, null, 2)
+    );
+
+    console.log(`Configuration saved to: ${this.calibrationPath}`);
+  }
+
+  /**
+   * Send command to robot via serial port
+   */
+  protected async sendCommand(command: string): Promise<void> {
+    if (!this.port || !this.port.isOpen) {
+      throw new Error("Robot not connected");
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      this.port!.write(command, (error) => {
+        if (error) {
+          reject(new Error(`Failed to send command: ${error.message}`));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  /**
+   * Read data from robot
+   */
+  protected async readData(timeout: number = 5000): Promise<Buffer> {
+    if (!this.port || !this.port.isOpen) {
+      throw new Error("Robot not connected");
+    }
+
+    return new Promise<Buffer>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error("Read timeout"));
+      }, timeout);
+
+      this.port!.once("data", (data: Buffer) => {
+        clearTimeout(timer);
+        resolve(data);
+      });
+    });
+  }
+
+  /**
+   * Disable torque on disconnect (SO-100 specific)
+   */
+  protected async disableTorque(): Promise<void> {
+    try {
+      await this.sendCommand("TORQUE_DISABLE\r\n");
+    } catch (error) {
+      console.warn("Warning: Could not disable torque on disconnect");
+    }
+  }
+}

src/lerobot/node/robots/so100_follower.ts

@@ -0,0 +1,465 @@
+/**
+ * SO-100 Follower Robot implementation for Node.js
+ * Mirrors Python lerobot/common/robots/so100_follower/so100_follower.py
+ */
+
+import { Robot } from "./robot.js";
+import type { RobotConfig } from "./config.js";
+import * as readline from "readline";
+
+export class SO100Follower extends Robot {
+  constructor(config: RobotConfig) {
+    super(config);
+
+    // Validate that this is an SO-100 follower config
+    if (config.type !== "so100_follower") {
+      throw new Error(
+        `Invalid robot type: ${config.type}. Expected: so100_follower`
+      );
+    }
+  }
+
+  /**
+   * Calibrate the SO-100 follower robot
+   * NOTE: Calibration logic has been moved to shared/common/calibration.ts
+   * This method is kept for backward compatibility but delegates to the main calibrate.ts
+   */
+  async calibrate(): Promise<void> {
+    throw new Error(
+      "Direct device calibration is deprecated. Use the main calibrate.ts orchestrator instead."
+    );
+  }
+
+  /**
+   * Initialize robot communication
+   * For now, just test basic serial connectivity
+   */
+  private async initializeRobot(): Promise<void> {
+    console.log("Initializing robot communication...");
+
+    try {
+      // For SO-100, we need to implement Feetech servo protocol
+      // For now, just test that we can send/receive data
+      console.log("Testing serial port connectivity...");
+
+      // Try to ping servo ID 1 (shoulder_pan motor)
+      // This is a very basic test - real implementation needs proper Feetech protocol
+      const pingPacket = Buffer.from([0xff, 0xff, 0x01, 0x02, 0x01, 0xfb]); // Basic ping packet
+
+      if (!this.port || !this.port.isOpen) {
+        throw new Error("Serial port not open");
+      }
+
+      // Send ping packet
+      await new Promise<void>((resolve, reject) => {
+        this.port!.write(pingPacket, (error) => {
+          if (error) {
+            reject(new Error(`Failed to send ping: ${error.message}`));
+          } else {
+            resolve();
+          }
+        });
+      });
+
+      console.log("Ping packet sent successfully");
+
+      // Try to read response with shorter timeout
+      try {
+        const response = await this.readData(1000); // 1 second timeout
+        console.log(`Response received: ${response.length} bytes`);
+      } catch (error) {
+        console.log("No response received (expected for basic test)");
+      }
+    } catch (error) {
+      throw new Error(
+        `Serial communication test failed: ${
+          error instanceof Error ? error.message : error
+        }`
+      );
+    }
+
+    console.log("Robot communication test completed.");
+  }
+
+  /**
+   * Read current motor positions
+   * Implements basic STS3215 servo protocol to read actual positions
+   */
+  private async readMotorPositions(): Promise<number[]> {
+    console.log("Reading motor positions...");
+
+    const motorPositions: number[] = [];
+    const motorIds = [1, 2, 3, 4, 5, 6]; // SO-100 has servo IDs 1-6
+    const motorNames = [
+      "shoulder_pan",
+      "shoulder_lift",
+      "elbow_flex",
+      "wrist_flex",
+      "wrist_roll",
+      "gripper",
+    ];
+
+    // Try to read position from each servo using STS3215 protocol
+    for (let i = 0; i < motorIds.length; i++) {
+      const motorId = motorIds[i];
+      const motorName = motorNames[i];
+
+      try {
+        console.log(`  Reading ${motorName} (ID ${motorId})...`);
+
+        // Create STS3215 Read Position packet
+        // Format: [0xFF, 0xFF, ID, Length, Instruction, Address, DataLength, Checksum]
+        // Present_Position address for STS3215 is 56 (0x38), length 2 bytes
+        const packet = Buffer.from([
+          0xff,
+          0xff, // Header
+          motorId, // Servo ID
+          0x04, // Length (Instruction + Address + DataLength + Checksum)
+          0x02, // Instruction: READ_DATA
+          0x38, // Address: Present_Position (56)
+          0x02, // Data Length: 2 bytes
+          0x00, // Checksum (will calculate)
+        ]);
+
+        // Calculate checksum: ~(ID + Length + Instruction + Address + DataLength) & 0xFF
+        const checksum = ~(motorId + 0x04 + 0x02 + 0x38 + 0x02) & 0xff;
+        packet[7] = checksum;
+
+        if (!this.port || !this.port.isOpen) {
+          throw new Error("Serial port not open");
+        }
+
+        // Send read position packet
+        await new Promise<void>((resolve, reject) => {
+          this.port!.write(packet, (error) => {
+            if (error) {
+              reject(new Error(`Failed to send read packet: ${error.message}`));
+            } else {
+              resolve();
+            }
+          });
+        });
+
+        // Try to read response (timeout after 500ms)
+        try {
+          const response = await this.readData(500);
+
+          if (response.length >= 7) {
+            // Parse response: [0xFF, 0xFF, ID, Length, Error, Data_L, Data_H, Checksum]
+            const id = response[2];
+            const error = response[4];
+
+            if (id === motorId && error === 0) {
+              // Extract 16-bit position from Data_L and Data_H
+              const position = response[5] | (response[6] << 8);
+              motorPositions.push(position);
+              console.log(`    ${motorName}: ${position} (0-4095 range)`);
+            } else {
+              console.warn(
+                `    ${motorName}: Error response (error code: ${error})`
+              );
+              motorPositions.push(2047); // Use center position as fallback
+            }
+          } else {
+            console.warn(`    ${motorName}: Invalid response length`);
+            motorPositions.push(2047); // Use center position as fallback
+          }
+        } catch (readError) {
+          console.warn(
+            `    ${motorName}: Read timeout - using fallback position`
+          );
+          motorPositions.push(2047); // Use center position as fallback
+        }
+      } catch (error) {
+        console.warn(
+          `    ${motorName}: Communication error - ${
+            error instanceof Error ? error.message : error
+          }`
+        );
+        motorPositions.push(2047); // Use center position as fallback
+      }
+
+      // Small delay between servo reads
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+
+    console.log(`Motor positions: [${motorPositions.join(", ")}]`);
+    return motorPositions;
+  }
+
+  /**
+   * Set motor limits and safety parameters
+   * TODO: Implement proper Feetech servo protocol
+   */
+  private async setMotorLimits(): Promise<any> {
+    console.log("Setting motor limits...");
+
+    // Set default limits for SO-100 (based on Python implementation)
+    const limits = {
+      position_min: [-180, -90, -90, -90, -90, -90],
+      position_max: [180, 90, 90, 90, 90, 90],
+      velocity_max: [100, 100, 100, 100, 100, 100],
+      torque_max: [50, 50, 50, 50, 25, 25],
+    };
+
+    // For now, just return the limits without sending to robot
+    // Real implementation needs Feetech servo protocol to set limits
+    console.log("Motor limits configured (mock).");
+    return limits;
+  }
+
+  /**
+   * Interactive calibration process - matches Python lerobot calibration flow
+   * Implements real calibration with user interaction
+   */
+  private async calibrateMotors(): Promise<any> {
+    console.log("\n=== INTERACTIVE CALIBRATION ===");
+    console.log("Starting SO-100 follower arm calibration...");
+
+    // Step 1: Move to middle position and record homing offsets
+    console.log("\n📍 STEP 1: Set Homing Position");
+    await this.promptUser(
+      "Move the SO-100 to the MIDDLE of its range of motion and press ENTER..."
+    );
+
+    const homingOffsets = await this.setHomingOffsets();
+
+    // Step 2: Record ranges of motion
+    console.log("\n📏 STEP 2: Record Joint Ranges");
+    const { rangeMins, rangeMaxes } = await this.recordRangesOfMotion();
+
+    // Step 3: Set special range for wrist_roll (full turn motor)
+    console.log("\n🔄 STEP 3: Configure Full-Turn Motor");
+    console.log("Setting wrist_roll as full-turn motor (0-4095 range)");
+    rangeMins["wrist_roll"] = 0;
+    rangeMaxes["wrist_roll"] = 4095;
+
+    // Step 4: Compile calibration results
+    const motorNames = [
+      "shoulder_pan",
+      "shoulder_lift",
+      "elbow_flex",
+      "wrist_flex",
+      "wrist_roll",
+      "gripper",
+    ];
+    const results = [];
+
+    for (let i = 0; i < motorNames.length; i++) {
+      const motorId = i + 1; // Servo IDs are 1-6
+      const motorName = motorNames[i];
+
+      results.push({
+        motor: motorId,
+        name: motorName,
+        status: "success",
+        homing_offset: homingOffsets[motorName],
+        range_min: rangeMins[motorName],
+        range_max: rangeMaxes[motorName],
+        range_size: rangeMaxes[motorName] - rangeMins[motorName],
+      });
+
+      console.log(
+        `✅ ${motorName} calibrated: range ${rangeMins[motorName]} to ${rangeMaxes[motorName]} (offset: ${homingOffsets[motorName]})`
+      );
+    }
+
+    console.log("\n🎉 Interactive calibration completed!");
+    return results;
+  }
+
+  /**
+   * Verify calibration was successful
+   * TODO: Implement proper verification with Feetech servo protocol
+   */
+  private async verifyCalibration(): Promise<void> {
+    console.log("Verifying calibration...");
+
+    // For now, just mock successful verification
+    // Real implementation should check:
+    // 1. All motors respond to ping
+    // 2. Position limits are set correctly
+    // 3. Homing offsets are applied
+    // 4. Motors can move to test positions
+
+    console.log("Calibration verification passed (mock).");
+  }
+
+  /**
+   * Prompt user for input (like Python's input() function)
+   */
+  private async promptUser(message: string): Promise<string> {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    return new Promise((resolve) => {
+      rl.question(message, (answer) => {
+        rl.close();
+        resolve(answer);
+      });
+    });
+  }
+
+  /**
+   * Record homing offsets (current positions as center)
+   * Mirrors Python bus.set_half_turn_homings()
+   */
+  private async setHomingOffsets(): Promise<{ [motor: string]: number }> {
+    console.log("Recording current positions as homing offsets...");
+
+    const currentPositions = await this.readMotorPositions();
+    const motorNames = [
+      "shoulder_pan",
+      "shoulder_lift",
+      "elbow_flex",
+      "wrist_flex",
+      "wrist_roll",
+      "gripper",
+    ];
+    const homingOffsets: { [motor: string]: number } = {};
+
+    for (let i = 0; i < motorNames.length; i++) {
+      const motorName = motorNames[i];
+      const position = currentPositions[i];
+      // Calculate homing offset (half turn offset from current position)
+      const maxRes = 4095; // STS3215 resolution
+      homingOffsets[motorName] = position - Math.floor(maxRes / 2);
+      console.log(
+        `  ${motorName}: offset ${homingOffsets[motorName]} (current pos: ${position})`
+      );
+    }
+
+    return homingOffsets;
+  }
+
+  /**
+   * Record ranges of motion by continuously reading positions
+   * Mirrors Python bus.record_ranges_of_motion()
+   */
+  private async recordRangesOfMotion(): Promise<{
+    rangeMins: { [motor: string]: number };
+    rangeMaxes: { [motor: string]: number };
+  }> {
+    console.log("\n=== RECORDING RANGES OF MOTION ===");
+    console.log(
+      "Move all joints sequentially through their entire ranges of motion."
+    );
+    console.log(
+      "Positions will be recorded continuously. Press ENTER to stop...\n"
+    );
+
+    const motorNames = [
+      "shoulder_pan",
+      "shoulder_lift",
+      "elbow_flex",
+      "wrist_flex",
+      "wrist_roll",
+      "gripper",
+    ];
+    const rangeMins: { [motor: string]: number } = {};
+    const rangeMaxes: { [motor: string]: number } = {};
+
+    // Initialize with current positions
+    const initialPositions = await this.readMotorPositions();
+    for (let i = 0; i < motorNames.length; i++) {
+      const motorName = motorNames[i];
+      const position = initialPositions[i];
+      rangeMins[motorName] = position;
+      rangeMaxes[motorName] = position;
+    }
+
+    let recording = true;
+    let readCount = 0;
+
+    // Set up readline to detect Enter key
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.on("line", () => {
+      recording = false;
+      rl.close();
+    });
+
+    console.log("Recording started... (move the robot joints now)");
+
+    // Continuous recording loop
+    while (recording) {
+      try {
+        const positions = await this.readMotorPositions();
+        readCount++;
+
+        // Update min/max ranges
+        for (let i = 0; i < motorNames.length; i++) {
+          const motorName = motorNames[i];
+          const position = positions[i];
+
+          if (position < rangeMins[motorName]) {
+            rangeMins[motorName] = position;
+          }
+          if (position > rangeMaxes[motorName]) {
+            rangeMaxes[motorName] = position;
+          }
+        }
+
+        // Show real-time feedback every 10 reads
+        if (readCount % 10 === 0) {
+          console.clear(); // Clear screen for live update
+          console.log("=== LIVE POSITION RECORDING ===");
+          console.log(`Readings: ${readCount} | Press ENTER to stop\n`);
+
+          console.log("Motor Name       Current    Min      Max      Range");
+          console.log("─".repeat(55));
+
+          for (let i = 0; i < motorNames.length; i++) {
+            const motorName = motorNames[i];
+            const current = positions[i];
+            const min = rangeMins[motorName];
+            const max = rangeMaxes[motorName];
+            const range = max - min;
+
+            console.log(
+              `${motorName.padEnd(15)} ${current.toString().padStart(6)} ${min
+                .toString()
+                .padStart(6)} ${max.toString().padStart(6)} ${range
+                .toString()
+                .padStart(8)}`
+            );
+          }
+          console.log("\nMove joints through their full range...");
+        }
+
+        // Small delay to avoid overwhelming the serial port
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      } catch (error) {
+        console.warn(
+          `Read error: ${error instanceof Error ? error.message : error}`
+        );
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+    }
+
+    console.log(`\nRecording stopped after ${readCount} readings.`);
+    console.log("\nFinal ranges recorded:");
+
+    for (const motorName of motorNames) {
+      const min = rangeMins[motorName];
+      const max = rangeMaxes[motorName];
+      const range = max - min;
+      console.log(`  ${motorName}: ${min} to ${max} (range: ${range})`);
+    }
+
+    return { rangeMins, rangeMaxes };
+  }
+}
+
+/**
+ * Factory function to create SO-100 follower robot
+ * Mirrors Python's make_robot_from_config pattern
+ */
+export function createSO100Follower(config: RobotConfig): SO100Follower {
+  return new SO100Follower(config);
+}

src/lerobot/node/teleoperators/config.ts

@@ -0,0 +1,12 @@
+/**
+ * Teleoperator configuration types
+ * Shared between Node.js and Web implementations
+ */
+
+export interface TeleoperatorConfig {
+  type: "so100_leader";
+  port: string;
+  id?: string;
+  calibration_dir?: string;
+  // SO-100 leader specific options
+}

src/lerobot/node/teleoperators/so100_leader.ts

@@ -0,0 +1,41 @@
+/**
+ * SO-100 Leader Teleoperator implementation for Node.js
+ *
+ * Minimal implementation - calibration logic moved to shared/common/calibration.ts
+ * This class only handles connection management and basic device operations
+ */
+
+import { Teleoperator } from "./teleoperator.js";
+import type { TeleoperatorConfig } from "./config.js";
+
+export class SO100Leader extends Teleoperator {
+  constructor(config: TeleoperatorConfig) {
+    super(config);
+
+    // Validate that this is an SO-100 leader config
+    if (config.type !== "so100_leader") {
+      throw new Error(
+        `Invalid teleoperator type: ${config.type}. Expected: so100_leader`
+      );
+    }
+  }
+
+  /**
+   * Calibrate the SO-100 leader teleoperator
+   * NOTE: Calibration logic has been moved to shared/common/calibration.ts
+   * This method is kept for backward compatibility but delegates to the main calibrate.ts
+   */
+  async calibrate(): Promise<void> {
+    throw new Error(
+      "Direct device calibration is deprecated. Use the main calibrate.ts orchestrator instead."
+    );
+  }
+}
+
+/**
+ * Factory function to create SO-100 leader teleoperator
+ * Mirrors Python's make_teleoperator_from_config pattern
+ */
+export function createSO100Leader(config: TeleoperatorConfig): SO100Leader {
+  return new SO100Leader(config);
+}

src/lerobot/node/teleoperators/teleoperator.ts

@@ -0,0 +1,148 @@
+/**
+ * Base Teleoperator class for Node.js platform
+ * Uses serialport package for serial communication
+ * Mirrors Python lerobot/common/teleoperators/teleoperator.py
+ */
+
+import { SerialPort } from "serialport";
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import type { TeleoperatorConfig } from "./config.js";
+import { getCalibrationDir, TELEOPERATORS } from "../constants.js";
+
+export abstract class Teleoperator {
+  protected port: SerialPort | null = null;
+  protected config: TeleoperatorConfig;
+  protected calibrationDir: string;
+  protected calibrationPath: string;
+  protected name: string;
+
+  constructor(config: TeleoperatorConfig) {
+    this.config = config;
+    this.name = config.type;
+
+    // Determine calibration directory
+    // Mirrors Python: config.calibration_dir if config.calibration_dir else HF_LEROBOT_CALIBRATION / TELEOPERATORS / self.name
+    this.calibrationDir =
+      config.calibration_dir ||
+      join(getCalibrationDir(), TELEOPERATORS, this.name);
+
+    // Use teleoperator ID or type as filename
+    const teleopId = config.id || this.name;
+    this.calibrationPath = join(this.calibrationDir, `${teleopId}.json`);
+  }
+
+  /**
+   * Connect to the teleoperator
+   * Mirrors Python teleoperator.connect()
+   */
+  async connect(_calibrate: boolean = false): Promise<void> {
+    try {
+      this.port = new SerialPort({
+        path: this.config.port,
+        baudRate: 1000000, // Correct baud rate for Feetech motors (SO-100) - matches Python lerobot
+        dataBits: 8, // 8 data bits - matches Python serial.EIGHTBITS
+        stopBits: 1, // 1 stop bit - matches Python default
+        parity: "none", // No parity - matches Python default
+        autoOpen: false,
+      });
+
+      // Open the port
+      await new Promise<void>((resolve, reject) => {
+        this.port!.open((error) => {
+          if (error) {
+            reject(
+              new Error(
+                `Failed to open port ${this.config.port}: ${error.message}`
+              )
+            );
+          } else {
+            resolve();
+          }
+        });
+      });
+    } catch (error) {
+      throw new Error(
+        `Could not connect to teleoperator on port ${this.config.port}`
+      );
+    }
+  }
+
+  /**
+   * Calibrate the teleoperator
+   * Must be implemented by subclasses
+   */
+  abstract calibrate(): Promise<void>;
+
+  /**
+   * Disconnect from the teleoperator
+   * Mirrors Python teleoperator.disconnect()
+   */
+  async disconnect(): Promise<void> {
+    if (this.port && this.port.isOpen) {
+      await new Promise<void>((resolve) => {
+        this.port!.close(() => {
+          resolve();
+        });
+      });
+
+      this.port = null;
+    }
+  }
+
+  /**
+   * Save calibration data to JSON file
+   * Mirrors Python's configuration saving
+   */
+  protected async saveCalibration(calibrationData: any): Promise<void> {
+    // Ensure calibration directory exists
+    await mkdir(this.calibrationDir, { recursive: true });
+
+    // Save calibration data as JSON
+    await writeFile(
+      this.calibrationPath,
+      JSON.stringify(calibrationData, null, 2)
+    );
+
+    console.log(`Configuration saved to: ${this.calibrationPath}`);
+  }
+
+  /**
+   * Send command to teleoperator via serial port
+   */
+  protected async sendCommand(command: string): Promise<void> {
+    if (!this.port || !this.port.isOpen) {
+      throw new Error("Teleoperator not connected");
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      this.port!.write(command, (error) => {
+        if (error) {
+          reject(new Error(`Failed to send command: ${error.message}`));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  /**
+   * Read data from teleoperator
+   */
+  protected async readData(timeout: number = 5000): Promise<Buffer> {
+    if (!this.port || !this.port.isOpen) {
+      throw new Error("Teleoperator not connected");
+    }
+
+    return new Promise<Buffer>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error("Read timeout"));
+      }, timeout);
+
+      this.port!.once("data", (data: Buffer) => {
+        clearTimeout(timer);
+        resolve(data);
+      });
+    });
+  }
+}

src/lerobot/web/calibrate.ts

@@ -0,0 +1,404 @@
+/**
+ * Web calibration functionality using Web Serial API
+ * For browser environments - matches Node.js implementation
+ */
+
+import type { CalibrateConfig } from "../node/robots/config.js";
+
+/**
+ * Web Serial Port wrapper to match Node.js SerialPort interface
+ */
+class WebSerialPortWrapper {
+  private port: SerialPort;
+  private reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+  private writer: WritableStreamDefaultWriter<Uint8Array> | null = null;
+
+  constructor(port: SerialPort) {
+    this.port = port;
+  }
+
+  get isOpen(): boolean {
+    return this.port !== null && this.port.readable !== null;
+  }
+
+  async initialize(): Promise<void> {
+    // Set up reader and writer for already opened port
+    if (this.port.readable) {
+      this.reader = this.port.readable.getReader();
+    }
+    if (this.port.writable) {
+      this.writer = this.port.writable.getWriter();
+    }
+  }
+
+  async write(data: Buffer): Promise<void> {
+    if (!this.writer) {
+      throw new Error("Port not open for writing");
+    }
+    await this.writer.write(new Uint8Array(data));
+  }
+
+  async read(timeout: number = 5000): Promise<Buffer> {
+    if (!this.reader) {
+      throw new Error("Port not open for reading");
+    }
+
+    return new Promise<Buffer>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error("Read timeout"));
+      }, timeout);
+
+      this.reader!.read()
+        .then(({ value, done }) => {
+          clearTimeout(timer);
+          if (done || !value) {
+            reject(new Error("Read failed"));
+          } else {
+            resolve(Buffer.from(value));
+          }
+        })
+        .catch(reject);
+    });
+  }
+
+  async close(): Promise<void> {
+    if (this.reader) {
+      await this.reader.cancel();
+      this.reader = null;
+    }
+    if (this.writer) {
+      this.writer.releaseLock();
+      this.writer = null;
+    }
+    // Don't close the port itself - let the UI manage that
+  }
+}
+
+/**
+ * SO-100 calibration configuration for web
+ */
+interface WebSO100CalibrationConfig {
+  deviceType: "so100_follower" | "so100_leader";
+  port: WebSerialPortWrapper;
+  motorNames: string[];
+  driveModes: number[];
+  calibModes: string[];
+  limits: {
+    position_min: number[];
+    position_max: number[];
+    velocity_max: number[];
+    torque_max: number[];
+  };
+}
+
+/**
+ * Read motor positions using Web Serial API
+ */
+async function readMotorPositions(
+  config: WebSO100CalibrationConfig
+): Promise<number[]> {
+  const motorPositions: number[] = [];
+  const motorIds = [1, 2, 3, 4, 5, 6]; // SO-100 uses servo IDs 1-6
+
+  for (let i = 0; i < motorIds.length; i++) {
+    const motorId = motorIds[i];
+
+    try {
+      // Create STS3215 Read Position packet
+      const packet = Buffer.from([
+        0xff,
+        0xff,
+        motorId,
+        0x04,
+        0x02,
+        0x38,
+        0x02,
+        0x00,
+      ]);
+      const checksum = ~(motorId + 0x04 + 0x02 + 0x38 + 0x02) & 0xff;
+      packet[7] = checksum;
+
+      await config.port.write(packet);
+
+      try {
+        const response = await config.port.read(100);
+        if (response.length >= 7) {
+          const id = response[2];
+          const error = response[4];
+          if (id === motorId && error === 0) {
+            const position = response[5] | (response[6] << 8);
+            motorPositions.push(position);
+          } else {
+            motorPositions.push(2047); // Fallback to center
+          }
+        } else {
+          motorPositions.push(2047);
+        }
+      } catch (readError) {
+        motorPositions.push(2047);
+      }
+    } catch (error) {
+      motorPositions.push(2047);
+    }
+
+    // Minimal delay between servo reads
+    await new Promise((resolve) => setTimeout(resolve, 2));
+  }
+
+  return motorPositions;
+}
+
+/**
+ * Interactive web calibration with live updates
+ */
+async function performWebCalibration(
+  config: WebSO100CalibrationConfig
+): Promise<any> {
+  // Step 1: Set homing position
+  alert(
+    `📍 STEP 1: Set Homing Position\n\nMove the SO-100 ${config.deviceType} to the MIDDLE of its range of motion and click OK...`
+  );
+
+  const currentPositions = await readMotorPositions(config);
+  const homingOffsets: { [motor: string]: number } = {};
+  for (let i = 0; i < config.motorNames.length; i++) {
+    const motorName = config.motorNames[i];
+    const position = currentPositions[i];
+    const maxRes = 4095; // STS3215 resolution
+    homingOffsets[motorName] = position - Math.floor(maxRes / 2);
+  }
+
+  // Step 2: Record ranges with simplified interface for web
+  alert(
+    `📏 STEP 2: Record Joint Ranges\n\nMove all joints through their full range of motion, then click OK when finished...`
+  );
+
+  const rangeMins: { [motor: string]: number } = {};
+  const rangeMaxes: { [motor: string]: number } = {};
+
+  // Initialize with current positions
+  const initialPositions = await readMotorPositions(config);
+  for (let i = 0; i < config.motorNames.length; i++) {
+    const motorName = config.motorNames[i];
+    const position = initialPositions[i];
+    rangeMins[motorName] = position;
+    rangeMaxes[motorName] = position;
+  }
+
+  // Record positions for a brief period
+  const recordingDuration = 10000; // 10 seconds
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < recordingDuration) {
+    const positions = await readMotorPositions(config);
+
+    for (let i = 0; i < config.motorNames.length; i++) {
+      const motorName = config.motorNames[i];
+      const position = positions[i];
+
+      if (position < rangeMins[motorName]) {
+        rangeMins[motorName] = position;
+      }
+      if (position > rangeMaxes[motorName]) {
+        rangeMaxes[motorName] = position;
+      }
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  return {
+    homing_offset: config.motorNames.map((name) => homingOffsets[name]),
+    drive_mode: config.driveModes,
+    start_pos: config.motorNames.map((name) => rangeMins[name]),
+    end_pos: config.motorNames.map((name) => rangeMaxes[name]),
+    calib_mode: config.calibModes,
+    motor_names: config.motorNames,
+  };
+}
+
+/**
+ * Calibrate a device using an already connected port
+ */
+export async function calibrateWithPort(
+  armType: "so100_follower" | "so100_leader",
+  armId: string,
+  connectedPort: SerialPort
+): Promise<void> {
+  try {
+    // Create web serial port wrapper
+    const port = new WebSerialPortWrapper(connectedPort);
+    await port.initialize();
+
+    // Get SO-100 calibration configuration
+    const so100Config: WebSO100CalibrationConfig = {
+      deviceType: armType,
+      port,
+      motorNames: [
+        "shoulder_pan",
+        "shoulder_lift",
+        "elbow_flex",
+        "wrist_flex",
+        "wrist_roll",
+        "gripper",
+      ],
+      driveModes: [0, 0, 0, 0, 0, 0],
+      calibModes: [
+        "position",
+        "position",
+        "position",
+        "position",
+        "position",
+        "position",
+      ],
+      limits: {
+        position_min: [0, 0, 0, 0, 0, 0],
+        position_max: [4095, 4095, 4095, 4095, 4095, 4095],
+        velocity_max: [100, 100, 100, 100, 100, 100],
+        torque_max: [50, 50, 50, 50, 25, 25],
+      },
+    };
+
+    // Perform calibration
+    const calibrationResults = await performWebCalibration(so100Config);
+
+    // Save to browser storage and download
+    const calibrationData = {
+      ...calibrationResults,
+      device_type: armType,
+      device_id: armId,
+      calibrated_at: new Date().toISOString(),
+      platform: "web",
+      api: "Web Serial API",
+    };
+
+    const storageKey = `lerobot_calibration_${armType}_${armId}`;
+    localStorage.setItem(storageKey, JSON.stringify(calibrationData));
+
+    // Download calibration file
+    downloadCalibrationFile(calibrationData, armId);
+
+    // Close wrapper (but not the underlying port)
+    await port.close();
+
+    console.log(`Configuration saved to browser storage and downloaded.`);
+  } catch (error) {
+    throw new Error(
+      `Web calibration failed: ${
+        error instanceof Error ? error.message : error
+      }`
+    );
+  }
+}
+
+/**
+ * Calibrate a device in the browser using Web Serial API
+ * Must be called from user interaction (button click)
+ * This version requests a new port - use calibrateWithPort for already connected ports
+ */
+export async function calibrate(config: CalibrateConfig): Promise<void> {
+  // Validate Web Serial API support
+  if (!("serial" in navigator)) {
+    throw new Error("Web Serial API not supported in this browser");
+  }
+
+  // Validate configuration
+  if (Boolean(config.robot) === Boolean(config.teleop)) {
+    throw new Error("Choose either a robot or a teleop.");
+  }
+
+  const deviceConfig = config.robot || config.teleop!;
+
+  try {
+    // Request a new port for this calibration
+    const port = await navigator.serial.requestPort();
+    await port.open({ baudRate: 1000000 });
+
+    // Use the new port calibration function
+    await calibrateWithPort(
+      deviceConfig.type as "so100_follower" | "so100_leader",
+      deviceConfig.id || deviceConfig.type,
+      port
+    );
+
+    // Close the port we opened
+    await port.close();
+  } catch (error) {
+    throw new Error(
+      `Web calibration failed: ${
+        error instanceof Error ? error.message : error
+      }`
+    );
+  }
+}
+
+/**
+ * Download calibration data as JSON file
+ */
+function downloadCalibrationFile(calibrationData: any, deviceId: string): void {
+  const dataStr = JSON.stringify(calibrationData, null, 2);
+  const dataBlob = new Blob([dataStr], { type: "application/json" });
+
+  const url = URL.createObjectURL(dataBlob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = `${deviceId}_calibration.json`;
+
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+  URL.revokeObjectURL(url);
+}
+
+/**
+ * Check if Web Serial API is supported
+ */
+export function isWebSerialSupported(): boolean {
+  return "serial" in navigator;
+}
+
+/**
+ * Create a calibration button for web interface
+ * Returns a button element that when clicked starts calibration
+ */
+export function createCalibrateButton(
+  config: CalibrateConfig
+): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.textContent = "Calibrate Device";
+  button.style.cssText = `
+    padding: 10px 20px;
+    background-color: #007bff;
+    color: white;
+    border: none;
+    border-radius: 5px;
+    cursor: pointer;
+    font-size: 16px;
+  `;
+
+  button.addEventListener("click", async () => {
+    button.disabled = true;
+    button.textContent = "Calibrating...";
+
+    try {
+      await calibrate(config);
+      button.textContent = "Calibration Complete!";
+      button.style.backgroundColor = "#28a745";
+    } catch (error) {
+      button.textContent = "Calibration Failed";
+      button.style.backgroundColor = "#dc3545";
+      console.error("Calibration error:", error);
+      alert(
+        `Calibration failed: ${error instanceof Error ? error.message : error}`
+      );
+    } finally {
+      setTimeout(() => {
+        button.disabled = false;
+        button.textContent = "Calibrate Device";
+        button.style.backgroundColor = "#007bff";
+      }, 3000);
+    }
+  });
+
+  return button;
+}

src/lerobot/web/robots/robot.ts

@@ -0,0 +1,172 @@
+/**
+ * Base Robot class for Web platform
+ * Uses Web Serial API for serial communication
+ * Mirrors Python lerobot/common/robots/robot.py but adapted for browser environment
+ */
+
+import type { RobotConfig } from "../../node/robots/config.js";
+
+// Web Serial API type declarations (minimal for our needs)
+declare global {
+  interface SerialPort {
+    open(options: { baudRate: number }): Promise<void>;
+    close(): Promise<void>;
+    readable: ReadableStream<Uint8Array> | null;
+    writable: WritableStream<Uint8Array> | null;
+  }
+}
+
+export abstract class Robot {
+  protected port: SerialPort | null = null;
+  protected config: RobotConfig;
+  protected name: string;
+  protected reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+  protected writer: WritableStreamDefaultWriter<Uint8Array> | null = null;
+
+  constructor(config: RobotConfig) {
+    this.config = config;
+    this.name = config.type;
+  }
+
+  /**
+   * Connect to the robot using Web Serial API
+   * Requires user interaction to select port
+   */
+  async connect(_calibrate: boolean = false): Promise<void> {
+    try {
+      // Request port from user (requires user interaction)
+      this.port = await navigator.serial.requestPort();
+
+      // Open the port with correct SO-100 baudRate
+      await this.port.open({ baudRate: 1000000 }); // Correct baudRate for Feetech motors (SO-100)
+
+      // Set up readable and writable streams
+      if (this.port.readable) {
+        this.reader = this.port.readable.getReader();
+      }
+
+      if (this.port.writable) {
+        this.writer = this.port.writable.getWriter();
+      }
+    } catch (error) {
+      throw new Error(
+        `Could not connect to robot: ${
+          error instanceof Error ? error.message : error
+        }`
+      );
+    }
+  }
+
+  /**
+   * Calibrate the robot
+   * Must be implemented by subclasses
+   */
+  abstract calibrate(): Promise<void>;
+
+  /**
+   * Disconnect from the robot
+   */
+  async disconnect(): Promise<void> {
+    if (this.reader) {
+      await this.reader.cancel();
+      this.reader.releaseLock();
+      this.reader = null;
+    }
+
+    if (this.writer) {
+      await this.writer.close();
+      this.writer = null;
+    }
+
+    if (this.port) {
+      await this.port.close();
+      this.port = null;
+    }
+  }
+
+  /**
+   * Save calibration data to browser storage
+   * Uses localStorage as fallback, IndexedDB preferred for larger data
+   */
+  protected async saveCalibration(calibrationData: any): Promise<void> {
+    const robotId = this.config.id || this.name;
+    const key = `lerobot_calibration_${this.name}_${robotId}`;
+
+    try {
+      // Save to localStorage for now (could be enhanced to use File System Access API)
+      localStorage.setItem(key, JSON.stringify(calibrationData));
+
+      // Optionally trigger download
+      this.downloadCalibration(calibrationData, robotId);
+
+      console.log(`Configuration saved to browser storage and downloaded.`);
+    } catch (error) {
+      this.downloadCalibration(calibrationData, robotId);
+      console.log(`Configuration downloaded as file.`);
+    }
+  }
+
+  /**
+   * Download calibration data as JSON file
+   */
+  private downloadCalibration(calibrationData: any, robotId: string): void {
+    const dataStr = JSON.stringify(calibrationData, null, 2);
+    const dataBlob = new Blob([dataStr], { type: "application/json" });
+
+    const url = URL.createObjectURL(dataBlob);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = `${robotId}_calibration.json`;
+
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    URL.revokeObjectURL(url);
+  }
+
+  /**
+   * Send command to robot via Web Serial API
+   */
+  protected async sendCommand(command: string): Promise<void> {
+    if (!this.writer) {
+      throw new Error("Robot not connected");
+    }
+
+    const encoder = new TextEncoder();
+    const data = encoder.encode(command);
+    await this.writer.write(data);
+  }
+
+  /**
+   * Read data from robot with timeout
+   */
+  protected async readData(timeout: number = 5000): Promise<Uint8Array> {
+    if (!this.reader) {
+      throw new Error("Robot not connected");
+    }
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => reject(new Error("Read timeout")), timeout);
+    });
+
+    const readPromise = this.reader.read().then((result) => {
+      if (result.done) {
+        throw new Error("Stream closed");
+      }
+      return result.value;
+    });
+
+    return Promise.race([readPromise, timeoutPromise]);
+  }
+
+  /**
+   * Disable torque on disconnect (SO-100 specific)
+   */
+  protected async disableTorque(): Promise<void> {
+    try {
+      await this.sendCommand("TORQUE_DISABLE\r\n");
+    } catch (error) {
+      console.warn("Warning: Could not disable torque on disconnect");
+    }
+  }
+}

src/main.ts

@@ -2,203 +2,552 @@
  * lerobot.js Web Interface
  *
  * Browser-based interface for lerobot functionality
- * Provides the same find-port functionality as the CLI but in the browser
+ * Provides port connection and calibration functionality
  */
 
 import "./web_interface.css";
 import { findPortWeb } from "./lerobot/web/find_port.js";
+import {
+  calibrateWithPort,
+  isWebSerialSupported,
+} from "./lerobot/web/calibrate.js";
 
+// Extend SerialPort interface for missing methods
+declare global {
+  interface SerialPort {
+    getInfo(): { usbVendorId?: number; usbProductId?: number };
+  }
+}
+
+// Store connected ports with connection state
+let connectedPorts: { port: SerialPort; name: string; isConnected: boolean }[] =
+  [];
+
+// Store original console.log before override
+const originalConsoleLog = console.log;
+
+// Main application setup
 document.querySelector<HTMLDivElement>("#app")!.innerHTML = `
-  <div class="lerobot-app">
-    <header class="lerobot-header">
-      <h1>🤖 lerobot.js</h1>
-      <p>use your robot in the web & node with an api similar to LeRobot in python</p>
-    </header>
+  <div>
+    <h1>LeRobot.js Demo</h1>
+    <p>Web Serial API implementation for robot calibration and control</p>
+    
+    <div id="serial-support" class="status"></div>
     
-    <main class="lerobot-main">
-      <section class="tool-section">
-        <h2>🔍 Find USB Ports</h2>
-        <p>Identify which USB ports your robot arms are connected to</p>
-        <div class="button-group">
-          <button id="show-ports-btn" class="secondary-btn" style="display: none;">Show Available Ports</button>
-          <button id="manage-devices-btn" class="secondary-btn">Manage Devices</button>
-          <button id="find-port-btn" class="primary-btn">Find MotorsBus Port</button>
+    <div class="cards-container">
+      <!-- Port Connection Card -->
+      <div class="card">
+        <h2>🔌 Port Connection</h2>
+        <p>Connect to your robot arms to test communication</p>
+        
+        <div class="controls">
+          <button id="connect-port">Connect to Port</button>
+          <button id="find-ports">Find Available Ports</button>
+        </div>
+        
+        <div id="connected-ports">
+          <h3>Connected Ports:</h3>
+          <div id="ports-list">No ports connected</div>
         </div>
-        <div id="info-box" class="info-box" style="display: none;">
-          <span class="info-icon">💡</span>
-          <span class="info-text">Use "Manage Devices" to pair additional devices or "Find MotorsBus Port" to start detection.</span>
+        
+        <div id="find-ports-log"></div>
+      </div>
+
+      <!-- Robot Calibration Card -->
+      <div class="card">
+        <h2>🤖 Robot Calibration</h2>
+        <p>Calibrate your SO-100 robot arms</p>
+        
+        <div class="controls">
+          <div class="form-group">
+            <label for="arm-type">Arm Type:</label>
+            <select id="arm-type">
+              <option value="so100_follower">SO-100 Follower (Robot)</option>
+              <option value="so100_leader">SO-100 Leader (Teleoperator)</option>
+            </select>
+          </div>
+          
+          <div class="form-group">
+            <label for="port-select">Select Port:</label>
+            <select id="port-select">
+              <option value="">No ports connected</option>
+            </select>
+          </div>
+          
+          <div class="form-group">
+            <label for="arm-id">Arm ID:</label>
+            <input type="text" id="arm-id" placeholder="e.g., my_robot" value="demo_arm">
+          </div>
+          
+          <button id="start-calibration" disabled>Start Calibration</button>
         </div>
-        <div id="port-results" class="results-area"></div>
-      </section>
-      
-      <section class="info-section" id="compatibility-section" style="display: none;">
-        <h3>Browser Compatibility Issue</h3>
-        <p>Your browser doesn't support the <a href="https://web.dev/serial/" target="_blank">WebSerial API</a>. Please use:</p>
-        <ul>
-          <li>Chrome/Edge 89+ or Chrome Android 105+</li>
-          <li>HTTPS connection (or localhost for development)</li>
-        </ul>
-        <p>Alternatively, use the <strong>CLI version</strong>: <code>npx lerobot find-port</code></p>
-      </section>
-    </main>
+        
+        <div id="calibration-status"></div>
+      </div>
+    </div>
+    
+    <div id="log"></div>
   </div>
 `;
 
-// Set up button functionality
-const showPortsBtn =
-  document.querySelector<HTMLButtonElement>("#show-ports-btn")!;
-const manageDevicesBtn = document.querySelector<HTMLButtonElement>(
-  "#manage-devices-btn"
-)!;
-const findPortBtn =
-  document.querySelector<HTMLButtonElement>("#find-port-btn")!;
-const resultsArea = document.querySelector<HTMLDivElement>("#port-results")!;
-const infoBox = document.querySelector<HTMLDivElement>("#info-box")!;
+// Add CSS for cards
+const style = document.createElement("style");
+style.textContent = `
+  .cards-container {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 2rem;
+    margin: 2rem 0;
+  }
+  
+  .card {
+    border: 1px solid #ddd;
+    border-radius: 8px;
+    padding: 1.5rem;
+    background: #f9f9f9;
+  }
+  
+  .card h2 {
+    margin-top: 0;
+    color: #333;
+  }
+  
+  .form-group {
+    margin: 1rem 0;
+  }
+  
+  .form-group label {
+    display: block;
+    margin-bottom: 0.5rem;
+    font-weight: bold;
+  }
+  
+  .form-group select,
+  .form-group input {
+    width: 100%;
+    padding: 0.5rem;
+    border: 1px solid #ccc;
+    border-radius: 4px;
+    font-size: 1rem;
+  }
+  
+  .controls button {
+    margin: 0.5rem 0.5rem 0.5rem 0;
+  }
+  
+  #connected-ports {
+    margin: 1rem 0;
+    padding: 1rem;
+    background: white;
+    border-radius: 4px;
+  }
+  
+  .port-item {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 0.5rem;
+    margin: 0.5rem 0;
+    background: #e9f5ff;
+    border-radius: 4px;
+  }
+  
+  .port-item button {
+    background: #dc3545;
+    color: white;
+    border: none;
+    padding: 0.25rem 0.5rem;
+    border-radius: 3px;
+    cursor: pointer;
+    font-size: 0.875rem;
+    margin-left: 0.25rem;
+  }
+  
+  .port-buttons {
+    display: flex;
+    gap: 0.25rem;
+  }
+  
+  .port-buttons button:not(.unpair-btn) {
+    background: #007bff;
+  }
+  
+  .unpair-btn {
+    background: #dc3545 !important;
+  }
+`;
+document.head.appendChild(style);
 
-// Function to display paired devices
-async function displayPairedDevices() {
+// Initialize the application
+async function initializeApp() {
+  // Check Web Serial API support
+  const supportDiv = document.querySelector<HTMLDivElement>("#serial-support")!;
+  if (isWebSerialSupported()) {
+    supportDiv.innerHTML = `
+      <div class="success">✅ Web Serial API is supported in this browser</div>
+    `;
+
+    // Restore previously connected ports on page load
+    await restoreConnectedPorts();
+  } else {
+    supportDiv.innerHTML = `
+      <div class="error">❌ Web Serial API is not supported. Please use Chrome/Edge with experimental features enabled.</div>
+    `;
+  }
+}
+
+// Restore connected ports from browser's serial port list
+async function restoreConnectedPorts() {
   try {
-    // Check WebSerial support
-    if (!("serial" in navigator)) {
-      resultsArea.innerHTML =
-        '<p class="error">WebSerial API not supported. Please use Chrome/Edge 89+ with HTTPS or localhost.</p>';
-      infoBox.style.display = "none";
-      showPortsBtn.style.display = "inline-block";
-      return;
-    }
+    const existingPorts = await navigator.serial.getPorts();
+
+    for (const port of existingPorts) {
+      // Try to reconnect to previously permitted ports
+      let isConnected = false;
+      const portName = getPortDisplayName(port);
 
-    // Check what ports we already have access to
-    const ports = await navigator.serial.getPorts();
-
-    if (ports.length > 0) {
-      // We have paired devices, show them
-      resultsArea.innerHTML = `<p class="success">Found ${ports.length} paired device(s):</p>`;
-      ports.forEach((port, index) => {
-        const info = port.getInfo();
-        if (info.usbVendorId && info.usbProductId) {
-          resultsArea.innerHTML += `<p class="log">Port ${index + 1}: USB:${
-            info.usbVendorId
-          }:${info.usbProductId}</p>`;
-        } else {
-          resultsArea.innerHTML += `<p class="log">Port ${
-            index + 1
-          }: Serial device</p>`;
+      try {
+        // Check if port is already open, if not, open it
+        if (!port.readable || !port.writable) {
+          await port.open({ baudRate: 1000000 });
         }
-      });
+        isConnected = true;
+        originalConsoleLog(`Restored connection to: ${portName}`);
+      } catch (error) {
+        originalConsoleLog(`Could not reconnect to port ${portName}:`, error);
+        // Port might be in use by another application or disconnected
+        // But we still add it to the list so user can see it's paired
+      }
 
-      // Show the info box with guidance
-      infoBox.style.display = "flex";
+      connectedPorts.push({ port, name: portName, isConnected });
+    }
 
-      // Hide show ports button since we have devices
-      showPortsBtn.style.display = "none";
-    } else {
-      // No devices paired, show helpful message
-      resultsArea.innerHTML =
-        '<p class="log">No paired devices found. Click "Show Available Ports" to get started.</p>';
+    if (connectedPorts.length > 0) {
+      const connectedCount = connectedPorts.filter((p) => p.isConnected).length;
+      originalConsoleLog(
+        `Found ${connectedPorts.length} paired ports, ${connectedCount} connected`
+      );
+      updatePortsList();
+      updateCalibrationButton();
+    }
+  } catch (error) {
+    originalConsoleLog("Could not restore ports:", error);
+  }
+}
+
+// Get a meaningful display name for a port
+function getPortDisplayName(port: SerialPort): string {
+  // Use original console.log to avoid showing debug info in the page UI
+  originalConsoleLog("=== PORT DEBUG INFO ===");
+  originalConsoleLog("Full port object:", port);
+  originalConsoleLog("Port readable:", port.readable);
+  originalConsoleLog("Port writable:", port.writable);
+
+  try {
+    const info = port.getInfo();
+    originalConsoleLog("Port getInfo() result:", info);
+    originalConsoleLog("USB Vendor ID:", info.usbVendorId);
+    originalConsoleLog("USB Product ID:", info.usbProductId);
 
-      // Hide the info box since we don't have devices
-      infoBox.style.display = "none";
+    // Log all properties of the info object
+    originalConsoleLog("All info properties:");
+    for (const [key, value] of Object.entries(info)) {
+      originalConsoleLog(`  ${key}:`, value);
+    }
+
+    // Try to extract port name from port info
+    if (info.usbVendorId && info.usbProductId) {
+      return `USB Port (${info.usbVendorId}:${info.usbProductId})`;
+    }
 
-      // Show the show ports button since we need it
-      showPortsBtn.style.display = "inline-block";
+    // For Windows COM ports, we can't get the exact name from Web Serial API
+    // but we can show some identifying information
+    if (info.usbVendorId) {
+      return `Serial Port (VID:${info.usbVendorId.toString(16).toUpperCase()})`;
     }
   } catch (error) {
-    resultsArea.innerHTML += `<p class="error">Error checking devices: ${
-      error instanceof Error ? error.message : error
-    }</p>`;
-    infoBox.style.display = "none";
-    showPortsBtn.style.display = "inline-block";
+    // getInfo() might not be available in all browsers
+    originalConsoleLog("Port info not available:", error);
+  }
+
+  originalConsoleLog("=== END PORT DEBUG ===");
+
+  // Fallback to generic name with unique identifier
+  const portIndex = connectedPorts.length;
+  return `Serial Port ${portIndex + 1}`;
+}
+
+// Simple port connection functionality (restored)
+const connectPortBtn =
+  document.querySelector<HTMLButtonElement>("#connect-port")!;
+const portsListDiv = document.querySelector<HTMLDivElement>("#ports-list")!;
+
+connectPortBtn.addEventListener("click", async () => {
+  try {
+    connectPortBtn.disabled = true;
+    connectPortBtn.textContent = "Connecting...";
+
+    // Simple port connection dialog
+    const port = await navigator.serial.requestPort();
+    await port.open({ baudRate: 1000000 });
+
+    // Add to connected ports with meaningful name
+    const portName = getPortDisplayName(port);
+    connectedPorts.push({ port, name: portName, isConnected: true });
+
+    updatePortsList();
+    updateCalibrationButton();
+
+    connectPortBtn.textContent = "Connect to Port";
+  } catch (error) {
+    alert(
+      `Failed to connect to port: ${
+        error instanceof Error ? error.message : error
+      }`
+    );
+    connectPortBtn.textContent = "Connect to Port";
+  } finally {
+    connectPortBtn.disabled = false;
+  }
+});
+
+// Update connected ports display
+function updatePortsList() {
+  if (connectedPorts.length === 0) {
+    portsListDiv.innerHTML = "No ports paired";
+  } else {
+    portsListDiv.innerHTML = connectedPorts
+      .map(
+        (portInfo, index) => `
+      <div class="port-item">
+        <span>${portInfo.name} ${portInfo.isConnected ? "🟢" : "🔴"}</span>
+        <div class="port-buttons">
+          ${
+            portInfo.isConnected
+              ? `<button onclick="disconnectPort(${index})">Disconnect</button>`
+              : `<button onclick="reconnectPort(${index})">Connect</button>`
+          }
+          <button onclick="unpairPort(${index})" class="unpair-btn">Unpair</button>
+        </div>
+      </div>
+    `
+      )
+      .join("");
   }
+
+  // Update port selector dropdown (only show connected ports for calibration)
+  updatePortSelector();
 }
 
-// Check browser compatibility and show warning if needed
-function checkBrowserCompatibility() {
-  const compatibilitySection = document.querySelector(
-    "#compatibility-section"
-  ) as HTMLElement;
+// Update port selector dropdown
+function updatePortSelector() {
+  const portSelect = document.querySelector<HTMLSelectElement>("#port-select")!;
 
-  if (!("serial" in navigator)) {
-    // Browser doesn't support WebSerial API, show compatibility warning
-    compatibilitySection.style.display = "block";
+  const connectedOnly = connectedPorts.filter(
+    (portInfo) => portInfo.isConnected
+  );
+
+  if (connectedOnly.length === 0) {
+    portSelect.innerHTML = '<option value="">No ports connected</option>';
   } else {
-    // Browser supports WebSerial API, hide compatibility section
-    compatibilitySection.style.display = "none";
+    portSelect.innerHTML = connectedOnly
+      .map((portInfo, connectedIndex) => {
+        // Find the original index in the full connectedPorts array
+        const originalIndex = connectedPorts.findIndex((p) => p === portInfo);
+        return `<option value="${originalIndex}">${portInfo.name}</option>`;
+      })
+      .join("");
   }
 }
 
-// Check for paired devices and browser compatibility on page load
-checkBrowserCompatibility();
-displayPairedDevices();
+// Make port management functions global
+(window as any).disconnectPort = async (index: number) => {
+  try {
+    const portInfo = connectedPorts[index];
+    await portInfo.port.close();
+    connectedPorts[index].isConnected = false;
+    updatePortsList();
+    updateCalibrationButton();
+    originalConsoleLog(`Disconnected from ${portInfo.name}`);
+  } catch (error) {
+    console.error("Failed to disconnect port:", error);
+  }
+};
 
-// Show available ports button (only for when no devices are paired)
-showPortsBtn.addEventListener("click", async () => {
+(window as any).reconnectPort = async (index: number) => {
   try {
-    showPortsBtn.disabled = true;
-    showPortsBtn.textContent = "Pairing devices...";
-    resultsArea.innerHTML =
-      '<p class="status">Requesting permission to access serial ports...</p>';
-
-    try {
-      await navigator.serial.requestPort();
-      // Refresh the display
-      await displayPairedDevices();
-    } catch (permissionError) {
-      console.log("Permission dialog cancelled:", permissionError);
-    }
+    const portInfo = connectedPorts[index];
+    await portInfo.port.open({ baudRate: 1000000 });
+    connectedPorts[index].isConnected = true;
+    updatePortsList();
+    updateCalibrationButton();
+    originalConsoleLog(`Reconnected to ${portInfo.name}`);
   } catch (error) {
-    resultsArea.innerHTML += `<p class="error">Error: ${
-      error instanceof Error ? error.message : error
-    }</p>`;
-  } finally {
-    showPortsBtn.disabled = false;
-    showPortsBtn.textContent = "Show Available Ports";
+    console.error("Failed to reconnect to port:", error);
+    alert(
+      `Failed to reconnect: ${error instanceof Error ? error.message : error}`
+    );
   }
-});
+};
 
-// Manage devices button (always available)
-manageDevicesBtn.addEventListener("click", async () => {
+(window as any).unpairPort = async (index: number) => {
   try {
-    manageDevicesBtn.disabled = true;
-    manageDevicesBtn.textContent = "Managing...";
-
-    // Always show the permission dialog to pair new devices
-    try {
-      await navigator.serial.requestPort();
-      // Refresh the display to show updated device list
-      await displayPairedDevices();
-      resultsArea.innerHTML +=
-        '<p class="success">Device pairing completed. Updated device list above.</p>';
-    } catch (permissionError) {
-      console.log("Permission dialog cancelled:", permissionError);
+    const portInfo = connectedPorts[index];
+
+    // Close the port first if it's connected
+    if (portInfo.isConnected) {
+      await portInfo.port.close();
     }
+
+    // Try to forget the port (requires newer browsers)
+    if ("forget" in portInfo.port) {
+      await (portInfo.port as any).forget();
+      originalConsoleLog(`Unpaired ${portInfo.name}`);
+    } else {
+      // Fallback for browsers that don't support forget()
+      originalConsoleLog(
+        `Browser doesn't support forget() - manually revoke in browser settings`
+      );
+      alert(
+        "This browser doesn't support automatic unpairing. Please revoke access manually in browser settings (Privacy & Security > Site Settings > Serial Ports)"
+      );
+    }
+
+    // Remove from our list
+    connectedPorts.splice(index, 1);
+    updatePortsList();
+    updateCalibrationButton();
   } catch (error) {
-    resultsArea.innerHTML += `<p class="error">Error: ${
-      error instanceof Error ? error.message : error
-    }</p>`;
-  } finally {
-    manageDevicesBtn.disabled = false;
-    manageDevicesBtn.textContent = "Manage Devices";
-    resultsArea.scrollTop = resultsArea.scrollHeight;
+    console.error("Failed to unpair port:", error);
+    alert(
+      `Failed to unpair: ${error instanceof Error ? error.message : error}`
+    );
   }
-});
+};
+
+// Set up find ports functionality (restored original)
+const findPortsBtn = document.querySelector<HTMLButtonElement>("#find-ports")!;
+const findPortsLogDiv =
+  document.querySelector<HTMLDivElement>("#find-ports-log")!;
 
-// Find port button
-findPortBtn.addEventListener("click", async () => {
+findPortsBtn.addEventListener("click", async () => {
   try {
-    findPortBtn.disabled = true;
-    findPortBtn.textContent = "Finding ports...";
-    resultsArea.innerHTML = '<p class="status">Starting port detection...</p>';
+    findPortsBtn.disabled = true;
+    findPortsBtn.textContent = "Finding ports...";
 
+    // Clear previous results
+    findPortsLogDiv.innerHTML = '<div class="status">Finding ports...</div>';
+
+    // Use the web find port functionality
     await findPortWeb((message: string) => {
-      resultsArea.innerHTML += `<p class="log">${message}</p>`;
-      resultsArea.scrollTop = resultsArea.scrollHeight;
+      findPortsLogDiv.innerHTML += `<div class="log-entry">${message}</div>`;
     });
   } catch (error) {
-    resultsArea.innerHTML += `<p class="error">Error: ${
-      error instanceof Error ? error.message : error
-    }</p>`;
+    // Check if user cancelled the dialog
+    if (
+      error instanceof Error &&
+      (error.message.includes("cancelled") ||
+        error.message.includes("canceled") ||
+        error.name === "NotAllowedError" ||
+        error.name === "AbortError")
+    ) {
+      // User cancelled - just log it, no UI message
+      console.log("Find ports cancelled by user");
+    } else {
+      // Real error - show it
+      findPortsLogDiv.innerHTML = `
+        <div class="error">Error finding ports: ${
+          error instanceof Error ? error.message : error
+        }</div>
+      `;
+    }
   } finally {
-    findPortBtn.disabled = false;
-    findPortBtn.textContent = "Find MotorsBus Port";
+    findPortsBtn.disabled = false;
+    findPortsBtn.textContent = "Find Available Ports";
   }
 });
+
+// Calibration functionality
+const armTypeSelect = document.querySelector<HTMLSelectElement>("#arm-type")!;
+const portSelect = document.querySelector<HTMLSelectElement>("#port-select")!;
+const armIdInput = document.querySelector<HTMLInputElement>("#arm-id")!;
+const startCalibrationBtn =
+  document.querySelector<HTMLButtonElement>("#start-calibration")!;
+const calibrationStatusDiv = document.querySelector<HTMLDivElement>(
+  "#calibration-status"
+)!;
+
+function updateCalibrationButton() {
+  const hasConnectedPorts = connectedPorts.some((port) => port.isConnected);
+  startCalibrationBtn.disabled = !hasConnectedPorts;
+
+  if (!hasConnectedPorts) {
+    startCalibrationBtn.textContent = "Connect a port first";
+  } else {
+    startCalibrationBtn.textContent = "Start Calibration";
+  }
+}
+
+startCalibrationBtn.addEventListener("click", async () => {
+  try {
+    startCalibrationBtn.disabled = true;
+    startCalibrationBtn.textContent = "Calibrating...";
+    calibrationStatusDiv.innerHTML =
+      '<div class="status">Starting calibration...</div>';
+
+    const armType = armTypeSelect.value as "so100_follower" | "so100_leader";
+    const portIndexStr = portSelect.value;
+    const armId = armIdInput.value.trim() || "demo_arm";
+
+    // Validate port selection
+    if (portIndexStr === "" || connectedPorts.length === 0) {
+      throw new Error("No port selected");
+    }
+
+    const portIndex = parseInt(portIndexStr);
+    if (portIndex < 0 || portIndex >= connectedPorts.length) {
+      throw new Error("Invalid port selection");
+    }
+
+    const selectedPortInfo = connectedPorts[portIndex];
+    if (!selectedPortInfo.isConnected) {
+      throw new Error("Selected port is not connected");
+    }
+
+    const selectedPort = selectedPortInfo.port;
+    await calibrateWithPort(armType, armId, selectedPort);
+
+    calibrationStatusDiv.innerHTML =
+      '<div class="success">✅ Calibration completed successfully!</div>';
+    startCalibrationBtn.textContent = "Start Calibration";
+  } catch (error) {
+    calibrationStatusDiv.innerHTML = `
+      <div class="error">❌ Calibration failed: ${
+        error instanceof Error ? error.message : error
+      }</div>
+    `;
+    startCalibrationBtn.textContent = "Start Calibration";
+  } finally {
+    startCalibrationBtn.disabled = !connectedPorts.some(
+      (port) => port.isConnected
+    );
+  }
+});
+
+// Initialize
+updateCalibrationButton();
+
+// Initialize the application
+initializeApp();
+
+// Override console.log to show in the page
+const logDiv = document.querySelector<HTMLDivElement>("#log")!;
+console.log = (...args) => {
+  originalConsoleLog.apply(console, args);
+
+  const logEntry = document.createElement("div");
+  logEntry.className = "log-entry";
+  logEntry.textContent = args.join(" ");
+  logDiv.appendChild(logEntry);
+  logDiv.scrollTop = logDiv.scrollHeight;
+};