feat: everything is using just one config

examples/robot-control-web/components/CalibrationPanel.tsx

@@ -92,8 +92,9 @@ export function CalibrationPanel({ robot, onFinish }: CalibrationPanelProps) {
       setIsCalibrating(true);
       initializeMotorData();
 
-      // Use the simple calibrate API - just pass the robot connection
-      const process = await calibrate(robot, {
+      // Use the unified config API for calibration
+      const process = await calibrate({
+        robot,
         onLiveUpdate: (data) => {
           setMotorData(data);
           setStatus(

examples/robot-control-web/components/TeleoperationPanel.tsx

@@ -99,14 +99,22 @@ export function TeleoperationPanel({
 
     return () => {
       // Cleanup on unmount
-      if (keyboardProcessRef.current) {
-        keyboardProcessRef.current.disconnect();
-        keyboardProcessRef.current = null;
-      }
-      if (directProcessRef.current) {
-        directProcessRef.current.disconnect();
-        directProcessRef.current = null;
-      }
+      const cleanup = async () => {
+        try {
+          if (keyboardProcessRef.current) {
+            await keyboardProcessRef.current.disconnect();
+            keyboardProcessRef.current = null;
+          }
+          if (directProcessRef.current) {
+            await directProcessRef.current.disconnect();
+            directProcessRef.current = null;
+          }
+          console.log("🧹 Teleoperation cleanup completed");
+        } catch (error) {
+          console.warn("Error during teleoperation cleanup:", error);
+        }
+      };
+      cleanup();
     };
   }, [robot]);
 
@@ -165,22 +173,33 @@ export function TeleoperationPanel({
     }
   };
 
-  const handleStop = () => {
-    if (keyboardProcessRef.current) {
-      keyboardProcessRef.current.stop();
-    }
-    if (directProcessRef.current) {
-      directProcessRef.current.stop();
+  const handleStop = async () => {
+    try {
+      if (keyboardProcessRef.current) {
+        keyboardProcessRef.current.stop();
+      }
+      if (directProcessRef.current) {
+        directProcessRef.current.stop();
+      }
+      console.log("🛑 Both keyboard and direct teleoperation stopped");
+    } catch (error) {
+      console.warn("Error during teleoperation stop:", error);
     }
-    console.log("🛑 Both keyboard and direct teleoperation stopped");
   };
 
-  const handleClose = () => {
-    if (keyboardProcessRef.current) {
-      keyboardProcessRef.current.stop();
-    }
-    if (directProcessRef.current) {
-      directProcessRef.current.stop();
+  const handleClose = async () => {
+    try {
+      if (keyboardProcessRef.current) {
+        keyboardProcessRef.current.stop();
+        await keyboardProcessRef.current.disconnect();
+      }
+      if (directProcessRef.current) {
+        directProcessRef.current.stop();
+        await directProcessRef.current.disconnect();
+      }
+      console.log("🔌 Properly disconnected from robot");
+    } catch (error) {
+      console.warn("Error during teleoperation cleanup:", error);
     }
     onClose();
   };

packages/web/README.md

@@ -6,7 +6,7 @@ Browser-native robotics control using WebSerial and WebUSB APIs.
 
 - **Direct Hardware Control**: STS3215 motor communication via WebSerial API
 - **Device Persistence**: WebUSB API for automatic robot reconnection
-- **Real-time Teleoperation**: Keyboard control with live motor feedback
+- **Extensible Teleoperation**: Multiple input devices (keyboard, direct control, future: leader arms, joysticks)
 - **Motor Calibration**: Automated homing offset and range recording
 - **Cross-browser Support**: Chrome/Edge 89+ with HTTPS or localhost
 - **TypeScript Native**: Full type safety and IntelliSense support
@@ -27,7 +27,14 @@ yarn add @lerobot/web
 ## Quick Start
 
 ```typescript
-import { findPort, releaseMotors, calibrate, teleoperate } from "@lerobot/web";
+import {
+  findPort,
+  releaseMotors,
+  calibrate,
+  teleoperate,
+  KeyboardTeleoperator,
+  DirectTeleoperator,
+} from "@lerobot/web";
 
 // 1. Find and connect to hardware
 const findProcess = await findPort();
@@ -39,7 +46,8 @@ await releaseMotors(robot);
 console.log("🔓 Motors released - you can move the robot by hand");
 
 // 3. Calibrate motors
-const calibrationProcess = await calibrate(robot, {
+const calibrationProcess = await calibrate({
+  robot,
   onProgress: (message) => console.log(message),
   onLiveUpdate: (data) => console.log("Live positions:", data),
 });
@@ -54,7 +62,11 @@ setTimeout(() => {
 const calibrationData = await calibrationProcess.result;
 
 // 4. Start teleoperation
-const teleop = await teleoperate(robot, { calibrationData });
+const teleop = await teleoperate({
+  robot,
+  calibrationData,
+  teleop: { type: "keyboard" }, // or { type: "direct" }
+});
 teleop.start();
 
 // Stop teleoperation when done
@@ -66,7 +78,7 @@ setTimeout(() => {
 
 ## Core API
 
-### `findPort(options?): Promise<FindPortProcess>`
+### `findPort(config?): Promise<FindPortProcess>`
 
 Discovers and connects to robotics hardware using WebSerial API. Two modes: interactive (shows port dialog) and auto-connect (reconnects to known robots).
 
@@ -157,12 +169,13 @@ interface RobotConfig {
 
 ---
 
-### `calibrate(robot, options?): Promise<CalibrationProcess>`
+### `calibrate(config): Promise<CalibrationProcess>`
 
 Calibrates motor homing offsets and records range of motion.
 
 ```typescript
-const calibrationProcess = await calibrate(robot, {
+const calibrationProcess = await calibrate({
+  robot,
   onProgress: (message) => {
     console.log(message); // "⚙️ Setting motor homing offsets"
   },
@@ -187,8 +200,8 @@ const calibrationData = await calibrationProcess.result;
 
 #### Parameters
 
-- `robot: RobotConnection` - Connected robot from `findPort()`
-- `options?: CalibrationOptions`
+- `config: CalibrateConfig`
+  - `robot: RobotConnection` - Connected robot from `findPort()`
   - `onProgress?: (message: string) => void` - Progress messages
   - `onLiveUpdate?: (data: LiveCalibrationData) => void` - Real-time position updates
 
@@ -214,13 +227,19 @@ const calibrationData = await calibrationProcess.result;
 
 ---
 
-### `teleoperate(robot, options?): Promise<TeleoperationProcess>`
+### `teleoperate(config): Promise<TeleoperationProcess>`
+
+Enables real-time robot control with extensible input devices. Supports keyboard control and direct programmatic movement, with architecture for future input devices like leader arms and joysticks.
 
-Enables real-time robot control with keyboard input and programmatic movement.
+#### Keyboard Teleoperation
 
 ```typescript
-const teleop = await teleoperate(robot, {
+import { teleoperate, KeyboardTeleoperator } from "@lerobot/web";
+
+const keyboardTeleop = await teleoperate({
+  robot,
   calibrationData: savedCalibrationData, // From calibrate()
+  teleop: { type: "keyboard" }, // Uses keyboard controls
   onStateUpdate: (state) => {
     console.log(`Active: ${state.isActive}`);
     console.log(`Motors:`, state.motorConfigs);
@@ -228,37 +247,62 @@ const teleop = await teleoperate(robot, {
 });
 
 // Start keyboard control
-teleop.start();
+keyboardTeleop.start();
+
+// Access keyboard-specific methods
+const keyboardController = keyboardTeleop.teleoperator as KeyboardTeleoperator;
+await keyboardController.moveMotor("shoulder_pan", 2048);
+
+// Stop when finished
+setTimeout(() => keyboardTeleop.stop(), 30000);
+```
+
+#### Direct Teleoperation
+
+```typescript
+import { teleoperate, DirectTeleoperator } from "@lerobot/web";
 
-// Programmatic control
-await teleop.moveMotor("shoulder_pan", 2048);
-await teleop.setMotorPositions({
+const directTeleop = await teleoperate({
+  robot,
+  calibrationData: savedCalibrationData,
+  teleop: { type: "direct" }, // For programmatic control
+  onStateUpdate: (state) => {
+    console.log(`Motors:`, state.motorConfigs);
+  },
+});
+
+directTeleop.start();
+
+// Access direct control methods
+const directController = directTeleop.teleoperator as DirectTeleoperator;
+await directController.moveMotor("shoulder_pan", 2048);
+await directController.setMotorPositions({
   shoulder_pan: 2048,
   elbow_flex: 1500,
 });
 
-// Stop teleoperation when finished
-setTimeout(() => {
-  console.log("Stopping teleoperation...");
-  teleop.stop();
-}, 30000); // Or call teleop.stop() when user is done
+// Stop when finished
+setTimeout(() => directTeleop.stop(), 30000);
 ```
 
 #### Parameters
 
-- `robot: RobotConnection` - Connected robot from `findPort()`
-- `options?: TeleoperationOptions`
+- `config: TeleoperateConfig`
+  - `robot: RobotConnection` - Connected robot from `findPort()`
+  - `teleop: TeleoperatorConfig` - Teleoperator configuration:
+    - `{ type: "keyboard", stepSize?: number, updateRate?: number, keyTimeout?: number }` - Keyboard control
+    - `{ type: "direct" }` - Direct programmatic control
   - `calibrationData?: { [motorName: string]: any }` - Calibration data from `calibrate()`
   - `onStateUpdate?: (state: TeleoperationState) => void` - State change callback
 
 #### Returns: `TeleoperationProcess`
 
-- `start(): void` - Begin keyboard teleoperation
-- `stop(): void` - Stop teleoperation and clear key states
-- `updateKeyState(key: string, pressed: boolean): void` - Manual key state control
+- `start(): void` - Begin teleoperation
+- `stop(): void` - Stop teleoperation and clear states
 - `getState(): TeleoperationState` - Current state and motor positions
-- `moveMotor(motorName: string, position: number): Promise<boolean>` - Move single motor
-- `setMotorPositions(positions: { [motorName: string]: number }): Promise<boolean>` - Move multiple motors
+- `teleoperator: BaseWebTeleoperator` - Access teleoperator-specific methods:
+  - **KeyboardTeleoperator**: `updateKeyState()`, `moveMotor()`, etc.
+  - **DirectTeleoperator**: `moveMotor()`, `setMotorPositions()`, etc.
 - `disconnect(): Promise<void>` - Stop and disconnect
 
 #### Keyboard Controls (SO-100)

packages/web/src/calibrate.ts

@@ -18,6 +18,7 @@ import { createSO100Config } from "./robots/so100_config.js";
 import type { RobotConnection } from "./types/robot-connection.js";
 import type { RobotHardwareConfig } from "./types/robot-config.js";
 import type {
+  CalibrateConfig,
   WebCalibrationResults,
   LiveCalibrationData,
   CalibrationProcess,
@@ -127,29 +128,27 @@ function applyRobotSpecificRangeAdjustments(
  * Main calibrate function - simple API, handles robot types internally
  */
 export async function calibrate(
-  robotConnection: RobotConnection,
-  options?: {
-    onLiveUpdate?: (data: LiveCalibrationData) => void;
-    onProgress?: (message: string) => void;
-  }
+  config: CalibrateConfig
 ): Promise<CalibrationProcess> {
+  const { robot, onLiveUpdate, onProgress } = config;
+
   // Validate required fields
-  if (!robotConnection.robotType) {
+  if (!robot.robotType) {
     throw new Error(
       "Robot type is required for calibration. Please configure the robot first."
     );
   }
 
   // Create web serial port wrapper
-  const port = new WebSerialPortWrapper(robotConnection.port);
+  const port = new WebSerialPortWrapper(robot.port);
   await port.initialize();
 
   // Get robot-specific configuration
-  let config: RobotHardwareConfig;
-  if (robotConnection.robotType.startsWith("so100")) {
-    config = createSO100Config(robotConnection.robotType);
+  let robotConfig: RobotHardwareConfig;
+  if (robot.robotType.startsWith("so100")) {
+    robotConfig = createSO100Config(robot.robotType);
   } else {
-    throw new Error(`Unsupported robot type: ${robotConnection.robotType}`);
+    throw new Error(`Unsupported robot type: ${robot.robotType}`);
   }
 
   let shouldStop = false;
@@ -158,26 +157,26 @@ export async function calibrate(
   // Start calibration process
   const resultPromise = (async (): Promise<WebCalibrationResults> => {
     // Step 1: Set homing offsets (automatic)
-    options?.onProgress?.("⚙️ Setting motor homing offsets");
+    onProgress?.("⚙️ Setting motor homing offsets");
     const homingOffsets = await setHomingOffsets(
       port,
-      config.motorIds,
-      config.motorNames
+      robotConfig.motorIds,
+      robotConfig.motorNames
     );
 
     // Step 2: Record ranges of motion with live updates
     const { rangeMins, rangeMaxes } = await recordRangesOfMotion(
       port,
-      config.motorIds,
-      config.motorNames,
+      robotConfig.motorIds,
+      robotConfig.motorNames,
       stopFunction,
-      options?.onLiveUpdate
+      onLiveUpdate
     );
 
     // Step 3: Apply robot-specific range adjustments
     applyRobotSpecificRangeAdjustments(
-      robotConnection.robotType!,
-      config.protocol,
+      robot.robotType!,
+      robotConfig.protocol,
       rangeMins,
       rangeMaxes
     );
@@ -185,8 +184,8 @@ export async function calibrate(
     // Step 4: Write hardware position limits to motors
     await writeHardwarePositionLimits(
       port,
-      config.motorIds,
-      config.motorNames,
+      robotConfig.motorIds,
+      robotConfig.motorNames,
       rangeMins,
       rangeMaxes
     );
@@ -194,13 +193,13 @@ export async function calibrate(
     // Step 5: Compile results
     const results: WebCalibrationResults = {};
 
-    for (let i = 0; i < config.motorNames.length; i++) {
-      const motorName = config.motorNames[i];
-      const motorId = config.motorIds[i];
+    for (let i = 0; i < robotConfig.motorNames.length; i++) {
+      const motorName = robotConfig.motorNames[i];
+      const motorId = robotConfig.motorIds[i];
 
       results[motorName] = {
         id: motorId,
-        drive_mode: config.driveModes[i],
+        drive_mode: robotConfig.driveModes[i],
         homing_offset: homingOffsets[motorName],
         range_min: rangeMins[motorName],
         range_max: rangeMaxes[motorName],

packages/web/src/find_port.ts

@@ -42,7 +42,7 @@ import type {
 } from "./types/robot-connection.js";
 import type {
   Serial,
-  FindPortOptions,
+  FindPortConfig,
   FindPortProcess,
   USBDevice,
 } from "./types/port-discovery.js";
@@ -171,7 +171,7 @@ async function getStoredUSBDeviceMetadata(port: SerialPort): Promise<{
  * Interactive mode: Show native dialogs for port + device selection
  */
 async function findPortInteractive(
-  options: FindPortOptions
+  options: FindPortConfig
 ): Promise<RobotConnection[]> {
   const { onMessage } = options;
 
@@ -239,7 +239,7 @@ async function findPortInteractive(
  */
 async function findPortAutoConnect(
   robotConfigs: RobotConfig[],
-  options: FindPortOptions
+  options: FindPortConfig
 ): Promise<RobotConnection[]> {
   const { onMessage } = options;
   const results: RobotConnection[] = [];
@@ -273,6 +273,8 @@ async function findPortAutoConnect(
           const wasOpen = port.readable !== null;
           if (!wasOpen) {
             await port.open({ baudRate: 1000000 });
+            // Small delay to allow port to stabilize after opening
+            await new Promise((resolve) => setTimeout(resolve, 100));
           }
 
           // Test connection by trying basic motor communication
@@ -280,7 +282,18 @@ async function findPortAutoConnect(
           await portWrapper.initialize();
 
           // Try to read from motor ID 1 (most robots have at least one motor)
-          const testPosition = await readMotorPosition(portWrapper, 1);
+          // Retry mechanism for more robust connection testing
+          let testPosition: number | null = null;
+          for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+              testPosition = await readMotorPosition(portWrapper, 1);
+              if (testPosition !== null) break;
+              await new Promise((resolve) => setTimeout(resolve, 50));
+            } catch (retryError) {
+              if (attempt === 2) throw retryError;
+              await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+          }
 
           // If we can read a position, this is likely a working robot port
           if (testPosition !== null) {
@@ -367,7 +380,7 @@ async function findPortAutoConnect(
  * Mode 2: Auto-connect - Returns RobotConnection[]
  */
 export async function findPort(
-  options: FindPortOptions = {}
+  config: FindPortConfig = {}
 ): Promise<FindPortProcess> {
   // Check WebSerial support
   if (!isWebSerialSupported()) {
@@ -376,7 +389,7 @@ export async function findPort(
     );
   }
 
-  const { robotConfigs, onMessage } = options;
+  const { robotConfigs, onMessage } = config;
   let stopped = false;
 
   // Determine mode
@@ -395,9 +408,9 @@ export async function findPort(
     }
 
     if (isAutoConnectMode) {
-      return await findPortAutoConnect(robotConfigs!, options);
+      return await findPortAutoConnect(robotConfigs!, config);
     } else {
-      return await findPortInteractive(options);
+      return await findPortInteractive(config);
     }
   })();
 

packages/web/src/index.ts

@@ -26,6 +26,12 @@ export type {
 } from "./types/robot-connection.js";
 
 export type {
+  FindPortConfig,
+  FindPortProcess,
+} from "./types/port-discovery.js";
+
+export type {
+  CalibrateConfig,
   WebCalibrationResults,
   LiveCalibrationData,
   CalibrationProcess,

packages/web/src/teleoperators/base-teleoperator.ts

@@ -48,6 +48,9 @@ export abstract class BaseWebTeleoperator implements WebTeleoperator {
 
   async disconnect(): Promise<void> {
     this.stop();
+    if (this.port && "close" in this.port) {
+      await (this.port as any).close();
+    }
   }
 
   onMotorConfigsUpdate(motorConfigs: MotorConfig[]): void {

packages/web/src/types/calibration.ts

@@ -2,18 +2,7 @@
  * Calibration-related types for web implementation
  */
 
-/**
- * Calibration results structure
- */
-export interface WebCalibrationResults {
-  [motorName: string]: {
-    id: number;
-    drive_mode: number;
-    homing_offset: number;
-    range_min: number;
-    range_max: number;
-  };
-}
+import type { RobotConnection } from "./robot-connection.js";
 
 /**
  * Live calibration data with current positions and ranges
@@ -27,6 +16,28 @@ export interface LiveCalibrationData {
   };
 }
 
+/**
+ * Config for calibrate function
+ */
+export interface CalibrateConfig {
+  robot: RobotConnection;
+  onLiveUpdate?: (data: LiveCalibrationData) => void;
+  onProgress?: (message: string) => void;
+}
+
+/**
+ * Calibration results structure
+ */
+export interface WebCalibrationResults {
+  [motorName: string]: {
+    id: number;
+    drive_mode: number;
+    homing_offset: number;
+    range_min: number;
+    range_max: number;
+  };
+}
+
 /**
  * Calibration process control object
  */

packages/web/src/types/port-discovery.ts

@@ -57,9 +57,9 @@ export interface USB {
 }
 
 /**
- * Options for findPort function
+ * Config for findPort function
  */
-export interface FindPortOptions {
+export interface FindPortConfig {
   // Auto-connect mode: provide robot configs to connect to
   robotConfigs?: RobotConfig[];
 

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

@@ -68,6 +68,13 @@ export class WebSerialPortWrapper {
   }
 
   async close(): Promise<void> {
-    // Don't close the port itself - just wrapper cleanup
+    try {
+      if (this.port && this.port.readable) {
+        await this.port.close();
+        console.log("🔌 Serial port closed successfully");
+      }
+    } catch (error) {
+      console.warn("Error closing serial port:", error);
+    }
   }
 }