recover: restore deleted src/lerobot/node/ folder from ec936d5

examples/demo/App.tsx

@@ -0,0 +1,19 @@
+import { useState } from "react";
+import { Home } from "./pages/Home";
+import { ErrorBoundary } from "./components/ErrorBoundary";
+import type { RobotConnection } from "@lerobot/web";
+
+export function App() {
+  const [connectedRobots, setConnectedRobots] = useState<RobotConnection[]>([]);
+
+  return (
+    <ErrorBoundary>
+      <div className="min-h-screen bg-background">
+        <Home
+          connectedRobots={connectedRobots}
+          onConnectedRobotsChange={setConnectedRobots}
+        />
+      </div>
+    </ErrorBoundary>
+  );
+}

examples/demo/components/CalibrationModal.tsx

@@ -0,0 +1,49 @@
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "./ui/dialog";
+import { Button } from "./ui/button";
+
+interface CalibrationModalProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  deviceType: string;
+  onContinue: () => void;
+}
+
+export function CalibrationModal({
+  open,
+  onOpenChange,
+  deviceType,
+  onContinue,
+}: CalibrationModalProps) {
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>📍 Set Homing Position</DialogTitle>
+          <DialogDescription className="text-base py-4">
+            Move the SO-100 {deviceType} to the <strong>MIDDLE</strong> of its
+            range of motion and click OK when ready.
+            <br />
+            <br />
+            The calibration will then automatically:
+            <br />• Record homing offsets
+            <br />• Record joint ranges (manual - you control when to stop)
+            <br />• Save configuration file
+          </DialogDescription>
+        </DialogHeader>
+
+        <DialogFooter>
+          <Button onClick={onContinue} className="w-full">
+            OK - Start Calibration
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

examples/demo/components/CalibrationPanel.tsx

@@ -0,0 +1,419 @@
+import { useState, useCallback, useMemo } from "react";
+import { Button } from "./ui/button.js";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "./ui/card.js";
+import { Badge } from "./ui/badge.js";
+import {
+  calibrate,
+  type WebCalibrationResults,
+  type LiveCalibrationData,
+  type CalibrationProcess,
+} from "@lerobot/web";
+import { releaseMotors } from "@lerobot/web";
+import { WebSerialPortWrapper } from "@lerobot/web";
+import { createSO100Config } from "@lerobot/web";
+import { CalibrationModal } from "./CalibrationModal.js";
+import type { RobotConnection } from "@lerobot/web";
+
+interface CalibrationPanelProps {
+  robot: RobotConnection;
+  onFinish: () => void;
+}
+
+export function CalibrationPanel({ robot, onFinish }: CalibrationPanelProps) {
+  // Simple state management
+  const [isCalibrating, setIsCalibrating] = useState(false);
+  const [calibrationResult, setCalibrationResult] =
+    useState<WebCalibrationResults | null>(null);
+  const [status, setStatus] = useState<string>("Ready to calibrate");
+  const [modalOpen, setModalOpen] = useState(false);
+  const [calibrationProcess, setCalibrationProcess] =
+    useState<CalibrationProcess | null>(null);
+  const [motorData, setMotorData] = useState<LiveCalibrationData>({});
+  const [isPreparing, setIsPreparing] = useState(false);
+
+  // Motor names for display
+  const motorNames = useMemo(
+    () => [
+      "shoulder_pan",
+      "shoulder_lift",
+      "elbow_flex",
+      "wrist_flex",
+      "wrist_roll",
+      "gripper",
+    ],
+    []
+  );
+
+  // Initialize motor data
+  const initializeMotorData = useCallback(() => {
+    const initialData: LiveCalibrationData = {};
+    motorNames.forEach((name) => {
+      initialData[name] = {
+        current: 2047,
+        min: 2047,
+        max: 2047,
+        range: 0,
+      };
+    });
+    setMotorData(initialData);
+  }, [motorNames]);
+
+  // Release motor torque for better UX - allows immediate joint movement
+  const releaseMotorTorque = useCallback(async () => {
+    if (!robot.port || !robot.robotType) {
+      return;
+    }
+
+    try {
+      setIsPreparing(true);
+      setStatus("🔓 Releasing motor torque - joints can now be moved freely");
+
+      // Create port wrapper and config to get motor IDs
+      const port = new WebSerialPortWrapper(robot.port);
+      await port.initialize();
+      const config = createSO100Config(robot.robotType);
+
+      // Release motors so they can be moved freely by hand
+      await releaseMotors(port, config.motorIds);
+
+      setStatus("✅ Joints are now free to move - set your homing position");
+    } catch (error) {
+      console.warn("Failed to release motor torque:", error);
+      setStatus("⚠️ Could not release motor torque - try moving joints gently");
+    } finally {
+      setIsPreparing(false);
+    }
+  }, [robot]);
+
+  // Start calibration using new API
+  const handleContinueCalibration = useCallback(async () => {
+    setModalOpen(false);
+
+    if (!robot.port || !robot.robotType) {
+      return;
+    }
+
+    try {
+      setStatus("🤖 Starting calibration process...");
+      setIsCalibrating(true);
+      initializeMotorData();
+
+      // Use the simple calibrate API - just pass the robot connection
+      const process = await calibrate(robot, {
+        onLiveUpdate: (data) => {
+          setMotorData(data);
+          setStatus(
+            "📏 Recording joint ranges - move all joints through their full range"
+          );
+        },
+        onProgress: (message) => {
+          setStatus(message);
+        },
+      });
+
+      setCalibrationProcess(process);
+
+      // Add Enter key listener for stopping (matching Node.js UX)
+      const handleKeyPress = (event: KeyboardEvent) => {
+        if (event.key === "Enter") {
+          process.stop();
+        }
+      };
+      document.addEventListener("keydown", handleKeyPress);
+
+      try {
+        // Wait for calibration to complete
+        const result = await process.result;
+        setCalibrationResult(result);
+
+        // App-level concern: Save results to storage
+        const serialNumber =
+          robot.serialNumber || robot.usbMetadata?.serialNumber || "unknown";
+        await saveCalibrationResults(
+          result,
+          robot.robotType,
+          robot.robotId || `${robot.robotType}_1`,
+          serialNumber
+        );
+
+        setStatus(
+          "✅ Calibration completed successfully! Configuration saved."
+        );
+      } finally {
+        document.removeEventListener("keydown", handleKeyPress);
+        setCalibrationProcess(null);
+        setIsCalibrating(false);
+      }
+    } catch (error) {
+      console.error("❌ Calibration failed:", error);
+      setStatus(
+        `❌ Calibration failed: ${
+          error instanceof Error ? error.message : error
+        }`
+      );
+      setIsCalibrating(false);
+      setCalibrationProcess(null);
+    }
+  }, [robot, initializeMotorData]);
+
+  // Stop calibration recording
+  const handleStopRecording = useCallback(() => {
+    if (calibrationProcess) {
+      calibrationProcess.stop();
+    }
+  }, [calibrationProcess]);
+
+  // App-level concern: Save calibration results
+  const saveCalibrationResults = async (
+    results: WebCalibrationResults,
+    robotType: string,
+    robotId: string,
+    serialNumber: string
+  ) => {
+    try {
+      // Save to unified storage (app-level functionality)
+      const { saveCalibrationData } = await import("../lib/unified-storage.js");
+
+      const fullCalibrationData = {
+        ...results,
+        device_type: robotType,
+        device_id: robotId,
+        calibrated_at: new Date().toISOString(),
+        platform: "web",
+        api: "Web Serial API",
+      };
+
+      const metadata = {
+        timestamp: new Date().toISOString(),
+        readCount: Object.keys(motorData).length > 0 ? 100 : 0, // Estimate
+      };
+
+      saveCalibrationData(serialNumber, fullCalibrationData, metadata);
+    } catch (error) {
+      console.warn("Failed to save calibration results:", error);
+    }
+  };
+
+  // App-level concern: JSON export functionality
+  const downloadConfigJSON = useCallback(() => {
+    if (!calibrationResult) return;
+
+    const jsonString = JSON.stringify(calibrationResult, null, 2);
+    const blob = new Blob([jsonString], { type: "application/json" });
+    const url = URL.createObjectURL(blob);
+
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = `${robot.robotId || robot.robotType}_calibration.json`;
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    URL.revokeObjectURL(url);
+  }, [calibrationResult, robot.robotId, robot.robotType]);
+
+  return (
+    <div className="space-y-4">
+      {/* Calibration Status Card */}
+      <Card>
+        <CardHeader>
+          <div className="flex items-center justify-between">
+            <div>
+              <CardTitle className="text-lg">
+                🛠️ Calibrating: {robot.robotId}
+              </CardTitle>
+              <CardDescription>
+                {robot.robotType?.replace("_", " ")} • {robot.name}
+              </CardDescription>
+            </div>
+            <Badge
+              variant={
+                isCalibrating
+                  ? "default"
+                  : calibrationResult
+                  ? "default"
+                  : "outline"
+              }
+            >
+              {isCalibrating
+                ? "Recording"
+                : calibrationResult
+                ? "Complete"
+                : "Ready"}
+            </Badge>
+          </div>
+        </CardHeader>
+        <CardContent>
+          <div className="space-y-4">
+            <div className="p-3 bg-blue-50 rounded-lg">
+              <p className="text-sm font-medium text-blue-900">Status:</p>
+              <p className="text-sm text-blue-800">{status}</p>
+              {isCalibrating && (
+                <p className="text-xs text-blue-600 mt-1">
+                  Move joints through full range | Press "Finish Recording" or
+                  Enter key when done
+                </p>
+              )}
+            </div>
+
+            <div className="flex gap-2">
+              {!isCalibrating && !calibrationResult && (
+                <Button
+                  onClick={async () => {
+                    // Release motor torque FIRST - so user can move joints immediately
+                    await releaseMotorTorque();
+                    // THEN open modal - user can now follow instructions right away
+                    setModalOpen(true);
+                  }}
+                  disabled={isPreparing}
+                >
+                  {isPreparing ? "Preparing..." : "Start Calibration"}
+                </Button>
+              )}
+
+              {isCalibrating && calibrationProcess && (
+                <Button onClick={handleStopRecording} variant="default">
+                  Finish Recording
+                </Button>
+              )}
+
+              {calibrationResult && (
+                <>
+                  <Button onClick={downloadConfigJSON} variant="outline">
+                    Download Config JSON
+                  </Button>
+                  <Button onClick={onFinish}>Done</Button>
+                </>
+              )}
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Configuration JSON Display */}
+      {calibrationResult && (
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-lg">
+              🎯 Calibration Configuration
+            </CardTitle>
+            <CardDescription>
+              Copy this JSON or download it for your robot setup
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <div className="space-y-3">
+              <pre className="bg-gray-100 p-4 rounded-lg text-sm overflow-x-auto border">
+                <code>{JSON.stringify(calibrationResult, null, 2)}</code>
+              </pre>
+              <div className="flex gap-2">
+                <Button onClick={downloadConfigJSON} variant="outline">
+                  📄 Download JSON File
+                </Button>
+                <Button
+                  onClick={() => {
+                    navigator.clipboard.writeText(
+                      JSON.stringify(calibrationResult, null, 2)
+                    );
+                  }}
+                  variant="outline"
+                >
+                  📋 Copy to Clipboard
+                </Button>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+      )}
+
+      {/* Live Position Recording Table */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-lg">Live Position Recording</CardTitle>
+          <CardDescription>
+            Real-time motor position feedback during calibration
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="overflow-hidden rounded-lg border">
+            <table className="w-full font-mono text-sm">
+              <thead className="bg-gray-50">
+                <tr>
+                  <th className="px-4 py-2 text-left font-medium text-gray-900">
+                    Motor Name
+                  </th>
+                  <th className="px-4 py-2 text-right font-medium text-gray-900">
+                    Current
+                  </th>
+                  <th className="px-4 py-2 text-right font-medium text-gray-900">
+                    Min
+                  </th>
+                  <th className="px-4 py-2 text-right font-medium text-gray-900">
+                    Max
+                  </th>
+                  <th className="px-4 py-2 text-right font-medium text-gray-900">
+                    Range
+                  </th>
+                </tr>
+              </thead>
+              <tbody className="divide-y divide-gray-200">
+                {motorNames.map((motorName) => {
+                  const motor = motorData[motorName] || {
+                    current: 2047,
+                    min: 2047,
+                    max: 2047,
+                    range: 0,
+                  };
+
+                  return (
+                    <tr key={motorName} className="hover:bg-gray-50">
+                      <td className="px-4 py-2 font-medium flex items-center gap-2">
+                        {motorName}
+                        {motor.range > 100 && (
+                          <span className="text-green-600 text-xs">✓</span>
+                        )}
+                      </td>
+                      <td className="px-4 py-2 text-right">{motor.current}</td>
+                      <td className="px-4 py-2 text-right">{motor.min}</td>
+                      <td className="px-4 py-2 text-right">{motor.max}</td>
+                      <td className="px-4 py-2 text-right font-medium">
+                        <span
+                          className={
+                            motor.range > 100
+                              ? "text-green-600"
+                              : "text-gray-500"
+                          }
+                        >
+                          {motor.range}
+                        </span>
+                      </td>
+                    </tr>
+                  );
+                })}
+              </tbody>
+            </table>
+          </div>
+
+          {isCalibrating && (
+            <div className="mt-3 text-center text-sm text-gray-600">
+              Move joints through their full range of motion...
+            </div>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* Calibration Modal */}
+      <CalibrationModal
+        open={modalOpen}
+        onOpenChange={setModalOpen}
+        deviceType={robot.robotType || "robot"}
+        onContinue={handleContinueCalibration}
+      />
+    </div>
+  );
+}

examples/demo/components/ErrorBoundary.tsx

@@ -0,0 +1,65 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+import { Alert, AlertDescription, AlertTitle } from "./ui/alert";
+import { Button } from "./ui/button";
+
+interface Props {
+  children: ReactNode;
+}
+
+interface State {
+  hasError: boolean;
+  error?: Error;
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error("ErrorBoundary caught an error:", error, errorInfo);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <div className="min-h-screen flex items-center justify-center p-8">
+          <div className="max-w-md w-full">
+            <Alert variant="destructive">
+              <AlertTitle>Something went wrong</AlertTitle>
+              <AlertDescription>
+                The application encountered an error. Please try refreshing the
+                page or contact support if the problem persists.
+              </AlertDescription>
+            </Alert>
+            <div className="mt-4 flex gap-2">
+              <Button onClick={() => window.location.reload()}>
+                Refresh Page
+              </Button>
+              <Button
+                variant="outline"
+                onClick={() =>
+                  this.setState({ hasError: false, error: undefined })
+                }
+              >
+                Try Again
+              </Button>
+            </div>
+            {process.env.NODE_ENV === "development" && this.state.error && (
+              <div className="mt-4 p-4 bg-gray-100 rounded-md text-xs">
+                <pre>{this.state.error.stack}</pre>
+              </div>
+            )}
+          </div>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}

examples/demo/components/PortManager.tsx

@@ -0,0 +1,1251 @@
+import { useState, useEffect } from "react";
+import { Button } from "./ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "./ui/card";
+import { Alert, AlertDescription } from "./ui/alert";
+import { Badge } from "./ui/badge";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "./ui/dialog";
+import { isWebSerialSupported } from "@lerobot/web";
+import type { RobotConnection } from "@lerobot/web";
+
+/**
+ * Type definitions for WebSerial API (missing from TypeScript)
+ */
+interface SerialPortInfo {
+  usbVendorId?: number;
+  usbProductId?: number;
+}
+
+declare global {
+  interface SerialPort {
+    getInfo(): SerialPortInfo;
+  }
+}
+
+interface PortManagerProps {
+  connectedRobots: RobotConnection[];
+  onConnectedRobotsChange: (robots: RobotConnection[]) => void;
+  onCalibrate?: (
+    port: SerialPort,
+    robotType: "so100_follower" | "so100_leader",
+    robotId: string
+  ) => void;
+  onTeleoperate?: (robot: RobotConnection) => void;
+}
+
+export function PortManager({
+  connectedRobots,
+  onConnectedRobotsChange,
+  onCalibrate,
+  onTeleoperate,
+}: PortManagerProps) {
+  const [isConnecting, setIsConnecting] = useState(false);
+  const [isFindingPorts, setIsFindingPorts] = useState(false);
+  const [findPortsLog, setFindPortsLog] = useState<string[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [confirmDeleteDialog, setConfirmDeleteDialog] = useState<{
+    open: boolean;
+    robotIndex: number;
+    robotName: string;
+    serialNumber: string;
+  }>({
+    open: false,
+    robotIndex: -1,
+    robotName: "",
+    serialNumber: "",
+  });
+  // Load saved port data from localStorage on mount
+  useEffect(() => {
+    loadSavedPorts();
+  }, []);
+
+  // Note: Robot data is now automatically saved to unified storage when robot config is updated
+
+  const loadSavedPorts = async () => {
+    try {
+      const existingPorts = await navigator.serial.getPorts();
+      const restoredPorts: RobotConnection[] = [];
+
+      for (const port of existingPorts) {
+        // Get USB device metadata to determine serial number
+        let serialNumber = null;
+        let usbMetadata = null;
+
+        try {
+          // Get all USB devices and try to match with this serial port
+          const usbDevices = await navigator.usb.getDevices();
+          const portInfo = port.getInfo();
+
+          // Try to find matching USB device by vendor/product ID
+          const matchingDevice = usbDevices.find(
+            (device) =>
+              device.vendorId === portInfo.usbVendorId &&
+              device.productId === portInfo.usbProductId
+          );
+
+          if (matchingDevice) {
+            serialNumber =
+              matchingDevice.serialNumber ||
+              `${matchingDevice.vendorId}-${
+                matchingDevice.productId
+              }-${Date.now()}`;
+            usbMetadata = {
+              vendorId: `0x${matchingDevice.vendorId
+                .toString(16)
+                .padStart(4, "0")}`,
+              productId: `0x${matchingDevice.productId
+                .toString(16)
+                .padStart(4, "0")}`,
+              serialNumber: matchingDevice.serialNumber || "Generated ID",
+              manufacturerName: matchingDevice.manufacturerName || "Unknown",
+              productName: matchingDevice.productName || "Unknown",
+              usbVersionMajor: matchingDevice.usbVersionMajor,
+              usbVersionMinor: matchingDevice.usbVersionMinor,
+              deviceClass: matchingDevice.deviceClass,
+              deviceSubclass: matchingDevice.deviceSubclass,
+              deviceProtocol: matchingDevice.deviceProtocol,
+            };
+            console.log("✅ Restored USB metadata for port:", serialNumber);
+          }
+        } catch (usbError) {
+          console.log("⚠️ Could not restore USB metadata:", usbError);
+          // Generate fallback if no USB metadata available
+          serialNumber = `fallback-${Date.now()}-${Math.random()
+            .toString(36)
+            .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;
+          } 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,
+          robotId,
+          serialNumber: serialNumber!,
+          usbMetadata: usbMetadata || undefined,
+        });
+      }
+
+      onConnectedRobotsChange(restoredPorts);
+    } catch (error) {
+      console.error("Failed to load saved ports:", error);
+    }
+  };
+
+  const getPortDisplayName = (port: SerialPort): string => {
+    try {
+      const info = port.getInfo();
+      if (info.usbVendorId && info.usbProductId) {
+        return `USB Port (${info.usbVendorId}:${info.usbProductId})`;
+      }
+      if (info.usbVendorId) {
+        return `Serial Port (VID:${info.usbVendorId
+          .toString(16)
+          .toUpperCase()})`;
+      }
+    } catch (error) {
+      // getInfo() might not be available
+    }
+    return `Serial Port ${Date.now()}`;
+  };
+
+  const handleConnect = async () => {
+    if (!isWebSerialSupported()) {
+      setError("Web Serial API is not supported in this browser");
+      return;
+    }
+
+    try {
+      setIsConnecting(true);
+      setError(null);
+
+      // Step 1: Request Web Serial port
+      console.log("Step 1: Requesting Web Serial port...");
+      const port = await navigator.serial.requestPort();
+      await port.open({ baudRate: 1000000 });
+
+      // Step 2: Request WebUSB device for metadata
+      console.log(
+        "Step 2: Requesting WebUSB device for unique identification..."
+      );
+      let serialNumber = null;
+      let usbMetadata = null;
+
+      try {
+        // Request USB device access for metadata
+        const usbDevice = await navigator.usb.requestDevice({
+          filters: [
+            { vendorId: 0x0403 }, // FTDI
+            { vendorId: 0x067b }, // Prolific
+            { vendorId: 0x10c4 }, // Silicon Labs
+            { vendorId: 0x1a86 }, // QinHeng Electronics (CH340)
+            { vendorId: 0x239a }, // Adafruit
+            { vendorId: 0x2341 }, // Arduino
+            { vendorId: 0x2e8a }, // Raspberry Pi Foundation
+            { vendorId: 0x1b4f }, // SparkFun
+          ],
+        });
+
+        if (usbDevice) {
+          serialNumber =
+            usbDevice.serialNumber ||
+            `${usbDevice.vendorId}-${usbDevice.productId}-${Date.now()}`;
+          usbMetadata = {
+            vendorId: `0x${usbDevice.vendorId.toString(16).padStart(4, "0")}`,
+            productId: `0x${usbDevice.productId.toString(16).padStart(4, "0")}`,
+            serialNumber: usbDevice.serialNumber || "Generated ID",
+            manufacturerName: usbDevice.manufacturerName || "Unknown",
+            productName: usbDevice.productName || "Unknown",
+            usbVersionMajor: usbDevice.usbVersionMajor,
+            usbVersionMinor: usbDevice.usbVersionMinor,
+            deviceClass: usbDevice.deviceClass,
+            deviceSubclass: usbDevice.deviceSubclass,
+            deviceProtocol: usbDevice.deviceProtocol,
+          };
+          console.log("✅ USB device metadata acquired:", usbMetadata);
+        }
+      } catch (usbError) {
+        console.log(
+          "⚠️ WebUSB request failed, generating fallback ID:",
+          usbError
+        );
+        // Generate a fallback unique ID if WebUSB fails
+        serialNumber = `fallback-${Date.now()}-${Math.random()
+          .toString(36)
+          .substr(2, 9)}`;
+        usbMetadata = {
+          vendorId: "Unknown",
+          productId: "Unknown",
+          serialNumber: serialNumber,
+          manufacturerName: "USB Metadata Not Available",
+          productName: "Check browser WebUSB support",
+        };
+      }
+
+      const portName = getPortDisplayName(port);
+
+      // Step 3: Check if this robot (by serial number) is already connected
+      const existingIndex = connectedRobots.findIndex(
+        (robot) => robot.serialNumber === serialNumber
+      );
+
+      if (existingIndex === -1) {
+        // New robot - add to list
+        const newRobot: RobotConnection = {
+          port,
+          name: portName,
+          isConnected: true,
+          serialNumber: serialNumber!,
+          usbMetadata: usbMetadata || undefined,
+        };
+
+        // Try to load saved robot info by serial number using unified storage
+        if (serialNumber) {
+          try {
+            const { getRobotConfig } = await import("../lib/unified-storage");
+            const savedConfig = getRobotConfig(serialNumber);
+            if (savedConfig) {
+              newRobot.robotType = savedConfig.robotType as
+                | "so100_follower"
+                | "so100_leader";
+              newRobot.robotId = savedConfig.robotId;
+              console.log("📋 Loaded saved robot configuration:", savedConfig);
+            }
+          } catch (error) {
+            console.warn("Failed to load saved robot data:", error);
+          }
+        }
+
+        onConnectedRobotsChange([...connectedRobots, newRobot]);
+        console.log("🤖 New robot connected with ID:", serialNumber);
+      } else {
+        // Existing robot - update port and connection status
+        const updatedRobots = connectedRobots.map((robot, index) =>
+          index === existingIndex
+            ? { ...robot, port, isConnected: true, name: portName }
+            : robot
+        );
+        onConnectedRobotsChange(updatedRobots);
+        console.log("🔄 Existing robot reconnected:", serialNumber);
+      }
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        (error.message.includes("cancelled") ||
+          error.message.includes("No port selected by the user") ||
+          error.name === "NotAllowedError")
+      ) {
+        // User cancelled - no error message needed, just log to console
+        console.log("Connection cancelled by user");
+        return;
+      }
+      setError(
+        error instanceof Error ? error.message : "Failed to connect to robot"
+      );
+    } finally {
+      setIsConnecting(false);
+    }
+  };
+
+  const handleDisconnect = async (index: number) => {
+    const portInfo = connectedRobots[index];
+    const robotName = portInfo.robotId || portInfo.name;
+    const serialNumber = portInfo.serialNumber || "unknown";
+
+    // Show confirmation dialog
+    setConfirmDeleteDialog({
+      open: true,
+      robotIndex: index,
+      robotName,
+      serialNumber,
+    });
+  };
+
+  const confirmDelete = async () => {
+    const { robotIndex } = confirmDeleteDialog;
+    const portInfo = connectedRobots[robotIndex];
+
+    setConfirmDeleteDialog({
+      open: false,
+      robotIndex: -1,
+      robotName: "",
+      serialNumber: "",
+    });
+
+    try {
+      // Close the serial port connection
+      if (portInfo.isConnected) {
+        await portInfo.port.close();
+      }
+
+      // Delete from unified storage if serial number is available
+      if (portInfo.serialNumber) {
+        try {
+          const { getUnifiedKey } = await import("../lib/unified-storage");
+          const unifiedKey = getUnifiedKey(portInfo.serialNumber);
+
+          // Remove unified storage data
+          localStorage.removeItem(unifiedKey);
+          console.log(`🗑️ Deleted unified robot data: ${unifiedKey}`);
+        } catch (error) {
+          console.warn("Failed to delete unified storage data:", error);
+        }
+      }
+
+      // Remove from UI
+      const updatedRobots = connectedRobots.filter((_, i) => i !== robotIndex);
+      onConnectedRobotsChange(updatedRobots);
+
+      console.log(
+        `✅ Robot "${confirmDeleteDialog.robotName}" permanently removed from system`
+      );
+    } catch (error) {
+      setError(
+        error instanceof Error ? error.message : "Failed to remove robot"
+      );
+    }
+  };
+
+  const cancelDelete = () => {
+    setConfirmDeleteDialog({
+      open: false,
+      robotIndex: -1,
+      robotName: "",
+      serialNumber: "",
+    });
+  };
+
+  const handleUpdatePortInfo = (
+    index: number,
+    robotType: "so100_follower" | "so100_leader",
+    robotId: string
+  ) => {
+    const updatedRobots = connectedRobots.map((robot, i) => {
+      if (i === index) {
+        const updatedRobot = { ...robot, robotType, robotId };
+
+        // Save robot configuration using unified storage
+        if (updatedRobot.serialNumber) {
+          import("../lib/unified-storage")
+            .then(({ saveRobotConfig }) => {
+              saveRobotConfig(
+                updatedRobot.serialNumber!,
+                robotType,
+                robotId,
+                updatedRobot.usbMetadata
+              );
+              console.log(
+                "💾 Saved robot configuration for:",
+                updatedRobot.serialNumber
+              );
+            })
+            .catch((error) => {
+              console.warn("Failed to save robot configuration:", error);
+            });
+        }
+
+        return updatedRobot;
+      }
+      return robot;
+    });
+    onConnectedRobotsChange(updatedRobots);
+  };
+
+  const handleFindPorts = async () => {
+    if (!isWebSerialSupported()) {
+      setError("Web Serial API is not supported in this browser");
+      return;
+    }
+
+    try {
+      setIsFindingPorts(true);
+      setFindPortsLog([]);
+      setError(null);
+
+      // Use the new findPort API from standard library
+      const { findPort } = await import("@lerobot/web");
+
+      const findPortProcess = await findPort({
+        onMessage: (message) => {
+          setFindPortsLog((prev) => [...prev, message]);
+        },
+      });
+
+      const robotConnections = (await findPortProcess.result) as any; // RobotConnection[] from findPort
+      const robotConnection = robotConnections[0]; // Get first robot from array
+
+      const portName = getPortDisplayName(robotConnection.port);
+      setFindPortsLog((prev) => [...prev, `✅ Port ready: ${portName}`]);
+
+      // Add to connected ports if not already there
+      const existingIndex = connectedRobots.findIndex(
+        (p) => p.name === portName
+      );
+      if (existingIndex === -1) {
+        const newPort: RobotConnection = {
+          port: robotConnection.port,
+          name: portName,
+          isConnected: true,
+          robotType: robotConnection.robotType,
+          robotId: robotConnection.robotId,
+          serialNumber: robotConnection.serialNumber,
+        };
+        onConnectedRobotsChange([...connectedRobots, newPort]);
+      }
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        (error.message.includes("cancelled") ||
+          error.name === "NotAllowedError")
+      ) {
+        // User cancelled - no message needed, just log to console
+        console.log("Port identification cancelled by user");
+        return;
+      }
+      setError(error instanceof Error ? error.message : "Failed to find ports");
+    } finally {
+      setIsFindingPorts(false);
+    }
+  };
+
+  const ensurePortIsOpen = async (robotIndex: number) => {
+    const robot = connectedRobots[robotIndex];
+    if (!robot) return false;
+
+    try {
+      // If port is already open, we're good
+      if (robot.port.readable !== null && robot.port.writable !== null) {
+        return true;
+      }
+
+      // Try to open the port
+      await robot.port.open({ baudRate: 1000000 });
+
+      // Update the robot's connection status
+      const updatedRobots = connectedRobots.map((r, i) =>
+        i === robotIndex ? { ...r, isConnected: true } : r
+      );
+      onConnectedRobotsChange(updatedRobots);
+
+      return true;
+    } catch (error) {
+      console.error("Failed to open port for calibration:", error);
+      setError(error instanceof Error ? error.message : "Failed to open port");
+      return false;
+    }
+  };
+
+  const handleCalibrate = async (port: RobotConnection) => {
+    if (!port.robotType || !port.robotId) {
+      setError("Please set robot type and ID before calibrating");
+      return;
+    }
+
+    // Find the robot index
+    const robotIndex = connectedRobots.findIndex((r) => r.port === port.port);
+    if (robotIndex === -1) {
+      setError("Robot not found in connected robots list");
+      return;
+    }
+
+    // Ensure port is open before calibrating
+    const isOpen = await ensurePortIsOpen(robotIndex);
+    if (!isOpen) {
+      return; // Error already set in ensurePortIsOpen
+    }
+
+    if (onCalibrate) {
+      onCalibrate(port.port, port.robotType, port.robotId);
+    }
+  };
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>🔌 Robot Connection Manager</CardTitle>
+        <CardDescription>
+          Connect, identify, and manage your robot arms
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <div className="space-y-6">
+          {/* Error Display */}
+          {error && (
+            <Alert variant="destructive">
+              <AlertDescription>{error}</AlertDescription>
+            </Alert>
+          )}
+
+          {/* Connection Controls */}
+          <div className="flex gap-2">
+            <Button
+              onClick={handleConnect}
+              disabled={isConnecting || !isWebSerialSupported()}
+              className="flex-1"
+            >
+              {isConnecting ? "Connecting..." : "Connect Robot"}
+            </Button>
+            <Button
+              variant="outline"
+              onClick={handleFindPorts}
+              disabled={isFindingPorts || !isWebSerialSupported()}
+              className="flex-1"
+            >
+              {isFindingPorts ? "Finding..." : "Find Port"}
+            </Button>
+          </div>
+
+          {/* Find Ports Log */}
+          {findPortsLog.length > 0 && (
+            <div className="bg-gray-50 p-3 rounded-md text-sm space-y-1">
+              {findPortsLog.map((log, index) => (
+                <div key={index} className="text-gray-700">
+                  {log}
+                </div>
+              ))}
+            </div>
+          )}
+
+          {/* Connected Ports */}
+          <div>
+            <h4 className="font-semibold mb-3">
+              Connected Robots ({connectedRobots.length})
+            </h4>
+
+            {connectedRobots.length === 0 ? (
+              <div className="text-center py-8 text-gray-500">
+                <div className="text-2xl mb-2">🤖</div>
+                <p>No robots connected</p>
+                <p className="text-xs">
+                  Use "Connect Robot" or "Find Port" to add robots
+                </p>
+              </div>
+            ) : (
+              <div className="space-y-4">
+                {connectedRobots.map((portInfo, index) => (
+                  <PortCard
+                    key={index}
+                    portInfo={portInfo}
+                    onDisconnect={() => handleDisconnect(index)}
+                    onUpdateInfo={(robotType, robotId) =>
+                      handleUpdatePortInfo(index, robotType, robotId)
+                    }
+                    onCalibrate={() => handleCalibrate(portInfo)}
+                    onTeleoperate={() => onTeleoperate?.(portInfo)}
+                  />
+                ))}
+              </div>
+            )}
+          </div>
+        </div>
+      </CardContent>
+
+      {/* Confirmation Dialog */}
+      <Dialog open={confirmDeleteDialog.open} onOpenChange={cancelDelete}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>🗑️ Permanently Delete Robot Data?</DialogTitle>
+            <DialogDescription>
+              This action cannot be undone. All robot data will be permanently
+              deleted.
+            </DialogDescription>
+          </DialogHeader>
+
+          <div className="space-y-3">
+            <div className="p-4 bg-red-50 rounded-lg border border-red-200">
+              <div className="font-medium text-red-900 mb-2">
+                Robot Information:
+              </div>
+              <div className="text-sm text-red-800 space-y-1">
+                <div>
+                  • Name:{" "}
+                  <span className="font-mono">
+                    {confirmDeleteDialog.robotName}
+                  </span>
+                </div>
+                <div>
+                  • Serial:{" "}
+                  <span className="font-mono">
+                    {confirmDeleteDialog.serialNumber}
+                  </span>
+                </div>
+              </div>
+            </div>
+
+            <div className="p-4 bg-red-50 rounded-lg border border-red-200">
+              <div className="font-medium text-red-900 mb-2">
+                This will permanently delete:
+              </div>
+              <div className="text-sm text-red-800 space-y-1">
+                <div>• Robot configuration</div>
+                <div>• Calibration data</div>
+                <div>• All saved settings</div>
+              </div>
+            </div>
+          </div>
+
+          <DialogFooter>
+            <Button variant="outline" onClick={cancelDelete}>
+              Cancel
+            </Button>
+            <Button variant="destructive" onClick={confirmDelete}>
+              Delete Forever
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </Card>
+  );
+}
+
+interface PortCardProps {
+  portInfo: RobotConnection;
+  onDisconnect: () => void;
+  onUpdateInfo: (
+    robotType: "so100_follower" | "so100_leader",
+    robotId: string
+  ) => void;
+  onCalibrate: () => void;
+  onTeleoperate: () => void;
+}
+
+function PortCard({
+  portInfo,
+  onDisconnect,
+  onUpdateInfo,
+  onCalibrate,
+  onTeleoperate,
+}: PortCardProps) {
+  const [robotType, setRobotType] = useState<"so100_follower" | "so100_leader">(
+    portInfo.robotType || "so100_follower"
+  );
+  const [robotId, setRobotId] = useState(portInfo.robotId || "");
+  const [isEditing, setIsEditing] = useState(false);
+  const [isScanning, setIsScanning] = useState(false);
+  const [motorIDs, setMotorIDs] = useState<number[]>([]);
+  const [portMetadata, setPortMetadata] = useState<any>(null);
+  const [showDeviceInfo, setShowDeviceInfo] = useState(false);
+
+  // Check for calibration using unified storage
+  const getCalibrationStatus = () => {
+    // Use the same serial number logic as calibration: prefer main serialNumber, fallback to USB metadata, then "unknown"
+    const serialNumber =
+      portInfo.serialNumber || portInfo.usbMetadata?.serialNumber || "unknown";
+
+    try {
+      // Use unified storage system with automatic migration
+      import("../lib/unified-storage")
+        .then(({ getCalibrationStatus }) => {
+          const status = getCalibrationStatus(serialNumber);
+          return status;
+        })
+        .catch((error) => {
+          console.warn("Failed to load unified calibration data:", error);
+          return null;
+        });
+
+      // For immediate synchronous return, try to get existing unified data first
+      const unifiedKey = `lerobotjs-${serialNumber}`;
+      const existing = localStorage.getItem(unifiedKey);
+      if (existing) {
+        const data = JSON.parse(existing);
+        if (data.calibration?.metadata) {
+          return {
+            timestamp: data.calibration.metadata.timestamp,
+            readCount: data.calibration.metadata.readCount,
+          };
+        }
+      }
+    } catch (error) {
+      console.warn("Failed to read calibration from unified storage:", error);
+    }
+    return null;
+  };
+
+  const calibrationStatus = getCalibrationStatus();
+
+  const handleSave = () => {
+    if (robotId.trim()) {
+      onUpdateInfo(robotType, robotId.trim());
+      setIsEditing(false);
+    }
+  };
+
+  // Use current values (either from props or local state)
+  const currentRobotType = portInfo.robotType || robotType;
+  const currentRobotId = portInfo.robotId || robotId;
+
+  const handleCancel = () => {
+    setRobotType(portInfo.robotType || "so100_follower");
+    setRobotId(portInfo.robotId || "");
+    setIsEditing(false);
+  };
+
+  // Scan for motor IDs and gather USB device metadata
+  const scanDeviceInfo = async () => {
+    if (!portInfo.port || !portInfo.isConnected) {
+      console.warn("Port not connected");
+      return;
+    }
+
+    setIsScanning(true);
+    setMotorIDs([]);
+    setPortMetadata(null);
+    const foundIDs: number[] = [];
+
+    try {
+      // Try to get USB device info using WebUSB for better metadata
+      let usbDeviceInfo = null;
+
+      try {
+        // First, check if we already have USB device permissions
+        let usbDevices = await navigator.usb.getDevices();
+        console.log("Already permitted USB devices:", usbDevices);
+
+        // If no devices found, request permission for USB-to-serial devices
+        if (usbDevices.length === 0) {
+          console.log(
+            "No USB permissions yet, requesting access to USB-to-serial devices..."
+          );
+
+          // Request access to common USB-to-serial chips
+          try {
+            const device = await navigator.usb.requestDevice({
+              filters: [
+                { vendorId: 0x0403 }, // FTDI
+                { vendorId: 0x067b }, // Prolific
+                { vendorId: 0x10c4 }, // Silicon Labs
+                { vendorId: 0x1a86 }, // QinHeng Electronics (CH340)
+                { vendorId: 0x239a }, // Adafruit
+                { vendorId: 0x2341 }, // Arduino
+                { vendorId: 0x2e8a }, // Raspberry Pi Foundation
+                { vendorId: 0x1b4f }, // SparkFun
+              ],
+            });
+
+            if (device) {
+              usbDevices = [device];
+              console.log("USB device access granted:", device);
+            }
+          } catch (requestError) {
+            console.log(
+              "User cancelled USB device selection or no devices found"
+            );
+            // Try requesting any device as fallback
+            try {
+              const anyDevice = await navigator.usb.requestDevice({
+                filters: [], // Allow any USB device
+              });
+              if (anyDevice) {
+                usbDevices = [anyDevice];
+                console.log("Fallback USB device selected:", anyDevice);
+              }
+            } catch (fallbackError) {
+              console.log("No USB device selected");
+            }
+          }
+        }
+
+        // Try to match with Web Serial port (this is tricky, so we'll take the first available)
+        if (usbDevices.length > 0) {
+          // Look for common USB-to-serial chip vendor IDs
+          const serialChipVendors = [
+            0x0403, // FTDI
+            0x067b, // Prolific
+            0x10c4, // Silicon Labs
+            0x1a86, // QinHeng Electronics (CH340)
+            0x239a, // Adafruit
+            0x2341, // Arduino
+            0x2e8a, // Raspberry Pi Foundation
+            0x1b4f, // SparkFun
+          ];
+
+          const serialDevice =
+            usbDevices.find((device) =>
+              serialChipVendors.includes(device.vendorId)
+            ) || usbDevices[0]; // Fallback to first device
+
+          if (serialDevice) {
+            usbDeviceInfo = {
+              vendorId: `0x${serialDevice.vendorId
+                .toString(16)
+                .padStart(4, "0")}`,
+              productId: `0x${serialDevice.productId
+                .toString(16)
+                .padStart(4, "0")}`,
+              serialNumber: serialDevice.serialNumber || "Not available",
+              manufacturerName: serialDevice.manufacturerName || "Unknown",
+              productName: serialDevice.productName || "Unknown",
+              usbVersionMajor: serialDevice.usbVersionMajor,
+              usbVersionMinor: serialDevice.usbVersionMinor,
+              deviceClass: serialDevice.deviceClass,
+              deviceSubclass: serialDevice.deviceSubclass,
+              deviceProtocol: serialDevice.deviceProtocol,
+            };
+            console.log("USB device info:", usbDeviceInfo);
+          }
+        }
+      } catch (usbError) {
+        console.log("WebUSB not available or no permissions:", usbError);
+        // Fallback to Web Serial API info
+        const portInfo_metadata = portInfo.port.getInfo();
+        console.log("Serial port metadata fallback:", portInfo_metadata);
+        if (Object.keys(portInfo_metadata).length > 0) {
+          usbDeviceInfo = {
+            vendorId: portInfo_metadata.usbVendorId
+              ? `0x${portInfo_metadata.usbVendorId
+                  .toString(16)
+                  .padStart(4, "0")}`
+              : "Not available",
+            productId: portInfo_metadata.usbProductId
+              ? `0x${portInfo_metadata.usbProductId
+                  .toString(16)
+                  .padStart(4, "0")}`
+              : "Not available",
+            serialNumber: "Not available via Web Serial",
+            manufacturerName: "Not available via Web Serial",
+            productName: "Not available via Web Serial",
+          };
+        }
+      }
+
+      setPortMetadata(usbDeviceInfo);
+
+      // Get reader/writer for the port
+      const reader = portInfo.port.readable?.getReader();
+      const writer = portInfo.port.writable?.getWriter();
+
+      if (!reader || !writer) {
+        console.warn("Cannot access port reader/writer");
+        setShowDeviceInfo(true);
+        return;
+      }
+
+      // Test motor IDs 1-10 (common range for servos)
+      for (let motorId = 1; motorId <= 10; motorId++) {
+        try {
+          // Create STS3215 ping packet
+          const packet = new Uint8Array([
+            0xff,
+            0xff,
+            motorId,
+            0x02,
+            0x01,
+            0x00,
+          ]);
+          const checksum = ~(motorId + 0x02 + 0x01) & 0xff;
+          packet[5] = checksum;
+
+          // Send ping
+          await writer.write(packet);
+
+          // Wait a bit for response
+          await new Promise((resolve) => setTimeout(resolve, 20));
+
+          // Try to read response with timeout
+          const timeoutPromise = new Promise((_, reject) =>
+            setTimeout(() => reject(new Error("Timeout")), 50)
+          );
+
+          try {
+            const result = (await Promise.race([
+              reader.read(),
+              timeoutPromise,
+            ])) as ReadableStreamReadResult<Uint8Array>;
+
+            if (
+              result &&
+              !result.done &&
+              result.value &&
+              result.value.length >= 6
+            ) {
+              const response = result.value;
+              const responseId = response[2];
+
+              // If we got a response with matching ID, motor exists
+              if (responseId === motorId) {
+                foundIDs.push(motorId);
+              }
+            }
+          } catch (readError) {
+            // No response from this motor ID - that's normal
+          }
+        } catch (error) {
+          console.warn(`Error testing motor ID ${motorId}:`, error);
+        }
+
+        // Small delay between tests
+        await new Promise((resolve) => setTimeout(resolve, 10));
+      }
+
+      reader.releaseLock();
+      writer.releaseLock();
+
+      setMotorIDs(foundIDs);
+      setShowDeviceInfo(true);
+    } catch (error) {
+      console.error("Device info scan failed:", error);
+    } finally {
+      setIsScanning(false);
+    }
+  };
+
+  return (
+    <div className="border rounded-lg p-4 space-y-3">
+      {/* Header with port name and status */}
+      <div className="flex items-center justify-between">
+        <div className="flex items-center space-x-2">
+          <div className="flex flex-col">
+            <span className="font-medium">{portInfo.name}</span>
+            {portInfo.serialNumber && (
+              <span className="text-xs text-gray-500 font-mono">
+                ID:{" "}
+                {portInfo.serialNumber.length > 20
+                  ? portInfo.serialNumber.substring(0, 20) + "..."
+                  : portInfo.serialNumber}
+              </span>
+            )}
+          </div>
+          <Badge variant={portInfo.isConnected ? "default" : "outline"}>
+            {portInfo.isConnected ? "Connected" : "Available"}
+          </Badge>
+        </div>
+        <Button variant="destructive" size="sm" onClick={onDisconnect}>
+          Remove
+        </Button>
+      </div>
+
+      {/* Robot Info Display (when not editing) */}
+      {!isEditing && currentRobotType && currentRobotId && (
+        <div className="flex items-center justify-between p-3 bg-gray-50 rounded-lg">
+          <div className="flex items-center space-x-3">
+            <div>
+              <div className="font-medium text-sm">{currentRobotId}</div>
+              <div className="text-xs text-gray-600">
+                {currentRobotType.replace("_", " ")}
+              </div>
+            </div>
+            {calibrationStatus && (
+              <Badge variant="default" className="bg-green-100 text-green-800">
+                ✅ Calibrated
+              </Badge>
+            )}
+          </div>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => setIsEditing(true)}
+          >
+            Edit
+          </Button>
+        </div>
+      )}
+
+      {/* Setup prompt for unconfigured robots */}
+      {!isEditing && (!currentRobotType || !currentRobotId) && (
+        <div className="flex items-center justify-between p-3 bg-blue-50 rounded-lg">
+          <div className="text-sm text-blue-800">
+            Robot needs configuration before use
+          </div>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => setIsEditing(true)}
+          >
+            Configure
+          </Button>
+        </div>
+      )}
+
+      {/* Robot Configuration Form (when editing) */}
+      {isEditing && (
+        <div className="space-y-3 p-3 bg-gray-50 rounded-lg">
+          <div className="grid grid-cols-2 gap-3">
+            <div>
+              <label className="text-sm font-medium block mb-1">
+                Robot Type
+              </label>
+              <select
+                value={robotType}
+                onChange={(e) =>
+                  setRobotType(
+                    e.target.value as "so100_follower" | "so100_leader"
+                  )
+                }
+                className="w-full px-2 py-1 border rounded text-sm"
+              >
+                <option value="so100_follower">SO-100 Follower</option>
+                <option value="so100_leader">SO-100 Leader</option>
+              </select>
+            </div>
+            <div>
+              <label className="text-sm font-medium block mb-1">Robot ID</label>
+              <input
+                type="text"
+                value={robotId}
+                onChange={(e) => setRobotId(e.target.value)}
+                placeholder="e.g., my_robot"
+                className="w-full px-2 py-1 border rounded text-sm"
+              />
+            </div>
+          </div>
+
+          <div className="flex gap-2">
+            <Button size="sm" onClick={handleSave} disabled={!robotId.trim()}>
+              Save
+            </Button>
+            <Button size="sm" variant="outline" onClick={handleCancel}>
+              Cancel
+            </Button>
+          </div>
+        </div>
+      )}
+
+      {/* Calibration Status and Action */}
+      {currentRobotType && currentRobotId && (
+        <div className="space-y-3">
+          <div className="flex items-center justify-between">
+            <div className="text-sm text-gray-600">
+              {calibrationStatus ? (
+                <span>
+                  Last calibrated:{" "}
+                  {new Date(calibrationStatus.timestamp).toLocaleDateString()}
+                  <span className="text-xs ml-1">
+                    ({calibrationStatus.readCount} readings)
+                  </span>
+                </span>
+              ) : (
+                <span>Not calibrated yet</span>
+              )}
+            </div>
+            <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 */}
+          <div className="flex items-center justify-between">
+            <div className="text-sm text-gray-600">
+              Scan device info and motor IDs
+            </div>
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={scanDeviceInfo}
+              disabled={!portInfo.isConnected || isScanning}
+            >
+              {isScanning ? "Scanning..." : "Show Device Info"}
+            </Button>
+          </div>
+
+          {/* Device Info Results */}
+          {showDeviceInfo && (
+            <div className="p-3 bg-gray-50 rounded-lg space-y-3">
+              {/* USB Device Information */}
+              {portMetadata && (
+                <div>
+                  <div className="text-sm font-medium mb-2">
+                    📱 USB Device Info:
+                  </div>
+                  <div className="space-y-1 text-xs">
+                    <div className="flex justify-between">
+                      <span className="text-gray-600">Vendor ID:</span>
+                      <span className="font-mono">{portMetadata.vendorId}</span>
+                    </div>
+                    <div className="flex justify-between">
+                      <span className="text-gray-600">Product ID:</span>
+                      <span className="font-mono">
+                        {portMetadata.productId}
+                      </span>
+                    </div>
+                    <div className="flex justify-between">
+                      <span className="text-gray-600">Serial Number:</span>
+                      <span className="font-mono text-green-600 font-semibold">
+                        {portMetadata.serialNumber}
+                      </span>
+                    </div>
+                    <div className="flex justify-between">
+                      <span className="text-gray-600">Manufacturer:</span>
+                      <span>{portMetadata.manufacturerName}</span>
+                    </div>
+                    <div className="flex justify-between">
+                      <span className="text-gray-600">Product:</span>
+                      <span>{portMetadata.productName}</span>
+                    </div>
+                    {portMetadata.usbVersionMajor && (
+                      <div className="flex justify-between">
+                        <span className="text-gray-600">USB Version:</span>
+                        <span>
+                          {portMetadata.usbVersionMajor}.
+                          {portMetadata.usbVersionMinor}
+                        </span>
+                      </div>
+                    )}
+                    {portMetadata.deviceClass !== undefined && (
+                      <div className="flex justify-between">
+                        <span className="text-gray-600">Device Class:</span>
+                        <span>
+                          0x
+                          {portMetadata.deviceClass
+                            .toString(16)
+                            .padStart(2, "0")}
+                        </span>
+                      </div>
+                    )}
+                  </div>
+                </div>
+              )}
+
+              {/* Motor IDs */}
+              <div>
+                <div className="text-sm font-medium mb-2">
+                  🤖 Found Motor IDs:
+                </div>
+                {motorIDs.length > 0 ? (
+                  <div className="flex flex-wrap gap-2">
+                    {motorIDs.map((id) => (
+                      <Badge key={id} variant="outline" className="text-xs">
+                        Motor {id}
+                      </Badge>
+                    ))}
+                  </div>
+                ) : (
+                  <div className="text-sm text-gray-500">
+                    No motor IDs found. Check connection and power.
+                  </div>
+                )}
+              </div>
+
+              <Button
+                size="sm"
+                variant="outline"
+                onClick={() => setShowDeviceInfo(false)}
+                className="mt-2 text-xs"
+              >
+                Hide
+              </Button>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

examples/demo/components/TeleoperationPanel.tsx

@@ -0,0 +1,530 @@
+import { 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 {
+  teleoperate,
+  type TeleoperationProcess,
+  type TeleoperationState,
+} from "@lerobot/web";
+import { getUnifiedRobotData } from "../lib/unified-storage";
+import type { RobotConnection } from "@lerobot/web";
+import { SO100_KEYBOARD_CONTROLS } from "@lerobot/web";
+
+interface TeleoperationPanelProps {
+  robot: RobotConnection;
+  onClose: () => void;
+}
+
+export function TeleoperationPanel({
+  robot,
+  onClose,
+}: TeleoperationPanelProps) {
+  const [teleoperationState, setTeleoperationState] =
+    useState<TeleoperationState>({
+      isActive: false,
+      motorConfigs: [],
+      lastUpdate: 0,
+      keyStates: {},
+    });
+  const [error, setError] = useState<string | null>(null);
+  const [, 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 = () => {
+    if (!teleoperationProcessRef.current) return;
+
+    teleoperationProcessRef.current.stop();
+    console.log("🛑 Teleoperation stopped");
+  };
+
+  const handleClose = () => {
+    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) => {
+      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 =
+        SO100_KEYBOARD_CONTROLS[
+          keyCode as keyof typeof SO100_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 Gripper */}
+        <div className="flex justify-center gap-2">
+          <div className="text-center">
+            <h4 className="text-xs font-semibold mb-2 text-gray-600">Roll</h4>
+            <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>
+            <div className="flex gap-1">
+              <KeyButton keyCode="o" size="sm">
+                O
+              </KeyButton>
+              <KeyButton keyCode="c" size="sm">
+                C
+              </KeyButton>
+            </div>
+          </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>
+                )}
+              </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, index) => {
+                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>
+                    <input
+                      type="range"
+                      min={motor.minPosition}
+                      max={motor.maxPosition}
+                      value={motor.currentPosition}
+                      disabled={!isActive}
+                      className={`w-full h-2 rounded-lg appearance-none cursor-pointer bg-gray-200 slider-thumb ${
+                        !isActive ? "opacity-50 cursor-not-allowed" : ""
+                      }`}
+                      style={{
+                        background: isActive
+                          ? `linear-gradient(to right, #3b82f6 0%, #3b82f6 ${
+                              ((motor.currentPosition - motor.minPosition) /
+                                (motor.maxPosition - motor.minPosition)) *
+                              100
+                            }%, #e5e7eb ${
+                              ((motor.currentPosition - motor.minPosition) /
+                                (motor.maxPosition - motor.minPosition)) *
+                              100
+                            }%, #e5e7eb 100%)`
+                          : "#e5e7eb",
+                      }}
+                      onChange={async (e) => {
+                        if (!isActive) return;
+                        const newPosition = parseInt(e.target.value);
+                        try {
+                          await moveMotorToPosition(index, newPosition);
+                        } catch (error) {
+                          console.warn(
+                            "Failed to move motor via slider:",
+                            error
+                          );
+                        }
+                      }}
+                    />
+                    <div className="flex justify-between text-xs text-gray-400">
+                      <span>{motor.minPosition}</span>
+                      <span>{motor.maxPosition}</span>
+                    </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>O Open gripper</li>
+                  <li>C Close 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>
+  );
+}

examples/demo/components/ui/alert.tsx

@@ -0,0 +1,58 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../../lib/utils";
+
+const alertVariants = cva(
+  "relative w-full rounded-lg border p-4 [&>svg~*]:pl-7 [&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:text-foreground",
+  {
+    variants: {
+      variant: {
+        default: "bg-background text-foreground",
+        destructive:
+          "border-destructive/50 text-destructive dark:border-destructive [&>svg]:text-destructive",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+);
+
+const Alert = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof alertVariants>
+>(({ className, variant, ...props }, ref) => (
+  <div
+    ref={ref}
+    role="alert"
+    className={cn(alertVariants({ variant }), className)}
+    {...props}
+  />
+));
+Alert.displayName = "Alert";
+
+const AlertTitle = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h5
+    ref={ref}
+    className={cn("mb-1 font-medium leading-none tracking-tight", className)}
+    {...props}
+  />
+));
+AlertTitle.displayName = "AlertTitle";
+
+const AlertDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("text-sm [&_p]:leading-relaxed", className)}
+    {...props}
+  />
+));
+AlertDescription.displayName = "AlertDescription";
+
+export { Alert, AlertTitle, AlertDescription };

examples/demo/components/ui/badge.tsx

@@ -0,0 +1,35 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../../lib/utils";
+
+const badgeVariants = cva(
+  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
+  {
+    variants: {
+      variant: {
+        default:
+          "border-transparent bg-primary text-primary-foreground hover:bg-primary/80",
+        secondary:
+          "border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        destructive:
+          "border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80",
+        outline: "text-foreground",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+);
+
+export interface BadgeProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof badgeVariants> {}
+
+function Badge({ className, variant, ...props }: BadgeProps) {
+  return (
+    <div className={cn(badgeVariants({ variant }), className)} {...props} />
+  );
+}
+
+export { Badge, badgeVariants };

examples/demo/components/ui/button.tsx

@@ -0,0 +1,53 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../../lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    return (
+      <button
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+Button.displayName = "Button";
+
+export { Button, buttonVariants };

examples/demo/components/ui/card.tsx

@@ -0,0 +1,85 @@
+import * as React from "react";
+import { cn } from "../../lib/utils";
+
+const Card = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      "rounded-lg border bg-card text-card-foreground shadow-sm",
+      className
+    )}
+    {...props}
+  />
+));
+Card.displayName = "Card";
+
+const CardHeader = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("flex flex-col space-y-1.5 p-6", className)}
+    {...props}
+  />
+));
+CardHeader.displayName = "CardHeader";
+
+const CardTitle = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h3
+    ref={ref}
+    className={cn(
+      "text-2xl font-semibold leading-none tracking-tight",
+      className
+    )}
+    {...props}
+  />
+));
+CardTitle.displayName = "CardTitle";
+
+const CardDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={cn("text-sm text-muted-foreground", className)}
+    {...props}
+  />
+));
+CardDescription.displayName = "CardDescription";
+
+const CardContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn("p-6 pt-0", className)} {...props} />
+));
+CardContent.displayName = "CardContent";
+
+const CardFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("flex items-center p-6 pt-0", className)}
+    {...props}
+  />
+));
+CardFooter.displayName = "CardFooter";
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardDescription,
+  CardContent,
+};

