refactor: calibrate for web

docs/api-comparison.md

@@ -0,0 +1,194 @@
+# lerobot API Comparison: Python vs Node.js vs Web
+
+This document provides a comprehensive three-way comparison of lerobot APIs across Python lerobot (original), Node.js lerobot.js, and Web lerobot.js platforms.
+
+## 🔄 Core Function Comparison
+
+| Function Category  | Python lerobot (Original) | Node.js lerobot.js            | Web Browser lerobot.js                                 | Key Pattern                                            |
+| ------------------ | ------------------------- | ----------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
+| **Port Discovery** | `find_port()`             | `findPort()`                  | `findPortWeb(logger)`                                  | Python → Node.js: Direct port, Web: Requires UI logger |
+| **Robot Creation** | `SO100Follower(config)`   | `createSO100Follower(config)` | `createWebTeleoperationController(port, serialNumber)` | Python: Class, Node.js: Factory, Web: Pre-opened port  |
+| **Calibration**    | `calibrate(cfg)`          | `calibrate(config)`           | `createCalibrationController(armType, port)`           | Python/Node.js: Function, Web: Controller pattern      |
+| **Teleoperation**  | `teleoperate(cfg)`        | `teleoperate(config)`         | `createWebTeleoperationController(port, serialNumber)` | Python/Node.js: Function, Web: Manual state management |
+
+## 📋 Detailed API Reference
+
+### Port Discovery
+
+| Aspect               | Python lerobot                            | Node.js lerobot.js                           | Web Browser lerobot.js                         |
+| -------------------- | ----------------------------------------- | -------------------------------------------- | ---------------------------------------------- |
+| **Function**         | `find_port()`                             | `findPort()`                                 | `findPortWeb(logger)`                          |
+| **Import**           | `from lerobot.find_port import find_port` | `import { findPort } from 'lerobot.js/node'` | `import { findPortWeb } from 'lerobot.js/web'` |
+| **Parameters**       | None                                      | None                                         | `logger: (message: string) => void`            |
+| **User Interaction** | Terminal prompts via `input()`            | Terminal prompts via readline                | Browser modals and buttons                     |
+| **Port Access**      | Direct system access via pyserial         | Direct system access                         | Web Serial API permissions                     |
+| **Return Value**     | None (prints to console)                  | None (prints to console)                     | None (calls logger function)                   |
+| **Example**          | `python<br>find_port()<br>`               | `js<br>await findPort();<br>`                | `js<br>await findPortWeb(console.log);<br>`    |
+
+### Robot Connection & Creation
+
+| Aspect              | Python lerobot                                                                                                                     | Node.js lerobot.js                                                                                                                                   | Web Browser lerobot.js                                                                                                                                                                         |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Creation**        | `SO100Follower(config)` or `make_robot_from_config(config)`                                                                        | `createSO100Follower(config)`                                                                                                                        | `createWebTeleoperationController(port, serialNumber)`                                                                                                                                         |
+| **Connection**      | `robot.connect()`                                                                                                                  | `await robot.connect()`                                                                                                                              | Port already opened before creation                                                                                                                                                            |
+| **Port Parameter**  | `RobotConfig(port='/dev/ttyUSB0')`                                                                                                 | `{ port: 'COM4' }` (string)                                                                                                                          | `SerialPort` object                                                                                                                                                                            |
+| **Baud Rate**       | Handled internally                                                                                                                 | Handled internally                                                                                                                                   | `await port.open({ baudRate: 1000000 })`                                                                                                                                                       |
+| **Factory Pattern** | `make_robot_from_config()` factory                                                                                                 | `createSO100Follower()` factory                                                                                                                      | `createWebTeleoperationController()` factory                                                                                                                                                   |
+| **Example**         | `python<br>from lerobot.common.robots.so100_follower import SO100Follower<br>robot = SO100Follower(config)<br>robot.connect()<br>` | `js<br>const robot = createSO100Follower({<br>  type: 'so100_follower',<br>  port: 'COM4',<br>  id: 'my_robot'<br>});<br>await robot.connect();<br>` | `js<br>const port = await navigator.serial.requestPort();<br>await port.open({ baudRate: 1000000 });<br>const robot = await createWebTeleoperationController(<br>  port, 'my_robot'<br>);<br>` |
+
+### Calibration
+
+| Aspect              | Python lerobot                                                                                                                                                                                                                                       | Node.js lerobot.js                                                                                                                  | Web Browser lerobot.js                                                                                                                                                                                                                                              |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Main Function**   | `calibrate(cfg)`                                                                                                                                                                                                                                     | `calibrate(config)`                                                                                                                 | `createCalibrationController(armType, port)`                                                                                                                                                                                                                        |
+| **Import**          | `from lerobot.calibrate import calibrate`                                                                                                                                                                                                            | `import { calibrate } from 'lerobot.js/node'`                                                                                       | `import { createCalibrationController } from 'lerobot.js/web'`                                                                                                                                                                                                      |
+| **Configuration**   | `CalibrateConfig` dataclass                                                                                                                                                                                                                          | Single config object                                                                                                                | Controller with methods                                                                                                                                                                                                                                             |
+| **Workflow**        | All-in-one function calls `device.calibrate()`                                                                                                                                                                                                       | All-in-one function                                                                                                                 | Step-by-step methods                                                                                                                                                                                                                                                |
+| **Device Pattern**  | Creates device, calls `device.calibrate()`, `device.disconnect()`                                                                                                                                                                                    | Automatic within calibrate()                                                                                                        | Manual controller lifecycle                                                                                                                                                                                                                                         |
+| **Homing**          | Automatic within `device.calibrate()`                                                                                                                                                                                                                | Automatic within calibrate()                                                                                                        | `await controller.performHomingStep()`                                                                                                                                                                                                                              |
+| **Range Recording** | Automatic within `device.calibrate()`                                                                                                                                                                                                                | Automatic within calibrate()                                                                                                        | `await controller.performRangeRecordingStep()`                                                                                                                                                                                                                      |
+| **Completion**      | Automatic save and disconnect                                                                                                                                                                                                                        | Automatic save                                                                                                                      | `await controller.finishCalibration()`                                                                                                                                                                                                                              |
+| **Data Storage**    | File system (HF cache)                                                                                                                                                                                                                               | File system (HF cache)                                                                                                              | localStorage + file download                                                                                                                                                                                                                                        |
+| **Example**         | `python<br>from lerobot.calibrate import calibrate<br>from lerobot.common.robots.so100_follower import SO100FollowerConfig<br>calibrate(CalibrateConfig(<br>  robot=SO100FollowerConfig(<br>    port='/dev/ttyUSB0', id='my_robot'<br>  )<br>))<br>` | `js<br>await calibrate({<br>  robot: {<br>    type: 'so100_follower',<br>    port: 'COM4',<br>    id: 'my_robot'<br>  }<br>});<br>` | `js<br>const controller = await createCalibrationController(<br>  'so100_follower', port<br>);<br>await controller.performHomingStep();<br>await controller.performRangeRecordingStep(stopCondition);<br>const results = await controller.finishCalibration();<br>` |
+
+### Teleoperation
+
+| Aspect                | Python lerobot                                                                                                                                                                                              | Node.js lerobot.js                                                                                                                                                       | Web Browser lerobot.js                                                                                                                                                                                                                                               |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Main Function**     | `teleoperate(cfg)`                                                                                                                                                                                          | `teleoperate(config)`                                                                                                                                                    | `createWebTeleoperationController(port, serialNumber)`                                                                                                                                                                                                               |
+| **Import**            | `from lerobot.teleoperate import teleoperate`                                                                                                                                                               | `import { teleoperate } from 'lerobot.js/node'`                                                                                                                          | `import { createWebTeleoperationController } from 'lerobot.js/web'`                                                                                                                                                                                                  |
+| **Control Loop**      | `teleop_loop()` with `get_action()` and `send_action()`                                                                                                                                                     | Automatic 60 FPS loop                                                                                                                                                    | Manual start/stop with `controller.start()`                                                                                                                                                                                                                          |
+| **Device Management** | Creates teleop and robot devices, connects both                                                                                                                                                             | Device creation handled internally                                                                                                                                       | Port opened externally, controller manages state                                                                                                                                                                                                                     |
+| **Input Handling**    | Teleoperator `get_action()` method                                                                                                                                                                          | Terminal raw mode                                                                                                                                                        | Browser event listeners                                                                                                                                                                                                                                              |
+| **Key State**         | Handled by teleoperator device                                                                                                                                                                              | Internal management                                                                                                                                                      | `controller.updateKeyState(key, pressed)`                                                                                                                                                                                                                            |
+| **Configuration**     | `TeleoperateConfig` with separate robot/teleop configs                                                                                                                                                      | `js<br>{<br>  robot: { type, port, id },<br>  teleop: { type: 'keyboard' },<br>  fps: 60,<br>  step_size: 25<br>}<br>`                                                   | Built into controller                                                                                                                                                                                                                                                |
+| **Example**           | `python<br>from lerobot.teleoperate import teleoperate<br>teleoperate(TeleoperateConfig(<br>  robot=SO100FollowerConfig(port='/dev/ttyUSB0'),<br>  teleop=SO100LeaderConfig(port='/dev/ttyUSB1')<br>))<br>` | `js<br>await teleoperate({<br>  robot: {<br>    type: 'so100_follower',<br>    port: 'COM4',<br>    id: 'my_robot'<br>  },<br>  teleop: { type: 'keyboard' }<br>});<br>` | `js<br>const controller = await createWebTeleoperationController(<br>  port, 'my_robot'<br>);<br>controller.start();<br>// Handle keyboard events manually<br>document.addEventListener('keydown', (e) => {<br>  controller.updateKeyState(e.key, true);<br>});<br>` |
+
+### Motor Control
+
+| Aspect                 | Python lerobot                                                                                                                           | Node.js lerobot.js                                                                                                                                         | Web Browser lerobot.js                                                                                                                            |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Get Positions**      | `robot.get_observation()` (includes motor positions)                                                                                     | `await robot.getMotorPositions()`                                                                                                                          | `controller.getMotorConfigs()` or `controller.getState()`                                                                                         |
+| **Set Positions**      | `robot.send_action(action)` (dict format)                                                                                                | `await robot.setMotorPositions(positions)`                                                                                                                 | `await controller.setMotorPositions(positions)`                                                                                                   |
+| **Position Format**    | `dict[str, float]` (action format)                                                                                                       | `Record<string, number>`                                                                                                                                   | `Record<string, number>` ✅ Same                                                                                                                  |
+| **Data Flow**          | `get_observation()` → `send_action()` loop                                                                                               | Direct position get/set methods                                                                                                                            | Controller state management                                                                                                                       |
+| **Action Features**    | `robot.action_features` (motor names)                                                                                                    | Motor names hardcoded in implementation                                                                                                                    | Motor configs with metadata                                                                                                                       |
+| **Calibration Limits** | Handled in robot implementation                                                                                                          | `robot.getCalibrationLimits()`                                                                                                                             | `controller.getMotorConfigs()` (includes limits)                                                                                                  |
+| **Home Position**      | Manual via action dict                                                                                                                   | Manual calculation                                                                                                                                         | `await controller.goToHomePosition()`                                                                                                             |
+| **Example**            | `python<br>obs = robot.get_observation()<br>action = {motor: value for motor in robot.action_features}<br>robot.send_action(action)<br>` | `js<br>const positions = await robot.getMotorPositions();<br>await robot.setMotorPositions({<br>  shoulder_pan: 2047,<br>  shoulder_lift: 1800<br>});<br>` | `js<br>const state = controller.getState();<br>await controller.setMotorPositions({<br>  shoulder_pan: 2047,<br>  shoulder_lift: 1800<br>});<br>` |
+
+### Calibration Data Management
+
+| Aspect               | Node.js                                     | Web Browser                           |
+| -------------------- | ------------------------------------------- | ------------------------------------- |
+| **Storage Location** | `~/.cache/huggingface/lerobot/calibration/` | `localStorage` + file download        |
+| **File Format**      | JSON files on disk                          | JSON in browser storage               |
+| **Loading**          | Automatic during `robot.connect()`          | Manual via `loadCalibrationConfig()`  |
+| **Saving**           | `robot.saveCalibration(results)`            | `saveCalibrationResults()` + download |
+| **Persistence**      | Permanent until deleted                     | Browser-specific, can be cleared      |
+| **Sharing**          | File system sharing                         | Manual file sharing                   |
+
+### Error Handling & Debugging
+
+| Aspect                | Node.js                  | Web Browser                          |
+| --------------------- | ------------------------ | ------------------------------------ |
+| **Connection Errors** | Standard Node.js errors  | Web Serial API errors                |
+| **Permission Issues** | File system permissions  | User permission prompts              |
+| **Port Conflicts**    | "Port in use" errors     | Silent failures or permission errors |
+| **Debugging**         | Console.log + terminal   | Browser DevTools console             |
+| **Logging**           | Built-in terminal output | Passed logger functions              |
+
+## 🎯 Usage Pattern Summary
+
+### Python lerobot (Original) - Research & Production
+
+```python
+# Configuration-driven, device-based approach
+from lerobot.find_port import find_port
+from lerobot.calibrate import calibrate, CalibrateConfig
+from lerobot.teleoperate import teleoperate, TeleoperateConfig
+from lerobot.common.robots.so100_follower import SO100FollowerConfig
+from lerobot.common.teleoperators.so100_leader import SO100LeaderConfig
+
+# Find port
+find_port()
+
+# Calibrate robot
+calibrate(CalibrateConfig(
+    robot=SO100FollowerConfig(port='/dev/ttyUSB0', id='my_robot')
+))
+
+# Teleoperation with leader-follower
+teleoperate(TeleoperateConfig(
+    robot=SO100FollowerConfig(port='/dev/ttyUSB0'),
+    teleop=SO100LeaderConfig(port='/dev/ttyUSB1')
+))
+```
+
+### Node.js lerobot.js - Server/Desktop Applications
+
+```javascript
+// High-level, all-in-one functions (mirrors Python closely)
+import { findPort, calibrate, teleoperate } from "lerobot.js/node";
+
+await findPort();
+await calibrate({
+  robot: { type: "so100_follower", port: "COM4", id: "my_robot" },
+});
+await teleoperate({
+  robot: { type: "so100_follower", port: "COM4" },
+  teleop: { type: "keyboard" },
+});
+```
+
+### Web Browser lerobot.js - Interactive Applications
+
+```javascript
+// Controller-based, step-by-step approach (browser constraints)
+import {
+  findPortWeb,
+  createCalibrationController,
+  createWebTeleoperationController,
+} from "lerobot.js/web";
+
+// User interaction required
+const port = await navigator.serial.requestPort();
+await port.open({ baudRate: 1000000 });
+
+// Step-by-step calibration
+const calibrator = await createCalibrationController("so100_follower", port);
+await calibrator.performHomingStep();
+await calibrator.performRangeRecordingStep(() => stopRecording);
+
+// Manual teleoperation control
+const controller = await createWebTeleoperationController(port, "my_robot");
+controller.start();
+```
+
+## 🔑 Key Architectural Differences
+
+1. **User Interaction Model**
+
+   - **Node.js**: Terminal-based with readline prompts
+   - **Web**: Browser UI with buttons and modals
+
+2. **Permission Model**
+
+   - **Node.js**: System-level permissions
+   - **Web**: User-granted permissions per device
+
+3. **State Management**
+
+   - **Node.js**: Function-based, stateless
+   - **Web**: Controller-based, stateful
+
+4. **Data Persistence**
+
+   - **Node.js**: File system with cross-session persistence
+   - **Web**: Browser storage with limited persistence
+
+5. **Platform Integration**
+   - **Node.js**: Deep system integration
+   - **Web**: Security-constrained browser environment
+
+This comparison helps developers choose the right platform and understand the API differences when porting between Node.js and Web implementations.

docs/planning/005_same_api.md

