feat: teleoperate in the web

src/demo/components/PortManager.tsx

@@ -28,12 +28,14 @@ interface PortManagerProps {
     robotType: "so100_follower" | "so100_leader",
     robotId: string
   ) => void;
+  onTeleoperate?: (robot: ConnectedRobot) => void;
 }
 
 export function PortManager({
   connectedRobots,
   onConnectedRobotsChange,
   onCalibrate,
+  onTeleoperate,
 }: PortManagerProps) {
   const [isConnecting, setIsConnecting] = useState(false);
   const [isFindingPorts, setIsFindingPorts] = useState(false);
@@ -55,68 +57,18 @@ export function PortManager({
     loadSavedPorts();
   }, []);
 
-  // Save port data to localStorage whenever connectedPorts changes
-  useEffect(() => {
-    savePortsToStorage();
-  }, [connectedRobots]);
+  // Note: Robot data is now automatically saved to unified storage when robot config is updated
 
   const loadSavedPorts = async () => {
     try {
-      const saved = localStorage.getItem("lerobot-ports");
-      if (!saved) return;
-
-      const savedData = JSON.parse(saved);
       const existingPorts = await navigator.serial.getPorts();
-
       const restoredPorts: ConnectedRobot[] = [];
 
       for (const port of existingPorts) {
-        // Find saved data by matching port info instead of display name
-        const portInfo = port.getInfo();
-        const savedPort = savedData.find((p: any) => {
-          // Try to match by USB vendor/product ID if available
-          if (portInfo.usbVendorId && portInfo.usbProductId) {
-            return (
-              p.usbVendorId === portInfo.usbVendorId &&
-              p.usbProductId === portInfo.usbProductId
-            );
-          }
-          // Fallback to name matching
-          return p.name === getPortDisplayName(port);
-        });
-
-        // Auto-connect to paired robots
-        let isConnected = false;
-        try {
-          // Check if already open
-          if (port.readable !== null && port.writable !== null) {
-            isConnected = true;
-            console.log("Port already open, reusing connection");
-          } else {
-            // Auto-open paired robots only if they have saved configuration
-            if (savedPort?.robotType && savedPort?.robotId) {
-              console.log(
-                `Auto-connecting to saved robot: ${savedPort.robotType} (${savedPort.robotId})`
-              );
-              await port.open({ baudRate: 1000000 });
-              isConnected = true;
-            } else {
-              console.log(
-                "Port found but no saved robot configuration, skipping auto-connect"
-              );
-              isConnected = false;
-            }
-          }
-        } catch (error) {
-          console.log("Could not auto-connect to paired robot:", error);
-          isConnected = false;
-        }
-
-        // Re-detect serial number for this port
+        // Get USB device metadata to determine serial number
         let serialNumber = null;
         let usbMetadata = null;
 
-        // Try to get USB device info to restore serial number
         try {
           // Get all USB devices and try to match with this serial port
           const usbDevices = await navigator.usb.getDevices();
@@ -161,12 +113,80 @@ export function PortManager({
             .substr(2, 9)}`;
         }
 
+        // Load robot configuration from unified storage
+        let robotType: "so100_follower" | "so100_leader" | undefined;
+        let robotId: string | undefined;
+        let shouldAutoConnect = false;
+
+        if (serialNumber) {
+          try {
+            const { getUnifiedRobotData } = await import(
+              "../lib/unified-storage"
+            );
+            const unifiedData = getUnifiedRobotData(serialNumber);
+            if (unifiedData?.device_info) {
+              robotType = unifiedData.device_info.robotType;
+              robotId = unifiedData.device_info.robotId;
+              shouldAutoConnect = true;
+              console.log(
+                `📋 Loaded robot config from unified storage: ${robotType} (${robotId})`
+              );
+            }
+          } catch (error) {
+            console.warn("Failed to load unified robot data:", error);
+          }
+        }
+
+        // Auto-connect to configured robots
+        let isConnected = false;
+        try {
+          // Check if already open
+          if (port.readable !== null && port.writable !== null) {
+            isConnected = true;
+            console.log("Port already open, reusing connection");
+          } else if (shouldAutoConnect && robotType && robotId) {
+            // Auto-open robots that have saved configuration
+            console.log(
+              `Auto-connecting to saved robot: ${robotType} (${robotId})`
+            );
+            await port.open({ baudRate: 1000000 });
+            isConnected = true;
+
+            // Register with singleton connection manager
+            try {
+              const { getRobotConnectionManager } = await import(
+                "../../lerobot/web/robot-connection"
+              );
+              const connectionManager = getRobotConnectionManager();
+              await connectionManager.connect(
+                port,
+                robotType,
+                robotId,
+                serialNumber!
+              );
+            } catch (error) {
+              console.warn(
+                "Failed to register with connection manager:",
+                error
+              );
+            }
+          } else {
+            console.log(
+              "Port found but no saved robot configuration, skipping auto-connect"
+            );
+            isConnected = false;
+          }
+        } catch (error) {
+          console.log("Could not auto-connect to robot:", error);
+          isConnected = false;
+        }
+
         restoredPorts.push({
           port,
           name: getPortDisplayName(port),
           isConnected,
-          robotType: savedPort?.robotType,
-          robotId: savedPort?.robotId,
+          robotType,
+          robotId,
           serialNumber: serialNumber!,
           usbMetadata: usbMetadata || undefined,
         });
@@ -178,24 +198,6 @@ export function PortManager({
     }
   };
 
-  const savePortsToStorage = () => {
-    try {
-      const dataToSave = connectedRobots.map((p) => {
-        const portInfo = p.port.getInfo();
-        return {
-          name: p.name,
-          robotType: p.robotType,
-          robotId: p.robotId,
-          usbVendorId: portInfo.usbVendorId,
-          usbProductId: portInfo.usbProductId,
-        };
-      });
-      localStorage.setItem("lerobot-ports", JSON.stringify(dataToSave));
-    } catch (error) {
-      console.error("Failed to save ports to storage:", error);
-    }
-  };
-
   const getPortDisplayName = (port: SerialPort): string => {
     try {
       const info = port.getInfo();
@@ -322,6 +324,27 @@ export function PortManager({
 
         onConnectedRobotsChange([...connectedRobots, newRobot]);
         console.log("🤖 New robot connected with ID:", serialNumber);
+
+        // Register with singleton connection manager if robot is configured
+        if (newRobot.robotType && newRobot.robotId) {
+          try {
+            const { getRobotConnectionManager } = await import(
+              "../../lerobot/web/robot-connection"
+            );
+            const connectionManager = getRobotConnectionManager();
+            await connectionManager.connect(
+              port,
+              newRobot.robotType,
+              newRobot.robotId,
+              serialNumber!
+            );
+          } catch (error) {
+            console.warn(
+              "Failed to register new connection with manager:",
+              error
+            );
+          }
+        }
       } else {
         // Existing robot - update port and connection status
         const updatedRobots = connectedRobots.map((robot, index) =>
@@ -391,44 +414,8 @@ export function PortManager({
           // Remove unified storage data
           localStorage.removeItem(unifiedKey);
           console.log(`🗑️ Deleted unified robot data: ${unifiedKey}`);
-
-          // Also clean up any old format keys for this robot (if they exist)
-          const oldKeys = [
-            `lerobot-robot-${portInfo.serialNumber}`,
-            `lerobot-calibration-${portInfo.serialNumber}`,
-          ];
-
-          // Try to find old calibration key by checking stored robot config
-          if (portInfo.robotType && portInfo.robotId) {
-            oldKeys.push(
-              `lerobot_calibration_${portInfo.robotType}_${portInfo.robotId}`
-            );
-          }
-
-          oldKeys.forEach((key) => {
-            if (localStorage.getItem(key)) {
-              localStorage.removeItem(key);
-              console.log(`🧹 Cleaned up old key: ${key}`);
-            }
-          });
         } catch (error) {
           console.warn("Failed to delete unified storage data:", error);
-
-          // Fallback: try to delete old format keys directly
-          if (portInfo.robotType && portInfo.robotId) {
-            const oldKeys = [
-              `lerobot-robot-${portInfo.serialNumber}`,
-              `lerobot-calibration-${portInfo.serialNumber}`,
-              `lerobot_calibration_${portInfo.robotType}_${portInfo.robotId}`,
-            ];
-
-            oldKeys.forEach((key) => {
-              if (localStorage.getItem(key)) {
-                localStorage.removeItem(key);
-                console.log(`🧹 Removed old format key: ${key}`);
-              }
-            });
-          }
         }
       }
 
@@ -683,6 +670,7 @@ export function PortManager({
                       handleUpdatePortInfo(index, robotType, robotId)
                     }
                     onCalibrate={() => handleCalibrate(portInfo)}
+                    onTeleoperate={() => onTeleoperate?.(portInfo)}
                   />
                 ))}
               </div>
@@ -757,6 +745,7 @@ interface PortCardProps {
     robotId: string
   ) => void;
   onCalibrate: () => void;
+  onTeleoperate: () => void;
 }
 
 function PortCard({
@@ -764,6 +753,7 @@ function PortCard({
   onDisconnect,
   onUpdateInfo,
   onCalibrate,
+  onTeleoperate,
 }: PortCardProps) {
   const [robotType, setRobotType] = useState<"so100_follower" | "so100_leader">(
     portInfo.robotType || "so100_follower"
@@ -1167,14 +1157,26 @@ function PortCard({
                 <span>Not calibrated yet</span>
               )}
             </div>
-            <Button
-              size="sm"
-              variant={calibrationStatus ? "outline" : "default"}
-              onClick={onCalibrate}
-              disabled={!currentRobotType || !currentRobotId}
-            >
-              {calibrationStatus ? "Re-calibrate" : "Calibrate"}
-            </Button>
+            <div className="flex gap-2">
+              <Button
+                size="sm"
+                variant={calibrationStatus ? "outline" : "default"}
+                onClick={onCalibrate}
+                disabled={!currentRobotType || !currentRobotId}
+              >
+                {calibrationStatus ? "Re-calibrate" : "Calibrate"}
+              </Button>
+              <Button
+                size="sm"
+                variant="outline"
+                onClick={onTeleoperate}
+                disabled={
+                  !currentRobotType || !currentRobotId || !portInfo.isConnected
+                }
+              >
+                🎮 Teleoperate
+              </Button>
+            </div>
           </div>
 
           {/* Device Info Scanner */}

src/demo/components/TeleoperationPanel.tsx

@@ -0,0 +1,367 @@
+import React, { useState } 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 { ConnectedRobot } from "../types";
+import { KEYBOARD_CONTROLS } from "../../lerobot/web/teleoperate";
+
+interface TeleoperationPanelProps {
+  robot: ConnectedRobot;
+  onClose: () => void;
+}
+
+export function TeleoperationPanel({
+  robot,
+  onClose,
+}: TeleoperationPanelProps) {
+  const [enabled, setEnabled] = useState(false);
+
+  const {
+    isConnected,
+    isActive,
+    motorConfigs,
+    keyStates,
+    error,
+    start,
+    stop,
+    goToHome,
+    simulateKeyPress,
+    simulateKeyRelease,
+  } = useTeleoperation({
+    robot,
+    enabled,
+    onError: (err: string) => console.error("Teleoperation error:", err),
+  });
+
+  const handleStart = async () => {
+    setEnabled(true);
+    await start();
+  };
+
+  const handleStop = () => {
+    stop();
+    setEnabled(false);
+  };
+
+  const handleClose = () => {
+    stop();
+    setEnabled(false);
+    onClose();
+  };
+
+  // Virtual keyboard component
+  const VirtualKeyboard = () => {
+    const isKeyPressed = (key: string) => {
+      return keyStates[key]?.pressed || false;
+    };
+
+    const KeyButton = ({
+      keyCode,
+      children,
+      className = "",
+      size = "default" as "default" | "sm" | "lg" | "icon",
+    }: {
+      keyCode: string;
+      children: React.ReactNode;
+      className?: string;
+      size?: "default" | "sm" | "lg" | "icon";
+    }) => {
+      const control =
+        KEYBOARD_CONTROLS[keyCode as keyof typeof KEYBOARD_CONTROLS];
+      const pressed = isKeyPressed(keyCode);
+
+      return (
+        <Button
+          variant={pressed ? "default" : "outline"}
+          size={size}
+          className={`
+            ${className}
+            ${
+              pressed
+                ? "bg-blue-600 text-white shadow-inner"
+                : "hover:bg-gray-100"
+            }
+            transition-all duration-75 font-mono text-xs
+            ${!isActive ? "opacity-50 cursor-not-allowed" : ""}
+          `}
+          disabled={!isActive}
+          onMouseDown={(e) => {
+            e.preventDefault();
+            if (isActive) simulateKeyPress(keyCode);
+          }}
+          onMouseUp={(e) => {
+            e.preventDefault();
+            if (isActive) simulateKeyRelease(keyCode);
+          }}
+          onMouseLeave={(e) => {
+            e.preventDefault();
+            if (isActive) simulateKeyRelease(keyCode);
+          }}
+          title={control?.description || keyCode}
+        >
+          {children}
+        </Button>
+      );
+    };
+
+    return (
+      <div className="space-y-4">
+        {/* Arrow Keys */}
+        <div className="text-center">
+          <h4 className="text-xs font-semibold mb-2 text-gray-600">Shoulder</h4>
+          <div className="flex flex-col items-center gap-1">
+            <KeyButton keyCode="ArrowUp" size="sm">
+              ↑
+            </KeyButton>
+            <div className="flex gap-1">
+              <KeyButton keyCode="ArrowLeft" size="sm">
+                ←
+              </KeyButton>
+              <KeyButton keyCode="ArrowDown" size="sm">
+                ↓
+              </KeyButton>
+              <KeyButton keyCode="ArrowRight" size="sm">
+                →
+              </KeyButton>
+            </div>
+          </div>
+        </div>
+
+        {/* WASD Keys */}
+        <div className="text-center">
+          <h4 className="text-xs font-semibold mb-2 text-gray-600">
+            Elbow/Wrist
+          </h4>
+          <div className="flex flex-col items-center gap-1">
+            <KeyButton keyCode="w" size="sm">
+              W
+            </KeyButton>
+            <div className="flex gap-1">
+              <KeyButton keyCode="a" size="sm">
+                A
+              </KeyButton>
+              <KeyButton keyCode="s" size="sm">
+                S
+              </KeyButton>
+              <KeyButton keyCode="d" size="sm">
+                D
+              </KeyButton>
+            </div>
+          </div>
+        </div>
+
+        {/* Q/E and Space */}
+        <div className="flex justify-center gap-2">
+          <div className="text-center">
+            <h4 className="text-xs font-semibold mb-2 text-gray-600">Roll</h4>
+            <div className="flex gap-1">
+              <KeyButton keyCode="q" size="sm">
+                Q
+              </KeyButton>
+              <KeyButton keyCode="e" size="sm">
+                E
+              </KeyButton>
+            </div>
+          </div>
+          <div className="text-center">
+            <h4 className="text-xs font-semibold mb-2 text-gray-600">
+              Gripper
+            </h4>
+            <KeyButton keyCode=" " size="sm" className="min-w-16">
+              ⎵
+            </KeyButton>
+          </div>
+        </div>
+
+        {/* Emergency Stop */}
+        <div className="text-center border-t pt-2">
+          <KeyButton
+            keyCode="Escape"
+            className="bg-red-100 border-red-300 hover:bg-red-200 text-red-800 text-xs"
+          >
+            ESC
+          </KeyButton>
+        </div>
+      </div>
+    );
+  };
+
+  return (
+    <div className="min-h-screen bg-gradient-to-br from-blue-50 to-indigo-100">
+      <div className="container mx-auto px-6 py-8">
+        {/* Header */}
+        <div className="flex justify-between items-center mb-6">
+          <div>
+            <h1 className="text-3xl font-bold text-gray-900">
+              🎮 Robot Teleoperation
+            </h1>
+            <p className="text-gray-600">
+              {robot.robotId || robot.name} - {robot.serialNumber}
+            </p>
+          </div>
+          <Button variant="outline" onClick={handleClose}>
+            ← Back to Dashboard
+          </Button>
+        </div>
+
+        {/* Error Alert */}
+        {error && (
+          <Alert variant="destructive" className="mb-6">
+            <AlertDescription>{error}</AlertDescription>
+          </Alert>
+        )}
+
+        <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+          {/* Status Panel */}
+          <Card>
+            <CardHeader>
+              <CardTitle className="flex items-center gap-2">
+                Status
+                <Badge variant={isConnected ? "default" : "destructive"}>
+                  {isConnected ? "Connected" : "Disconnected"}
+                </Badge>
+              </CardTitle>
+            </CardHeader>
+            <CardContent className="space-y-4">
+              <div className="flex items-center justify-between">
+                <span className="text-sm text-gray-600">Teleoperation</span>
+                <Badge variant={isActive ? "default" : "secondary"}>
+                  {isActive ? "Active" : "Stopped"}
+                </Badge>
+              </div>
+
+              <div className="flex items-center justify-between">
+                <span className="text-sm text-gray-600">Active Keys</span>
+                <Badge variant="outline">
+                  {
+                    Object.values(keyStates).filter((state) => state.pressed)
+                      .length
+                  }
+                </Badge>
+              </div>
+
+              <div className="space-y-2">
+                {isActive ? (
+                  <Button
+                    onClick={handleStop}
+                    variant="destructive"
+                    className="w-full"
+                  >
+                    ⏹️ Stop Teleoperation
+                  </Button>
+                ) : (
+                  <Button
+                    onClick={handleStart}
+                    disabled={!isConnected}
+                    className="w-full"
+                  >
+                    ▶️ Start Teleoperation
+                  </Button>
+                )}
+
+                <Button
+                  onClick={goToHome}
+                  variant="outline"
+                  disabled={!isConnected}
+                  className="w-full"
+                >
+                  🏠 Go to Home
+                </Button>
+              </div>
+            </CardContent>
+          </Card>
+
+          {/* Virtual Keyboard */}
+          <Card>
+            <CardHeader>
+              <CardTitle>Virtual Keyboard</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <VirtualKeyboard />
+            </CardContent>
+          </Card>
+
+          {/* Motor Status */}
+          <Card>
+            <CardHeader>
+              <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;
+
+                return (
+                  <div key={motor.name} className="space-y-1">
+                    <div className="flex justify-between items-center">
+                      <span className="text-sm font-medium">
+                        {motor.name.replace("_", " ")}
+                      </span>
+                      <span className="text-xs text-gray-500">
+                        {motor.currentPosition}
+                      </span>
+                    </div>
+                    <Progress value={percentage} className="h-2" />
+                    <div className="flex justify-between text-xs text-gray-400">
+                      <span>{motor.minPosition}</span>
+                      <span>{motor.maxPosition}</span>
+                    </div>
+                  </div>
+                );
+              })}
+            </CardContent>
+          </Card>
+        </div>
+
+        {/* Help Card */}
+        <Card className="mt-6">
+          <CardHeader>
+            <CardTitle>Control Instructions</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 text-sm">
+              <div>
+                <h4 className="font-semibold mb-2">Arrow Keys</h4>
+                <ul className="space-y-1 text-gray-600">
+                  <li>↑ ↓ Shoulder lift</li>
+                  <li>← → Shoulder pan</li>
+                </ul>
+              </div>
+              <div>
+                <h4 className="font-semibold mb-2">WASD Keys</h4>
+                <ul className="space-y-1 text-gray-600">
+                  <li>W S Elbow flex</li>
+                  <li>A D Wrist flex</li>
+                </ul>
+              </div>
+              <div>
+                <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>
+                </ul>
+              </div>
+              <div>
+                <h4 className="font-semibold mb-2 text-red-700">Emergency</h4>
+                <ul className="space-y-1 text-red-600">
+                  <li>ESC Emergency stop</li>
+                </ul>
+              </div>
+            </div>
+            <div className="mt-4 p-3 bg-blue-50 rounded-lg">
+              <p className="text-sm text-blue-800">
+                💡 <strong>Pro tip:</strong> Use your physical keyboard for
+                faster control, or click the virtual keys below. Hold keys down
+                for continuous movement.
+              </p>
+            </div>
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  );
+}

src/demo/hooks/useRobotConnection.ts

@@ -0,0 +1,91 @@
+import { useState, useEffect, useCallback } from "react";
+import {
+  getRobotConnectionManager,
+  type RobotConnectionState,
+  writeMotorPosition,
+  readMotorPosition,
+  readAllMotorPositions,
+} from "../../lerobot/web/robot-connection";
+
+export interface UseRobotConnectionResult {
+  // Connection state
+  isConnected: boolean;
+  robotType?: "so100_follower" | "so100_leader";
+  robotId?: string;
+  serialNumber?: string;
+  lastError?: string;
+
+  // Connection management
+  connect: (
+    port: SerialPort,
+    robotType: string,
+    robotId: string,
+    serialNumber: string
+  ) => Promise<void>;
+  disconnect: () => Promise<void>;
+
+  // Robot operations
+  writeMotorPosition: (motorId: number, position: number) => Promise<void>;
+  readMotorPosition: (motorId: number) => Promise<number | null>;
+  readAllMotorPositions: (motorIds: number[]) => Promise<number[]>;
+
+  // Raw port access (for advanced use cases)
+  getPort: () => SerialPort | null;
+}
+
+/**
+ * React hook for robot connection management
+ * Uses the singleton connection manager as single source of truth
+ */
+export function useRobotConnection(): UseRobotConnectionResult {
+  const manager = getRobotConnectionManager();
+  const [state, setState] = useState<RobotConnectionState>(manager.getState());
+
+  // Subscribe to connection state changes
+  useEffect(() => {
+    const unsubscribe = manager.onStateChange(setState);
+
+    // Set initial state
+    setState(manager.getState());
+
+    return unsubscribe;
+  }, [manager]);
+
+  // Connection management functions
+  const connect = useCallback(
+    async (
+      port: SerialPort,
+      robotType: string,
+      robotId: string,
+      serialNumber: string
+    ) => {
+      await manager.connect(port, robotType, robotId, serialNumber);
+    },
+    [manager]
+  );
+
+  const disconnect = useCallback(async () => {
+    await manager.disconnect();
+  }, [manager]);
+
+  const getPort = useCallback(() => {
+    return manager.getPort();
+  }, [manager]);
+
+  return {
+    // State
+    isConnected: state.isConnected,
+    robotType: state.robotType,
+    robotId: state.robotId,
+    serialNumber: state.serialNumber,
+    lastError: state.lastError,
+
+    // Methods
+    connect,
+    disconnect,
+    writeMotorPosition,
+    readMotorPosition,
+    readAllMotorPositions,
+    getPort,
+  };
+}

src/demo/hooks/useTeleoperation.ts

@@ -0,0 +1,486 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import { useRobotConnection } from "./useRobotConnection";
+import { getUnifiedRobotData } from "../lib/unified-storage";
+import type { ConnectedRobot } from "../types";
+
+export interface MotorConfig {
+  name: string;
+  minPosition: number;
+  maxPosition: number;
+  currentPosition: number;
+  homePosition: number;
+}
+
+export interface KeyState {
+  pressed: boolean;
+  lastPressed: number;
+}
+
+export interface UseTeleoperationOptions {
+  robot: ConnectedRobot;
+  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;
+}
+
+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" },
+  " ": { motorIndex: 5, direction: 1, description: "Gripper open/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]
+  );
+
+  return {
+    isConnected: connection.isConnected,
+    isActive,
+    motorConfigs,
+    keyStates,
+    error,
+    start,
+    stop,
+    goToHome,
+    simulateKeyPress,
+    simulateKeyRelease,
+  };
+}

src/demo/pages/Home.tsx

@@ -10,6 +10,7 @@ import {
 import { Alert, AlertDescription } from "../components/ui/alert";
 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";
 
@@ -26,6 +27,8 @@ export function Home({
 }: HomeProps) {
   const [calibratingRobot, setCalibratingRobot] =
     useState<ConnectedRobot | null>(null);
+  const [teleoperatingRobot, setTeleoperatingRobot] =
+    useState<ConnectedRobot | null>(null);
   const isSupported = isWebSerialSupported();
 
   const handleCalibrate = (
@@ -40,10 +43,18 @@ export function Home({
     }
   };
 
+  const handleTeleoperate = (robot: ConnectedRobot) => {
+    setTeleoperatingRobot(robot);
+  };
+
   const handleFinishCalibration = () => {
     setCalibratingRobot(null);
   };
 
+  const handleFinishTeleoperation = () => {
+    setTeleoperatingRobot(null);
+  };
+
   return (
     <div className="min-h-screen bg-gradient-to-br from-blue-50 to-indigo-100">
       <div className="container mx-auto px-6 py-12">
@@ -83,10 +94,16 @@ export function Home({
               onFinish={handleFinishCalibration}
             />
           </div>
+        ) : teleoperatingRobot ? (
+          <TeleoperationPanel
+            robot={teleoperatingRobot}
+            onClose={handleFinishTeleoperation}
+          />
         ) : (
           <div className="max-w-6xl mx-auto">
             <PortManager
               onCalibrate={handleCalibrate}
+              onTeleoperate={handleTeleoperate}
               connectedRobots={connectedRobots}
               onConnectedRobotsChange={onConnectedRobotsChange}
             />

src/lerobot/web/motor-utils.ts

@@ -0,0 +1,266 @@
+/**
+ * Shared Motor Communication Utilities
+ * Proven patterns from calibrate.ts for consistent motor communication
+ * Used by both calibration and teleoperation
+ */
+
+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
+ */
+export async function readMotorPosition(
+  port: MotorCommunicationPort,
+  motorId: number
+): Promise<number | null> {
+  try {
+    // Create Read Position packet using proven pattern
+    const packet = new Uint8Array([
+      0xff,
+      0xff, // Header
+      motorId, // Servo ID
+      0x04, // Length
+      0x02, // Instruction: READ_DATA
+      STS3215_PROTOCOL.PRESENT_POSITION_ADDRESS, // Present_Position register address
+      0x02, // Data length (2 bytes)
+      0x00, // Checksum placeholder
+    ]);
+
+    const checksum =
+      ~(
+        motorId +
+        0x04 +
+        0x02 +
+        STS3215_PROTOCOL.PRESENT_POSITION_ADDRESS +
+        0x02
+      ) & 0xff;
+    packet[7] = checksum;
+
+    // PROVEN PATTERN: Professional Feetech communication with retry logic
+    let attempts = 0;
+
+    while (attempts < STS3215_PROTOCOL.MAX_RETRIES) {
+      attempts++;
+
+      // CRITICAL: Clear any remaining data in buffer first (from calibration lessons)
+      try {
+        await port.read(0); // Non-blocking read to clear buffer
+      } catch (e) {
+        // Expected - buffer was empty
+      }
+
+      // Write command with PROVEN timing
+      await port.write(packet);
+
+      // PROVEN TIMING: Arduino library uses careful timing - Web Serial needs more
+      await new Promise((resolve) =>
+        setTimeout(resolve, STS3215_PROTOCOL.WRITE_TO_READ_DELAY)
+      );
+
+      try {
+        const response = await 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);
+            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
+      }
+
+      // PROVEN TIMING: Professional timing between attempts
+      if (attempts < STS3215_PROTOCOL.MAX_RETRIES) {
+        await new Promise((resolve) =>
+          setTimeout(resolve, STS3215_PROTOCOL.RETRY_DELAY)
+        );
+      }
+    }
+
+    // If all attempts failed, return null
+    return null;
+  } catch (error) {
+    console.warn(`Failed to read motor ${motorId} position:`, error);
+    return null;
+  }
+}
+
+/**
+ * Read all motor positions with PROVEN patterns
+ * Exactly matches calibrate.ts readMotorPositions() function
+ */
+export async function readAllMotorPositions(
+  port: MotorCommunicationPort,
+  motorIds: number[]
+): Promise<number[]> {
+  const motorPositions: number[] = [];
+
+  for (let i = 0; i < motorIds.length; i++) {
+    const motorId = motorIds[i];
+
+    const position = await readMotorPosition(port, motorId);
+
+    if (position !== null) {
+      motorPositions.push(position);
+    } else {
+      // Use fallback value for failed reads
+      const fallback = Math.floor((STS3215_PROTOCOL.RESOLUTION - 1) / 2);
+      motorPositions.push(fallback);
+    }
+
+    // PROVEN PATTERN: Professional inter-motor delay
+    await new Promise((resolve) =>
+      setTimeout(resolve, STS3215_PROTOCOL.INTER_MOTOR_DELAY)
+    );
+  }
+
+  return motorPositions;
+}
+
+/**
+ * Write motor position with error handling
+ */
+export async function writeMotorPosition(
+  port: MotorCommunicationPort,
+  motorId: number,
+  position: number
+): Promise<void> {
+  // STS3215 Write Goal_Position packet
+  const packet = new Uint8Array([
+    0xff,
+    0xff, // Header
+    motorId, // Servo ID
+    0x05, // Length
+    0x03, // Instruction: WRITE_DATA
+    STS3215_PROTOCOL.GOAL_POSITION_ADDRESS, // 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 +
+      STS3215_PROTOCOL.GOAL_POSITION_ADDRESS +
+      (position & 0xff) +
+      ((position >> 8) & 0xff)
+    ) & 0xff;
+  packet[8] = checksum;
+
+  await port.write(packet);
+}
+
+/**
+ * Generic function to write a 2-byte value to a motor register
+ * Matches calibrate.ts writeMotorRegister() exactly
+ */
+export async function writeMotorRegister(
+  port: MotorCommunicationPort,
+  motorId: number,
+  registerAddress: number,
+  value: number
+): 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 placeholder
+  ]);
+
+  // Calculate checksum
+  const checksum =
+    ~(
+      motorId +
+      0x05 +
+      0x03 +
+      registerAddress +
+      (value & 0xff) +
+      ((value >> 8) & 0xff)
+    ) & 0xff;
+  packet[8] = checksum;
+
+  // Simple write then read like calibration
+  await port.write(packet);
+
+  // Wait for response (silent unless error)
+  try {
+    await port.read(200);
+  } catch (error) {
+    // Silent - response not required for successful operation
+  }
+}
+
+/**
+ * Sign-magnitude encoding functions (from calibrate.ts)
+ */
+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;
+}
+
+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/robot-connection.ts

@@ -0,0 +1,228 @@
+/**
+ * Core Robot Connection Manager
+ * Single source of truth for robot connections in the web library
+ * Provides singleton access to robot ports and connection state
+ */
+
+import {
+  readMotorPosition as readMotorPositionUtil,
+  writeMotorPosition as writeMotorPositionUtil,
+  readAllMotorPositions as readAllMotorPositionsUtil,
+  writeMotorRegister,
+  type MotorCommunicationPort,
+} from "./motor-utils.js";
+
+export interface RobotConnectionState {
+  isConnected: boolean;
+  robotType?: "so100_follower" | "so100_leader";
+  robotId?: string;
+  serialNumber?: string;
+  lastError?: string;
+}
+
+export interface RobotConnectionManager {
+  // State
+  getState(): RobotConnectionState;
+
+  // Connection management
+  connect(
+    port: SerialPort,
+    robotType: string,
+    robotId: string,
+    serialNumber: string
+  ): Promise<void>;
+  disconnect(): Promise<void>;
+
+  // Port access
+  getPort(): SerialPort | null;
+
+  // Serial operations (shared by calibration, teleoperation, etc.)
+  writeData(data: Uint8Array): Promise<void>;
+  readData(timeout?: number): Promise<Uint8Array>;
+
+  // Event system
+  onStateChange(callback: (state: RobotConnectionState) => void): () => void;
+}
+
+/**
+ * Singleton Robot Connection Manager Implementation
+ */
+class RobotConnectionManagerImpl implements RobotConnectionManager {
+  private port: SerialPort | null = null;
+  private state: RobotConnectionState = { isConnected: false };
+  private stateChangeCallbacks: Set<(state: RobotConnectionState) => void> =
+    new Set();
+
+  getState(): RobotConnectionState {
+    return { ...this.state };
+  }
+
+  async connect(
+    port: SerialPort,
+    robotType: string,
+    robotId: string,
+    serialNumber: string
+  ): Promise<void> {
+    try {
+      // Validate port is open
+      if (!port.readable || !port.writable) {
+        throw new Error("Port is not open");
+      }
+
+      // Update connection state
+      this.port = port;
+      this.state = {
+        isConnected: true,
+        robotType: robotType as "so100_follower" | "so100_leader",
+        robotId,
+        serialNumber,
+        lastError: undefined,
+      };
+
+      this.notifyStateChange();
+      console.log(
+        `🤖 Robot connected: ${robotType} (${robotId}) - ${serialNumber}`
+      );
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : "Connection failed";
+      this.state = {
+        isConnected: false,
+        lastError: errorMessage,
+      };
+      this.notifyStateChange();
+      throw error;
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    this.port = null;
+    this.state = { isConnected: false };
+    this.notifyStateChange();
+    console.log("🤖 Robot disconnected");
+  }
+
+  getPort(): SerialPort | null {
+    return this.port;
+  }
+
+  async writeData(data: Uint8Array): Promise<void> {
+    if (!this.port?.writable) {
+      throw new Error("Robot not connected or port not writable");
+    }
+
+    const writer = this.port.writable.getWriter();
+    try {
+      await writer.write(data);
+    } finally {
+      writer.releaseLock();
+    }
+  }
+
+  async readData(timeout: number = 1000): Promise<Uint8Array> {
+    if (!this.port?.readable) {
+      throw new Error("Robot not connected or port not readable");
+    }
+
+    const reader = this.port.readable.getReader();
+
+    try {
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new Error("Read timeout")), timeout);
+      });
+
+      const readPromise = reader.read().then((result) => {
+        if (result.done || !result.value) {
+          throw new Error("Read failed - port closed or no data");
+        }
+        return result.value;
+      });
+
+      return await Promise.race([readPromise, timeoutPromise]);
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  onStateChange(callback: (state: RobotConnectionState) => void): () => void {
+    this.stateChangeCallbacks.add(callback);
+
+    // Return unsubscribe function
+    return () => {
+      this.stateChangeCallbacks.delete(callback);
+    };
+  }
+
+  private notifyStateChange(): void {
+    this.stateChangeCallbacks.forEach((callback) => {
+      try {
+        callback(this.getState());
+      } catch (error) {
+        console.warn("Error in state change callback:", error);
+      }
+    });
+  }
+}
+
+// Singleton instance
+const robotConnectionManager = new RobotConnectionManagerImpl();
+
+/**
+ * Get the singleton robot connection manager
+ * This is the single source of truth for robot connections
+ */
+export function getRobotConnectionManager(): RobotConnectionManager {
+  return robotConnectionManager;
+}
+
+/**
+ * Utility functions for common robot operations
+ * Uses shared motor communication utilities for consistency
+ */
+
+/**
+ * Adapter to make robot connection manager compatible with motor utils
+ */
+class RobotConnectionManagerAdapter implements MotorCommunicationPort {
+  private manager: RobotConnectionManager;
+
+  constructor(manager: RobotConnectionManager) {
+    this.manager = manager;
+  }
+
+  async write(data: Uint8Array): Promise<void> {
+    return this.manager.writeData(data);
+  }
+
+  async read(timeout?: number): Promise<Uint8Array> {
+    return this.manager.readData(timeout);
+  }
+}
+
+export async function writeMotorPosition(
+  motorId: number,
+  position: number
+): Promise<void> {
+  const manager = getRobotConnectionManager();
+  const adapter = new RobotConnectionManagerAdapter(manager);
+
+  return writeMotorPositionUtil(adapter, motorId, position);
+}
+
+export async function readMotorPosition(
+  motorId: number
+): Promise<number | null> {
+  const manager = getRobotConnectionManager();
+  const adapter = new RobotConnectionManagerAdapter(manager);
+
+  return readMotorPositionUtil(adapter, motorId);
+}
+
+export async function readAllMotorPositions(
+  motorIds: number[]
+): Promise<number[]> {
+  const manager = getRobotConnectionManager();
+  const adapter = new RobotConnectionManagerAdapter(manager);
+
+  return readAllMotorPositionsUtil(adapter, motorIds);
+}

src/lerobot/web/teleoperate.ts

@@ -0,0 +1,525 @@
+/**
+ * Web teleoperation functionality using Web Serial API
+ * Mirrors the Node.js implementation but adapted for browser environment
+ */
+
+import type { UnifiedRobotData } from "../../demo/lib/unified-storage.js";
+
+/**
+ * Motor position and limits for teleoperation
+ */
+export interface MotorConfig {
+  id: number;
+  name: string;
+  currentPosition: number;
+  minPosition: number;
+  maxPosition: number;
+  homePosition: number;
+}
+
+/**
+ * Teleoperation state
+ */
+export interface TeleoperationState {
+  isActive: boolean;
+  motorConfigs: MotorConfig[];
+  lastUpdate: number;
+  keyStates: { [key: string]: { pressed: boolean; timestamp: number } };
+}
+
+/**
+ * Keyboard control mapping (matches Node.js version)
+ */
+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" },
+  " ": { motor: "gripper", direction: 1, description: "Gripper toggle" },
+
+  // Emergency stop
+  Escape: {
+    motor: "emergency_stop",
+    direction: 0,
+    description: "Emergency stop",
+  },
+} as const;
+
+/**
+ * Web Serial Port wrapper for teleoperation
+ * Uses the same pattern as calibration - per-operation reader/writer access
+ */
+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
+  }
+}
+
+/**
+ * Load calibration data from unified storage with fallback to defaults
+ * Improved version that properly loads and applies calibration ranges
+ */
+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;
+    }
+
+    // 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;
+  }
+}
+
+/**
+ * Web teleoperation controller
+ */
+export class WebTeleoperationController {
+  private port: WebTeleoperationPort;
+  private motorConfigs: MotorConfig[] = [];
+  private isActive: boolean = false;
+  private updateInterval: NodeJS.Timeout | null = null;
+  private keyStates: {
+    [key: string]: { pressed: boolean; timestamp: number };
+  } = {};
+
+  // 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);
+  }
+
+  async initialize(): Promise<void> {
+    await this.port.initialize();
+
+    // Read current positions
+    for (const config of this.motorConfigs) {
+      const position = await this.port.readMotorPosition(config.id);
+      if (position !== null) {
+        config.currentPosition = position;
+      }
+    }
+  }
+
+  getMotorConfigs(): MotorConfig[] {
+    return [...this.motorConfigs];
+  }
+
+  getState(): TeleoperationState {
+    return {
+      isActive: this.isActive,
+      motorConfigs: [...this.motorConfigs],
+      lastUpdate: Date.now(),
+      keyStates: { ...this.keyStates },
+    };
+  }
+
+  updateKeyState(key: string, pressed: boolean): void {
+    this.keyStates[key] = {
+      pressed,
+      timestamp: Date.now(),
+    };
+  }
+
+  start(): void {
+    if (this.isActive) return;
+
+    this.isActive = true;
+    this.updateInterval = setInterval(() => {
+      this.updateMotorPositions();
+    }, 1000 / this.UPDATE_RATE);
+
+    console.log("🎮 Web teleoperation started");
+  }
+
+  stop(): void {
+    if (!this.isActive) return;
+
+    this.isActive = false;
+
+    if (this.updateInterval) {
+      clearInterval(this.updateInterval);
+      this.updateInterval = null;
+    }
+
+    // Clear all key states
+    this.keyStates = {};
+
+    console.log("⏹️ Web teleoperation stopped");
+  }
+
+  async disconnect(): Promise<void> {
+    this.stop();
+    await this.port.disconnect();
+  }
+
+  private updateMotorPositions(): void {
+    const now = Date.now();
+
+    // Clear timed-out keys
+    Object.keys(this.keyStates).forEach((key) => {
+      if (now - this.keyStates[key].timestamp > this.KEY_TIMEOUT) {
+        delete this.keyStates[key];
+      }
+    });
+
+    // Process active keys
+    const activeKeys = Object.keys(this.keyStates).filter(
+      (key) =>
+        this.keyStates[key].pressed &&
+        now - this.keyStates[key].timestamp <= this.KEY_TIMEOUT
+    );
+
+    // Emergency stop check
+    if (activeKeys.includes("Escape")) {
+      this.stop();
+      return;
+    }
+
+    // Calculate target positions based on active keys
+    const targetPositions: { [motorName: string]: number } = {};
+
+    for (const key of activeKeys) {
+      const control = KEYBOARD_CONTROLS[key as keyof typeof KEYBOARD_CONTROLS];
+      if (!control || control.motor === "emergency_stop") continue;
+
+      const motorConfig = this.motorConfigs.find(
+        (m) => m.name === control.motor
+      );
+      if (!motorConfig) continue;
+
+      // Calculate new position
+      const currentTarget =
+        targetPositions[motorConfig.name] ?? motorConfig.currentPosition;
+      const newPosition = currentTarget + control.direction * this.STEP_SIZE;
+
+      // Apply limits
+      targetPositions[motorConfig.name] = Math.max(
+        motorConfig.minPosition,
+        Math.min(motorConfig.maxPosition, newPosition)
+      );
+    }
+
+    // Send motor commands
+    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;
+            }
+          });
+      }
+    });
+  }
+
+  // Programmatic control methods
+  async moveMotor(motorName: string, targetPosition: number): Promise<boolean> {
+    const motorConfig = this.motorConfigs.find((m) => m.name === motorName);
+    if (!motorConfig) return false;
+
+    const clampedPosition = Math.max(
+      motorConfig.minPosition,
+      Math.min(motorConfig.maxPosition, targetPosition)
+    );
+
+    const success = await this.port.writeMotorPosition(
+      motorConfig.id,
+      Math.round(clampedPosition)
+    );
+    if (success) {
+      motorConfig.currentPosition = clampedPosition;
+    }
+
+    return success;
+  }
+
+  async setMotorPositions(positions: {
+    [motorName: string]: number;
+  }): Promise<boolean> {
+    const results = await Promise.all(
+      Object.entries(positions).map(([motorName, position]) =>
+        this.moveMotor(motorName, position)
+      )
+    );
+
+    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
+ */
+export async function createWebTeleoperationController(
+  port: SerialPort,
+  serialNumber: string
+): Promise<WebTeleoperationController> {
+  const controller = new WebTeleoperationController(port, serialNumber);
+  await controller.initialize();
+  return controller;
+}