feat: remove unused code, apply DRY

docs/api-comparison.md

@@ -1,194 +0,0 @@
-# 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.

src/demo/App.tsx

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

src/demo/components/CalibrationPanel.tsx

@@ -18,7 +18,7 @@ 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 { RobotConnection } from "../../lerobot/web/find_port.js";
+import type { RobotConnection } from "../../lerobot/web/types/robot-connection.js";
 
 interface CalibrationPanelProps {
   robot: RobotConnection;
@@ -104,16 +104,8 @@ export function CalibrationPanel({ robot, onFinish }: CalibrationPanelProps) {
       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, {
+      // Use the simple calibrate API - just pass the robot connection
+      const process = await calibrate(robot, {
         onLiveUpdate: (data) => {
           setMotorData(data);
           setStatus(

src/demo/components/PortManager.tsx

@@ -18,7 +18,7 @@ import {
   DialogTitle,
 } from "./ui/dialog";
 import { isWebSerialSupported } from "../../lerobot/web/calibrate";
-import type { RobotConnection } from "../../lerobot/web/find_port.js";
+import type { RobotConnection } from "../../lerobot/web/types/robot-connection.js";
 
 /**
  * Type definitions for WebSerial API (missing from TypeScript)

src/demo/components/TeleoperationPanel.tsx

@@ -1,12 +1,17 @@
-import React, { useState } from "react";
+import React, { useState, useEffect, useRef, useCallback } from "react";
 import { Button } from "./ui/button";
 import { Card, CardContent, CardHeader, CardTitle } from "./ui/card";
 import { Badge } from "./ui/badge";
 import { Alert, AlertDescription } from "./ui/alert";
 import { Progress } from "./ui/progress";
-import { useTeleoperation } from "../hooks/useTeleoperation";
-import type { RobotConnection } from "../../lerobot/web/find_port.js";
-import { KEYBOARD_CONTROLS } from "../../lerobot/web/teleoperate";
+import {
+  teleoperate,
+  type TeleoperationProcess,
+  type TeleoperationState,
+} from "../../lerobot/web/teleoperate.js";
+import { getUnifiedRobotData } from "../lib/unified-storage";
+import type { RobotConnection } from "../../lerobot/web/types/robot-connection.js";
+import { SO100_KEYBOARD_CONTROLS } from "../../lerobot/web/robots/so100_config.js";
 
 interface TeleoperationPanelProps {
   robot: RobotConnection;
@@ -17,41 +22,171 @@ export function TeleoperationPanel({
   robot,
   onClose,
 }: TeleoperationPanelProps) {
-  const [enabled, setEnabled] = useState(false);
-
-  const {
-    isConnected,
-    isActive,
-    motorConfigs,
-    keyStates,
-    error,
-    start,
-    stop,
-    simulateKeyPress,
-    simulateKeyRelease,
-    moveMotorToPosition,
-  } = useTeleoperation({
-    robot,
-    enabled,
-    onError: (err: string) => console.error("Teleoperation error:", err),
-  });
-
-  const handleStart = async () => {
-    setEnabled(true);
-    await start();
+  const [teleoperationState, setTeleoperationState] =
+    useState<TeleoperationState>({
+      isActive: false,
+      motorConfigs: [],
+      lastUpdate: 0,
+      keyStates: {},
+    });
+  const [error, setError] = useState<string | null>(null);
+  const [isInitialized, setIsInitialized] = useState(false);
+
+  const teleoperationProcessRef = useRef<TeleoperationProcess | null>(null);
+
+  // Initialize teleoperation process
+  useEffect(() => {
+    const initializeTeleoperation = async () => {
+      if (!robot || !robot.robotType) {
+        setError("No robot configuration available");
+        return;
+      }
+
+      try {
+        // Load calibration data from demo storage (app concern)
+        let calibrationData;
+        if (robot.serialNumber) {
+          const data = getUnifiedRobotData(robot.serialNumber);
+          calibrationData = data?.calibration;
+          if (calibrationData) {
+            console.log("✅ Loaded calibration data for", robot.serialNumber);
+          }
+        }
+
+        // Create teleoperation process using clean library API
+        const process = await teleoperate(robot, {
+          calibrationData,
+          onStateUpdate: (state: TeleoperationState) => {
+            setTeleoperationState(state);
+          },
+        });
+
+        teleoperationProcessRef.current = process;
+        setTeleoperationState(process.getState());
+        setIsInitialized(true);
+        setError(null);
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error
+            ? error.message
+            : "Failed to initialize teleoperation";
+        setError(errorMessage);
+        console.error("❌ Failed to initialize teleoperation:", error);
+      }
+    };
+
+    initializeTeleoperation();
+
+    return () => {
+      // Cleanup on unmount
+      if (teleoperationProcessRef.current) {
+        teleoperationProcessRef.current.disconnect();
+        teleoperationProcessRef.current = null;
+      }
+    };
+  }, [robot]);
+
+  // Keyboard event handlers
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (!teleoperationState.isActive || !teleoperationProcessRef.current)
+        return;
+
+      const key = event.key;
+      event.preventDefault();
+      teleoperationProcessRef.current.updateKeyState(key, true);
+    },
+    [teleoperationState.isActive]
+  );
+
+  const handleKeyUp = useCallback(
+    (event: KeyboardEvent) => {
+      if (!teleoperationState.isActive || !teleoperationProcessRef.current)
+        return;
+
+      const key = event.key;
+      event.preventDefault();
+      teleoperationProcessRef.current.updateKeyState(key, false);
+    },
+    [teleoperationState.isActive]
+  );
+
+  // Register keyboard events
+  useEffect(() => {
+    if (teleoperationState.isActive) {
+      window.addEventListener("keydown", handleKeyDown);
+      window.addEventListener("keyup", handleKeyUp);
+
+      return () => {
+        window.removeEventListener("keydown", handleKeyDown);
+        window.removeEventListener("keyup", handleKeyUp);
+      };
+    }
+  }, [teleoperationState.isActive, handleKeyDown, handleKeyUp]);
+
+  const handleStart = () => {
+    if (!teleoperationProcessRef.current) {
+      setError("Teleoperation not initialized");
+      return;
+    }
+
+    try {
+      teleoperationProcessRef.current.start();
+      console.log("🎮 Teleoperation started");
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error
+          ? error.message
+          : "Failed to start teleoperation";
+      setError(errorMessage);
+    }
   };
 
   const handleStop = () => {
-    stop();
-    setEnabled(false);
+    if (!teleoperationProcessRef.current) return;
+
+    teleoperationProcessRef.current.stop();
+    console.log("🛑 Teleoperation stopped");
   };
 
   const handleClose = () => {
-    stop();
-    setEnabled(false);
+    if (teleoperationProcessRef.current) {
+      teleoperationProcessRef.current.stop();
+    }
     onClose();
   };
 
+  const simulateKeyPress = (key: string) => {
+    if (!teleoperationProcessRef.current) return;
+    teleoperationProcessRef.current.updateKeyState(key, true);
+  };
+
+  const simulateKeyRelease = (key: string) => {
+    if (!teleoperationProcessRef.current) return;
+    teleoperationProcessRef.current.updateKeyState(key, false);
+  };
+
+  const moveMotorToPosition = async (motorIndex: number, position: number) => {
+    if (!teleoperationProcessRef.current) return;
+
+    try {
+      const motorName = teleoperationState.motorConfigs[motorIndex]?.name;
+      if (motorName) {
+        await teleoperationProcessRef.current.moveMotor(motorName, position);
+      }
+    } catch (error) {
+      console.warn(
+        `Failed to move motor ${motorIndex + 1} to position ${position}:`,
+        error
+      );
+    }
+  };
+
+  const isConnected = robot?.isConnected || false;
+  const isActive = teleoperationState.isActive;
+  const motorConfigs = teleoperationState.motorConfigs;
+  const keyStates = teleoperationState.keyStates;
+
   // Virtual keyboard component
   const VirtualKeyboard = () => {
     const isKeyPressed = (key: string) => {
@@ -70,7 +205,9 @@ export function TeleoperationPanel({
       size?: "default" | "sm" | "lg" | "icon";
     }) => {
       const control =
-        KEYBOARD_CONTROLS[keyCode as keyof typeof KEYBOARD_CONTROLS];
+        SO100_KEYBOARD_CONTROLS[
+          keyCode as keyof typeof SO100_KEYBOARD_CONTROLS
+        ];
       const pressed = isKeyPressed(keyCode);
 
       return (

src/demo/hooks/useTeleoperation.ts

@@ -1,518 +0,0 @@
-import { useState, useEffect, useCallback, useRef } from "react";
-import { useRobotConnection } from "./useRobotConnection";
-import { getUnifiedRobotData } from "../lib/unified-storage";
-import type { RobotConnection } from "../../lerobot/web/find_port.js";
-
-export interface MotorConfig {
-  name: string;
-  minPosition: number;
-  maxPosition: number;
-  currentPosition: number;
-  homePosition: number;
-}
-
-export interface KeyState {
-  pressed: boolean;
-  lastPressed: number;
-}
-
-export interface UseTeleoperationOptions {
-  robot: RobotConnection;
-  enabled: boolean;
-  onError?: (error: string) => void;
-}
-
-export interface UseTeleoperationResult {
-  // Connection state from singleton
-  isConnected: boolean;
-  isActive: boolean;
-
-  // Motor state
-  motorConfigs: MotorConfig[];
-
-  // Keyboard state
-  keyStates: Record<string, KeyState>;
-
-  // Error state
-  error: string | null;
-
-  // Control methods
-  start: () => void;
-  stop: () => void;
-  goToHome: () => Promise<void>;
-  simulateKeyPress: (key: string) => void;
-  simulateKeyRelease: (key: string) => void;
-  moveMotorToPosition: (motorIndex: number, position: number) => Promise<void>;
-}
-
-const MOTOR_CONFIGS: MotorConfig[] = [
-  {
-    name: "shoulder_pan",
-    minPosition: 0,
-    maxPosition: 4095,
-    currentPosition: 2048,
-    homePosition: 2048,
-  },
-  {
-    name: "shoulder_lift",
-    minPosition: 1024,
-    maxPosition: 3072,
-    currentPosition: 2048,
-    homePosition: 2048,
-  },
-  {
-    name: "elbow_flex",
-    minPosition: 1024,
-    maxPosition: 3072,
-    currentPosition: 2048,
-    homePosition: 2048,
-  },
-  {
-    name: "wrist_flex",
-    minPosition: 1024,
-    maxPosition: 3072,
-    currentPosition: 2048,
-    homePosition: 2048,
-  },
-  {
-    name: "wrist_roll",
-    minPosition: 0,
-    maxPosition: 4095,
-    currentPosition: 2048,
-    homePosition: 2048,
-  },
-  {
-    name: "gripper",
-    minPosition: 1800,
-    maxPosition: 2400,
-    currentPosition: 2100,
-    homePosition: 2100,
-  },
-];
-
-// PROVEN VALUES from Node.js implementation (conventions.md)
-const SMOOTH_CONTROL_CONFIG = {
-  STEP_SIZE: 25, // Proven optimal from conventions.md
-  CHANGE_THRESHOLD: 0.5, // Prevents micro-movements and unnecessary commands
-  MOTOR_DELAY: 1, // Minimal delay between motor commands (from conventions.md)
-  UPDATE_INTERVAL: 30, // 30ms = ~33Hz for responsive control (was 50ms = 20Hz)
-} as const;
-
-const KEYBOARD_CONTROLS = {
-  ArrowUp: { motorIndex: 1, direction: 1, description: "Shoulder lift up" },
-  ArrowDown: {
-    motorIndex: 1,
-    direction: -1,
-    description: "Shoulder lift down",
-  },
-  ArrowLeft: { motorIndex: 0, direction: -1, description: "Shoulder pan left" },
-  ArrowRight: {
-    motorIndex: 0,
-    direction: 1,
-    description: "Shoulder pan right",
-  },
-  w: { motorIndex: 2, direction: 1, description: "Elbow flex up" },
-  s: { motorIndex: 2, direction: -1, description: "Elbow flex down" },
-  a: { motorIndex: 3, direction: -1, description: "Wrist flex left" },
-  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" },
-  o: { motorIndex: 5, direction: 1, description: "Gripper open" },
-  c: { motorIndex: 5, direction: -1, description: "Gripper close" },
-  Escape: { motorIndex: -1, direction: 0, description: "Emergency stop" },
-};
-
-export function useTeleoperation({
-  robot,
-  enabled,
-  onError,
-}: UseTeleoperationOptions): UseTeleoperationResult {
-  const connection = useRobotConnection();
-  const [isActive, setIsActive] = useState(false);
-  const [motorConfigs, setMotorConfigs] =
-    useState<MotorConfig[]>(MOTOR_CONFIGS);
-  const [keyStates, setKeyStates] = useState<Record<string, KeyState>>({});
-  const [error, setError] = useState<string | null>(null);
-
-  const activeKeysRef = useRef<Set<string>>(new Set());
-  const motorPositionsRef = useRef<number[]>(
-    MOTOR_CONFIGS.map((m) => m.homePosition)
-  );
-  const movementIntervalRef = useRef<NodeJS.Timeout | null>(null);
-
-  // Load calibration data
-  useEffect(() => {
-    const loadCalibration = async () => {
-      try {
-        if (!robot.serialNumber) {
-          console.warn("No serial number available for calibration loading");
-          return;
-        }
-
-        const data = getUnifiedRobotData(robot.serialNumber);
-        if (data?.calibration) {
-          // Map motor names to calibration data
-          const motorNames = [
-            "shoulder_pan",
-            "shoulder_lift",
-            "elbow_flex",
-            "wrist_flex",
-            "wrist_roll",
-            "gripper",
-          ];
-          const calibratedConfigs = MOTOR_CONFIGS.map((config, index) => {
-            const motorName = motorNames[index] as keyof NonNullable<
-              typeof data.calibration
-            >;
-            const calibratedMotor = data.calibration![motorName];
-            if (
-              calibratedMotor &&
-              typeof calibratedMotor === "object" &&
-              "homing_offset" in calibratedMotor &&
-              "range_min" in calibratedMotor &&
-              "range_max" in calibratedMotor
-            ) {
-              // Use 2048 as default home position, adjusted by homing offset
-              const homePosition = 2048 + (calibratedMotor.homing_offset || 0);
-              return {
-                ...config,
-                homePosition,
-                currentPosition: homePosition,
-                // IMPORTANT: Use actual calibrated limits instead of hardcoded ones
-                minPosition: calibratedMotor.range_min || config.minPosition,
-                maxPosition: calibratedMotor.range_max || config.maxPosition,
-              };
-            }
-            return config;
-          });
-          setMotorConfigs(calibratedConfigs);
-          // DON'T set motorPositionsRef here - it will be set when teleoperation starts
-          // motorPositionsRef.current = calibratedConfigs.map((m) => m.homePosition);
-          console.log("✅ Loaded calibration data for", robot.serialNumber);
-        }
-      } catch (error) {
-        console.warn("Failed to load calibration:", error);
-      }
-    };
-
-    loadCalibration();
-  }, [robot.serialNumber]);
-
-  // Keyboard event handlers
-  const handleKeyDown = useCallback(
-    (event: KeyboardEvent) => {
-      if (!isActive) return;
-
-      const key = event.key;
-      if (key in KEYBOARD_CONTROLS) {
-        event.preventDefault();
-
-        if (key === "Escape") {
-          setIsActive(false);
-          activeKeysRef.current.clear();
-          return;
-        }
-
-        if (!activeKeysRef.current.has(key)) {
-          activeKeysRef.current.add(key);
-          setKeyStates((prev) => ({
-            ...prev,
-            [key]: { pressed: true, lastPressed: Date.now() },
-          }));
-        }
-      }
-    },
-    [isActive]
-  );
-
-  const handleKeyUp = useCallback(
-    (event: KeyboardEvent) => {
-      if (!isActive) return;
-
-      const key = event.key;
-      if (key in KEYBOARD_CONTROLS) {
-        event.preventDefault();
-        activeKeysRef.current.delete(key);
-        setKeyStates((prev) => ({
-          ...prev,
-          [key]: { pressed: false, lastPressed: Date.now() },
-        }));
-      }
-    },
-    [isActive]
-  );
-
-  // Register keyboard events
-  useEffect(() => {
-    if (enabled && isActive) {
-      window.addEventListener("keydown", handleKeyDown);
-      window.addEventListener("keyup", handleKeyUp);
-
-      return () => {
-        window.removeEventListener("keydown", handleKeyDown);
-        window.removeEventListener("keyup", handleKeyUp);
-      };
-    }
-  }, [enabled, isActive, handleKeyDown, handleKeyUp]);
-
-  // CONTINUOUS MOVEMENT: For held keys with PROVEN smooth patterns from Node.js
-  useEffect(() => {
-    if (!isActive || !connection.isConnected) {
-      if (movementIntervalRef.current) {
-        clearInterval(movementIntervalRef.current);
-        movementIntervalRef.current = null;
-      }
-      return;
-    }
-
-    const processMovement = async () => {
-      if (activeKeysRef.current.size === 0) return;
-
-      const activeKeys = Array.from(activeKeysRef.current);
-      const changedMotors: Array<{ index: number; position: number }> = [];
-
-      // PROVEN PATTERN: Process all active keys and collect changes
-      for (const key of activeKeys) {
-        const control =
-          KEYBOARD_CONTROLS[key as keyof typeof KEYBOARD_CONTROLS];
-        if (control && control.motorIndex >= 0) {
-          const motorIndex = control.motorIndex;
-          const direction = control.direction;
-          const motor = motorConfigs[motorIndex];
-
-          if (motor) {
-            const currentPos = motorPositionsRef.current[motorIndex];
-            let newPos =
-              currentPos + direction * SMOOTH_CONTROL_CONFIG.STEP_SIZE;
-
-            // Clamp to motor limits
-            newPos = Math.max(
-              motor.minPosition,
-              Math.min(motor.maxPosition, newPos)
-            );
-
-            // PROVEN PATTERN: Only update if change is meaningful (0.5 unit threshold)
-            if (
-              Math.abs(newPos - currentPos) >
-              SMOOTH_CONTROL_CONFIG.CHANGE_THRESHOLD
-            ) {
-              motorPositionsRef.current[motorIndex] = newPos;
-              changedMotors.push({ index: motorIndex, position: newPos });
-            }
-          }
-        }
-      }
-
-      // PROVEN PATTERN: Only send commands for motors that actually changed
-      if (changedMotors.length > 0) {
-        try {
-          for (const { index, position } of changedMotors) {
-            await connection.writeMotorPosition(index + 1, position);
-
-            // PROVEN PATTERN: Minimal delay between motor commands (1ms)
-            if (changedMotors.length > 1) {
-              await new Promise((resolve) =>
-                setTimeout(resolve, SMOOTH_CONTROL_CONFIG.MOTOR_DELAY)
-              );
-            }
-          }
-
-          // Update UI to reflect changes
-          setMotorConfigs((prev) =>
-            prev.map((config, index) => ({
-              ...config,
-              currentPosition: motorPositionsRef.current[index],
-            }))
-          );
-        } catch (error) {
-          console.warn("Failed to update robot positions:", error);
-        }
-      }
-    };
-
-    // PROVEN TIMING: 30ms interval (~33Hz) for responsive continuous movement
-    movementIntervalRef.current = setInterval(
-      processMovement,
-      SMOOTH_CONTROL_CONFIG.UPDATE_INTERVAL
-    );
-
-    return () => {
-      if (movementIntervalRef.current) {
-        clearInterval(movementIntervalRef.current);
-        movementIntervalRef.current = null;
-      }
-    };
-  }, [
-    isActive,
-    connection.isConnected,
-    connection.writeMotorPosition,
-    motorConfigs,
-  ]);
-
-  // Control methods
-  const start = useCallback(async () => {
-    if (!connection.isConnected) {
-      setError("Robot not connected");
-      onError?.("Robot not connected");
-      return;
-    }
-
-    try {
-      console.log(
-        "🎮 Starting teleoperation - reading current motor positions..."
-      );
-
-      // Read current positions of all motors using PROVEN utility
-      const motorIds = [1, 2, 3, 4, 5, 6];
-      const currentPositions = await connection.readAllMotorPositions(motorIds);
-
-      // Log all positions (trust the utility's fallback handling)
-      for (let i = 0; i < currentPositions.length; i++) {
-        const position = currentPositions[i];
-        console.log(`📍 Motor ${i + 1} current position: ${position}`);
-      }
-
-      // CRITICAL: Update positions BEFORE activating movement
-      motorPositionsRef.current = currentPositions;
-
-      // Update UI to show actual current positions
-      setMotorConfigs((prev) =>
-        prev.map((config, index) => ({
-          ...config,
-          currentPosition: currentPositions[index],
-        }))
-      );
-
-      // IMPORTANT: Only activate AFTER positions are synchronized
-      setIsActive(true);
-      setError(null);
-      console.log(
-        "✅ Teleoperation started with synchronized positions:",
-        currentPositions
-      );
-    } catch (error) {
-      const errorMessage =
-        error instanceof Error
-          ? error.message
-          : "Failed to start teleoperation";
-      setError(errorMessage);
-      onError?.(errorMessage);
-      console.error("❌ Failed to start teleoperation:", error);
-    }
-  }, [
-    connection.isConnected,
-    connection.readAllMotorPositions,
-    motorConfigs,
-    onError,
-  ]);
-
-  const stop = useCallback(() => {
-    setIsActive(false);
-    activeKeysRef.current.clear();
-    setKeyStates({});
-    console.log("🛑 Teleoperation stopped");
-  }, []);
-
-  const goToHome = useCallback(async () => {
-    if (!connection.isConnected) {
-      setError("Robot not connected");
-      return;
-    }
-
-    try {
-      for (let i = 0; i < motorConfigs.length; i++) {
-        const motor = motorConfigs[i];
-        await connection.writeMotorPosition(i + 1, motor.homePosition);
-        motorPositionsRef.current[i] = motor.homePosition;
-      }
-
-      setMotorConfigs((prev) =>
-        prev.map((config) => ({
-          ...config,
-          currentPosition: config.homePosition,
-        }))
-      );
-
-      console.log("🏠 Moved to home position");
-    } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : "Failed to go to home";
-      setError(errorMessage);
-      onError?.(errorMessage);
-    }
-  }, [
-    connection.isConnected,
-    connection.writeMotorPosition,
-    motorConfigs,
-    onError,
-  ]);
-
-  const simulateKeyPress = useCallback(
-    (key: string) => {
-      if (!isActive) return;
-
-      activeKeysRef.current.add(key);
-      setKeyStates((prev) => ({
-        ...prev,
-        [key]: { pressed: true, lastPressed: Date.now() },
-      }));
-    },
-    [isActive]
-  );
-
-  const simulateKeyRelease = useCallback(
-    (key: string) => {
-      if (!isActive) return;
-
-      activeKeysRef.current.delete(key);
-      setKeyStates((prev) => ({
-        ...prev,
-        [key]: { pressed: false, lastPressed: Date.now() },
-      }));
-    },
-    [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,
-    motorConfigs,
-    keyStates,
-    error,
-    start,
-    stop,
-    goToHome,
-    simulateKeyPress,
-    simulateKeyRelease,
-    moveMotorToPosition,
-  };
-}

src/demo/pages/Home.tsx

@@ -12,7 +12,7 @@ import { PortManager } from "../components/PortManager";
 import { CalibrationPanel } from "../components/CalibrationPanel";
 import { TeleoperationPanel } from "../components/TeleoperationPanel";
 import { isWebSerialSupported } from "../../lerobot/web/calibrate";
-import type { RobotConnection } from "../../lerobot/web/find_port.js";
+import type { RobotConnection } from "../../lerobot/web/types/robot-connection.js";
 
 interface HomeProps {
   onGetStarted: () => void;

src/lerobot/web/calibrate.ts

@@ -1,14 +1,10 @@
 /**
  * Web calibration functionality using Web Serial API
- * Minimal library - does calibration, user handles storage/UI/etc.
+ * Simple library API - pass in robotConnection, get calibration results
  *
- * 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
+ * Handles different robot types internally - users don't need to know about configs
  */
 
-import { createSO100Config } from "./robots/so100_config.js";
 import { WebSerialPortWrapper } from "./utils/serial-port-wrapper.js";
 import {
   readAllMotorPositions,
@@ -19,33 +15,11 @@ import {
   setHomingOffsets,
   writeHardwarePositionLimits,
 } from "./utils/motor-calibration.js";
-import type { RobotConnection } from "./find_port.js";
-
-/**
- * Device calibration configuration interface
- * Currently designed for SO-100, but can be extended for other robot types
- */
-interface WebCalibrationConfig {
-  deviceType: "so100_follower" | "so100_leader";
-  port: WebSerialPortWrapper;
-  motorNames: string[];
-  motorIds: number[];
-  driveModes: number[];
+import { createSO100Config } from "./robots/so100_config.js";
+import type { RobotConnection } from "./types/robot-connection.js";
 
-  // Protocol-specific configuration
-  protocol: {
-    resolution: number;
-    homingOffsetAddress: number;
-    homingOffsetLength: number;
-    presentPositionAddress: number;
-    presentPositionLength: number;
-    minPositionLimitAddress: number;
-    minPositionLimitLength: number;
-    maxPositionLimitAddress: number;
-    maxPositionLimitLength: number;
-    signMagnitudeBit: number;
-  };
-}
+// Import shared robot hardware configuration interface
+import type { RobotHardwareConfig } from "./types/robot-config.js";
 
 /**
  * Calibration results structure matching Python lerobot format exactly
@@ -149,25 +123,33 @@ async function recordRangesOfMotion(
 }
 
 /**
- * Create SO-100 web configuration
+ * Apply robot-specific range adjustments
+ * Different robot types may have special cases (like continuous rotation motors)
  */
-function createSO100WebConfig(
-  deviceType: "so100_follower" | "so100_leader",
-  port: WebSerialPortWrapper
-): WebCalibrationConfig {
-  const so100Config = createSO100Config(deviceType);
+function applyRobotSpecificRangeAdjustments(
+  robotType: string,
+  protocol: { resolution: number },
+  rangeMins: { [motor: string]: number },
+  rangeMaxes: { [motor: string]: number }
+): void {
+  // SO-100 specific: wrist_roll is a continuous rotation motor
+  if (robotType.startsWith("so100") && rangeMins["wrist_roll"] !== undefined) {
+    // 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"] = protocol.resolution - 1;
+  }
 
-  return {
-    ...so100Config,
-    port,
-  };
+  // Future robot types can add their own specific adjustments here
+  // if (robotType.startsWith('newrobot') && rangeMins["special_joint"] !== undefined) {
+  //   rangeMins["special_joint"] = 0;
+  //   rangeMaxes["special_joint"] = 2048;
+  // }
 }
 
 /**
- * Main calibrate function - minimal library API
- * Currently supports SO-100 robots (follower and leader)
- *
- * Takes a unified RobotConnection object from findPort()
+ * Main calibrate function - simple API, handles robot types internally
  */
 export async function calibrate(
   robotConnection: RobotConnection,
@@ -187,8 +169,13 @@ export async function calibrate(
   const port = new WebSerialPortWrapper(robotConnection.port);
   await port.initialize();
 
-  // Get SO-100 specific calibration configuration
-  const config = createSO100WebConfig(robotConnection.robotType, port);
+  // Get robot-specific configuration (extensible - add new robot types here)
+  let config: RobotHardwareConfig;
+  if (robotConnection.robotType.startsWith("so100")) {
+    config = createSO100Config(robotConnection.robotType);
+  } else {
+    throw new Error(`Unsupported robot type: ${robotConnection.robotType}`);
+  }
 
   let shouldStop = false;
   const stopFunction = () => shouldStop;
@@ -198,30 +185,31 @@ export async function calibrate(
     // Step 1: Set homing offsets (automatic)
     options?.onProgress?.("⚙️ Setting motor homing offsets");
     const homingOffsets = await setHomingOffsets(
-      config.port,
+      port,
       config.motorIds,
       config.motorNames
     );
 
     // Step 2: Record ranges of motion with live updates
     const { rangeMins, rangeMaxes } = await recordRangesOfMotion(
-      config.port,
+      port,
       config.motorIds,
       config.motorNames,
       stopFunction,
       options?.onLiveUpdate
     );
 
-    // 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;
+    // Step 3: Apply robot-specific range adjustments
+    applyRobotSpecificRangeAdjustments(
+      robotConnection.robotType!,
+      config.protocol,
+      rangeMins,
+      rangeMaxes
+    );
 
     // Step 4: Write hardware position limits to motors
     await writeHardwarePositionLimits(
-      config.port,
+      port,
       config.motorIds,
       config.motorNames,
       rangeMins,

src/lerobot/web/find_port.ts

@@ -29,30 +29,15 @@
  */
 
 import { getRobotConnectionManager } from "./robot-connection.js";
+import type {
+  RobotConnection,
+  RobotConfig,
+  SerialPort,
+} from "./types/robot-connection.js";
 
 /**
- * Type definitions for WebSerial API (not yet in all TypeScript libs)
+ * Extended WebSerial API type definitions
  */
-interface SerialPort {
-  readonly readable: ReadableStream;
-  readonly writable: WritableStream;
-  getInfo(): SerialPortInfo;
-  open(options: SerialOptions): Promise<void>;
-  close(): Promise<void>;
-}
-
-interface SerialPortInfo {
-  usbVendorId?: number;
-  usbProductId?: number;
-}
-
-interface SerialOptions {
-  baudRate: number;
-  dataBits?: number;
-  stopBits?: number;
-  parity?: "none" | "even" | "odd";
-}
-
 interface Serial extends EventTarget {
   getPorts(): Promise<SerialPort[]>;
   requestPort(options?: SerialPortRequestOptions): Promise<SerialPort>;
@@ -73,43 +58,6 @@ declare global {
   }
 }
 
-/**
- * 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
- */
-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;
-  };
-}
-
-/**
- * Minimal robot config for finding/connecting to specific robots
- */
-export interface RobotConfig {
-  robotType: "so100_follower" | "so100_leader";
-  robotId: string;
-  serialNumber: string;
-}
-
 /**
  * Options for findPort function
  */
@@ -366,6 +314,3 @@ export async function findPort(
     },
   };
 }
-
-// Export the main function (renamed from findPortWeb)
-export { findPort as findPortWeb }; // Backward compatibility alias

src/lerobot/web/robots/so100_config.ts

@@ -1,8 +1,10 @@
 /**
- * SO-100 specific configuration for web calibration
+ * SO-100 specific hardware configuration
  * Matches Node.js SO-100 config structure and Python lerobot exactly
  */
 
+import type { RobotHardwareConfig } from "../types/robot-config.js";
+
 /**
  * STS3215 Protocol Configuration for SO-100 devices
  */
@@ -38,16 +40,60 @@ export const SO100_CONFIG = {
 };
 
 /**
- * Create SO-100 calibration configuration
+ * SO-100 Keyboard Controls for Teleoperation
+ * Robot-specific mapping optimized for SO-100 joint layout
+ */
+export const SO100_KEYBOARD_CONTROLS = {
+  // Shoulder controls
+  ArrowUp: { motor: "shoulder_lift", direction: 1, description: "Shoulder up" },
+  ArrowDown: {
+    motor: "shoulder_lift",
+    direction: -1,
+    description: "Shoulder down",
+  },
+  ArrowLeft: {
+    motor: "shoulder_pan",
+    direction: -1,
+    description: "Shoulder left",
+  },
+  ArrowRight: {
+    motor: "shoulder_pan",
+    direction: 1,
+    description: "Shoulder right",
+  },
+
+  // WASD controls
+  w: { motor: "elbow_flex", direction: 1, description: "Elbow flex" },
+  s: { motor: "elbow_flex", direction: -1, description: "Elbow extend" },
+  a: { motor: "wrist_flex", direction: -1, description: "Wrist down" },
+  d: { motor: "wrist_flex", direction: 1, description: "Wrist up" },
+
+  // Wrist roll and gripper
+  q: { motor: "wrist_roll", direction: -1, description: "Wrist roll left" },
+  e: { motor: "wrist_roll", direction: 1, description: "Wrist roll right" },
+  o: { motor: "gripper", direction: 1, description: "Gripper open" },
+  c: { motor: "gripper", direction: -1, description: "Gripper close" },
+
+  // Emergency stop
+  Escape: {
+    motor: "emergency_stop",
+    direction: 0,
+    description: "Emergency stop",
+  },
+} as const;
+
+/**
+ * Create SO-100 hardware configuration
  */
 export function createSO100Config(
   deviceType: "so100_follower" | "so100_leader"
-) {
+): RobotHardwareConfig {
   return {
     deviceType,
     motorNames: SO100_CONFIG.motorNames,
     motorIds: SO100_CONFIG.motorIds,
     driveModes: SO100_CONFIG.driveModes,
+    keyboardControls: SO100_KEYBOARD_CONTROLS,
     protocol: WEB_STS3215_PROTOCOL,
   };
 }

src/lerobot/web/teleoperate.ts

@@ -3,7 +3,18 @@
  * Mirrors the Node.js implementation but adapted for browser environment
  */
 
-import type { UnifiedRobotData } from "../../demo/lib/unified-storage.js";
+import { createSO100Config } from "./robots/so100_config.js";
+import type {
+  RobotHardwareConfig,
+  KeyboardControl,
+} from "./types/robot-config.js";
+import type { RobotConnection } from "./types/robot-connection.js";
+import { WebSerialPortWrapper } from "./utils/serial-port-wrapper.js";
+import {
+  readMotorPosition,
+  writeMotorPosition,
+  type MotorCommunicationPort,
+} from "./utils/motor-communication.js";
 
 /**
  * Motor position and limits for teleoperation
@@ -14,7 +25,6 @@ export interface MotorConfig {
   currentPosition: number;
   minPosition: number;
   maxPosition: number;
-  homePosition: number;
 }
 
 /**
@@ -28,328 +38,103 @@ export interface TeleoperationState {
 }
 
 /**
- * Keyboard control mapping (matches Node.js version)
+ * Teleoperation process control object (matches calibrate pattern)
  */
-export const KEYBOARD_CONTROLS = {
-  // Shoulder controls
-  ArrowUp: { motor: "shoulder_lift", direction: 1, description: "Shoulder up" },
-  ArrowDown: {
-    motor: "shoulder_lift",
-    direction: -1,
-    description: "Shoulder down",
-  },
-  ArrowLeft: {
-    motor: "shoulder_pan",
-    direction: -1,
-    description: "Shoulder left",
-  },
-  ArrowRight: {
-    motor: "shoulder_pan",
-    direction: 1,
-    description: "Shoulder right",
-  },
-
-  // WASD controls
-  w: { motor: "elbow_flex", direction: 1, description: "Elbow flex" },
-  s: { motor: "elbow_flex", direction: -1, description: "Elbow extend" },
-  a: { motor: "wrist_flex", direction: -1, description: "Wrist down" },
-  d: { motor: "wrist_flex", direction: 1, description: "Wrist up" },
-
-  // Wrist roll and gripper
-  q: { motor: "wrist_roll", direction: -1, description: "Wrist roll left" },
-  e: { motor: "wrist_roll", direction: 1, description: "Wrist roll right" },
-  o: { motor: "gripper", direction: 1, description: "Gripper open" },
-  c: { motor: "gripper", direction: -1, description: "Gripper close" },
-
-  // Emergency stop
-  Escape: {
-    motor: "emergency_stop",
-    direction: 0,
-    description: "Emergency stop",
-  },
-} as const;
+export interface TeleoperationProcess {
+  start(): void;
+  stop(): void;
+  updateKeyState(key: string, pressed: boolean): void;
+  getState(): TeleoperationState;
+  moveMotor(motorName: string, position: number): Promise<boolean>;
+  setMotorPositions(positions: {
+    [motorName: string]: number;
+  }): Promise<boolean>;
+  disconnect(): Promise<void>;
+}
 
 /**
- * Web Serial Port wrapper for teleoperation
- * Uses the same pattern as calibration - per-operation reader/writer access
+ * Create motor configurations from robot hardware config
+ * Pure function - converts robot specs to motor configs with defaults
  */
-class WebTeleoperationPort {
-  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 teleoperation");
-    }
-    // Port is already open and ready - no need to grab persistent readers/writers
-  }
-
-  async writeMotorPosition(
-    motorId: number,
-    position: number
-  ): Promise<boolean> {
-    if (!this.port.writable) {
-      throw new Error("Port not open for writing");
-    }
-
-    try {
-      // STS3215 Write Goal_Position packet (matches Node.js exactly)
-      const packet = new Uint8Array([
-        0xff,
-        0xff, // Header
-        motorId, // Servo ID
-        0x05, // Length
-        0x03, // Instruction: WRITE_DATA
-        42, // Goal_Position register address
-        position & 0xff, // Position low byte
-        (position >> 8) & 0xff, // Position high byte
-        0x00, // Checksum placeholder
-      ]);
-
-      // Calculate checksum
-      const checksum =
-        ~(
-          motorId +
-          0x05 +
-          0x03 +
-          42 +
-          (position & 0xff) +
-          ((position >> 8) & 0xff)
-        ) & 0xff;
-      packet[8] = checksum;
-
-      // Use per-operation writer like calibration does
-      const writer = this.port.writable.getWriter();
-      try {
-        await writer.write(packet);
-        return true;
-      } finally {
-        writer.releaseLock();
-      }
-    } catch (error) {
-      console.warn(`Failed to write motor ${motorId} position:`, error);
-      return false;
-    }
-  }
-
-  async readMotorPosition(motorId: number): Promise<number | null> {
-    if (!this.port.writable || !this.port.readable) {
-      throw new Error("Port not open for reading/writing");
-    }
-
-    const writer = this.port.writable.getWriter();
-    const reader = this.port.readable.getReader();
-
-    try {
-      // STS3215 Read Present_Position packet
-      const packet = new Uint8Array([
-        0xff,
-        0xff, // Header
-        motorId, // Servo ID
-        0x04, // Length
-        0x02, // Instruction: READ_DATA
-        56, // Present_Position register address
-        0x02, // Data length (2 bytes)
-        0x00, // Checksum placeholder
-      ]);
-
-      const checksum = ~(motorId + 0x04 + 0x02 + 56 + 0x02) & 0xff;
-      packet[7] = checksum;
-
-      // Clear buffer first
-      try {
-        const { value, done } = await reader.read();
-        if (done) return null;
-      } catch (e) {
-        // Buffer was empty, continue
-      }
-
-      await writer.write(packet);
-      await new Promise((resolve) => setTimeout(resolve, 10));
-
-      const { value: response, done } = await reader.read();
-      if (done || !response || response.length < 7) {
-        return null;
-      }
-
-      const id = response[2];
-      const error = response[4];
-
-      if (id === motorId && error === 0) {
-        return response[5] | (response[6] << 8);
-      }
-
-      return null;
-    } catch (error) {
-      console.warn(`Failed to read motor ${motorId} position:`, error);
-      return null;
-    } finally {
-      reader.releaseLock();
-      writer.releaseLock();
-    }
-  }
-
-  async disconnect(): Promise<void> {
-    // Don't close the port itself - just cleanup wrapper
-    // The port is managed by PortManager
-  }
+function createMotorConfigsFromRobotConfig(
+  robotConfig: RobotHardwareConfig
+): MotorConfig[] {
+  return robotConfig.motorNames.map((name: string, i: number) => ({
+    id: robotConfig.motorIds[i],
+    name,
+    currentPosition: 2048,
+    minPosition: 1024,
+    maxPosition: 3072,
+  }));
 }
 
 /**
- * Load calibration data from unified storage with fallback to defaults
- * Improved version that properly loads and applies calibration ranges
+ * Apply calibration data to motor configurations
+ * Pure function - takes calibration data as parameter
  */
-export function loadCalibrationConfig(serialNumber: string): MotorConfig[] {
-  // Default SO-100 configuration (matches Node.js defaults)
-  const defaultConfigs: MotorConfig[] = [
-    {
-      id: 1,
-      name: "shoulder_pan",
-      currentPosition: 2048,
-      minPosition: 1024,
-      maxPosition: 3072,
-      homePosition: 2048,
-    },
-    {
-      id: 2,
-      name: "shoulder_lift",
-      currentPosition: 2048,
-      minPosition: 1024,
-      maxPosition: 3072,
-      homePosition: 2048,
-    },
-    {
-      id: 3,
-      name: "elbow_flex",
-      currentPosition: 2048,
-      minPosition: 1024,
-      maxPosition: 3072,
-      homePosition: 2048,
-    },
-    {
-      id: 4,
-      name: "wrist_flex",
-      currentPosition: 2048,
-      minPosition: 1024,
-      maxPosition: 3072,
-      homePosition: 2048,
-    },
-    {
-      id: 5,
-      name: "wrist_roll",
-      currentPosition: 2048,
-      minPosition: 1024,
-      maxPosition: 3072,
-      homePosition: 2048,
-    },
-    {
-      id: 6,
-      name: "gripper",
-      currentPosition: 2048,
-      minPosition: 1024,
-      maxPosition: 3072,
-      homePosition: 2048,
-    },
-  ];
-
-  try {
-    // Load from unified storage
-    const unifiedKey = `lerobotjs-${serialNumber}`;
-    const unifiedDataRaw = localStorage.getItem(unifiedKey);
-
-    if (!unifiedDataRaw) {
-      console.log(
-        `No calibration data found for ${serialNumber}, using defaults`
-      );
-      return defaultConfigs;
-    }
-
-    const unifiedData: UnifiedRobotData = JSON.parse(unifiedDataRaw);
-
-    if (!unifiedData.calibration) {
-      console.log(
-        `No calibration in unified data for ${serialNumber}, using defaults`
-      );
-      return defaultConfigs;
+export function applyCalibrationToMotorConfigs(
+  defaultConfigs: MotorConfig[],
+  calibrationData: { [motorName: string]: any }
+): MotorConfig[] {
+  return defaultConfigs.map((defaultConfig) => {
+    const calibData = calibrationData[defaultConfig.name];
+
+    if (
+      calibData &&
+      typeof calibData === "object" &&
+      "id" in calibData &&
+      "range_min" in calibData &&
+      "range_max" in calibData
+    ) {
+      // Use calibrated values but keep current position as default
+      return {
+        ...defaultConfig,
+        id: calibData.id,
+        minPosition: calibData.range_min,
+        maxPosition: calibData.range_max,
+      };
     }
 
-    // Map calibration data to motor configs
-    const calibratedConfigs: MotorConfig[] = defaultConfigs.map(
-      (defaultConfig) => {
-        const calibData = (unifiedData.calibration as any)?.[
-          defaultConfig.name
-        ];
-
-        if (
-          calibData &&
-          typeof calibData === "object" &&
-          "id" in calibData &&
-          "range_min" in calibData &&
-          "range_max" in calibData
-        ) {
-          // Use calibrated values but keep current position as default
-          return {
-            ...defaultConfig,
-            id: calibData.id,
-            minPosition: calibData.range_min,
-            maxPosition: calibData.range_max,
-            homePosition: Math.floor(
-              (calibData.range_min + calibData.range_max) / 2
-            ),
-          };
-        }
-
-        return defaultConfig;
-      }
-    );
-
-    console.log(`✅ Loaded calibration data for ${serialNumber}`);
-    return calibratedConfigs;
-  } catch (error) {
-    console.warn(`Failed to load calibration for ${serialNumber}:`, error);
-    return defaultConfigs;
-  }
+    return defaultConfig;
+  });
 }
 
 /**
  * Web teleoperation controller
+ * Now uses shared utilities instead of custom port handling
  */
 export class WebTeleoperationController {
-  private port: WebTeleoperationPort;
+  private port: MotorCommunicationPort;
   private motorConfigs: MotorConfig[] = [];
+  private keyboardControls: { [key: string]: KeyboardControl } = {};
   private isActive: boolean = false;
   private updateInterval: NodeJS.Timeout | null = null;
   private keyStates: {
     [key: string]: { pressed: boolean; timestamp: number };
   } = {};
+  private onStateUpdate?: (state: TeleoperationState) => void;
 
   // Movement parameters (matches Node.js)
   private readonly STEP_SIZE = 8;
   private readonly UPDATE_RATE = 60; // 60 FPS
-  private readonly KEY_TIMEOUT = 100; // ms
-
-  constructor(port: SerialPort, serialNumber: string) {
-    this.port = new WebTeleoperationPort(port);
-    this.motorConfigs = loadCalibrationConfig(serialNumber);
+  private readonly KEY_TIMEOUT = 600; // ms - longer than browser keyboard repeat delay (~500ms)
+
+  constructor(
+    port: MotorCommunicationPort,
+    motorConfigs: MotorConfig[],
+    keyboardControls: { [key: string]: KeyboardControl },
+    onStateUpdate?: (state: TeleoperationState) => void
+  ) {
+    this.port = port;
+    this.motorConfigs = motorConfigs;
+    this.keyboardControls = keyboardControls;
+    this.onStateUpdate = onStateUpdate;
   }
 
   async initialize(): Promise<void> {
-    await this.port.initialize();
-
-    // Read current positions
+    // Read current positions using proven utilities
     for (const config of this.motorConfigs) {
-      const position = await this.port.readMotorPosition(config.id);
+      const position = await readMotorPosition(this.port, config.id);
       if (position !== null) {
         config.currentPosition = position;
       }
@@ -401,11 +186,16 @@ export class WebTeleoperationController {
     this.keyStates = {};
 
     console.log("⏹️ Web teleoperation stopped");
+
+    // Notify UI of state change
+    if (this.onStateUpdate) {
+      this.onStateUpdate(this.getState());
+    }
   }
 
   async disconnect(): Promise<void> {
     this.stop();
-    await this.port.disconnect();
+    // No need to manually disconnect - port wrapper handles this
   }
 
   private updateMotorPositions(): void {
@@ -435,7 +225,7 @@ export class WebTeleoperationController {
     const targetPositions: { [motorName: string]: number } = {};
 
     for (const key of activeKeys) {
-      const control = KEYBOARD_CONTROLS[key as keyof typeof KEYBOARD_CONTROLS];
+      const control = this.keyboardControls[key];
       if (!control || control.motor === "emergency_stop") continue;
 
       const motorConfig = this.motorConfigs.find(
@@ -455,16 +245,23 @@ export class WebTeleoperationController {
       );
     }
 
-    // Send motor commands
+    // Send motor commands using proven utilities
     Object.entries(targetPositions).forEach(([motorName, targetPosition]) => {
       const motorConfig = this.motorConfigs.find((m) => m.name === motorName);
       if (motorConfig && targetPosition !== motorConfig.currentPosition) {
-        this.port
-          .writeMotorPosition(motorConfig.id, Math.round(targetPosition))
-          .then((success) => {
-            if (success) {
-              motorConfig.currentPosition = targetPosition;
-            }
+        writeMotorPosition(
+          this.port,
+          motorConfig.id,
+          Math.round(targetPosition)
+        )
+          .then(() => {
+            motorConfig.currentPosition = targetPosition;
+          })
+          .catch((error) => {
+            console.warn(
+              `Failed to write motor ${motorConfig.id} position:`,
+              error
+            );
           });
       }
     });
@@ -480,15 +277,18 @@ export class WebTeleoperationController {
       Math.min(motorConfig.maxPosition, targetPosition)
     );
 
-    const success = await this.port.writeMotorPosition(
-      motorConfig.id,
-      Math.round(clampedPosition)
-    );
-    if (success) {
+    try {
+      await writeMotorPosition(
+        this.port,
+        motorConfig.id,
+        Math.round(clampedPosition)
+      );
       motorConfig.currentPosition = clampedPosition;
+      return true;
+    } catch (error) {
+      console.warn(`Failed to move motor ${motorName}:`, error);
+      return false;
     }
-
-    return success;
   }
 
   async setMotorPositions(positions: {
@@ -502,25 +302,81 @@ export class WebTeleoperationController {
 
     return results.every((result) => result);
   }
-
-  async goToHomePosition(): Promise<boolean> {
-    const homePositions = this.motorConfigs.reduce((acc, config) => {
-      acc[config.name] = config.homePosition;
-      return acc;
-    }, {} as { [motorName: string]: number });
-
-    return this.setMotorPositions(homePositions);
-  }
 }
 
 /**
- * Create teleoperation controller for connected robot
+ * Main teleoperate function - simple API matching calibrate pattern
+ * Handles robot types internally, creates appropriate motor configurations
  */
-export async function createWebTeleoperationController(
-  port: SerialPort,
-  serialNumber: string
-): Promise<WebTeleoperationController> {
-  const controller = new WebTeleoperationController(port, serialNumber);
+export async function teleoperate(
+  robotConnection: RobotConnection,
+  options?: {
+    calibrationData?: { [motorName: string]: any };
+    onStateUpdate?: (state: TeleoperationState) => void;
+  }
+): Promise<TeleoperationProcess> {
+  // Validate required fields
+  if (!robotConnection.robotType) {
+    throw new Error(
+      "Robot type is required for teleoperation. Please configure the robot first."
+    );
+  }
+
+  // Create web serial port wrapper (same pattern as calibrate.ts)
+  const port = new WebSerialPortWrapper(robotConnection.port);
+  await port.initialize();
+
+  // Get robot-specific configuration (same pattern as calibrate.ts)
+  let config: RobotHardwareConfig;
+  if (robotConnection.robotType.startsWith("so100")) {
+    config = createSO100Config(robotConnection.robotType);
+  } else {
+    throw new Error(`Unsupported robot type: ${robotConnection.robotType}`);
+  }
+
+  // Create motor configs from robot hardware specs (single call, no duplication)
+  const defaultMotorConfigs = createMotorConfigsFromRobotConfig(config);
+
+  // Apply calibration data if provided
+  const motorConfigs = options?.calibrationData
+    ? applyCalibrationToMotorConfigs(
+        defaultMotorConfigs,
+        options.calibrationData
+      )
+    : defaultMotorConfigs;
+
+  // Create and initialize controller using shared utilities
+  const controller = new WebTeleoperationController(
+    port,
+    motorConfigs,
+    config.keyboardControls,
+    options?.onStateUpdate
+  );
   await controller.initialize();
-  return controller;
+
+  // Wrap controller in process object (matches calibrate pattern)
+  return {
+    start: () => {
+      controller.start();
+      // Optional state update callback
+      if (options?.onStateUpdate) {
+        const updateLoop = () => {
+          if (controller.getState().isActive) {
+            options.onStateUpdate!(controller.getState());
+            setTimeout(updateLoop, 100); // 10fps state updates
+          }
+        };
+        updateLoop();
+      }
+    },
+    stop: () => controller.stop(),
+    updateKeyState: (key: string, pressed: boolean) =>
+      controller.updateKeyState(key, pressed),
+    getState: () => controller.getState(),
+    moveMotor: (motorName: string, position: number) =>
+      controller.moveMotor(motorName, position),
+    setMotorPositions: (positions: { [motorName: string]: number }) =>
+      controller.setMotorPositions(positions),
+    disconnect: () => controller.disconnect(),
+  };
 }

src/lerobot/web/types/robot-config.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared robot hardware configuration types
+ * Used across calibration, teleoperation, and other robot operations
+ */
+
+/**
+ * Keyboard control mapping for teleoperation
+ */
+export interface KeyboardControl {
+  motor: string;
+  direction: number;
+  description: string;
+}
+
+/**
+ * Robot hardware configuration interface
+ * Defines the contract that all robot configurations must implement
+ */
+export interface RobotHardwareConfig {
+  deviceType: string;
+  motorNames: string[];
+  motorIds: number[];
+  driveModes: number[];
+
+  // Keyboard controls for teleoperation (robot-specific)
+  keyboardControls: { [key: string]: KeyboardControl };
+
+  protocol: {
+    resolution: number;
+    homingOffsetAddress: number;
+    homingOffsetLength: number;
+    presentPositionAddress: number;
+    presentPositionLength: number;
+    minPositionLimitAddress: number;
+    minPositionLimitLength: number;
+    maxPositionLimitAddress: number;
+    maxPositionLimitLength: number;
+    signMagnitudeBit: number;
+  };
+}

src/lerobot/web/types/robot-connection.ts

@@ -0,0 +1,64 @@
+/**
+ * Core robot connection types used across the lerobot.js web library
+ * These types are shared between findPort, calibrate, teleoperate, and other modules
+ */
+
+/**
+ * Type definitions for WebSerial API (not yet in all TypeScript libs)
+ */
+export interface SerialPort {
+  readonly readable: ReadableStream;
+  readonly writable: WritableStream;
+  getInfo(): SerialPortInfo;
+  open(options: SerialOptions): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface SerialPortInfo {
+  usbVendorId?: number;
+  usbProductId?: number;
+}
+
+export interface SerialOptions {
+  baudRate: number;
+  dataBits?: number;
+  stopBits?: number;
+  parity?: "none" | "even" | "odd";
+}
+
+/**
+ * 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
+ */
+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;
+  };
+}
+
+/**
+ * Minimal robot config for finding/connecting to specific robots
+ */
+export interface RobotConfig {
+  robotType: "so100_follower" | "so100_leader";
+  robotId: string;
+  serialNumber: string;
+}