@@ -0,0 +1,447 @@
+# User Story 005: Building Block API - Clean, Composable, Unified
+
+## 🎯 Goal
+
+Create a clean building block API across Python lerobot, Node.js lerobot.js, and Web lerobot.js where users manage state and workflow while we abstract away robotics complexity. Users learn core concepts once and apply them everywhere.
+
+## 🚨 Problem Statement
+
+Currently, the APIs have fundamentally different approaches:
+
+### Current Inconsistencies
+
+1. **State Management**:
+   - Python/Node.js: Functions handle connection lifecycle internally
+   - Web: User must manually manage controllers and connections
+2. **Complexity Exposure**:
+   - Python/Node.js: `calibrate(config)` - single call does everything
+   - Web: Multi-step `controller.performHomingStep()`, `controller.moveToPosition()`, etc.
+3. **Resource Management**:
+   - Python/Node.js: Each function connects/disconnects automatically
+   - Web: User manages port lifecycle manually
+4. **Device Identification**:
+   - Node.js: Port discovery finds system ports by name (COM4, /dev/ttyUSB0)
+   - Web: No device identification - WebSerial can't distinguish between identical devices
+
+### User Pain Points
+
+- **Different Mental Models**: Same operations require different approaches per platform
+- **Web Complexity Exposure**: Users must understand servo protocols and multi-step procedures
+- **Inconsistent Resource Management**: Some platforms auto-manage, others don't
+- **Device Identification Issues**: Web can't identify which physical robot is connected
+- **Hidden State Problems**: Users can't control when connections happen or track device status
+
+## 🎯 Success Criteria
+
+### Primary Goal: Building Block Consistency
+
+- [ ] **Same Operation Patterns**: All platforms use identical patterns for core operations
+- [ ] **Clean Responsibility Split**: Users manage state/UI, library handles robotics
+- [ ] **Self-Contained Operations**: Each function manages its own connection lifecycle
+- [ ] **Unified Control Model**: Long-running operations use same session-based control
+
+### Secondary Goal: Platform-Appropriate Implementation
+
+- [ ] **Smart Device Pairing**: Web uses WebUSB + WebSerial for device identification + communication
+- [ ] **Hidden Robotics Complexity**: Baud rates, protocols, servo commands abstracted away
+- [ ] **Graceful Resource Management**: Automatic connection cleanup with user control
+- [ ] **Consistent Error Handling**: Platform-specific errors mapped to common patterns
+
+## 📋 Ground Truth Decisions
+
+### 1. Building Block Philosophy
+
+**DECIDED: User manages state, we provide clean tools**
+
+✅ **User Responsibilities:**
+
+- Device pairing and storage (when to pair, how to persist)
+- UI workflow (when to show dialogs, how to display progress)
+- State management (which devices they have, tracking connections)
+- Error handling UI (how to display errors to end users)
+
+✅ **Library Responsibilities:**
+
+- WebUSB + WebSerial pairing dialogs (native browser interactions)
+- Baud rate configuration (1000000 for SO-100)
+- STS3215 servo protocol implementation
+- Calibration and teleoperation procedures
+- Resource conflict prevention with clear error messages
+
+### 2. Device Pairing vs Connection Pattern
+
+**DECIDED: Separate pairing (once) from connection (per operation)**
+
+```javascript
+// PAIRING: One-time device identification (stores device reference)
+const deviceInfo = await lerobot.pairDevice();
+// User stores this: localStorage, state management, etc.
+
+// OPERATIONS: Each function connects internally using device reference
+const session = await lerobot.calibrate({ robot: { device: deviceInfo } });
+await session.stop(); // Graceful disconnect
+
+const session2 = await lerobot.teleoperate({ robot: { device: deviceInfo } });
+await session2.stop(); // Independent connection lifecycle
+```
+
+**Web Implementation Details:**
+
+- `pairDevice()` shows WebUSB dialog → gets device info → shows WebSerial dialog → extracts serial ID
+- Each operation connects to paired device internally (no singleton state)
+- Users never see servo protocols, baud rates, or connection management
+
+### 3. Connection Lifecycle Pattern
+
+**DECIDED: Each operation is self-contained (like Python/Node.js)**
+
+```javascript
+// PYTHON/NODE.JS CURRENT PATTERN (keep this):
+await calibrate(config); // Internally: connect → calibrate → disconnect
+await teleoperate(config); // Internally: connect → teleoperate → disconnect
+
+// WEB NEW PATTERN (match Python/Node.js):
+const cal = await calibrate({ robot: { device: pairedDevice } }); // connect → start calibration
+await cal.stop(); // disconnect
+
+const tel = await teleoperate({ robot: { device: pairedDevice } }); // connect → start teleoperation
+await tel.stop(); // disconnect
+```
+
+**Key Principle:** No shared connections, no singletons, each operation manages its own lifecycle.
+
+### 4. Long-Running Operation Control
+
+**DECIDED: Both calibrate and teleoperate are long-running until user stops**
+
+```javascript
+// UNIFIED SESSION PATTERN for both operations:
+interface RobotSession {
+  stop(): Promise<void>; // Graceful shutdown + disconnect
+  getState(): SessionState; // Current operation state
+}
+
+// Both operations return controllable sessions:
+const calibration = await lerobot.calibrate({
+  robot: { device: myDevice },
+  onStateChange: (state) => updateUI(state),
+});
+
+const teleoperation = await lerobot.teleoperate({
+  robot: { device: myDevice },
+  onStateChange: (state) => updateUI(state),
+});
+
+// Same control pattern for both:
+await calibration.stop();
+await teleoperation.stop();
+```
+
+**Calibrate Reality Check:**
+
+- Starts calibration procedure
+- Waits for user to move robot through ranges
+- Records positions until user decides to stop
+- Can run indefinitely like teleoperate
+
+### 5. Web Device Identification Solution
+
+**DECIDED: WebUSB + WebSerial both required**
+
+```javascript
+// Why both APIs are needed:
+// 1. WebUSB: Get device serial number → "This is robot arm #ABC123"
+// 2. WebSerial: Actual communication → Send servo commands
+
+async function pairDevice(): Promise<DeviceInfo> {
+  // Step 1: WebUSB for device identification
+  const usbDevice = await navigator.usb.requestDevice({...});
+  const serialId = extractSerialNumber(usbDevice);
+
+  // Step 2: WebSerial for communication
+  const serialPort = await navigator.serial.requestPort();
+  await serialPort.open({ baudRate: 1000000 }); // We handle baud rate
+
+  return {
+    serialId,
+    usbDevice,
+    serialPort,
+    type: detectRobotType(usbDevice) // We detect SO-100 vs other robots
+  };
+}
+```
+
+## 🛠️ Implementation Architecture
+
+### Core Building Blocks
+
+```javascript
+// DEVICE PAIRING (Web-specific, one-time)
+export async function pairDevice(): Promise<DeviceInfo>
+
+// UNIFIED OPERATIONS (Same across all platforms)
+export async function calibrate(config: CalibrationConfig): Promise<CalibrationSession>
+export async function teleoperate(config: TeleoperationConfig): Promise<TeleoperationSession>
+
+// UNIFIED SESSION CONTROL
+interface RobotSession {
+  stop(): Promise<void>
+  getState(): SessionState
+}
+```
+
+### Platform-Specific Implementation
+
+**Node.js (No changes needed - already correct pattern):**
+
+```javascript
+// Each function connects/disconnects internally - keep as-is
+export async function calibrate(config) {
+  const device = createDevice(config.robot);
+  await device.connect();
+  // ... calibration work
+  await device.disconnect();
+}
+```
+
+**Web (New unified wrapper):**
+
+```javascript
+// Hide controller complexity behind unified interface
+export async function calibrate(config) {
+  let connection = null;
+  try {
+    connection = await connectToDevice(config.robot.device); // We handle WebSerial setup
+    const session = new CalibrationSession(connection, config);
+    return session; // User controls session lifecycle
+  } catch (error) {
+    if (connection) await connection.disconnect();
+    throw error;
+  }
+}
+```
+
+## 📋 Detailed API Specification
+
+### 1. Device Pairing API (Web Only)
+
+```javascript
+// Web-specific device pairing
+interface DeviceInfo {
+  serialId: string;        // From WebUSB device descriptor
+  robotType: 'so100_follower' | 'so100_leader';
+  usbVendorId: number;
+  usbProductId: number;
+  // Internal connection details (user doesn't need to know)
+}
+
+export async function pairDevice(): Promise<DeviceInfo>
+```
+
+**User Workflow:**
+
+1. Call `pairDevice()` → Native browser dialogs appear
+2. Store `DeviceInfo` in their state management
+3. Use stored device for all subsequent operations
+
+### 2. Unified Calibration API
+
+```javascript
+interface CalibrationConfig {
+  robot: {
+    device: DeviceInfo;     // Web: paired device, Node.js: { type, port }
+  };
+  onStateChange?: (state: 'connecting' | 'connected' | 'active' | 'stopping' | 'stopped') => void;
+  onProgress?: (progress: CalibrationProgress) => void;
+}
+
+interface CalibrationSession extends RobotSession {
+  stop(): Promise<CalibrationResults>;  // Returns calibration data
+}
+
+// SAME across all platforms:
+export async function calibrate(config: CalibrationConfig): Promise<CalibrationSession>
+```
+
+### 3. Unified Teleoperation API
+
+```javascript
+interface TeleoperationConfig {
+  robot: {
+    device: DeviceInfo;     // Web: paired device, Node.js: { type, port }
+  };
+  controls?: {
+    [key: string]: ControlMapping;
+  };
+  onStateChange?: (state: SessionState) => void;
+}
+
+interface TeleoperationSession extends RobotSession {
+  updateKeyState(key: string, pressed: boolean): void; // For keyboard control
+  getCurrentPositions(): Promise<Record<string, number>>;
+}
+
+// SAME across all platforms:
+export async function teleoperate(config: TeleoperationConfig): Promise<TeleoperationSession>
+```
+
+### 4. Error Handling
+
+```javascript
+// Standard error types across platforms
+class DeviceNotPairedError extends Error {}
+class DeviceConnectionError extends Error {}
+class DeviceAlreadyConnectedError extends Error {}
+class CalibrationError extends Error {}
+class TeleoperationError extends Error {}
+
+// Platform-specific errors mapped to standard types
+// Web: WebSerial/WebUSB errors → DeviceConnectionError
+// Node.js: SerialPort errors → DeviceConnectionError
+```
+
+## 🔄 User Experience Flows
+
+### First-Time Web User
+
+```javascript
+// 1. Pair device once (shows native browser dialogs)
+const myRobot = await lerobot.pairDevice();
+localStorage.setItem("myRobot", JSON.stringify(myRobot));
+
+// 2. Use paired device for operations
+const calibration = await lerobot.calibrate({
+  robot: { device: myRobot },
+  onStateChange: (state) => updateStatus(state),
+});
+
+// 3. User controls session
+await calibration.stop();
+```
+
+### Returning Web User
+
+```javascript
+// 1. Load stored device (no browser dialogs)
+const myRobot = JSON.parse(localStorage.getItem("myRobot"));
+
+// 2. Operations work immediately (connect internally)
+const teleoperation = await lerobot.teleoperate({
+  robot: { device: myRobot },
+  onStateChange: (state) => updateStatus(state),
+});
+```
+
+### Node.js User (Unchanged)
+
+```javascript
+// Same as current - no changes needed
+const calibration = await lerobot.calibrate({
+  robot: { type: "so100_follower", port: "COM4" },
+});
+await calibration.stop();
+```
+
+## 🧪 Implementation Phases
+
+### Phase 1: Core Building Blocks
+
+- [ ] Define unified interfaces (`RobotSession`, `DeviceInfo`)
+- [ ] Implement Web `pairDevice()` with WebUSB + WebSerial
+- [ ] Create session-based wrappers for Web calibration/teleoperation
+- [ ] Standardize error types and mapping
+
+### Phase 2: API Unification
+
+- [ ] Ensure Node.js returns session objects (minimal changes)
+- [ ] Web operations return sessions that hide controller complexity
+- [ ] Unified state change callbacks and progress reporting
+- [ ] Cross-platform testing with real hardware
+
+### Phase 3: Developer Experience
+
+- [ ] Update examples to use building block pattern
+- [ ] Create migration guide from current APIs
+- [ ] Unified documentation with platform-specific notes
+- [ ] Performance optimization and bundle size analysis
+
+## 📊 Success Metrics
+
+### Developer Experience
+
+- [ ] **Single Learning Curve**: Core concepts (pairing, sessions, operations) work everywhere
+- [ ] **User Control**: Developers control state, UI, and workflow completely
+- [ ] **Platform Abstraction**: Robotics complexity hidden, platform differences minimal
+
+### Technical Quality
+
+- [ ] **Resource Management**: No connection leaks, graceful cleanup
+- [ ] **Error Handling**: Clear, actionable errors with consistent types
+- [ ] **Performance**: No regressions, efficient resource usage
+
+### API Consistency
+
+- [ ] **Same Patterns**: Operations, sessions, and control work identically
+- [ ] **Platform Appropriate**: Each platform uses native capabilities optimally
+- [ ] **Migration Path**: Existing code can adopt new patterns incrementally
+
+## 🔍 Edge Cases & Considerations
+
+### Multiple Device Management
+
+```javascript
+// User manages multiple devices
+const robot1 = await lerobot.pairDevice(); // First robot
+const robot2 = await lerobot.pairDevice(); // Second robot
+
+// Independent sessions
+const cal1 = await lerobot.calibrate({ robot: { device: robot1 } });
+const tel2 = await lerobot.teleoperate({ robot: { device: robot2 } });
+```
+
+### Resource Conflicts
+
+```javascript
+// Library prevents conflicts with clear errors
+const session1 = await lerobot.calibrate({ robot: { device: myRobot } });
+
+try {
+  const session2 = await lerobot.teleoperate({ robot: { device: myRobot } });
+} catch (error) {
+  if (error instanceof DeviceAlreadyConnectedError) {
+    // User gets clear message: "Device already in use by calibration. Stop calibration first."
+    await session1.stop();
+    const session2 = await lerobot.teleoperate({ robot: { device: myRobot } });
+  }
+}
+```
+
+### Browser Tab Management
+
+```javascript
+// Sessions automatically cleanup on page unload
+window.addEventListener("beforeunload", async () => {
+  if (currentSession) {
+    await currentSession.stop(); // Graceful disconnect
+  }
+});
+```
+
+## 📝 Definition of Done
+
+- [ ] **Web Pairing**: `pairDevice()` uses WebUSB + WebSerial to identify and store device info
+- [ ] **Session Control**: Both `calibrate()` and `teleoperate()` return controllable sessions
+- [ ] **Self-Contained Operations**: Each operation connects/disconnects internally, no shared state
+- [ ] **Unified Error Handling**: Platform-specific errors mapped to consistent error types
+- [ ] **Resource Management**: Clear error messages for conflicts, automatic cleanup
+- [ ] **Documentation**: Single API reference with platform-specific implementation notes
+- [ ] **Migration Path**: Existing users can adopt new patterns without breaking changes
+- [ ] **Hardware Validation**: Tested with real SO-100 hardware on all platforms
+
+---
+
+**Priority**: 🔴 Critical - Blocks adoption due to API inconsistency
+**Effort**: 🔥🔥🔥 High - Significant Web refactoring, but Node.js mostly unchanged
+**Impact**: 🚀🚀🚀 Transformative - Enables true cross-platform development
+
+**Impact**: 🚀🚀🚀 Very High - Transforms user experience and enables widespread adoption

src/demo/App.tsx

@@ -1,10 +1,10 @@
 import React, { useState } from "react";
 import { Home } from "./pages/Home";
 import { ErrorBoundary } from "./components/ErrorBoundary";