examples/demo/components/ui/dialog.tsx

@@ -0,0 +1,120 @@
+import * as React from "react";
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+import { X } from "lucide-react";
+
+import { cn } from "../../lib/utils";
+
+const Dialog = DialogPrimitive.Root;
+
+const DialogTrigger = DialogPrimitive.Trigger;
+
+const DialogPortal = DialogPrimitive.Portal;
+
+const DialogClose = DialogPrimitive.Close;
+
+const DialogOverlay = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Overlay
+    ref={ref}
+    className={cn(
+      "fixed inset-0 z-50 bg-background/80 backdrop-blur-sm data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      className
+    )}
+    {...props}
+  />
+));
+DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
+
+const DialogContent = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
+>(({ className, children, ...props }, ref) => (
+  <DialogPortal>
+    <DialogOverlay />
+    <DialogPrimitive.Content
+      ref={ref}
+      className={cn(
+        "fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground">
+        <X className="h-4 w-4" />
+        <span className="sr-only">Close</span>
+      </DialogPrimitive.Close>
+    </DialogPrimitive.Content>
+  </DialogPortal>
+));
+DialogContent.displayName = DialogPrimitive.Content.displayName;
+
+const DialogHeader = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn(
+      "flex flex-col space-y-1.5 text-center sm:text-left",
+      className
+    )}
+    {...props}
+  />
+);
+DialogHeader.displayName = "DialogHeader";
+
+const DialogFooter = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn(
+      "flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2",
+      className
+    )}
+    {...props}
+  />
+);
+DialogFooter.displayName = "DialogFooter";
+
+const DialogTitle = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Title>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Title
+    ref={ref}
+    className={cn(
+      "text-lg font-semibold leading-none tracking-tight",
+      className
+    )}
+    {...props}
+  />
+));
+DialogTitle.displayName = DialogPrimitive.Title.displayName;
+
+const DialogDescription = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Description>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Description>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Description
+    ref={ref}
+    className={cn("text-sm text-muted-foreground", className)}
+    {...props}
+  />
+));
+DialogDescription.displayName = DialogPrimitive.Description.displayName;
+
+export {
+  Dialog,
+  DialogPortal,
+  DialogOverlay,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+};

