refactor: move types into dedicated files

docs/conventions.md

@@ -18,6 +18,7 @@
 - **Library/Demo Separation**: Standard library handles hardware communication, demos handle storage/UI concerns - never mix these responsibilities
 - **No Code Duplication**: Use shared utils, never reimplement the same functionality across files
 - **Direct Library Usage**: End users call library functions directly (e.g., `calibrate()`, `teleoperate()`) - avoid unnecessary abstraction layers
+- **Comments**: Write about the functionality, not what you did. We only need to know what the code is doing to make it more easy to understand, not a history of the changes
 
 ## Project Goals
 

src/lerobot/web/calibrate.ts

@@ -8,7 +8,6 @@
 import { WebSerialPortWrapper } from "./utils/serial-port-wrapper.js";
 import {
   readAllMotorPositions,
-  releaseMotors,
   type MotorCommunicationPort,
 } from "./utils/motor-communication.js";
 import {
@@ -17,42 +16,12 @@ import {
 } from "./utils/motor-calibration.js";
 import { createSO100Config } from "./robots/so100_config.js";
 import type { RobotConnection } from "./types/robot-connection.js";
-
-// Import shared robot hardware configuration interface
 import type { RobotHardwareConfig } from "./types/robot-config.js";
-
-/**
- * Calibration results structure matching Python lerobot format exactly
- */
-export interface WebCalibrationResults {
-  [motorName: string]: {
-    id: number;
-    drive_mode: number;
-    homing_offset: number;
-    range_min: number;
-    range_max: number;
-  };
-}
-
-/**
- * Live calibration data with current positions and ranges
- */
-export interface LiveCalibrationData {
-  [motorName: string]: {
-    current: number;
-    min: number;
-    max: number;
-    range: number;
-  };
-}
-
-/**
- * Calibration process control object
- */
-export interface CalibrationProcess {
-  stop(): void;
-  result: Promise<WebCalibrationResults>;
-}
+import type {
+  WebCalibrationResults,
+  LiveCalibrationData,
+  CalibrationProcess,
+} from "./types/calibration.js";
 
 /**
  * Record ranges of motion with live updates

src/lerobot/web/find_port.ts

@@ -28,29 +28,19 @@
  * await calibrate(storedRobots[0], options);
  */
 
-import { getRobotConnectionManager } from "./robot-connection.js";
+import { getRobotConnectionManager } from "./utils/robot-connection-manager.js";
 import type {
   RobotConnection,
   RobotConfig,
   SerialPort,
 } from "./types/robot-connection.js";
-
-/**
- * Extended WebSerial API type definitions
- */
-interface Serial extends EventTarget {
-  getPorts(): Promise<SerialPort[]>;
-  requestPort(options?: SerialPortRequestOptions): Promise<SerialPort>;
-}
-
-interface SerialPortRequestOptions {
-  filters?: SerialPortFilter[];
-}
-
-interface SerialPortFilter {
-  usbVendorId?: number;
-  usbProductId?: number;
-}
+import type {
+  Serial,
+  SerialPortRequestOptions,
+  SerialPortFilter,
+  FindPortOptions,
+  FindPortProcess,
+} from "./types/port-discovery.js";
 
 declare global {
   interface Navigator {
@@ -58,34 +48,6 @@ declare global {
   }
 }
 
-/**
- * Options for findPort function
- */
-export interface FindPortOptions {
-  // Auto-connect mode: provide robot configs to connect to
-  robotConfigs?: RobotConfig[];
-
-  // Callbacks
-  onMessage?: (message: string) => void;
-  onRequestUserAction?: (
-    message: string,
-    type: "confirm" | "select"
-  ) => Promise<boolean>;
-}
-
-/**
- * Process object returned by findPort
- */
-export interface FindPortProcess {
-  // Result promise - Always returns RobotConnection[] (consistent API)
-  // Interactive mode: single robot in array
-  // Auto-connect mode: all successfully connected robots in array
-  result: Promise<RobotConnection[]>;
-
-  // Control
-  stop: () => void;
-}
-
 /**
  * Check if WebSerial API is available
  */
@@ -104,34 +66,6 @@ function getPortDisplayName(port: SerialPort): string {
   return "Serial Device";
 }
 
-/**
- * Try to get serial number from a port by opening and reading device info
- */
-async function getPortSerialNumber(port: SerialPort): Promise<string | null> {
-  try {
-    const wasOpen = port.readable !== null;
-
-    // Open port if not already open
-    if (!wasOpen) {
-      await port.open({ baudRate: 1000000 });
-    }
-
-    // For now, we'll return null since reading serial number from STS3215 motors
-    // requires specific protocol implementation. This is a placeholder for future enhancement.
-    // In practice, serial numbers are typically stored in device metadata or configuration.
-
-    // Close port if we opened it
-    if (!wasOpen && port.readable) {
-      await port.close();
-    }
-
-    return null;
-  } catch (error) {
-    console.warn("Could not read serial number from port:", error);
-    return null;
-  }
-}
-
 /**
  * Interactive mode: Show native dialog for port selection
  */

src/lerobot/web/teleoperate.ts

@@ -1,6 +1,5 @@
 /**
  * Web teleoperation functionality using Web Serial API
- * Mirrors the Node.js implementation but adapted for browser environment
  */
 
 import { createSO100Config } from "./robots/so100_config.js";
@@ -15,42 +14,11 @@ import {
   writeMotorPosition,
   type MotorCommunicationPort,
 } from "./utils/motor-communication.js";
-
-/**
- * Motor position and limits for teleoperation
- */
-export interface MotorConfig {
-  id: number;
-  name: string;
-  currentPosition: number;
-  minPosition: number;
-  maxPosition: number;
-}
-
-/**
- * Teleoperation state
- */
-export interface TeleoperationState {
-  isActive: boolean;
-  motorConfigs: MotorConfig[];
-  lastUpdate: number;
-  keyStates: { [key: string]: { pressed: boolean; timestamp: number } };
-}
-
-/**
- * Teleoperation process control object (matches calibrate pattern)
- */
-export interface TeleoperationProcess {
-  start(): void;
-  stop(): void;
-  updateKeyState(key: string, pressed: boolean): void;
-  getState(): TeleoperationState;
-  moveMotor(motorName: string, position: number): Promise<boolean>;
-  setMotorPositions(positions: {
-    [motorName: string]: number;
-  }): Promise<boolean>;
-  disconnect(): Promise<void>;
-}
+import type {
+  MotorConfig,
+  TeleoperationState,
+  TeleoperationProcess,
+} from "./types/teleoperation.js";
 
 /**
  * Create motor configurations from robot hardware config

src/lerobot/web/types/calibration.ts

@@ -0,0 +1,36 @@
+/**
+ * Calibration-related types for web implementation
+ */
+
+/**
+ * Calibration results structure matching Python lerobot format exactly
+ */
+export interface WebCalibrationResults {
+  [motorName: string]: {
+    id: number;
+    drive_mode: number;
+    homing_offset: number;
+    range_min: number;
+    range_max: number;
+  };
+}
+
+/**
+ * Live calibration data with current positions and ranges
+ */
+export interface LiveCalibrationData {
+  [motorName: string]: {
+    current: number;
+    min: number;
+    max: number;
+    range: number;
+  };
+}
+
+/**
+ * Calibration process control object
+ */
+export interface CalibrationProcess {
+  stop(): void;
+  result: Promise<WebCalibrationResults>;
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Port discovery and WebSerial API types for web implementation
+ */
+
+// Import types needed in this file
+import type {
+  RobotConnection,
+  RobotConfig,
+  SerialPort,
+} from "./robot-connection.js";
+
+/**
+ * Extended WebSerial API type definitions
+ */
+export interface Serial extends EventTarget {
+  getPorts(): Promise<SerialPort[]>;
+  requestPort(options?: SerialPortRequestOptions): Promise<SerialPort>;
+}
+
+export interface SerialPortRequestOptions {
+  filters?: SerialPortFilter[];
+}
+
+export interface SerialPortFilter {
+  usbVendorId?: number;
+  usbProductId?: number;
+}
+
+/**
+ * Options for findPort function
+ */
+export interface FindPortOptions {
+  // Auto-connect mode: provide robot configs to connect to
+  robotConfigs?: RobotConfig[];
+
+  // Callbacks
+  onMessage?: (message: string) => void;
+  onRequestUserAction?: (
+    message: string,
+    type: "confirm" | "select"
+  ) => Promise<boolean>;
+}
+
+/**
+ * Process object returned by findPort
+ */
+export interface FindPortProcess {
+  // Result promise - Always returns RobotConnection[] (consistent API)
+  // Interactive mode: single robot in array
+  // Auto-connect mode: all successfully connected robots in array
+  result: Promise<RobotConnection[]>;
+
+  // Control
+  stop: () => void;
+}
+
+// Re-export commonly used types for convenience
+export type { RobotConnection, RobotConfig, SerialPort };

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

@@ -0,0 +1,43 @@
+/**
+ * Robot connection management and process types for web implementation
+ */
+
+import type { SerialPort } from "./robot-connection.js";
+
+/**
+ * Robot connection state tracking
+ */
+export interface RobotConnectionState {
+  isConnected: boolean;
+  robotType?: "so100_follower" | "so100_leader";
+  robotId?: string;
+  serialNumber?: string;
+  lastError?: string;
+}
+
+/**
+ * Robot connection manager interface
+ */
+export interface RobotConnectionManager {
+  // State
+  getState(): RobotConnectionState;
+
+  // Connection management
+  connect(
+    port: SerialPort,
+    robotType: string,
+    robotId: string,
+    serialNumber: string
+  ): Promise<void>;
+  disconnect(): Promise<void>;
+
+  // Port access
+  getPort(): SerialPort | null;
+
+  // Serial operations (shared by calibration, teleoperation, etc.)
+  writeData(data: Uint8Array): Promise<void>;
+  readData(timeout?: number): Promise<Uint8Array>;
+
+  // Event system
+  onStateChange(callback: (state: RobotConnectionState) => void): () => void;
+}

src/lerobot/web/types/teleoperation.ts

@@ -0,0 +1,39 @@
+/**
+ * Teleoperation-related types for web implementation
+ */
+
+/**
+ * Motor position and limits for teleoperation
+ */
+export interface MotorConfig {
+  id: number;
+  name: string;
+  currentPosition: number;
+  minPosition: number;
+  maxPosition: number;
+}
+
+/**
+ * Teleoperation state
+ */
+export interface TeleoperationState {
+  isActive: boolean;
+  motorConfigs: MotorConfig[];
+  lastUpdate: number;
+  keyStates: { [key: string]: { pressed: boolean; timestamp: number } };
+}
+
+/**
+ * Teleoperation process control object (matches calibrate pattern)
+ */
+export interface TeleoperationProcess {
+  start(): void;
+  stop(): void;
+  updateKeyState(key: string, pressed: boolean): void;
+  getState(): TeleoperationState;
+  moveMotor(motorName: string, position: number): Promise<boolean>;
+  setMotorPositions(positions: {
+    [motorName: string]: number;
+  }): Promise<boolean>;
+  disconnect(): Promise<void>;
+}

src/lerobot/web/{robot-connection.ts → utils/robot-connection-manager.ts}

@@ -1,48 +1,18 @@
 /**
- * Core Robot Connection Manager
- * Single source of truth for robot connections in the web library
- * Provides singleton access to robot ports and connection state
+ * Internal Robot Connection Manager Utility
+ * Singleton manager providing shared robot connection state and communication
+ * Used internally by calibrate, teleoperate, find_port, etc.
+ *
+ * This is an internal utility - users should not import this directly.
+ * Instead, use the public APIs: calibrate(), findPort(), teleoperate()
  */
 
-import {
-  readMotorPosition as readMotorPositionUtil,
-  writeMotorPosition as writeMotorPositionUtil,
-  readAllMotorPositions as readAllMotorPositionsUtil,
-  writeMotorRegister,
-  type MotorCommunicationPort,
-} from "./utils/motor-communication.js";
-
-export interface RobotConnectionState {
-  isConnected: boolean;
-  robotType?: "so100_follower" | "so100_leader";
-  robotId?: string;
-  serialNumber?: string;
-  lastError?: string;
-}
-
-export interface RobotConnectionManager {
-  // State
-  getState(): RobotConnectionState;
-
-  // Connection management
-  connect(
-    port: SerialPort,
-    robotType: string,
-    robotId: string,
-    serialNumber: string
-  ): Promise<void>;
-  disconnect(): Promise<void>;
-
-  // Port access
-  getPort(): SerialPort | null;
-
-  // Serial operations (shared by calibration, teleoperation, etc.)
-  writeData(data: Uint8Array): Promise<void>;
-  readData(timeout?: number): Promise<Uint8Array>;
-
-  // Event system
-  onStateChange(callback: (state: RobotConnectionState) => void): () => void;
-}
+import type { MotorCommunicationPort } from "./motor-communication.js";
+import type { SerialPort } from "../types/robot-connection.js";
+import type {
+  RobotConnectionState,
+  RobotConnectionManager,
+} from "../types/robot-processes.js";
 
 /**
  * Singleton Robot Connection Manager Implementation
@@ -131,12 +101,14 @@ class RobotConnectionManagerImpl implements RobotConnectionManager {
         setTimeout(() => reject(new Error("Read timeout")), timeout);
       });
 
-      const readPromise = reader.read().then((result) => {
-        if (result.done || !result.value) {
-          throw new Error("Read failed - port closed or no data");
-        }
-        return result.value;
-      });
+      const readPromise = reader
+        .read()
+        .then((result: { done: boolean; value?: Uint8Array }) => {
+          if (result.done || !result.value) {
+            throw new Error("Read failed - port closed or no data");
+          }
+          return result.value;
+        });
 
       return await Promise.race([readPromise, timeoutPromise]);
     } finally {
@@ -176,14 +148,10 @@ export function getRobotConnectionManager(): RobotConnectionManager {
 }
 
 /**
- * Utility functions for common robot operations
- * Uses shared motor communication utilities for consistency
+ * Adapter to make robot connection manager compatible with motor-communication utilities
+ * Provides the MotorCommunicationPort interface for the singleton manager
  */
-
-/**
- * Adapter to make robot connection manager compatible with motor utils
- */
-class RobotConnectionManagerAdapter implements MotorCommunicationPort {
+export class RobotConnectionManagerAdapter implements MotorCommunicationPort {
   private manager: RobotConnectionManager;
 
   constructor(manager: RobotConnectionManager) {
@@ -198,31 +166,3 @@ class RobotConnectionManagerAdapter implements MotorCommunicationPort {
     return this.manager.readData(timeout);
   }
 }
-
-export async function writeMotorPosition(
-  motorId: number,
-  position: number
-): Promise<void> {
-  const manager = getRobotConnectionManager();
-  const adapter = new RobotConnectionManagerAdapter(manager);
-
-  return writeMotorPositionUtil(adapter, motorId, position);
-}
-
-export async function readMotorPosition(
-  motorId: number
-): Promise<number | null> {
-  const manager = getRobotConnectionManager();
-  const adapter = new RobotConnectionManagerAdapter(manager);
-
-  return readMotorPositionUtil(adapter, motorId);
-}
-
-export async function readAllMotorPositions(
-  motorIds: number[]
-): Promise<number[]> {
-  const manager = getRobotConnectionManager();
-  const adapter = new RobotConnectionManagerAdapter(manager);
-
-  return readAllMotorPositionsUtil(adapter, motorIds);
-}