-import type { ConnectedRobot } from "./types";
+import type { RobotConnection } from "../lerobot/web/find_port.js";
 
 export function App() {
-  const [connectedRobots, setConnectedRobots] = useState<ConnectedRobot[]>([]);
+  const [connectedRobots, setConnectedRobots] = useState<RobotConnection[]>([]);
 
   return (
     <ErrorBoundary>

src/demo/components/CalibrationPanel.tsx

@@ -1,10 +1,4 @@
-import React, {
-  useState,
-  useEffect,
-  useCallback,
-  useRef,
-  useMemo,
-} from "react";
+import React, { useState, useCallback, useMemo } from "react";
 import { Button } from "./ui/button";
 import {
   Card,
@@ -15,45 +9,35 @@ import {
 } from "./ui/card";
 import { Badge } from "./ui/badge";
 import {
-  createCalibrationController,
-  WebCalibrationController,
-  saveCalibrationResults,
+  calibrate,
   type WebCalibrationResults,
+  type LiveCalibrationData,
+  type CalibrationProcess,
 } from "../../lerobot/web/calibrate";
+import { releaseMotors } from "../../lerobot/web/utils/motor-communication.js";
+import { WebSerialPortWrapper } from "../../lerobot/web/utils/serial-port-wrapper.js";
+import { createSO100Config } from "../../lerobot/web/robots/so100_config.js";
 import { CalibrationModal } from "./CalibrationModal";
-import type { ConnectedRobot } from "../types";
+import type { RobotConnection } from "../../lerobot/web/find_port.js";
 
 interface CalibrationPanelProps {
-  robot: ConnectedRobot;
+  robot: RobotConnection;
   onFinish: () => void;
 }
 
-interface MotorCalibrationData {
-  name: string;
-  current: number;
-  min: number;
-  max: number;
-  range: number;
-}
-
-/**
- * Custom hook for calibration that manages the serial port properly
- * Uses vanilla calibration functions internally, provides React-friendly interface
- */
-function useCalibration(robot: ConnectedRobot) {
-  const [controller, setController] = useState<WebCalibrationController | null>(
-    null
-  );
+export function CalibrationPanel({ robot, onFinish }: CalibrationPanelProps) {
+  // Simple state management
   const [isCalibrating, setIsCalibrating] = useState(false);
-  const [isRecordingRanges, setIsRecordingRanges] = useState(false);
   const [calibrationResult, setCalibrationResult] =
     useState<WebCalibrationResults | null>(null);
   const [status, setStatus] = useState<string>("Ready to calibrate");
+  const [modalOpen, setModalOpen] = useState(false);
+  const [calibrationProcess, setCalibrationProcess] =
+    useState<CalibrationProcess | null>(null);
+  const [motorData, setMotorData] = useState<LiveCalibrationData>({});
+  const [isPreparing, setIsPreparing] = useState(false);
 
-  // Motor data state
-  const [motorData, setMotorData] = useState<MotorCalibrationData[]>([]);
-
-  // Static motor names - use useMemo to prevent recreation on every render
+  // Motor names for display
   const motorNames = useMemo(
     () => [
       "shoulder_pan",
@@ -66,268 +50,49 @@ function useCalibration(robot: ConnectedRobot) {
     []
   );
 
-  // Initialize controller when robot changes
-  const initializeController = useCallback(async () => {
-    if (!robot.port || !robot.robotType) {
-      throw new Error("Invalid robot configuration");
-    }
-
-    const newController = await createCalibrationController(
-      robot.robotType,
-      robot.port
-    );
-    setController(newController);
-    return newController;
-  }, [robot.port, robot.robotType]);
-
-  // Read motor positions using the controller (no concurrent access)
-  const readMotorPositions = useCallback(async (): Promise<number[]> => {
-    if (!controller) {
-      throw new Error("Controller not initialized");
-    }
-    return await controller.readMotorPositions();
-  }, [controller]);
-
-  // Update motor data from positions
-  const updateMotorData = useCallback(
-    (
-      positions: number[],
-      rangeMins?: { [motor: string]: number },
-      rangeMaxes?: { [motor: string]: number }
-    ) => {
-      const newData = motorNames.map((name, index) => {
-        const current = positions[index];
-        const min = rangeMins ? rangeMins[name] : current;
-        const max = rangeMaxes ? rangeMaxes[name] : current;
-
-        return {
-          name,
-          current,
-          min,
-          max,
-          range: max - min,
-        };
-      });
-
-      setMotorData(newData);
-    },
-    [motorNames]
-  );
-
   // Initialize motor data
   const initializeMotorData = useCallback(() => {
-    const initialData = motorNames.map((name) => ({
-      name,
-      current: 2047,
-      min: 2047,
-      max: 2047,
-      range: 0,
-    }));
+    const initialData: LiveCalibrationData = {};
+    motorNames.forEach((name) => {
+      initialData[name] = {
+        current: 2047,
+        min: 2047,
+        max: 2047,
+        range: 0,
+      };
+    });
     setMotorData(initialData);
   }, [motorNames]);
 
-  // Start calibration process
-  const startCalibration = useCallback(async () => {
+  // Release motor torque for better UX - allows immediate joint movement
+  const releaseMotorTorque = useCallback(async () => {
+    if (!robot.port || !robot.robotType) {
+      return;
+    }
+
     try {
-      setStatus("🤖 Starting calibration process...");
-      setIsCalibrating(true);
+      setIsPreparing(true);
+      setStatus("🔓 Releasing motor torque - joints can now be moved freely");
 
-      const ctrl = await initializeController();
+      // Create port wrapper and config to get motor IDs
+      const port = new WebSerialPortWrapper(robot.port);
+      await port.initialize();
+      const config = createSO100Config(robot.robotType);
 
-      // Step 1: Homing
-      setStatus("📍 Setting homing position...");
-      await ctrl.performHomingStep();
+      // Release motors so they can be moved freely by hand
+      await releaseMotors(port, config.motorIds);
 
-      return ctrl;
+      setStatus("✅ Joints are now free to move - set your homing position");
     } catch (error) {
-      setIsCalibrating(false);
-      throw error;
+      console.warn("Failed to release motor torque:", error);
+      setStatus("⚠️ Could not release motor torque - try moving joints gently");
+    } finally {
+      setIsPreparing(false);
     }
-  }, [initializeController]);
-
-  // Start range recording
-  const startRangeRecording = useCallback(
-    async (
-      controllerToUse: WebCalibrationController,
-      stopFunction: () => boolean,
-      onUpdate?: (
-        mins: { [motor: string]: number },
-        maxes: { [motor: string]: number },
-        currentPositions: { [motor: string]: number }
-      ) => void
-    ) => {
-      if (!controllerToUse) {
-        throw new Error("Controller not provided");
-      }
-
-      setStatus(
-        "📏 Recording joint ranges - move all joints through their full range"
-      );
-      setIsRecordingRanges(true);
-
-      try {
-        await controllerToUse.performRangeRecordingStep(
-          stopFunction,
-          (rangeMins, rangeMaxes, currentPositions) => {
-            setStatus("📏 Recording joint ranges - capturing data...");
-
-            // Update motor data with CURRENT LIVE POSITIONS (not averages!)
-            const currentPositionsArray = motorNames.map(
-              (name) => currentPositions[name]
-            );
-            updateMotorData(currentPositionsArray, rangeMins, rangeMaxes);
-
-            if (onUpdate) {
-              onUpdate(rangeMins, rangeMaxes, currentPositions);
-            }
-          }
-        );
-      } finally {
-        setIsRecordingRanges(false);
-      }
-    },
-    [motorNames, updateMotorData]
-  );
-
-  // Finish calibration
-  const finishCalibration = useCallback(
-    async (
-      controllerToUse?: WebCalibrationController,
-      recordingCount?: number
-    ) => {
-      const ctrl = controllerToUse || controller;
-      if (!ctrl) {
-        throw new Error("Controller not initialized");
-      }
-
-      setStatus("💾 Finishing calibration...");
-      const result = await ctrl.finishCalibration();
-      setCalibrationResult(result);
-
-      // Save results using serial number for dashboard detection
-      // Use the same serial number logic as dashboard: prefer main serialNumber, fallback to USB metadata, then "unknown"
-      const serialNumber =
-        robot.serialNumber || robot.usbMetadata?.serialNumber || "unknown";
-
-      console.log("🔍 Debug - Saving calibration with:", {
-        robotType: robot.robotType,
-        robotId: robot.robotId,
-        mainSerialNumber: robot.serialNumber,
-        usbSerialNumber: robot.usbMetadata?.serialNumber,
-        finalSerialNumber: serialNumber,
-        storageKey: `lerobotjs-${serialNumber}`,
-      });
-
-      await saveCalibrationResults(
-        result,
-        robot.robotType!,
-        robot.robotId || `${robot.robotType}_1`,
-        serialNumber,
-        recordingCount || 0
-      );
-
-      // Update final motor data
-      const finalData = motorNames.map((motorName) => {
-        const motorResult = result[motorName];
-        return {
-          name: motorName,
-          current: (motorResult.range_min + motorResult.range_max) / 2,
-          min: motorResult.range_min,
-          max: motorResult.range_max,
-          range: motorResult.range_max - motorResult.range_min,
-        };
-      });
+  }, [robot]);
 
-      setMotorData(finalData);
-      setStatus("✅ Calibration completed successfully! Configuration saved.");
-      setIsCalibrating(false);
-
-      return result;
-    },
-    [controller, robot.robotType, robot.robotId, motorNames]
-  );
-
-  // Reset states
-  const reset = useCallback(() => {
-    setController(null);
-    setIsCalibrating(false);
-    setIsRecordingRanges(false);
-    setCalibrationResult(null);
-    setStatus("Ready to calibrate");
-    initializeMotorData();
-  }, [initializeMotorData]);
-
-  // Initialize on mount
-  useEffect(() => {
-    initializeMotorData();
-  }, [initializeMotorData]);
-
-  return {
-    // State
-    controller,
-    isCalibrating,
-    isRecordingRanges,
-    calibrationResult,
-    status,
-    motorData,
-
-    // Actions
-    startCalibration,
-    startRangeRecording,
-    finishCalibration,
-    readMotorPositions,
-    reset,
-
-    // Utilities
-    updateMotorData,
-  };
-}
-
-export function CalibrationPanel({ robot, onFinish }: CalibrationPanelProps) {
-  const {
-    controller,
-    isCalibrating,
-    isRecordingRanges,
-    calibrationResult,
-    status,
-    motorData,
-    startCalibration,
-    startRangeRecording,
-    finishCalibration,
-    readMotorPositions,
-    reset,
-    updateMotorData,
-  } = useCalibration(robot);
-
-  // Modal state
-  const [modalOpen, setModalOpen] = useState(false);
-
-  // Recording state
-  const [stopRecordingFunction, setStopRecordingFunction] = useState<
-    (() => void) | null
-  >(null);
-
-  // Motor names matching Python lerobot exactly (NOT Node CLI)
-  const motorNames = [
-    "shoulder_pan",
-    "shoulder_lift",
-    "elbow_flex",
-    "wrist_flex",
-    "wrist_roll",
-    "gripper",
-  ];
-
-  // Motor IDs for SO-100 (STS3215 servos)
-  const motorIds = [1, 2, 3, 4, 5, 6];
-
-  // Keep track of last known good positions to avoid glitches
-  const lastKnownPositions = useRef<number[]>([
-    2047, 2047, 2047, 2047, 2047, 2047,
-  ]);
-
-  // NO concurrent motor reading - let the calibration hook handle all serial operations
-
-  const handleContinueCalibration = async () => {
+  // Start calibration using new API
+  const handleContinueCalibration = useCallback(async () => {
     setModalOpen(false);
 
     if (!robot.port || !robot.robotType) {
@@ -335,76 +100,119 @@ export function CalibrationPanel({ robot, onFinish }: CalibrationPanelProps) {
     }
 
     try {
-      const ctrl = await startCalibration();
-
-      // Set up manual control - user decides when to stop
-      let shouldStopRecording = false;
-      let recordingCount = 0;
+      setStatus("🤖 Starting calibration process...");
+      setIsCalibrating(true);
+      initializeMotorData();
+
+      // Use the new unified calibrate API - pass the whole robot connection
+      const robotConnection = {
+        port: robot.port,
+        robotType: robot.robotType!,
+        robotId: robot.robotId || `${robot.robotType}_1`,
+        serialNumber: robot.serialNumber || `unknown_${Date.now()}`,
+        connected: robot.isConnected,
+      } as any; // Type assertion to work around SerialPort type differences
+
+      const process = await calibrate(robotConnection, {
+        onLiveUpdate: (data) => {
+          setMotorData(data);
+          setStatus(
+            "📏 Recording joint ranges - move all joints through their full range"
+          );
+        },
+        onProgress: (message) => {
+          setStatus(message);
+        },
+      });
 
-      // Create stop function and store it in state for the button
-      const stopRecording = () => {
-        shouldStopRecording = true;
-      };
-      setStopRecordingFunction(() => stopRecording);
+      setCalibrationProcess(process);
 
-      // Add Enter key listener
+      // Add Enter key listener for stopping (matching Node.js UX)
       const handleKeyPress = (event: KeyboardEvent) => {
         if (event.key === "Enter") {
-          shouldStopRecording = true;
+          process.stop();
         }
       };
-
       document.addEventListener("keydown", handleKeyPress);
 
       try {
-        await startRangeRecording(
-          ctrl,
-          () => {
-            return shouldStopRecording;
-          },
-          (rangeMins, rangeMaxes, currentPositions) => {
-            recordingCount++;
-          }
+        // Wait for calibration to complete
+        const result = await process.result;
+        setCalibrationResult(result);
+
+        // App-level concern: Save results to storage
+        const serialNumber =
+          robot.serialNumber || robot.usbMetadata?.serialNumber || "unknown";
+        await saveCalibrationResults(
+          result,
+          robot.robotType,
+          robot.robotId || `${robot.robotType}_1`,
+          serialNumber
+        );
+
+        setStatus(
+          "✅ Calibration completed successfully! Configuration saved."
         );
       } finally {
         document.removeEventListener("keydown", handleKeyPress);
-        setStopRecordingFunction(null);
+        setCalibrationProcess(null);
+        setIsCalibrating(false);
       }
-
-      // Step 3: Finish calibration with recording count
-      await finishCalibration(ctrl, recordingCount);
     } catch (error) {
       console.error("❌ Calibration failed:", error);
+      setStatus(
+        `❌ Calibration failed: ${
+          error instanceof Error ? error.message : error
+        }`
+      );
+      setIsCalibrating(false);
+      setCalibrationProcess(null);
     }
-  };
+  }, [robot, initializeMotorData]);
 
-  // Generate calibration config JSON matching Python lerobot format (OBJECT format, not arrays)
-  const generateConfigJSON = () => {
-    // Use the calibration result if available
-    if (calibrationResult) {
-      return calibrationResult;
+  // Stop calibration recording
+  const handleStopRecording = useCallback(() => {
+    if (calibrationProcess) {
+      calibrationProcess.stop();
     }
+  }, [calibrationProcess]);
+
+  // App-level concern: Save calibration results
+  const saveCalibrationResults = async (
+    results: WebCalibrationResults,
+    robotType: string,
+    robotId: string,
+    serialNumber: string
+  ) => {
+    try {
+      // Save to unified storage (app-level functionality)
+      const { saveCalibrationData } = await import("../lib/unified-storage.js");
+
+      const fullCalibrationData = {
+        ...results,
+        device_type: robotType,
+        device_id: robotId,
+        calibrated_at: new Date().toISOString(),
+        platform: "web",
+        api: "Web Serial API",
+      };
 
-    // Fallback: generate from motor data (shouldn't happen with new flow)
-    const calibrationData: any = {};
-    motorNames.forEach((motorName, index) => {
-      const motor = motorData[index];
-      calibrationData[motorName] = {
-        homing_offset: motor.current - 2047, // Center offset for STS3215 (4095/2)
-        drive_mode: 0, // Python lerobot SO-100 uses drive_mode 0
-        start_pos: motor.min,
-        end_pos: motor.max,
-        calib_mode: "middle", // Python lerobot SO-100 standard
+      const metadata = {
+        timestamp: new Date().toISOString(),
+        readCount: Object.keys(motorData).length > 0 ? 100 : 0, // Estimate
       };
-    });
 
-    return calibrationData;
+      saveCalibrationData(serialNumber, fullCalibrationData, metadata);
+    } catch (error) {
+      console.warn("Failed to save calibration results:", error);
+    }
   };
 
-  // Download calibration config as JSON file
-  const downloadConfigJSON = () => {
-    const configData = generateConfigJSON();
-    const jsonString = JSON.stringify(configData, null, 2);
+  // App-level concern: JSON export functionality
+  const downloadConfigJSON = useCallback(() => {
+    if (!calibrationResult) return;
+
+    const jsonString = JSON.stringify(calibrationResult, null, 2);
     const blob = new Blob([jsonString], { type: "application/json" });
     const url = URL.createObjectURL(blob);
 
@@ -415,7 +223,7 @@ export function CalibrationPanel({ robot, onFinish }: CalibrationPanelProps) {
     link.click();
     document.body.removeChild(link);
     URL.revokeObjectURL(url);
-  };
+  }, [calibrationResult, robot.robotId, robot.robotType]);
 
   return (
     <div className="space-y-4">
@@ -455,27 +263,29 @@ export function CalibrationPanel({ robot, onFinish }: CalibrationPanelProps) {
               <p className="text-sm text-blue-800">{status}</p>
               {isCalibrating && (
                 <p className="text-xs text-blue-600 mt-1">
-                  Move joints through full range | Press "Finish Recording" when
-                  done
+                  Move joints through full range | Press "Finish Recording" or
+                  Enter key when done
                 </p>
               )}
             </div>
 
             <div className="flex gap-2">
               {!isCalibrating && !calibrationResult && (
-                <Button onClick={() => setModalOpen(true)}>
-                  Start Calibration
-                </Button>
-              )}
-
-              {isCalibrating && !isRecordingRanges && (
-                <Button onClick={finishCalibration} variant="outline">
-                  Finish Calibration
+                <Button
+                  onClick={async () => {
+                    // Release motor torque FIRST - so user can move joints immediately
+                    await releaseMotorTorque();
+                    // THEN open modal - user can now follow instructions right away
+                    setModalOpen(true);
+                  }}
+                  disabled={isPreparing}
+                >
+                  {isPreparing ? "Preparing..." : "Start Calibration"}
                 </Button>
               )}
 
-              {isRecordingRanges && stopRecordingFunction && (
-                <Button onClick={stopRecordingFunction} variant="default">
+              {isCalibrating && calibrationProcess && (
+                <Button onClick={handleStopRecording} variant="default">
                   Finish Recording
                 </Button>
               )}
@@ -507,7 +317,7 @@ export function CalibrationPanel({ robot, onFinish }: CalibrationPanelProps) {
           <CardContent>
             <div className="space-y-3">
               <pre className="bg-gray-100 p-4 rounded-lg text-sm overflow-x-auto border">
-                <code>{JSON.stringify(generateConfigJSON(), null, 2)}</code>
+                <code>{JSON.stringify(calibrationResult, null, 2)}</code>
               </pre>
               <div className="flex gap-2">
                 <Button onClick={downloadConfigJSON} variant="outline">
@@ -516,7 +326,7 @@ export function CalibrationPanel({ robot, onFinish }: CalibrationPanelProps) {
                 <Button
                   onClick={() => {
                     navigator.clipboard.writeText(
-                      JSON.stringify(generateConfigJSON(), null, 2)
+                      JSON.stringify(calibrationResult, null, 2)
                     );
                   }}
                   variant="outline"
@@ -529,12 +339,12 @@ export function CalibrationPanel({ robot, onFinish }: CalibrationPanelProps) {
         </Card>
       )}
 
-      {/* Live Position Recording Table (matching Node CLI exactly) */}
+      {/* Live Position Recording Table */}
       <Card>
         <CardHeader>
           <CardTitle className="text-lg">Live Position Recording</CardTitle>
           <CardDescription>
-            Real-time motor position feedback - exactly like Node CLI
+            Real-time motor position feedback during calibration
           </CardDescription>
         </CardHeader>
         <CardContent>
@@ -560,28 +370,39 @@ export function CalibrationPanel({ robot, onFinish }: CalibrationPanelProps) {
                 </tr>
               </thead>
               <tbody className="divide-y divide-gray-200">
-                {motorData.map((motor, index) => (
-                  <tr key={index} className="hover:bg-gray-50">
-                    <td className="px-4 py-2 font-medium flex items-center gap-2">
-                      {motor.name}
-                      {motor.range > 100 && (
-                        <span className="text-green-600 text-xs">✓</span>
-                      )}
-                    </td>
-                    <td className="px-4 py-2 text-right">{motor.current}</td>
-                    <td className="px-4 py-2 text-right">{motor.min}</td>
-                    <td className="px-4 py-2 text-right">{motor.max}</td>
-                    <td className="px-4 py-2 text-right font-medium">
-                      <span
-                        className={
-                          motor.range > 100 ? "text-green-600" : "text-gray-500"
-                        }
-                      >
-                        {motor.range}
-                      </span>
-                    </td>
-                  </tr>
-                ))}
+                {motorNames.map((motorName) => {
+                  const motor = motorData[motorName] || {
+                    current: 2047,
+                    min: 2047,
+                    max: 2047,
+                    range: 0,
+                  };
+
+                  return (
+                    <tr key={motorName} className="hover:bg-gray-50">
+                      <td className="px-4 py-2 font-medium flex items-center gap-2">
+                        {motorName}
+                        {motor.range > 100 && (
+                          <span className="text-green-600 text-xs">✓</span>
+                        )}
+                      </td>
+                      <td className="px-4 py-2 text-right">{motor.current}</td>
+                      <td className="px-4 py-2 text-right">{motor.min}</td>
+                      <td className="px-4 py-2 text-right">{motor.max}</td>
+                      <td className="px-4 py-2 text-right font-medium">
+                        <span
+                          className={
+                            motor.range > 100
+                              ? "text-green-600"
+                              : "text-gray-500"
+                          }
+                        >
+                          {motor.range}
+                        </span>
+                      </td>
+                    </tr>
+                  );
+                })}
               </tbody>
             </table>
           </div>

src/demo/components/PortManager.tsx

@@ -18,17 +18,31 @@ import {
   DialogTitle,
 } from "./ui/dialog";
 import { isWebSerialSupported } from "../../lerobot/web/calibrate";
-import type { ConnectedRobot } from "../types";
+import type { RobotConnection } from "../../lerobot/web/find_port.js";
+
+/**
+ * Type definitions for WebSerial API (missing from TypeScript)
+ */
+interface SerialPortInfo {
+  usbVendorId?: number;
+  usbProductId?: number;
+}
+
+declare global {
+  interface SerialPort {
+    getInfo(): SerialPortInfo;
+  }
+}
 
 interface PortManagerProps {
-  connectedRobots: ConnectedRobot[];
-  onConnectedRobotsChange: (robots: ConnectedRobot[]) => void;
+  connectedRobots: RobotConnection[];
+  onConnectedRobotsChange: (robots: RobotConnection[]) => void;
   onCalibrate?: (
     port: SerialPort,
     robotType: "so100_follower" | "so100_leader",
     robotId: string
   ) => void;
-  onTeleoperate?: (robot: ConnectedRobot) => void;
+  onTeleoperate?: (robot: RobotConnection) => void;
 }
 
 export function PortManager({
@@ -62,7 +76,7 @@ export function PortManager({
   const loadSavedPorts = async () => {
     try {
       const existingPorts = await navigator.serial.getPorts();
-      const restoredPorts: ConnectedRobot[] = [];
+      const restoredPorts: RobotConnection[] = [];
 
       for (const port of existingPorts) {
         // Get USB device metadata to determine serial number
@@ -297,7 +311,7 @@ export function PortManager({
 
       if (existingIndex === -1) {
         // New robot - add to list
-        const newRobot: ConnectedRobot = {
+        const newRobot: RobotConnection = {
           port,
           name: portName,
           isConnected: true,
@@ -489,47 +503,35 @@ export function PortManager({
       setFindPortsLog([]);
       setError(null);
 
-      // Get initial ports
-      const initialPorts = await navigator.serial.getPorts();
-      setFindPortsLog((prev) => [
-        ...prev,
-        `Found ${initialPorts.length} existing paired port(s)`,
-      ]);
-
-      // Ask user to disconnect
-      setFindPortsLog((prev) => [
-        ...prev,
-        "Please disconnect the USB cable from your robot and click OK",
-      ]);
-
-      // Simple implementation - just show the instruction
-      // In a real implementation, we'd monitor port changes
-      const confirmed = confirm(
-        "Disconnect the USB cable from your robot and click OK when done"
-      );
+      // Use the new findPort API from standard library
+      const { findPort } = await import("../../lerobot/web/find_port.js");
 
-      if (confirmed) {
-        setFindPortsLog((prev) => [...prev, "Reconnect the USB cable now"]);
+      const findPortProcess = await findPort({
+        onMessage: (message) => {
+          setFindPortsLog((prev) => [...prev, message]);
+        },
+      });
 
-        // Request port selection
-        const port = await navigator.serial.requestPort();
-        await port.open({ baudRate: 1000000 });
+      const robotConnections = (await findPortProcess.result) as any; // RobotConnection[] from findPort
+      const robotConnection = robotConnections[0]; // Get first robot from array
 
-        const portName = getPortDisplayName(port);
-        setFindPortsLog((prev) => [...prev, `Identified port: ${portName}`]);
+      const portName = getPortDisplayName(robotConnection.port);
+      setFindPortsLog((prev) => [...prev, `✅ Port ready: ${portName}`]);
 
-        // Add to connected ports if not already there
-        const existingIndex = connectedRobots.findIndex(
-          (p) => p.name === portName
-        );
-        if (existingIndex === -1) {
-          const newPort: ConnectedRobot = {
-            port,
-            name: portName,
-            isConnected: true,
-          };
-          onConnectedRobotsChange([...connectedRobots, newPort]);
-        }
+      // Add to connected ports if not already there
+      const existingIndex = connectedRobots.findIndex(
+        (p) => p.name === portName
+      );
+      if (existingIndex === -1) {
+        const newPort: RobotConnection = {
+          port: robotConnection.port,
+          name: portName,
+          isConnected: true,
+          robotType: robotConnection.robotType,
+          robotId: robotConnection.robotId,
+          serialNumber: robotConnection.serialNumber,
+        };
+        onConnectedRobotsChange([...connectedRobots, newPort]);
       }
     } catch (error) {
       if (
@@ -574,7 +576,7 @@ export function PortManager({
     }
   };
 
-  const handleCalibrate = async (port: ConnectedRobot) => {
+  const handleCalibrate = async (port: RobotConnection) => {
     if (!port.robotType || !port.robotId) {
       setError("Please set robot type and ID before calibrating");
       return;
@@ -738,7 +740,7 @@ export function PortManager({
 }
 
 interface PortCardProps {
-  portInfo: ConnectedRobot;
+  portInfo: RobotConnection;
   onDisconnect: () => void;
   onUpdateInfo: (
     robotType: "so100_follower" | "so100_leader",

src/demo/components/TeleoperationPanel.tsx

@@ -5,11 +5,11 @@ import { Badge } from "./ui/badge";
 import { Alert, AlertDescription } from "./ui/alert";
 import { Progress } from "./ui/progress";
 import { useTeleoperation } from "../hooks/useTeleoperation";
-import type { ConnectedRobot } from "../types";
+import type { RobotConnection } from "../../lerobot/web/find_port.js";
 import { KEYBOARD_CONTROLS } from "../../lerobot/web/teleoperate";
 
 interface TeleoperationPanelProps {
-  robot: ConnectedRobot;
+  robot: RobotConnection;
   onClose: () => void;
 }
 
@@ -27,9 +27,9 @@ export function TeleoperationPanel({
     error,
     start,
     stop,
-    goToHome,
     simulateKeyPress,
     simulateKeyRelease,
+    moveMotorToPosition,
   } = useTeleoperation({
     robot,
     enabled,
@@ -153,7 +153,7 @@ export function TeleoperationPanel({
           </div>
         </div>
 
-        {/* Q/E and Space */}
+        {/* Q/E and Gripper */}
         <div className="flex justify-center gap-2">
           <div className="text-center">
             <h4 className="text-xs font-semibold mb-2 text-gray-600">Roll</h4>
@@ -170,9 +170,14 @@ export function TeleoperationPanel({
             <h4 className="text-xs font-semibold mb-2 text-gray-600">
               Gripper
             </h4>
-            <KeyButton keyCode=" " size="sm" className="min-w-16">
-              ⎵
-            </KeyButton>
+            <div className="flex gap-1">
+              <KeyButton keyCode="o" size="sm">
+                O
+              </KeyButton>
+              <KeyButton keyCode="c" size="sm">
+                C
+              </KeyButton>
+            </div>
           </div>
         </div>
 
@@ -261,15 +266,6 @@ export function TeleoperationPanel({
                     ▶️ Start Teleoperation
                   </Button>
                 )}
-
-                <Button
-                  onClick={goToHome}
-                  variant="outline"
-                  disabled={!isConnected}
-                  className="w-full"
-                >
-                  🏠 Go to Home
-                </Button>
               </div>
             </CardContent>
           </Card>
@@ -290,11 +286,7 @@ export function TeleoperationPanel({
               <CardTitle>Motor Positions</CardTitle>
             </CardHeader>
             <CardContent className="space-y-3">
-              {motorConfigs.map((motor) => {
-                const range = motor.maxPosition - motor.minPosition;
-                const position = motor.currentPosition - motor.minPosition;
-                const percentage = range > 0 ? (position / range) * 100 : 0;
-
+              {motorConfigs.map((motor, index) => {
                 return (
                   <div key={motor.name} className="space-y-1">
                     <div className="flex justify-between items-center">
@@ -305,7 +297,41 @@ export function TeleoperationPanel({
                         {motor.currentPosition}
                       </span>
                     </div>
-                    <Progress value={percentage} className="h-2" />
+                    <input
+                      type="range"
+                      min={motor.minPosition}
+                      max={motor.maxPosition}
+                      value={motor.currentPosition}
+                      disabled={!isActive}
+                      className={`w-full h-2 rounded-lg appearance-none cursor-pointer bg-gray-200 slider-thumb ${
+                        !isActive ? "opacity-50 cursor-not-allowed" : ""
+                      }`}
+                      style={{
+                        background: isActive
+                          ? `linear-gradient(to right, #3b82f6 0%, #3b82f6 ${
+                              ((motor.currentPosition - motor.minPosition) /
+                                (motor.maxPosition - motor.minPosition)) *
+                              100
+                            }%, #e5e7eb ${
+                              ((motor.currentPosition - motor.minPosition) /
+                                (motor.maxPosition - motor.minPosition)) *
+                              100
+                            }%, #e5e7eb 100%)`
+                          : "#e5e7eb",
+                      }}
+                      onChange={async (e) => {
+                        if (!isActive) return;
+                        const newPosition = parseInt(e.target.value);
+                        try {
+                          await moveMotorToPosition(index, newPosition);
+                        } catch (error) {
+                          console.warn(
+                            "Failed to move motor via slider:",
+                            error
+                          );
+                        }
+                      }}
+                    />
                     <div className="flex justify-between text-xs text-gray-400">
                       <span>{motor.minPosition}</span>
                       <span>{motor.maxPosition}</span>
@@ -342,7 +368,8 @@ export function TeleoperationPanel({
                 <h4 className="font-semibold mb-2">Other Keys</h4>
                 <ul className="space-y-1 text-gray-600">
                   <li>Q E Wrist roll</li>
-                  <li>Space Gripper</li>
+                  <li>O Open gripper</li>
+                  <li>C Close gripper</li>
                 </ul>
               </div>
               <div>

src/demo/hooks/useTeleoperation.ts

@@ -1,7 +1,7 @@
 import { useState, useEffect, useCallback, useRef } from "react";
 import { useRobotConnection } from "./useRobotConnection";
 import { getUnifiedRobotData } from "../lib/unified-storage";
-import type { ConnectedRobot } from "../types";
+import type { RobotConnection } from "../../lerobot/web/find_port.js";
 
 export interface MotorConfig {
   name: string;
@@ -17,7 +17,7 @@ export interface KeyState {
 }
 
 export interface UseTeleoperationOptions {
-  robot: ConnectedRobot;
+  robot: RobotConnection;
   enabled: boolean;
   onError?: (error: string) => void;
 }
@@ -42,6 +42,7 @@ export interface UseTeleoperationResult {
   goToHome: () => Promise<void>;
   simulateKeyPress: (key: string) => void;
   simulateKeyRelease: (key: string) => void;
+  moveMotorToPosition: (motorIndex: number, position: number) => Promise<void>;
 }
 
 const MOTOR_CONFIGS: MotorConfig[] = [
@@ -116,7 +117,8 @@ const KEYBOARD_CONTROLS = {
   d: { motorIndex: 3, direction: 1, description: "Wrist flex right" },
   q: { motorIndex: 4, direction: -1, description: "Wrist roll left" },
   e: { motorIndex: 4, direction: 1, description: "Wrist roll right" },
-  " ": { motorIndex: 5, direction: 1, description: "Gripper open/close" },
+  o: { motorIndex: 5, direction: 1, description: "Gripper open" },
+  c: { motorIndex: 5, direction: -1, description: "Gripper close" },
   Escape: { motorIndex: -1, direction: 0, description: "Emergency stop" },
 };
 
@@ -471,6 +473,35 @@ export function useTeleoperation({
     [isActive]
   );
 
+  const moveMotorToPosition = useCallback(
+    async (motorIndex: number, position: number) => {
+      if (!connection.isConnected) {
+        return;
+      }
+
+      try {
+        await connection.writeMotorPosition(motorIndex + 1, position);
+
+        // Update internal state
+        motorPositionsRef.current[motorIndex] = position;
+
+        setMotorConfigs((prev) =>
+          prev.map((config, index) => ({
+            ...config,
+            currentPosition:
+              index === motorIndex ? position : config.currentPosition,
+          }))
+        );
+      } catch (error) {
+        console.warn(
+          `Failed to move motor ${motorIndex + 1} to position ${position}:`,
+          error
+        );
+      }
+    },
+    [connection.isConnected, connection.writeMotorPosition]
+  );
+
   return {
     isConnected: connection.isConnected,
     isActive,
@@ -482,5 +513,6 @@ export function useTeleoperation({
     goToHome,
     simulateKeyPress,
     simulateKeyRelease,
+    moveMotorToPosition,
   };
 }

src/demo/pages/Home.tsx

@@ -12,12 +12,12 @@ import { PortManager } from "../components/PortManager";
 import { CalibrationPanel } from "../components/CalibrationPanel";
 import { TeleoperationPanel } from "../components/TeleoperationPanel";
 import { isWebSerialSupported } from "../../lerobot/web/calibrate";
-import type { ConnectedRobot } from "../types";
+import type { RobotConnection } from "../../lerobot/web/find_port.js";
 
 interface HomeProps {
   onGetStarted: () => void;
-  connectedRobots: ConnectedRobot[];
-  onConnectedRobotsChange: (robots: ConnectedRobot[]) => void;
+  connectedRobots: RobotConnection[];
+  onConnectedRobotsChange: (robots: RobotConnection[]) => void;
 }
 
 export function Home({
@@ -26,9 +26,9 @@ export function Home({
   onConnectedRobotsChange,
 }: HomeProps) {
   const [calibratingRobot, setCalibratingRobot] =
-    useState<ConnectedRobot | null>(null);
+    useState<RobotConnection | null>(null);
   const [teleoperatingRobot, setTeleoperatingRobot] =
-    useState<ConnectedRobot | null>(null);
+    useState<RobotConnection | null>(null);
   const isSupported = isWebSerialSupported();
 
   const handleCalibrate = (
@@ -43,7 +43,7 @@ export function Home({
     }
   };
 
-  const handleTeleoperate = (robot: ConnectedRobot) => {
+  const handleTeleoperate = (robot: RobotConnection) => {
     setTeleoperatingRobot(robot);
   };
 

src/demo/types.ts

@@ -1,20 +1,2 @@
-export interface ConnectedRobot {
-  port: SerialPort;
-  name: string;
-  isConnected: boolean;
-  robotType?: "so100_follower" | "so100_leader";
-  robotId?: string;
-  serialNumber?: string; // Unique identifier from USB device
-  usbMetadata?: {
-    vendorId: string;
-    productId: string;
-    serialNumber: string;
-    manufacturerName: string;
-    productName: string;
-    usbVersionMajor?: number;
-    usbVersionMinor?: number;
-    deviceClass?: number;
-    deviceSubclass?: number;
-    deviceProtocol?: number;
-  };
-}
+// Demo uses the standard library RobotConnection interface directly
+// No need for separate types - just import RobotConnection where needed

src/lerobot/web/calibrate.ts

@@ -1,13 +1,29 @@
 /**
  * Web calibration functionality using Web Serial API
- * For browser environments - matches Node.js implementation exactly
+ * Minimal library - does calibration, user handles storage/UI/etc.
+ *
+ * Currently supports SO-100 robots. Other robot types can be added by:
+ * 1. Creating robot-specific config files in ./robots/
+ * 2. Extending the calibrate() function to accept different robot types
+ * 3. Adding robot-specific protocol configurations
  */
 
-import type { CalibrateConfig } from "../node/robots/config.js";
+import { createSO100Config } from "./robots/so100_config.js";
+import { WebSerialPortWrapper } from "./utils/serial-port-wrapper.js";
+import {
+  readAllMotorPositions,
+  releaseMotors,
+  type MotorCommunicationPort,
+} from "./utils/motor-communication.js";
+import {
+  setHomingOffsets,
+  writeHardwarePositionLimits,
+} from "./utils/motor-calibration.js";
+import type { RobotConnection } from "./find_port.js";
 
 /**
- * Device-agnostic calibration configuration for web
- * Mirrors the Node.js SO100CalibrationConfig exactly
+ * Device calibration configuration interface
+ * Currently designed for SO-100, but can be extended for other robot types
  */
 interface WebCalibrationConfig {
   deviceType: "so100_follower" | "so100_leader";
@@ -15,9 +31,8 @@ interface WebCalibrationConfig {
   motorNames: string[];
   motorIds: number[];
   driveModes: number[];
-  calibModes: string[];
 
-  // Protocol-specific configuration (matches Node.js exactly)
+  // Protocol-specific configuration
   protocol: {
     resolution: number;
     homingOffsetAddress: number;
@@ -30,13 +45,6 @@ interface WebCalibrationConfig {
     maxPositionLimitLength: number;
     signMagnitudeBit: number;
   };
-
-  limits: {
-    position_min: number[];
-    position_max: number[];
-    velocity_max: number[];
-    torque_max: number[];
-  };
 }
 
 /**
@@ -53,470 +61,34 @@ export interface WebCalibrationResults {
 }
 
 /**
- * STS3215 Protocol Configuration for web (matches Node.js exactly)
- */
-const WEB_STS3215_PROTOCOL = {
-  resolution: 4096, // 12-bit resolution (0-4095)
-  homingOffsetAddress: 31, // Address for Homing_Offset register
-  homingOffsetLength: 2, // 2 bytes for Homing_Offset
-  presentPositionAddress: 56, // Address for Present_Position register
-  presentPositionLength: 2, // 2 bytes for Present_Position
-  minPositionLimitAddress: 9, // Address for Min_Position_Limit register
-  minPositionLimitLength: 2, // 2 bytes for Min_Position_Limit
-  maxPositionLimitAddress: 11, // Address for Max_Position_Limit register
-  maxPositionLimitLength: 2, // 2 bytes for Max_Position_Limit
-  signMagnitudeBit: 11, // Bit 11 is sign bit for Homing_Offset encoding
-} as const;
-
-/**
- * Sign-magnitude encoding functions (matches Node.js exactly)
- */
-function encodeSignMagnitude(value: number, signBitIndex: number): number {
-  const maxMagnitude = (1 << signBitIndex) - 1;
-  const magnitude = Math.abs(value);
-
-  if (magnitude > maxMagnitude) {
-    throw new Error(
-      `Magnitude ${magnitude} exceeds ${maxMagnitude} (max for signBitIndex=${signBitIndex})`
-    );
-  }
-
-  const directionBit = value < 0 ? 1 : 0;
-  return (directionBit << signBitIndex) | magnitude;
-}
-
-/**
- * PROPER Web Serial Port wrapper following Chrome documentation exactly
- * Direct write/read with immediate lock release - NO persistent connections
- */
-class WebSerialPortWrapper {
-  private port: SerialPort;
-
-  constructor(port: SerialPort) {
-    this.port = port;
-  }
-
-  get isOpen(): boolean {
-    return (
-      this.port !== null &&
-      this.port.readable !== null &&
-      this.port.writable !== null
-    );
-  }
-
-  async initialize(): Promise<void> {
-    if (!this.port.readable || !this.port.writable) {
-      throw new Error("Port is not open for reading/writing");
-    }
-  }
-
-  /**
-   * Write data - EXACTLY like Chrome documentation
-   * Get writer, write, release lock immediately
-   */
-  async write(data: Uint8Array): Promise<void> {
-    if (!this.port.writable) {
-      throw new Error("Port not open for writing");
-    }
-
-    // Write packet to motor
-
-    const writer = this.port.writable.getWriter();
-    try {
-      await writer.write(data);
-    } finally {
-      writer.releaseLock();
-    }
-  }
-
-  /**
-   * Read data - EXACTLY like Chrome documentation
-   * Get reader, read once, release lock immediately
-   */
-  async read(timeout: number = 1000): Promise<Uint8Array> {
-    if (!this.port.readable) {
-      throw new Error("Port not open for reading");
-    }
-
-    const reader = this.port.readable.getReader();
-
-    try {
-      // Set up timeout
-      const timeoutPromise = new Promise<never>((_, reject) => {
-        setTimeout(() => reject(new Error("Read timeout")), timeout);
-      });
-
-      // Race between read and timeout
-      const result = await Promise.race([reader.read(), timeoutPromise]);
-
-      const { value, done } = result;
-
-      if (done || !value) {
-        throw new Error("Read failed - port closed or no data");
-      }
-
-      const response = new Uint8Array(value);
-      return response;
-    } finally {
-      reader.releaseLock();
-    }
-  }
-
-  async close(): Promise<void> {
-    // Don't close the port itself - just wrapper cleanup
-  }
-}
-
-/**
- * Read motor positions using device-agnostic configuration (exactly like Node.js)
- */
-async function readMotorPositions(
-  config: WebCalibrationConfig
-): Promise<number[]> {
-  const motorPositions: number[] = [];
-
-  // Reading motor positions
-
-  for (let i = 0; i < config.motorIds.length; i++) {
-    const motorId = config.motorIds[i];
-    const motorName = config.motorNames[i];
-
-    try {
-      // Create Read Position packet using configurable address
-      const packet = new Uint8Array([
-        0xff,
-        0xff,
-        motorId,
-        0x04,
-        0x02,
-        config.protocol.presentPositionAddress, // Configurable address
-        0x02,
-        0x00,
-      ]);
-      const checksum =
-        ~(
-          motorId +
-          0x04 +
-          0x02 +
-          config.protocol.presentPositionAddress +
-          0x02
-        ) & 0xff;
-      packet[7] = checksum;
-
-      // Professional Feetech communication pattern (based on matthieuvigne/STS_servos)
-      let attempts = 0;
-      let success = false;
-
-      while (attempts < 3 && !success) {
-        attempts++;
-
-        // Clear any remaining data in buffer first (critical for Web Serial)
-        try {
-          await config.port.read(0); // Non-blocking read to clear buffer
-        } catch (e) {
-          // Expected - buffer was empty
-        }
-
-        // Write command with proper timing
-        await config.port.write(packet);
-
-        // Arduino library uses careful timing - Web Serial needs more
-        await new Promise((resolve) => setTimeout(resolve, 10));
-
-        const response = await config.port.read(150);
-
-        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);
-            success = true;
-          } else if (id === motorId && error !== 0) {
-            // Motor error, retry
-          } else {
-            // Wrong response ID, retry
-          }
-        } else {
-          // Short response, retry
-        }
-
-        // Professional timing between attempts (like Arduino libraries)
-        if (!success && attempts < 3) {
-          await new Promise((resolve) => setTimeout(resolve, 20));
-        }
-      }
-
-      // If all attempts failed, use fallback
-      if (!success) {
-        const fallback = Math.floor((config.protocol.resolution - 1) / 2);
-        motorPositions.push(fallback);
-      }
-    } catch (error) {
-      const fallback = Math.floor((config.protocol.resolution - 1) / 2);
-      motorPositions.push(fallback);
-    }
-
-    // Professional inter-motor delay (based on Arduino STS_servos library)
-    await new Promise((resolve) => setTimeout(resolve, 10));
-  }
-
-  return motorPositions;
-}
-
-/**
- * Reset homing offsets to 0 for all motors (matches Node.js exactly)
- */
-async function resetHomingOffsets(config: WebCalibrationConfig): Promise<void> {
-  for (let i = 0; i < config.motorIds.length; i++) {
-    const motorId = config.motorIds[i];
-    const motorName = config.motorNames[i];
-
-    try {
-      const homingOffsetValue = 0;
-
-      // Create Write Homing_Offset packet using configurable address
-      const packet = new Uint8Array([
-        0xff,
-        0xff, // Header
-        motorId, // Servo ID
-        0x05, // Length
-        0x03, // Instruction: WRITE_DATA
-        config.protocol.homingOffsetAddress, // Configurable address
-        homingOffsetValue & 0xff, // Data_L (low byte)
-        (homingOffsetValue >> 8) & 0xff, // Data_H (high byte)
-        0x00, // Checksum (will calculate)
-      ]);
-
-      // Calculate checksum using configurable address
-      const checksum =
-        ~(
-          motorId +
-          0x05 +
-          0x03 +
-          config.protocol.homingOffsetAddress +
-          (homingOffsetValue & 0xff) +
-          ((homingOffsetValue >> 8) & 0xff)
-        ) & 0xff;
-      packet[8] = checksum;
-
-      // Simple write then read like Node.js
-      await config.port.write(packet);
-
-      // Wait for response (silent unless error)
-      try {
-        await config.port.read(200);
-      } catch (error) {
-        // Silent - response not required for successful operation
-      }
-    } catch (error) {
-      throw new Error(
-        `Failed to reset homing offset for ${motorName}: ${
-          error instanceof Error ? error.message : error
-        }`
-      );
-    }
-  }
-}
-
-/**
- * Write homing offsets to motor registers immediately (matches Node.js exactly)
- */
-async function writeHomingOffsetsToMotors(
-  config: WebCalibrationConfig,
-  homingOffsets: { [motor: string]: number }
-): Promise<void> {
-  for (let i = 0; i < config.motorIds.length; i++) {
-    const motorId = config.motorIds[i];
-    const motorName = config.motorNames[i];
-    const homingOffset = homingOffsets[motorName];
-
-    try {
-      // Encode using sign-magnitude format
-      const encodedOffset = encodeSignMagnitude(
-        homingOffset,
-        config.protocol.signMagnitudeBit
-      );
-
-      // Create Write Homing_Offset packet
-      const packet = new Uint8Array([
-        0xff,
-        0xff, // Header
-        motorId, // Servo ID
-        0x05, // Length
-        0x03, // Instruction: WRITE_DATA
-        config.protocol.homingOffsetAddress, // Homing_Offset address
-        encodedOffset & 0xff, // Data_L (low byte)
-        (encodedOffset >> 8) & 0xff, // Data_H (high byte)
-        0x00, // Checksum (will calculate)
-      ]);
-
-      // Calculate checksum
-      const checksum =
-        ~(
-          motorId +
-          0x05 +
-          0x03 +
-          config.protocol.homingOffsetAddress +
-          (encodedOffset & 0xff) +
-          ((encodedOffset >> 8) & 0xff)
-        ) & 0xff;
-      packet[8] = checksum;
-
-      // Simple write then read like Node.js
-      await config.port.write(packet);
-
-      // Wait for response (silent unless error)
-      try {
-        await config.port.read(200);
-      } catch (error) {
-        // Silent - response not required for successful operation
-      }
-    } catch (error) {
-      throw new Error(
-        `Failed to write homing offset for ${motorName}: ${
-          error instanceof Error ? error.message : error
-        }`
-      );
-    }
-  }
-}
-
-/**
- * Record homing offsets with immediate writing (matches Node.js exactly)
+ * Live calibration data with current positions and ranges
  */
-async function setHomingOffsets(
-  config: WebCalibrationConfig
-): Promise<{ [motor: string]: number }> {
-  console.log("🏠 Setting homing offsets...");
-
-  // CRITICAL: Reset existing homing offsets to 0 first (matching Python)
-  await resetHomingOffsets(config);
-
-  // Wait a moment for reset to take effect
-  await new Promise((resolve) => setTimeout(resolve, 100));
-
-  // Now read positions (which will be true physical positions)
-  const currentPositions = await readMotorPositions(config);
-  const homingOffsets: { [motor: string]: number } = {};
-
-  const halfTurn = Math.floor((config.protocol.resolution - 1) / 2);
-
-  for (let i = 0; i < config.motorNames.length; i++) {
-    const motorName = config.motorNames[i];
-    const position = currentPositions[i];
-
-    // Generic formula: pos - int((max_res - 1) / 2) using configurable resolution
-    const homingOffset = position - halfTurn;
-    homingOffsets[motorName] = homingOffset;
-  }
-
-  // CRITICAL: Write homing offsets to motors immediately (matching Python exactly)
-  await writeHomingOffsetsToMotors(config, homingOffsets);
-
-  return homingOffsets;
-}
-
-/**
- * Generic function to write a 2-byte value to a motor register (matches Node.js exactly)
- */
-async function writeMotorRegister(
-  config: WebCalibrationConfig,
-  motorId: number,
-  registerAddress: number,
-  value: number,
-  description: string
-): Promise<void> {
-  // Create Write Register packet
-  const packet = new Uint8Array([
-    0xff,
-    0xff, // Header
-    motorId, // Servo ID
-    0x05, // Length
-    0x03, // Instruction: WRITE_DATA
-    registerAddress, // Register address
-    value & 0xff, // Data_L (low byte)
-    (value >> 8) & 0xff, // Data_H (high byte)
-    0x00, // Checksum (will calculate)
-  ]);
-
-  // Calculate checksum
-  const checksum =
-    ~(
-      motorId +
-      0x05 +
-      0x03 +
-      registerAddress +
-      (value & 0xff) +
-      ((value >> 8) & 0xff)
-    ) & 0xff;
-  packet[8] = checksum;
-
-  // Simple write then read like Node.js
-  await config.port.write(packet);
-
-  // Wait for response (silent unless error)
-  try {
-    await config.port.read(200);
-  } catch (error) {
-    // Silent - response not required for successful operation
-  }
+export interface LiveCalibrationData {
+  [motorName: string]: {
+    current: number;
+    min: number;
+    max: number;
+    range: number;
+  };
 }
 
 /**
- * Write hardware position limits to motors (matches Node.js exactly)
+ * Calibration process control object
  */
-async function writeHardwarePositionLimits(
-  config: WebCalibrationConfig,
-  rangeMins: { [motor: string]: number },
-  rangeMaxes: { [motor: string]: number }
-): Promise<void> {
-  for (let i = 0; i < config.motorIds.length; i++) {
-    const motorId = config.motorIds[i];
-    const motorName = config.motorNames[i];
-    const minLimit = rangeMins[motorName];
-    const maxLimit = rangeMaxes[motorName];
-
-    try {
-      // Write Min_Position_Limit register
-      await writeMotorRegister(
-        config,
-        motorId,
-        config.protocol.minPositionLimitAddress,
-        minLimit,
-        `Min_Position_Limit for ${motorName}`
-      );
-
-      // Write Max_Position_Limit register
-      await writeMotorRegister(
-        config,
-        motorId,
-        config.protocol.maxPositionLimitAddress,
-        maxLimit,
-        `Max_Position_Limit for ${motorName}`
-      );
-    } catch (error) {
-      throw new Error(
-        `Failed to write position limits for ${motorName}: ${
-          error instanceof Error ? error.message : error
-        }`
-      );
-    }
-  }
+export interface CalibrationProcess {
+  stop(): void;
+  result: Promise<WebCalibrationResults>;
 }
 
 /**
- * Record ranges of motion with manual control (user decides when to stop)
+ * Record ranges of motion with live updates
  */
 async function recordRangesOfMotion(
-  config: WebCalibrationConfig,
+  port: MotorCommunicationPort,
+  motorIds: number[],
+  motorNames: string[],
   shouldStop: () => boolean,
-  onUpdate?: (
-    rangeMins: { [motor: string]: number },
-    rangeMaxes: { [motor: string]: number },
-    currentPositions: { [motor: string]: number }
-  ) => void
+  onLiveUpdate?: (data: LiveCalibrationData) => void
 ): Promise<{
   rangeMins: { [motor: string]: number };
   rangeMaxes: { [motor: string]: number };
@@ -525,29 +97,23 @@ async function recordRangesOfMotion(
   const rangeMaxes: { [motor: string]: number } = {};
 
   // Read actual current positions (matching Python exactly)
-  // After homing offsets are applied, these should be ~2047 (centered)
-  const startPositions = await readMotorPositions(config);
+  const startPositions = await readAllMotorPositions(port, motorIds);
 
-  for (let i = 0; i < config.motorNames.length; i++) {
-    const motorName = config.motorNames[i];
+  for (let i = 0; i < motorNames.length; i++) {
+    const motorName = motorNames[i];
     const startPosition = startPositions[i];
-    rangeMins[motorName] = startPosition; // Use actual position, not hardcoded 2047
-    rangeMaxes[motorName] = startPosition; // Use actual position, not hardcoded 2047
+    rangeMins[motorName] = startPosition;
+    rangeMaxes[motorName] = startPosition;
   }
 
-  // Manual recording using simple while loop like Node.js
-  let recordingCount = 0;
-
+  // Recording loop
   while (!shouldStop()) {
     try {
-      const positions = await readMotorPositions(config);
-      recordingCount++;
+      const positions = await readAllMotorPositions(port, motorIds);
 
-      for (let i = 0; i < config.motorNames.length; i++) {
-        const motorName = config.motorNames[i];
+      for (let i = 0; i < motorNames.length; i++) {
+        const motorName = motorNames[i];
         const position = positions[i];
-        const oldMin = rangeMins[motorName];
-        const oldMax = rangeMaxes[motorName];
 
         if (position < rangeMins[motorName]) {
           rangeMins[motorName] = position;
@@ -555,275 +121,141 @@ async function recordRangesOfMotion(
         if (position > rangeMaxes[motorName]) {
           rangeMaxes[motorName] = position;
         }
-
-        // Track range expansions silently
       }
 
-      // Continue recording silently
-
-      // Call update callback if provided (for live UI updates)
-      if (onUpdate) {
-        // Convert positions array to motor name map for UI
-        const currentPositions: { [motor: string]: number } = {};
-        for (let i = 0; i < config.motorNames.length; i++) {
-          currentPositions[config.motorNames[i]] = positions[i];
+      // Call live update callback if provided
+      if (onLiveUpdate) {
+        const liveData: LiveCalibrationData = {};
+        for (let i = 0; i < motorNames.length; i++) {
+          const motorName = motorNames[i];
+          liveData[motorName] = {
+            current: positions[i],
+            min: rangeMins[motorName],
+            max: rangeMaxes[motorName],
+            range: rangeMaxes[motorName] - rangeMins[motorName],
+          };
         }
-        onUpdate(rangeMins, rangeMaxes, currentPositions);
+        onLiveUpdate(liveData);
       }
     } catch (error) {
-      console.warn("Error during range recording:", error);
+      // Continue recording despite errors
     }
 
-    // 20fps reading rate for stable Web Serial communication while maintaining responsive UI
+    // 20fps reading rate for stable Web Serial communication
     await new Promise((resolve) => setTimeout(resolve, 50));
   }
 
-  // Range recording finished
-
   return { rangeMins, rangeMaxes };
 }
 
 /**
- * Interactive web calibration with manual control - user decides when to stop recording
+ * Create SO-100 web configuration
  */
-async function performWebCalibration(
-  config: WebCalibrationConfig,
-  shouldStopRecording: () => boolean,
-  onRangeUpdate?: (
-    rangeMins: { [motor: string]: number },
-    rangeMaxes: { [motor: string]: number },
-    currentPositions: { [motor: string]: number }
-  ) => void
-): Promise<WebCalibrationResults> {
-  // Step 1: Set homing position
-  const homingOffsets = await setHomingOffsets(config);
-
-  // Step 2: Record ranges of motion with manual control
-  const { rangeMins, rangeMaxes } = await recordRangesOfMotion(
-    config,
-    shouldStopRecording,
-    onRangeUpdate
-  );
-
-  // Step 3: Set special range for wrist_roll (full turn motor)
-  rangeMins["wrist_roll"] = 0;
-  rangeMaxes["wrist_roll"] = 4095;
-
-  // Step 4: Write hardware position limits to motors (matching Python behavior)
-  await writeHardwarePositionLimits(config, rangeMins, rangeMaxes);
-
-  // Compile results in Python-compatible format (NOT array format!)
-  const results: WebCalibrationResults = {};
-
-  for (let i = 0; i < config.motorNames.length; i++) {
-    const motorName = config.motorNames[i];
-    const motorId = config.motorIds[i];
-
-    results[motorName] = {
-      id: motorId,
-      drive_mode: config.driveModes[i],
-      homing_offset: homingOffsets[motorName],
-      range_min: rangeMins[motorName],
-      range_max: rangeMaxes[motorName],
-    };
-  }
+function createSO100WebConfig(
+  deviceType: "so100_follower" | "so100_leader",
+  port: WebSerialPortWrapper
+): WebCalibrationConfig {
+  const so100Config = createSO100Config(deviceType);
 
-  return results;
+  return {
+    ...so100Config,
+    port,
+  };
 }
 
 /**
- * Step-by-step calibration for React components
+ * Main calibrate function - minimal library API
+ * Currently supports SO-100 robots (follower and leader)
+ *
+ * Takes a unified RobotConnection object from findPort()
  */
-export class WebCalibrationController {
-  private config: WebCalibrationConfig;
-  private homingOffsets: { [motor: string]: number } | null = null;
-  private rangeMins: { [motor: string]: number } | null = null;
-  private rangeMaxes: { [motor: string]: number } | null = null;
-
-  constructor(config: WebCalibrationConfig) {
-    this.config = config;
+export async function calibrate(
+  robotConnection: RobotConnection,
+  options?: {
+    onLiveUpdate?: (data: LiveCalibrationData) => void;
+    onProgress?: (message: string) => void;
   }
-
-  async readMotorPositions(): Promise<number[]> {
-    return await readMotorPositions(this.config);
+): Promise<CalibrationProcess> {
+  // Validate required fields
+  if (!robotConnection.robotType) {
+    throw new Error(
+      "Robot type is required for calibration. Please configure the robot first."
+    );
   }
 
-  async performHomingStep(): Promise<void> {
-    this.homingOffsets = await setHomingOffsets(this.config);
-  }
+  // Create web serial port wrapper
+  const port = new WebSerialPortWrapper(robotConnection.port);
+  await port.initialize();
 
-  async performRangeRecordingStep(
-    shouldStop: () => boolean,
-    onUpdate?: (
-      rangeMins: { [motor: string]: number },
-      rangeMaxes: { [motor: string]: number },
-      currentPositions: { [motor: string]: number }
-    ) => void
-  ): Promise<void> {
-    const { rangeMins, rangeMaxes } = await recordRangesOfMotion(
-      this.config,
-      shouldStop,
-      onUpdate
+  // Get SO-100 specific calibration configuration
+  const config = createSO100WebConfig(robotConnection.robotType, port);
+
+  let shouldStop = false;
+  const stopFunction = () => shouldStop;
+
+  // Start calibration process
+  const resultPromise = (async (): Promise<WebCalibrationResults> => {
+    // Step 1: Set homing offsets (automatic)
+    options?.onProgress?.("⚙️ Setting motor homing offsets");
+    const homingOffsets = await setHomingOffsets(
+      config.port,
+      config.motorIds,
+      config.motorNames
     );
-    this.rangeMins = rangeMins;
-    this.rangeMaxes = rangeMaxes;
 
-    // Set special range for wrist_roll (full turn motor)
-    this.rangeMins["wrist_roll"] = 0;
-    this.rangeMaxes["wrist_roll"] = 4095;
-  }
+    // Step 2: Record ranges of motion with live updates
+    const { rangeMins, rangeMaxes } = await recordRangesOfMotion(
+      config.port,
+      config.motorIds,
+      config.motorNames,
+      stopFunction,
+      options?.onLiveUpdate
+    );
 
-  async finishCalibration(): Promise<WebCalibrationResults> {
-    if (!this.homingOffsets || !this.rangeMins || !this.rangeMaxes) {
-      throw new Error("Must complete all calibration steps first");
-    }
+    // Step 3: Set special range for wrist_roll (full turn motor)
+    // The wrist_roll is a continuous rotation motor that should use the full
+    // 0-4095 range regardless of what the user recorded during calibration.
+    // This matches the hardware specification and Python lerobot behavior.
+    rangeMins["wrist_roll"] = 0;
+    rangeMaxes["wrist_roll"] = 4095;
 
-    // Write hardware position limits to motors (matching Python behavior)
+    // Step 4: Write hardware position limits to motors
     await writeHardwarePositionLimits(
-      this.config,
-      this.rangeMins,
-      this.rangeMaxes
+      config.port,
+      config.motorIds,
+      config.motorNames,
+      rangeMins,
+      rangeMaxes
     );
 
-    // Compile results in Python-compatible format (NOT array format!)
+    // Step 5: Compile results in Python-compatible format
     const results: WebCalibrationResults = {};
 
-    for (let i = 0; i < this.config.motorNames.length; i++) {
-      const motorName = this.config.motorNames[i];
-      const motorId = this.config.motorIds[i];
+    for (let i = 0; i < config.motorNames.length; i++) {
+      const motorName = config.motorNames[i];
+      const motorId = config.motorIds[i];
 
       results[motorName] = {
         id: motorId,
-        drive_mode: this.config.driveModes[i],
-        homing_offset: this.homingOffsets[motorName],
-        range_min: this.rangeMins[motorName],
-        range_max: this.rangeMaxes[motorName],
+        drive_mode: config.driveModes[i],
+        homing_offset: homingOffsets[motorName],
+        range_min: rangeMins[motorName],
+        range_max: rangeMaxes[motorName],
       };
     }
 
-    console.log("🎉 Calibration completed successfully!");
     return results;
-  }
-}
+  })();
 
-/**
- * Create SO-100 web configuration (matches Node.js exactly)
- */
-function createSO100WebConfig(
-  deviceType: "so100_follower" | "so100_leader",
-  port: WebSerialPortWrapper
-): WebCalibrationConfig {
+  // Return control object
   return {
-    deviceType,
-    port,
-    motorNames: [
-      "shoulder_pan",
-      "shoulder_lift",
-      "elbow_flex",
-      "wrist_flex",
-      "wrist_roll",
-      "gripper",
-    ],
-    motorIds: [1, 2, 3, 4, 5, 6],
-    protocol: WEB_STS3215_PROTOCOL,
-    driveModes: [0, 0, 0, 0, 0, 0], // Python lerobot uses drive_mode=0 for all motors
-    calibModes: ["DEGREE", "DEGREE", "DEGREE", "DEGREE", "DEGREE", "LINEAR"],
-    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],
+    stop: () => {
+      shouldStop = true;
     },
+    result: resultPromise,
   };
 }
 
-/**
- * Create a calibration controller for step-by-step calibration in React components
- */
-export async function createCalibrationController(
-  armType: "so100_follower" | "so100_leader",
-  connectedPort: SerialPort
-): Promise<WebCalibrationController> {
-  // Create web serial port wrapper
-  const port = new WebSerialPortWrapper(connectedPort);
-  await port.initialize();
-
-  // Get device-agnostic calibration configuration
-  const config = createSO100WebConfig(armType, port);
-
-  return new WebCalibrationController(config);
-}
-
-/**
- * Save calibration results to unified storage system
- */
-export async function saveCalibrationResults(
-  calibrationResults: WebCalibrationResults,
-  armType: "so100_follower" | "so100_leader",
-  armId: string,
-  serialNumber: string,
-  recordingCount: number = 0
-): Promise<void> {
-  // Prepare full calibration data
-  const fullCalibrationData = {
-    ...calibrationResults,
-    device_type: armType,
-    device_id: armId,
-    calibrated_at: new Date().toISOString(),
-    platform: "web",
-    api: "Web Serial API",
-  };
-
-  const metadata = {
-    timestamp: new Date().toISOString(),
-    readCount: recordingCount,
-  };
-
-  // Try to save using unified storage system
-  try {
-    const { saveCalibrationData } = await import(
-      "../../demo/lib/unified-storage.js"
-    );
-    saveCalibrationData(serialNumber, fullCalibrationData, metadata);
-    console.log(
-      `✅ Calibration saved to unified storage: lerobotjs-${serialNumber}`
-    );
-  } catch (error) {
-    console.warn(
-      "Failed to save to unified storage, falling back to old format:",
-      error
-    );
-
-    // Fallback to old storage format for compatibility
-    const fullDataKey = `lerobot_calibration_${armType}_${armId}`;
-    localStorage.setItem(fullDataKey, JSON.stringify(fullCalibrationData));
-
-    const dashboardKey = `lerobot-calibration-${serialNumber}`;
-    localStorage.setItem(dashboardKey, JSON.stringify(metadata));
-
-    console.log(`📊 Dashboard data saved to: ${dashboardKey}`);
-    console.log(`🔧 Full calibration data saved to: ${fullDataKey}`);
-  }
-}
-
-/**
- * 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
  */

src/lerobot/web/find_port.ts

@@ -1,10 +1,35 @@
 /**
  * Browser implementation of find_port using WebSerial API
+ * Clean API with native dialogs and auto-connect modes
  *
- * Provides the same functionality as the Node.js version but adapted for browser environment
- * Uses WebSerial API for serial port detection and user interaction through DOM
+ * Usage Examples:
+ *
+ * // Interactive mode - always returns array
+ * const findProcess = await findPort();
+ * const robotConnections = await findProcess.result;
+ * const robot = robotConnections[0]; // First (and only) robot
+ * await calibrate(robot, options);
+ *
+ * // Auto-connect mode - returns array of all attempted connections
+ * const findProcess = await findPort({
+ *   robotConfigs: [
+ *     { robotType: "so100_follower", robotId: "arm1", serialNumber: "ABC123" },
+ *     { robotType: "so100_leader", robotId: "arm2", serialNumber: "DEF456" }
+ *   ]
+ * });
+ * const robotConnections = await findProcess.result;
+ * for (const robot of robotConnections.filter(r => r.isConnected)) {
+ *   await calibrate(robot, options);
+ * }
+ *
+ * // Store/load from localStorage
+ * localStorage.setItem('myRobots', JSON.stringify(robotConnections));
+ * const storedRobots = JSON.parse(localStorage.getItem('myRobots'));
+ * await calibrate(storedRobots[0], options);
  */
 
+import { getRobotConnectionManager } from "./robot-connection.js";
+
 /**
  * Type definitions for WebSerial API (not yet in all TypeScript libs)
  */
@@ -49,244 +74,298 @@ declare global {
 }
 
 /**
- * Check if WebSerial API is available
+ * Unified robot connection interface used across all functions
+ * This same object works for findPort, calibrate, teleoperate, etc.
+ * Includes all fields needed by demo and other applications
  */
-function isWebSerialSupported(): boolean {
-  return "serial" in navigator;
+export interface RobotConnection {
+  port: SerialPort;
+  name: string; // Display name for UI
+  isConnected: boolean; // Connection status
+  robotType?: "so100_follower" | "so100_leader"; // Optional until user configures
+  robotId?: string; // Optional until user configures
+  serialNumber: string; // Always required for identification
+  error?: string; // Error message if connection failed
+  usbMetadata?: {
+    // USB device information
+    vendorId: string;
+    productId: string;
+    serialNumber: string;
+    manufacturerName: string;
+    productName: string;
+    usbVersionMajor?: number;
+    usbVersionMinor?: number;
+    deviceClass?: number;
+    deviceSubclass?: number;
+    deviceProtocol?: number;
+  };
 }
 
 /**
- * Get all available serial ports (requires user permission)
- * Browser equivalent of Node.js findAvailablePorts()
+ * Minimal robot config for finding/connecting to specific robots
  */
-async function findAvailablePortsWeb(): Promise<SerialPort[]> {
-  if (!isWebSerialSupported()) {
-    throw new Error(
-      "WebSerial API not supported. Please use Chrome/Edge 89+ or Chrome Android 105+"
-    );
-  }
-
-  try {
-    return await navigator.serial.getPorts();
-  } catch (error) {
-    throw new Error(
-      `Failed to get serial ports: ${
-        error instanceof Error ? error.message : error
-      }`
-    );
-  }
+export interface RobotConfig {
+  robotType: "so100_follower" | "so100_leader";
+  robotId: string;
+  serialNumber: string;
 }
 
 /**
- * Format port info for display
- * Mimics the Node.js port listing format
+ * Options for findPort function
  */
-function formatPortInfo(ports: SerialPort[]): string[] {
-  return ports.map((port, index) => {
-    const info = port.getInfo();
-    if (info.usbVendorId && info.usbProductId) {
-      return `Port ${index + 1} (USB:${info.usbVendorId}:${info.usbProductId})`;
-    }
-    return `Port ${index + 1}`;
-  });
+export interface FindPortOptions {
+  // Auto-connect mode: provide robot configs to connect to
+  robotConfigs?: RobotConfig[];
+
+  // Callbacks
+  onMessage?: (message: string) => void;
+  onRequestUserAction?: (
+    message: string,
+    type: "confirm" | "select"
+  ) => Promise<boolean>;
 }
 
 /**
- * Sleep for specified milliseconds
- * Same as Node.js version
+ * Process object returned by findPort
  */
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+export interface FindPortProcess {
+  // Result promise - Always returns RobotConnection[] (consistent API)
+  // Interactive mode: single robot in array
+  // Auto-connect mode: all successfully connected robots in array
+  result: Promise<RobotConnection[]>;
+
+  // Control
+  stop: () => void;
 }
 
 /**
- * Wait for user interaction (button click or similar)
- * Browser equivalent of Node.js readline input()
+ * Check if WebSerial API is available
  */
-function waitForUserAction(message: string): Promise<void> {
-  return new Promise((resolve) => {
-    const modal = document.createElement("div");
-    modal.style.cssText = `
-      position: fixed;
-      top: 0;
-      left: 0;
-      width: 100%;
-      height: 100%;
-      background: rgba(0,0,0,0.5);
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      z-index: 1000;
-    `;
-
-    const dialog = document.createElement("div");
-    dialog.style.cssText = `
-      background: white;
-      padding: 2rem;
-      border-radius: 8px;
-      text-align: center;
-      max-width: 500px;
-      margin: 1rem;
-    `;
-
-    dialog.innerHTML = `
-      <h3>Port Detection</h3>
-      <p style="margin: 1rem 0;">${message}</p>
-      <button id="continue-btn" style="
-        background: #3498db;
-        color: white;
-        border: none;
-        padding: 12px 24px;
-        border-radius: 6px;
-        cursor: pointer;
-        font-size: 1rem;
-      ">Continue</button>
-    `;
-
-    modal.appendChild(dialog);
-    document.body.appendChild(modal);
-
-    const continueBtn = dialog.querySelector(
-      "#continue-btn"
-    ) as HTMLButtonElement;
-    continueBtn.addEventListener("click", () => {
-      document.body.removeChild(modal);
-      resolve();
-    });
-  });
+function isWebSerialSupported(): boolean {
+  return "serial" in navigator;
 }
 
 /**
- * Request permission to access serial ports
+ * Get display name for a port
  */
-async function requestSerialPermission(
-  logger: (message: string) => void
-): Promise<void> {
-  logger("Requesting permission to access serial ports...");
-  logger(
-    'Please select a serial device when prompted, or click "Cancel" if no devices are connected yet.'
-  );
+function getPortDisplayName(port: SerialPort): string {
+  const info = port.getInfo();
+  if (info.usbVendorId && info.usbProductId) {
+    return `USB Device (${info.usbVendorId}:${info.usbProductId})`;
+  }
+  return "Serial Device";
+}
 
+/**
+ * Try to get serial number from a port by opening and reading device info
+ */
+async function getPortSerialNumber(port: SerialPort): Promise<string | null> {
   try {
-    // This will show the browser's serial port selection dialog
-    await navigator.serial.requestPort();
-    logger("✅ Permission granted to access serial ports.");
+    const wasOpen = port.readable !== null;
+
+    // Open port if not already open
+    if (!wasOpen) {
+      await port.open({ baudRate: 1000000 });
+    }
+
+    // For now, we'll return null since reading serial number from STS3215 motors
+    // requires specific protocol implementation. This is a placeholder for future enhancement.
+    // In practice, serial numbers are typically stored in device metadata or configuration.
+
+    // Close port if we opened it
+    if (!wasOpen && port.readable) {
+      await port.close();
+    }
+
+    return null;
   } catch (error) {
-    // User cancelled the dialog - this is OK, they might not have devices connected yet
-    console.log("Permission dialog cancelled:", error);
+    console.warn("Could not read serial number from port:", error);
+    return null;
   }
 }
 
 /**
- * Main find port function for browser
- * Maintains identical UX and messaging to Node.js version
+ * Interactive mode: Show native dialog for port selection
  */
-export async function findPortWeb(
-  logger: (message: string) => void
-): Promise<void> {
-  logger("Finding all available ports for the MotorsBus.");
+async function findPortInteractive(
+  options: FindPortOptions
+): Promise<RobotConnection[]> {
+  const { onMessage } = options;
 
-  // Check WebSerial support
-  if (!isWebSerialSupported()) {
-    throw new Error(
-      "WebSerial API not supported. Please use Chrome/Edge 89+ with HTTPS or localhost."
-    );
-  }
+  onMessage?.("Opening port selection dialog...");
 
-  // Get initial ports (check what we already have access to)
-  let portsBefore: SerialPort[];
   try {
-    portsBefore = await findAvailablePortsWeb();
+    // Use native browser dialog - much better UX than port diffing!
+    const port = await navigator.serial.requestPort();
+
+    // Open the port
+    await port.open({ baudRate: 1000000 });
+
+    const portName = getPortDisplayName(port);
+    onMessage?.(`✅ Connected to ${portName}`);
+
+    // Return unified RobotConnection object in array (consistent API)
+    // In interactive mode, user will need to specify robot details separately
+    return [
+      {
+        port,
+        name: portName,
+        isConnected: true,
+        robotType: "so100_follower", // Default, user can change
+        robotId: "interactive_robot",
+        serialNumber: `interactive_${Date.now()}`,
+      },
+    ];
   } catch (error) {
+    if (
+      error instanceof Error &&
+      (error.message.includes("cancelled") || error.name === "NotAllowedError")
+    ) {
+      throw new Error("Port selection cancelled by user");
+    }
     throw new Error(
-      `Failed to get serial ports: ${
-        error instanceof Error ? error.message : error
-      }`
+      `Failed to select port: ${error instanceof Error ? error.message : error}`
     );
   }
+}
 
-  // If no ports are available, request permission
-  if (portsBefore.length === 0) {
-    logger(
-      "⚠️ No serial ports available. Requesting permission to access devices..."
-    );
-    await requestSerialPermission(logger);
-
-    // Try again after permission request
-    portsBefore = await findAvailablePortsWeb();
-
-    if (portsBefore.length === 0) {
-      throw new Error(
-        'No ports detected. Please connect your devices, use "Show Available Ports" first, or check browser compatibility.'
-      );
+/**
+ * Auto-connect mode: Connect to robots by serial number
+ * Returns all successfully connected robots
+ */
+async function findPortAutoConnect(
+  robotConfigs: RobotConfig[],
+  options: FindPortOptions
+): Promise<RobotConnection[]> {
+  const { onMessage } = options;
+  const results: RobotConnection[] = [];
+
+  onMessage?.(`🔍 Auto-connecting to ${robotConfigs.length} robot(s)...`);
+
+  // Get all available ports
+  const availablePorts = await navigator.serial.getPorts();
+  onMessage?.(`Found ${availablePorts.length} available port(s)`);
+
+  for (const config of robotConfigs) {
+    onMessage?.(`Connecting to ${config.robotId} (${config.serialNumber})...`);
+
+    let connected = false;
+    let matchedPort: SerialPort | null = null;
+    let error: string | undefined;
+
+    try {
+      // For now, we'll try each available port and see if we can connect
+      // In a future enhancement, we could match by actual serial number reading
+      for (const port of availablePorts) {
+        try {
+          // Try to open and use this port
+          const wasOpen = port.readable !== null;
+          if (!wasOpen) {
+            await port.open({ baudRate: 1000000 });
+          }
+
+          // Test connection by trying to communicate
+          const manager = getRobotConnectionManager();
+          await manager.connect(
+            port,
+            config.robotType,
+            config.robotId,
+            config.serialNumber
+          );
+
+          matchedPort = port;
+          connected = true;
+          onMessage?.(`✅ Connected to ${config.robotId}`);
+          break;
+        } catch (portError) {
+          // This port didn't work, try next one
+          console.log(
+            `Port ${getPortDisplayName(port)} didn't match ${config.robotId}:`,
+            portError
+          );
+          continue;
+        }
+      }
+
+      if (!connected) {
+        error = `No matching port found for ${config.robotId} (${config.serialNumber})`;
+        onMessage?.(`❌ ${error}`);
+      }
+    } catch (err) {
+      error = err instanceof Error ? err.message : "Unknown error";
+      onMessage?.(`❌ Failed to connect to ${config.robotId}: ${error}`);
     }
+
+    // Add result (successful or failed)
+    results.push({
+      port: matchedPort!,
+      name: matchedPort ? getPortDisplayName(matchedPort) : "Unknown Port",
+      isConnected: connected,
+      robotType: config.robotType,
+      robotId: config.robotId,
+      serialNumber: config.serialNumber,
+      error,
+    });
   }
 
-  // Show current ports
-  const portsBeforeFormatted = formatPortInfo(portsBefore);
-  logger(
-    `Ports before disconnecting: [${portsBeforeFormatted
-      .map((p) => `'${p}'`)
-      .join(", ")}]`
+  const successCount = results.filter((r) => r.isConnected).length;
+  onMessage?.(
+    `🎯 Connected to ${successCount}/${robotConfigs.length} robot(s)`
   );
 
-  // Ask user to disconnect device
-  logger(
-    "Remove the USB cable from your MotorsBus and press Continue when done."
-  );
-  await waitForUserAction(
-    "Remove the USB cable from your MotorsBus and press Continue when done."
-  );
+  return results;
+}
 
-  // Allow some time for port to be released (equivalent to Python's time.sleep(0.5))
-  await sleep(500);
+/**
+ * Main findPort function - clean API with Two modes:
+ *
+ * Mode 1: Interactive - Returns single RobotConnection
+ * Mode 2: Auto-connect - Returns RobotConnection[]
+ */
+export async function findPort(
+  options: FindPortOptions = {}
+): Promise<FindPortProcess> {
+  // Check WebSerial support
+  if (!isWebSerialSupported()) {
+    throw new Error(
+      "WebSerial API not supported. Please use Chrome/Edge 89+ with HTTPS or localhost."
+    );
+  }
+
+  const { robotConfigs, onMessage } = options;
+  let stopped = false;
+
+  // Determine mode
+  const isAutoConnectMode = robotConfigs && robotConfigs.length > 0;
 
-  // Get ports after disconnection
-  const portsAfter = await findAvailablePortsWeb();
-  const portsAfterFormatted = formatPortInfo(portsAfter);
-  logger(
-    `Ports after disconnecting: [${portsAfterFormatted
-      .map((p) => `'${p}'`)
-      .join(", ")}]`
+  onMessage?.(
+    `🤖 ${
+      isAutoConnectMode ? "Auto-connect" : "Interactive"
+    } port discovery started`
   );
 
-  // Find the difference by comparing port objects directly
-  // This handles cases where multiple devices have the same vendor/product ID
-  const removedPorts = portsBefore.filter((portBefore) => {
-    return !portsAfter.includes(portBefore);
-  });
-
-  // If object comparison fails (e.g., browser creates new objects), fall back to count-based detection
-  if (removedPorts.length === 0 && portsBefore.length > portsAfter.length) {
-    const countDifference = portsBefore.length - portsAfter.length;
-    if (countDifference === 1) {
-      logger(`The port of this MotorsBus is one of the disconnected devices.`);
-      logger(
-        "Note: Exact port identification not possible with identical devices."
-      );
-      logger("Reconnect the USB cable.");
-      return;
-    } else {
-      logger(`${countDifference} ports were removed, but expected exactly 1.`);
-      logger("Please disconnect only one device and try again.");
-      return;
+  // Create result promise
+  const resultPromise = (async () => {
+    if (stopped) {
+      throw new Error("Port discovery was stopped");
     }
-  }
 
-  if (removedPorts.length === 1) {
-    const port = formatPortInfo(removedPorts)[0];
-    logger(`The port of this MotorsBus is '${port}'`);
-    logger("Reconnect the USB cable.");
-  } else if (removedPorts.length === 0) {
-    logger("No difference found, did you remove the USB cable?");
-    logger("Please try again: disconnect one device and click Continue.");
-    return;
-  } else {
-    const portNames = formatPortInfo(removedPorts);
-    throw new Error(
-      `Could not detect the port. More than one port was found (${JSON.stringify(
-        portNames
-      )}).`
-    );
-  }
+    if (isAutoConnectMode) {
+      return await findPortAutoConnect(robotConfigs!, options);
+    } else {
+      return await findPortInteractive(options);
+    }
+  })();
+
+  // Return process object
+  return {
+    result: resultPromise,
+    stop: () => {
+      stopped = true;
+      onMessage?.("🛑 Port discovery stopped");
+    },
+  };
 }
+
+// Export the main function (renamed from findPortWeb)
+export { findPort as findPortWeb }; // Backward compatibility alias

src/lerobot/web/robot-connection.ts

@@ -10,7 +10,7 @@ import {
   readAllMotorPositions as readAllMotorPositionsUtil,
   writeMotorRegister,
   type MotorCommunicationPort,
-} from "./motor-utils.js";
+} from "./utils/motor-communication.js";
 
 export interface RobotConnectionState {
   isConnected: boolean;

src/lerobot/web/robots/so100_config.ts

@@ -0,0 +1,53 @@
+/**
+ * SO-100 specific configuration for web calibration
+ * Matches Node.js SO-100 config structure and Python lerobot exactly
+ */
+
+/**
+ * STS3215 Protocol Configuration for SO-100 devices
+ */
+export const WEB_STS3215_PROTOCOL = {
+  resolution: 4096, // 12-bit resolution (0-4095)
+  homingOffsetAddress: 31, // Address for Homing_Offset register
+  homingOffsetLength: 2, // 2 bytes for Homing_Offset
+  presentPositionAddress: 56, // Address for Present_Position register
+  presentPositionLength: 2, // 2 bytes for Present_Position
+  minPositionLimitAddress: 9, // Address for Min_Position_Limit register
+  minPositionLimitLength: 2, // 2 bytes for Min_Position_Limit
+  maxPositionLimitAddress: 11, // Address for Max_Position_Limit register
+  maxPositionLimitLength: 2, // 2 bytes for Max_Position_Limit
+  signMagnitudeBit: 11, // Bit 11 is sign bit for Homing_Offset encoding
+} as const;
+
+/**
+ * SO-100 Device Configuration
+ * Motor names, IDs, and drive modes for both follower and leader
+ */
+export const SO100_CONFIG = {
+  motorNames: [
+    "shoulder_pan",
+    "shoulder_lift",
+    "elbow_flex",
+    "wrist_flex",
+    "wrist_roll",
+    "gripper",
+  ],
+  motorIds: [1, 2, 3, 4, 5, 6],
+  // Python lerobot uses drive_mode=0 for all SO-100 motors
+  driveModes: [0, 0, 0, 0, 0, 0],
+};
+
+/**
+ * Create SO-100 calibration configuration
+ */
+export function createSO100Config(
+  deviceType: "so100_follower" | "so100_leader"
+) {
+  return {
+    deviceType,
+    motorNames: SO100_CONFIG.motorNames,
+    motorIds: SO100_CONFIG.motorIds,
+    driveModes: SO100_CONFIG.driveModes,
+    protocol: WEB_STS3215_PROTOCOL,
+  };
+}

src/lerobot/web/teleoperate.ts

@@ -58,7 +58,8 @@ export const KEYBOARD_CONTROLS = {
   // Wrist roll and gripper
   q: { motor: "wrist_roll", direction: -1, description: "Wrist roll left" },
   e: { motor: "wrist_roll", direction: 1, description: "Wrist roll right" },
-  " ": { motor: "gripper", direction: 1, description: "Gripper toggle" },
+  o: { motor: "gripper", direction: 1, description: "Gripper open" },
+  c: { motor: "gripper", direction: -1, description: "Gripper close" },
 
   // Emergency stop
   Escape: {

src/lerobot/web/utils/motor-calibration.ts

@@ -0,0 +1,183 @@
+/**
+ * Motor Calibration Utilities
+ * Specialized functions for motor calibration procedures
+ */
+
+import { STS3215_PROTOCOL } from "./sts3215-protocol.js";
+import { encodeSignMagnitude } from "./sign-magnitude.js";
+import {
+  readAllMotorPositions,
+  writeMotorRegister,
+  type MotorCommunicationPort,
+} from "./motor-communication.js";
+
+/**
+ * Reset homing offsets to 0 for all motors (matches Node.js exactly)
+ */
+export async function resetHomingOffsets(
+  port: MotorCommunicationPort,
+  motorIds: number[]
+): Promise<void> {
+  for (let i = 0; i < motorIds.length; i++) {
+    const motorId = motorIds[i];
+
+    try {
+      const packet = new Uint8Array([
+        0xff,
+        0xff,
+        motorId,
+        0x05,
+        0x03,
+        STS3215_PROTOCOL.HOMING_OFFSET_ADDRESS,
+        0x00, // Low byte of 0
+        0x00, // High byte of 0
+        0x00, // Checksum
+      ]);
+
+      const checksum =
+        ~(
+          motorId +
+          0x05 +
+          0x03 +
+          STS3215_PROTOCOL.HOMING_OFFSET_ADDRESS +
+          0x00 +
+          0x00
+        ) & 0xff;
+      packet[8] = checksum;
+
+      await port.write(packet);
+
+      try {
+        await port.read(200);
+      } catch (error) {
+        // Silent - response not required
+      }
+    } catch (error) {
+      throw new Error(`Failed to reset homing offset for motor ${motorId}`);
+    }
+  }
+}
+
+/**
+ * Write homing offsets to motor registers immediately
+ */
+export async function writeHomingOffsetsToMotors(
+  port: MotorCommunicationPort,
+  motorIds: number[],
+  motorNames: string[],
+  homingOffsets: { [motor: string]: number }
+): Promise<void> {
+  for (let i = 0; i < motorIds.length; i++) {
+    const motorId = motorIds[i];
+    const motorName = motorNames[i];
+    const homingOffset = homingOffsets[motorName];
+
+    try {
+      const encodedOffset = encodeSignMagnitude(
+        homingOffset,
+        STS3215_PROTOCOL.SIGN_MAGNITUDE_BIT
+      );
+
+      const packet = new Uint8Array([
+        0xff,
+        0xff,
+        motorId,
+        0x05,
+        0x03,
+        STS3215_PROTOCOL.HOMING_OFFSET_ADDRESS,
+        encodedOffset & 0xff,
+        (encodedOffset >> 8) & 0xff,
+        0x00,
+      ]);
+
+      const checksum =
+        ~(
+          motorId +
+          0x05 +
+          0x03 +
+          STS3215_PROTOCOL.HOMING_OFFSET_ADDRESS +
+          (encodedOffset & 0xff) +
+          ((encodedOffset >> 8) & 0xff)
+        ) & 0xff;
+      packet[8] = checksum;
+
+      await port.write(packet);
+
+      try {
+        await port.read(200);
+      } catch (error) {
+        // Silent - response not required
+      }
+    } catch (error) {
+      throw new Error(`Failed to write homing offset for ${motorName}`);
+    }
+  }
+}
+
+/**
+ * Set homing offsets with immediate writing (matches Node.js exactly)
+ */
+export async function setHomingOffsets(
+  port: MotorCommunicationPort,
+  motorIds: number[],
+  motorNames: string[]
+): Promise<{ [motor: string]: number }> {
+  // Reset existing homing offsets to 0 first
+  await resetHomingOffsets(port, motorIds);
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  // Read positions (which will be true physical positions)
+  const currentPositions = await readAllMotorPositions(port, motorIds);
+  const homingOffsets: { [motor: string]: number } = {};
+
+  const halfTurn = Math.floor((STS3215_PROTOCOL.RESOLUTION - 1) / 2);
+
+  for (let i = 0; i < motorNames.length; i++) {
+    const motorName = motorNames[i];
+    const position = currentPositions[i];
+    homingOffsets[motorName] = position - halfTurn;
+  }
+
+  // Write homing offsets to motors immediately
+  await writeHomingOffsetsToMotors(port, motorIds, motorNames, homingOffsets);
+
+  return homingOffsets;
+}
+
+/**
+ * Write hardware position limits to motors
+ */
+export async function writeHardwarePositionLimits(
+  port: MotorCommunicationPort,
+  motorIds: number[],
+  motorNames: string[],
+  rangeMins: { [motor: string]: number },
+  rangeMaxes: { [motor: string]: number }
+): Promise<void> {
+  for (let i = 0; i < motorIds.length; i++) {
+    const motorId = motorIds[i];
+    const motorName = motorNames[i];
+    const minLimit = rangeMins[motorName];
+    const maxLimit = rangeMaxes[motorName];
+
+    try {
+      // Write Min_Position_Limit register
+      await writeMotorRegister(
+        port,
+        motorId,
+        STS3215_PROTOCOL.MIN_POSITION_LIMIT_ADDRESS,
+        minLimit
+      );
+
+      // Write Max_Position_Limit register
+      await writeMotorRegister(
+        port,
+        motorId,
+        STS3215_PROTOCOL.MAX_POSITION_LIMIT_ADDRESS,
+        maxLimit
+      );
+    } catch (error) {
+      throw new Error(`Failed to write position limits for ${motorName}`);
+    }
+  }
+}

src/lerobot/web/{motor-utils.ts → utils/motor-communication.ts}

@@ -1,40 +1,22 @@
 /**
- * Shared Motor Communication Utilities
- * Proven patterns from calibrate.ts for consistent motor communication
- * Used by both calibration and teleoperation
+ * Motor Communication Utilities
+ * Proven patterns for STS3215 motor reading and writing operations
  */
 
+import { STS3215_PROTOCOL } from "./sts3215-protocol.js";
+
+/**
+ * Interface for motor communication port
+ * Compatible with both WebSerialPortWrapper and RobotConnectionManager
+ */
 export interface MotorCommunicationPort {
   write(data: Uint8Array): Promise<void>;
   read(timeout?: number): Promise<Uint8Array>;
 }
 
-/**
- * STS3215 Protocol Constants
- * Single source of truth for all motor communication
- */
-export const STS3215_PROTOCOL = {
-  // Register addresses
-  PRESENT_POSITION_ADDRESS: 56,
-  GOAL_POSITION_ADDRESS: 42,
-  HOMING_OFFSET_ADDRESS: 31,
-  MIN_POSITION_LIMIT_ADDRESS: 9,
-  MAX_POSITION_LIMIT_ADDRESS: 11,
-
-  // Protocol constants
-  RESOLUTION: 4096, // 12-bit resolution (0-4095)
-  SIGN_MAGNITUDE_BIT: 11, // Bit 11 is sign bit for Homing_Offset encoding
-
-  // Communication timing (proven from calibration)
-  WRITE_TO_READ_DELAY: 10,
-  RETRY_DELAY: 20,
-  INTER_MOTOR_DELAY: 10,
-  MAX_RETRIES: 3,
-} as const;
-
 /**
  * Read single motor position with PROVEN retry logic
- * Reuses exact patterns from calibrate.ts
+ * Extracted from calibrate.ts with all proven timing and retry patterns
  */
 export async function readMotorPosition(
   port: MotorCommunicationPort,
@@ -94,13 +76,7 @@ export async function readMotorPosition(
           if (id === motorId && error === 0) {
             const position = response[5] | (response[6] << 8);
             return position;
-          } else if (id === motorId && error !== 0) {
-            // Motor error, retry
-          } else {
-            // Wrong response ID, retry
           }
-        } else {
-          // Short response, retry
         }
       } catch (readError) {
         // Read timeout, retry
@@ -117,7 +93,6 @@ export async function readMotorPosition(
     // If all attempts failed, return null
     return null;
   } catch (error) {
-    console.warn(`Failed to read motor ${motorId} position:`, error);
     return null;
   }
 }
@@ -155,7 +130,7 @@ export async function readAllMotorPositions(
 }
 
 /**
- * Write motor position with error handling
+ * Write motor goal position
  */
 export async function writeMotorPosition(
   port: MotorCommunicationPort,
@@ -237,30 +212,71 @@ export async function writeMotorRegister(
 }
 
 /**
- * Sign-magnitude encoding functions (from calibrate.ts)
+ * Lock a motor (motor will hold its position and resist movement)
+ */
+export async function lockMotor(
+  port: MotorCommunicationPort,
+  motorId: number
+): Promise<void> {
+  await writeMotorRegister(
+    port,
+    motorId,
+    STS3215_PROTOCOL.TORQUE_ENABLE_ADDRESS,
+    1
+  );
+  // Small delay for command processing
+  await new Promise((resolve) =>
+    setTimeout(resolve, STS3215_PROTOCOL.WRITE_TO_READ_DELAY)
+  );
+}
+
+/**
+ * Release a motor (motor can be moved freely by hand)
  */
-export function encodeSignMagnitude(
-  value: number,
-  signBitIndex: number = STS3215_PROTOCOL.SIGN_MAGNITUDE_BIT
-): number {
-  const maxMagnitude = (1 << signBitIndex) - 1;
-  const magnitude = Math.abs(value);
+export async function releaseMotor(
+  port: MotorCommunicationPort,
+  motorId: number
+): Promise<void> {
+  await writeMotorRegister(
+    port,
+    motorId,
+    STS3215_PROTOCOL.TORQUE_ENABLE_ADDRESS,
+    0
+  );
+  // Small delay for command processing
+  await new Promise((resolve) =>
+    setTimeout(resolve, STS3215_PROTOCOL.WRITE_TO_READ_DELAY)
+  );
+}
 
-  if (magnitude > maxMagnitude) {
-    throw new Error(
-      `Magnitude ${magnitude} exceeds ${maxMagnitude} (max for signBitIndex=${signBitIndex})`
+/**
+ * Release motors (motors can be moved freely - perfect for calibration)
+ */
+export async function releaseMotors(
+  port: MotorCommunicationPort,
+  motorIds: number[]
+): Promise<void> {
+  for (const motorId of motorIds) {
+    await releaseMotor(port, motorId);
+    // Small delay between motors
+    await new Promise((resolve) =>
+      setTimeout(resolve, STS3215_PROTOCOL.INTER_MOTOR_DELAY)
     );
   }
-
-  const directionBit = value < 0 ? 1 : 0;
-  return (directionBit << signBitIndex) | magnitude;
 }
 
-export function decodeSignMagnitude(
-  encodedValue: number,
-  signBitIndex: number = STS3215_PROTOCOL.SIGN_MAGNITUDE_BIT
-): number {
-  const signBit = (encodedValue >> signBitIndex) & 1;
-  const magnitude = encodedValue & ((1 << signBitIndex) - 1);
-  return signBit ? -magnitude : magnitude;
+/**
+ * Lock motors (motors will hold their positions - perfect after calibration)
+ */
+export async function lockMotors(
+  port: MotorCommunicationPort,
+  motorIds: number[]
+): Promise<void> {
+  for (const motorId of motorIds) {
+    await lockMotor(port, motorId);
+    // Small delay between motors
+    await new Promise((resolve) =>
+      setTimeout(resolve, STS3215_PROTOCOL.INTER_MOTOR_DELAY)
+    );
+  }
 }

src/lerobot/web/utils/serial-port-wrapper.ts

@@ -0,0 +1,72 @@
+/**
+ * Web Serial Port Wrapper
+ * Standardized Web Serial API interface with immediate lock release
+ */
+
+/**
+ * Web Serial Port wrapper - direct write/read with immediate lock release
+ * Follows Chrome documentation exactly for proper Web Serial API usage
+ */
+export class WebSerialPortWrapper {
+  private port: SerialPort;
+
+  constructor(port: SerialPort) {
+    this.port = port;
+  }
+
+  get isOpen(): boolean {
+    return (
+      this.port !== null &&
+      this.port.readable !== null &&
+      this.port.writable !== null
+    );
+  }
+
+  async initialize(): Promise<void> {
+    if (!this.port.readable || !this.port.writable) {
+      throw new Error("Port is not open for reading/writing");
+    }
+  }
+
+  async write(data: Uint8Array): Promise<void> {
+    if (!this.port.writable) {
+      throw new Error("Port not open for writing");
+    }
+
+    const writer = this.port.writable.getWriter();
+    try {
+      await writer.write(data);
+    } finally {
+      writer.releaseLock();
+    }
+  }
+
+  async read(timeout: number = 1000): Promise<Uint8Array> {
+    if (!this.port.readable) {
+      throw new Error("Port not open for reading");
+    }
+
+    const reader = this.port.readable.getReader();
+
+    try {
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new Error("Read timeout")), timeout);
+      });
+
+      const result = await Promise.race([reader.read(), timeoutPromise]);
+      const { value, done } = result;
+
+      if (done || !value) {
+        throw new Error("Read failed - port closed or no data");
+      }
+
+      return new Uint8Array(value);
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  async close(): Promise<void> {
+    // Don't close the port itself - just wrapper cleanup
+  }
+}

src/lerobot/web/utils/sign-magnitude.ts

@@ -0,0 +1,41 @@
+/**
+ * Sign-Magnitude Encoding Utilities
+ * For STS3215 motor homing offset encoding/decoding
+ */
+
+import { STS3215_PROTOCOL } from "./sts3215-protocol.js";
+
+/**
+ * Encode a signed integer using sign-magnitude format
+ * Bit at sign_bit_index represents sign (0=positive, 1=negative)
+ * Lower bits represent magnitude
+ */
+export function encodeSignMagnitude(
+  value: number,
+  signBitIndex: number = STS3215_PROTOCOL.SIGN_MAGNITUDE_BIT
+): number {
+  const maxMagnitude = (1 << signBitIndex) - 1;
+  const magnitude = Math.abs(value);
+
+  if (magnitude > maxMagnitude) {
+    throw new Error(
+      `Magnitude ${magnitude} exceeds ${maxMagnitude} (max for signBitIndex=${signBitIndex})`
+    );
+  }
+
+  const directionBit = value < 0 ? 1 : 0;
+  return (directionBit << signBitIndex) | magnitude;
+}
+
+/**
+ * Decode a sign-magnitude encoded value back to signed integer
+ * Extracts sign bit and magnitude, then applies sign
+ */
+export function decodeSignMagnitude(
+  encodedValue: number,
+  signBitIndex: number = STS3215_PROTOCOL.SIGN_MAGNITUDE_BIT
+): number {
+  const signBit = (encodedValue >> signBitIndex) & 1;
+  const magnitude = encodedValue & ((1 << signBitIndex) - 1);
+  return signBit ? -magnitude : magnitude;
+}

src/lerobot/web/utils/sts3215-protocol.ts

@@ -0,0 +1,34 @@
+/**
+ * STS3215 Protocol Constants and Configuration
+ * Single source of truth for all STS3215 motor communication
+ */
+
+/**
+ * STS3215 Protocol Configuration
+ * Register addresses, timing, and communication constants
+ */
+export const STS3215_PROTOCOL = {
+  // Register addresses
+  PRESENT_POSITION_ADDRESS: 56,
+  GOAL_POSITION_ADDRESS: 42,
+  HOMING_OFFSET_ADDRESS: 31,
+  MIN_POSITION_LIMIT_ADDRESS: 9,
+  MAX_POSITION_LIMIT_ADDRESS: 11,
+  TORQUE_ENABLE_ADDRESS: 40, // Torque Enable register (0=disable, 1=enable)
+
+  // Protocol constants
+  RESOLUTION: 4096, // 12-bit resolution (0-4095)
+  SIGN_MAGNITUDE_BIT: 11, // Bit 11 is sign bit for Homing_Offset encoding
+
+  // Data lengths
+  HOMING_OFFSET_LENGTH: 2,
+  PRESENT_POSITION_LENGTH: 2,
+  MIN_POSITION_LIMIT_LENGTH: 2,
+  MAX_POSITION_LIMIT_LENGTH: 2,
+
+  // Communication timing (proven from calibration)
+  WRITE_TO_READ_DELAY: 10,
+  RETRY_DELAY: 20,
+  INTER_MOTOR_DELAY: 10,
+  MAX_RETRIES: 3,
+} as const;

tsconfig.json

@@ -6,6 +6,9 @@
     "lib": ["ES2020", "DOM", "DOM.Iterable"],
     "skipLibCheck": true,
 
+    /* React */
+    "jsx": "react-jsx",
+
     /* Bundler mode */
     "moduleResolution": "bundler",
     "allowImportingTsExtensions": true,