examples/demo/components/ui/progress.tsx

@@ -0,0 +1,26 @@
+import * as React from "react";
+import * as ProgressPrimitive from "@radix-ui/react-progress";
+
+import { cn } from "../../lib/utils";
+
+const Progress = React.forwardRef<
+  React.ElementRef<typeof ProgressPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof ProgressPrimitive.Root>
+>(({ className, value, ...props }, ref) => (
+  <ProgressPrimitive.Root
+    ref={ref}
+    className={cn(
+      "relative h-4 w-full overflow-hidden rounded-full bg-secondary",
+      className
+    )}
+    {...props}
+  >
+    <ProgressPrimitive.Indicator
+      className="h-full w-full flex-1 bg-primary transition-all"
+      style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
+    />
+  </ProgressPrimitive.Root>
+));
+Progress.displayName = ProgressPrimitive.Root.displayName;
+
+export { Progress };

examples/demo/index.css

@@ -0,0 +1,12 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}

examples/demo/lib/unified-storage.ts

@@ -0,0 +1,325 @@
+// Unified storage system for robot data
+// Consolidates robot config, calibration data, and metadata under one key per device
+
+export interface UnifiedRobotData {
+  device_info: {
+    serialNumber: string;
+    robotType: "so100_follower" | "so100_leader";
+    robotId: string;
+    usbMetadata?: any;
+    lastUpdated: string;
+  };
+  calibration?: {
+    // Motor calibration data (from lerobot_calibration_* keys)
+    shoulder_pan?: {
+      id: number;
+      drive_mode: number;
+      homing_offset: number;
+      range_min: number;
+      range_max: number;
+    };
+    shoulder_lift?: {
+      id: number;
+      drive_mode: number;
+      homing_offset: number;
+      range_min: number;
+      range_max: number;
+    };
+    elbow_flex?: {
+      id: number;
+      drive_mode: number;
+      homing_offset: number;
+      range_min: number;
+      range_max: number;
+    };
+    wrist_flex?: {
+      id: number;
+      drive_mode: number;
+      homing_offset: number;
+      range_min: number;
+      range_max: number;
+    };
+    wrist_roll?: {
+      id: number;
+      drive_mode: number;
+      homing_offset: number;
+      range_min: number;
+      range_max: number;
+    };
+    gripper?: {
+      id: number;
+      drive_mode: number;
+      homing_offset: number;
+      range_min: number;
+      range_max: number;
+    };
+
+    // Calibration metadata (from lerobot-calibration-* keys)
+    metadata: {
+      timestamp: string;
+      readCount: number;
+      platform: string;
+      api: string;
+      device_type: string;
+      device_id: string;
+      calibrated_at: string;
+    };
+  };
+}
+
+/**
+ * Get unified storage key for a robot by serial number
+ */
+export function getUnifiedKey(serialNumber: string): string {
+  return `lerobotjs-${serialNumber}`;
+}
+
+/**
+ * Migrate data from old storage keys to unified format
+ * Safely combines data from three sources:
+ * 1. lerobot-robot-{serialNumber} - robot config
+ * 2. lerobot-calibration-{serialNumber} - calibration metadata
+ * 3. lerobot_calibration_{robotType}_{robotId} - actual calibration data
+ */
+export function migrateToUnifiedStorage(
+  serialNumber: string
+): UnifiedRobotData | null {
+  try {
+    const unifiedKey = getUnifiedKey(serialNumber);
+
+    // Check if already migrated
+    const existing = localStorage.getItem(unifiedKey);
+    if (existing) {
+      console.log(`✅ Data already unified for ${serialNumber}`);
+      return JSON.parse(existing);
+    }
+
+    console.log(`🔄 Migrating data for serial number: ${serialNumber}`);
+
+    // 1. Get robot configuration
+    const robotConfigKey = `lerobot-robot-${serialNumber}`;
+    const robotConfigRaw = localStorage.getItem(robotConfigKey);
+
+    if (!robotConfigRaw) {
+      return null;
+    }
+
+    const robotConfig = JSON.parse(robotConfigRaw);
+    console.log(`📋 Found robot config:`, robotConfig);
+
+    // 2. Get calibration metadata
+    const calibrationMetaKey = `lerobot-calibration-${serialNumber}`;
+    const calibrationMetaRaw = localStorage.getItem(calibrationMetaKey);
+    const calibrationMeta = calibrationMetaRaw
+      ? JSON.parse(calibrationMetaRaw)
+      : null;
+    console.log(`📊 Found calibration metadata:`, calibrationMeta);
+
+    // 3. Get actual calibration data (using robotType and robotId from config)
+    const calibrationDataKey = `lerobot_calibration_${robotConfig.robotType}_${robotConfig.robotId}`;
+    const calibrationDataRaw = localStorage.getItem(calibrationDataKey);
+    const calibrationData = calibrationDataRaw
+      ? JSON.parse(calibrationDataRaw)
+      : null;
+    console.log(`🔧 Found calibration data:`, calibrationData);
+
+    // 4. Build unified structure
+    const unifiedData: UnifiedRobotData = {
+      device_info: {
+        serialNumber: robotConfig.serialNumber || serialNumber,
+        robotType: robotConfig.robotType,
+        robotId: robotConfig.robotId,
+        lastUpdated: robotConfig.lastUpdated || new Date().toISOString(),
+      },
+    };
+
+    // Add calibration if available
+    if (calibrationData && calibrationMeta) {
+      const motors: any = {};
+
+      // Copy motor data (excluding metadata fields)
+      Object.keys(calibrationData).forEach((key) => {
+        if (
+          ![
+            "device_type",
+            "device_id",
+            "calibrated_at",
+            "platform",
+            "api",
+          ].includes(key)
+        ) {
+          motors[key] = calibrationData[key];
+        }
+      });
+
+      unifiedData.calibration = {
+        ...motors,
+        metadata: {
+          timestamp: calibrationMeta.timestamp || calibrationData.calibrated_at,
+          readCount: calibrationMeta.readCount || 0,
+          platform: calibrationData.platform || "web",
+          api: calibrationData.api || "Web Serial API",
+          device_type: calibrationData.device_type || robotConfig.robotType,
+          device_id: calibrationData.device_id || robotConfig.robotId,
+          calibrated_at:
+            calibrationData.calibrated_at || calibrationMeta.timestamp,
+        },
+      };
+    }
+
+    // 5. Save unified data
+    localStorage.setItem(unifiedKey, JSON.stringify(unifiedData));
+    console.log(`✅ Successfully unified data for ${serialNumber}`);
+    console.log(`📦 Unified data:`, unifiedData);
+
+    // 6. Clean up old keys (optional - keep for now for safety)
+    // localStorage.removeItem(robotConfigKey);
+    // localStorage.removeItem(calibrationMetaKey);
+    // localStorage.removeItem(calibrationDataKey);
+
+    return unifiedData;
+  } catch (error) {
+    console.error(`❌ Failed to migrate data for ${serialNumber}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Get unified robot data
+ */
+export function getUnifiedRobotData(
+  serialNumber: string
+): UnifiedRobotData | null {
+  const unifiedKey = getUnifiedKey(serialNumber);
+
+  // Try to get existing unified data
+  const existing = localStorage.getItem(unifiedKey);
+  if (existing) {
+    try {
+      return JSON.parse(existing);
+    } catch (error) {
+      console.warn(`Failed to parse unified data for ${serialNumber}:`, error);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Save robot configuration to unified storage
+ */
+export function saveRobotConfig(
+  serialNumber: string,
+  robotType: "so100_follower" | "so100_leader",
+  robotId: string,
+  usbMetadata?: any
+): void {
+  const unifiedKey = getUnifiedKey(serialNumber);
+  const existing =
+    getUnifiedRobotData(serialNumber) || ({} as UnifiedRobotData);
+
+  existing.device_info = {
+    serialNumber,
+    robotType,
+    robotId,
+    usbMetadata,
+    lastUpdated: new Date().toISOString(),
+  };
+
+  localStorage.setItem(unifiedKey, JSON.stringify(existing));
+  console.log(`💾 Saved robot config for ${serialNumber}`);
+}
+
+/**
+ * Save calibration data to unified storage
+ */
+export function saveCalibrationData(
+  serialNumber: string,
+  calibrationData: any,
+  metadata: { timestamp: string; readCount: number }
+): void {
+  const unifiedKey = getUnifiedKey(serialNumber);
+  const existing =
+    getUnifiedRobotData(serialNumber) || ({} as UnifiedRobotData);
+
+  // Ensure device_info exists
+  if (!existing.device_info) {
+    console.warn(
+      `No device info found for ${serialNumber}, cannot save calibration`
+    );
+    return;
+  }
+
+  // Extract motor data (exclude metadata fields)
+  const motors: any = {};
+  Object.keys(calibrationData).forEach((key) => {
+    if (
+      ![
+        "device_type",
+        "device_id",
+        "calibrated_at",
+        "platform",
+        "api",
+      ].includes(key)
+    ) {
+      motors[key] = calibrationData[key];
+    }
+  });
+
+  existing.calibration = {
+    ...motors,
+    metadata: {
+      timestamp: metadata.timestamp,
+      readCount: metadata.readCount,
+      platform: calibrationData.platform || "web",
+      api: calibrationData.api || "Web Serial API",
+      device_type:
+        calibrationData.device_type || existing.device_info.robotType,
+      device_id: calibrationData.device_id || existing.device_info.robotId,
+      calibrated_at: calibrationData.calibrated_at || metadata.timestamp,
+    },
+  };
+
+  localStorage.setItem(unifiedKey, JSON.stringify(existing));
+  console.log(`🔧 Saved calibration data for ${serialNumber}`);
+}
+
+/**
+ * Check if robot is calibrated
+ */
+export function isRobotCalibrated(serialNumber: string): boolean {
+  const data = getUnifiedRobotData(serialNumber);
+  return !!data?.calibration?.metadata?.timestamp;
+}
+
+/**
+ * Get calibration status for dashboard
+ */
+export function getCalibrationStatus(
+  serialNumber: string
+): { timestamp: string; readCount: number } | null {
+  const data = getUnifiedRobotData(serialNumber);
+  if (data?.calibration?.metadata) {
+    return {
+      timestamp: data.calibration.metadata.timestamp,
+      readCount: data.calibration.metadata.readCount,
+    };
+  }
+  return null;
+}
+
+/**
+ * Get robot configuration
+ */
+export function getRobotConfig(
+  serialNumber: string
+): { robotType: string; robotId: string } | null {
+  const data = getUnifiedRobotData(serialNumber);
+  if (data?.device_info) {
+    return {
+      robotType: data.device_info.robotType,
+      robotId: data.device_info.robotId,
+    };
+  }
+  return null;
+}

examples/demo/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

examples/demo/main.tsx

@@ -0,0 +1,5 @@
+import ReactDOM from "react-dom/client";
+import { App } from "./App";
+import "./index.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(<App />);

examples/demo/pages/Home.tsx

@@ -0,0 +1,99 @@
+import { useState } from "react";
+import { Button } from "../components/ui/button";
+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";
+import type { RobotConnection } from "@lerobot/web";
+
+interface HomeProps {
+  connectedRobots: RobotConnection[];
+  onConnectedRobotsChange: (robots: RobotConnection[]) => void;
+}
+
+export function Home({ connectedRobots, onConnectedRobotsChange }: HomeProps) {
+  const [calibratingRobot, setCalibratingRobot] =
+    useState<RobotConnection | null>(null);
+  const [teleoperatingRobot, setTeleoperatingRobot] =
+    useState<RobotConnection | null>(null);
+  const isSupported = isWebSerialSupported();
+
+  const handleCalibrate = (port: SerialPort) => {
+    // Find the robot from connectedRobots
+    const robot = connectedRobots.find((r) => r.port === port);
+    if (robot) {
+      setCalibratingRobot(robot);
+    }
+  };
+
+  const handleTeleoperate = (robot: RobotConnection) => {
+    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">
+        {/* Header */}
+        <div className="text-center mb-12">
+          <h1 className="text-4xl font-bold text-gray-900 mb-4">
+            🤖 LeRobot.js
+          </h1>
+          <p className="text-xl text-gray-600 mb-8">
+            Robotics for the web and node
+          </p>
+
+          {!isSupported && (
+            <Alert variant="destructive" className="max-w-2xl mx-auto mb-8">
+              <AlertDescription>
+                Web Serial API is not supported in this browser. Please use
+                Chrome, Edge, or another Chromium-based browser to use this
+                demo.
+              </AlertDescription>
+            </Alert>
+          )}
+        </div>
+
+        {/* Main Content */}
+        {calibratingRobot ? (
+          <div className="max-w-6xl mx-auto">
+            <div className="mb-4">
+              <Button
+                variant="outline"
+                onClick={() => setCalibratingRobot(null)}
+              >
+                ← Back to Dashboard
+              </Button>
+            </div>
+            <CalibrationPanel
+              robot={calibratingRobot}
+              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}
+            />
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

src/lerobot/node/calibrate.ts

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

src/lerobot/node/common/calibration.ts

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

src/lerobot/node/common/so100_config.ts

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

src/lerobot/node/constants.ts

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

src/lerobot/node/find_port.ts

@@ -0,0 +1,127 @@
+/**
+ * Helper to find the USB port associated with your MotorsBus.
+ *
+ * Direct port of Python lerobot find_port.py
+ *
+ * Example:
+ * ```
+ * npx lerobot find-port
+ * ```
+ */
+
+import { SerialPort } from "serialport";
+import { createInterface } from "readline";
+import { platform } from "os";
+import { readdir } from "fs/promises";
+import { join } from "path";
+
+/**
+ * Find all available serial ports on the system
+ * Mirrors Python's find_available_ports() function
+ */
+async function findAvailablePorts(): Promise<string[]> {
+  if (platform() === "win32") {
+    // List COM ports using serialport library (equivalent to pyserial)
+    const ports = await SerialPort.list();
+    return ports.map((port) => port.path);
+  } else {
+    // List /dev/tty* ports for Unix-based systems (Linux/macOS)
+    try {
+      const devFiles = await readdir("/dev");
+      const ttyPorts = devFiles
+        .filter((file) => file.startsWith("tty"))
+        .map((file) => join("/dev", file));
+      return ttyPorts;
+    } catch (error) {
+      // Fallback to serialport library if /dev reading fails
+      const ports = await SerialPort.list();
+      return ports.map((port) => port.path);
+    }
+  }
+}
+
+/**
+ * Create readline interface for user input
+ * Equivalent to Python's input() function
+ */
+function createReadlineInterface() {
+  return createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+/**
+ * Prompt user for input and wait for response
+ * Equivalent to Python's input() function
+ */
+function waitForInput(prompt: string = ""): Promise<string> {
+  const rl = createReadlineInterface();
+  return new Promise((resolve) => {
+    if (prompt) {
+      process.stdout.write(prompt);
+    }
+    rl.on("line", (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+/**
+ * Sleep for specified milliseconds
+ * Equivalent to Python's time.sleep()
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Main find port function - direct port of Python find_port()
+ * Maintains identical UX and messaging
+ */
+export async function findPort(): Promise<void> {
+  console.log("Finding all available ports for the MotorsBus.");
+
+  const portsBefore = await findAvailablePorts();
+  console.log("Ports before disconnecting:", portsBefore);
+
+  console.log(
+    "Remove the USB cable from your MotorsBus and press Enter when done."
+  );
+  await waitForInput();
+
+  // Allow some time for port to be released (equivalent to Python's time.sleep(0.5))
+  await sleep(500);
+
+  const portsAfter = await findAvailablePorts();
+  const portsDiff = portsBefore.filter((port) => !portsAfter.includes(port));
+
+  if (portsDiff.length === 1) {
+    const port = portsDiff[0];
+    console.log(`The port of this MotorsBus is '${port}'`);
+    console.log("Reconnect the USB cable.");
+  } else if (portsDiff.length === 0) {
+    throw new Error(
+      `Could not detect the port. No difference was found (${JSON.stringify(
+        portsDiff
+      )}).`
+    );
+  } else {
+    throw new Error(
+      `Could not detect the port. More than one port was found (${JSON.stringify(
+        portsDiff
+      )}).`
+    );
+  }
+}
+
+/**
+ * CLI entry point when called directly
+ */
+if (import.meta.url === `file://${process.argv[1]}`) {
+  findPort().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}

src/lerobot/node/robots/config.ts

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

src/lerobot/node/robots/robot.ts

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

src/lerobot/node/robots/so100_follower.ts

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

src/lerobot/node/teleoperators/config.ts

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

src/lerobot/node/teleoperators/so100_leader.ts

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

src/lerobot/node/teleoperators/teleoperator.ts

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