chore: remove comments that make no sense

docs/conventions.md

@@ -19,6 +19,7 @@
 - **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
+- **No Reference Comments**: Never write comments like "same pattern as calibrate.ts", "matches Node.js", "copied from X", etc. Comments should explain what the code does, not where it came from or what it's similar to
 
 ## Project Goals
 

src/lerobot/web/calibrate.ts

@@ -39,7 +39,7 @@ async function recordRangesOfMotion(
   const rangeMins: { [motor: string]: number } = {};
   const rangeMaxes: { [motor: string]: number } = {};
 
-  // Read actual current positions (matching Python exactly)
+  // Read actual current positions
   const startPositions = await readAllMotorPositions(port, motorIds);
 
   for (let i = 0; i < motorNames.length; i++) {
@@ -105,7 +105,6 @@ function applyRobotSpecificRangeAdjustments(
   if (robotType.startsWith("so100") && rangeMins["wrist_roll"] !== undefined) {
     // The wrist_roll is a continuous rotation motor that should use the full
     // 0-4095 range regardless of what the user recorded during calibration.
-    // This matches the hardware specification and Python lerobot behavior.
     rangeMins["wrist_roll"] = 0;
     rangeMaxes["wrist_roll"] = protocol.resolution - 1;
   }
@@ -185,7 +184,7 @@ export async function calibrate(
       rangeMaxes
     );
 
-    // Step 5: Compile results in Python-compatible format
+    // Step 5: Compile results
     const results: WebCalibrationResults = {};
 
     for (let i = 0; i < config.motorNames.length; i++) {

src/lerobot/web/find_port.ts

@@ -28,7 +28,8 @@
  * await calibrate(storedRobots[0], options);
  */
 
-import { getRobotConnectionManager } from "./utils/robot-connection-manager.js";
+import { WebSerialPortWrapper } from "./utils/serial-port-wrapper.js";
+import { readMotorPosition } from "./utils/motor-communication.js";
 import type {
   RobotConnection,
   RobotConfig,
@@ -146,19 +147,22 @@ async function findPortAutoConnect(
             await port.open({ baudRate: 1000000 });
           }
 
-          // Test connection by trying to communicate
-          const manager = getRobotConnectionManager();
-          await manager.connect(
-            port,
-            config.robotType,
-            config.robotId,
-            config.serialNumber
-          );
-
-          matchedPort = port;
-          connected = true;
-          onMessage?.(`✅ Connected to ${config.robotId}`);
-          break;
+          // Test connection by trying basic motor communication
+          const portWrapper = new WebSerialPortWrapper(port);
+          await portWrapper.initialize();
+
+          // Try to read from motor ID 1 (most robots have at least one motor)
+          const testPosition = await readMotorPosition(portWrapper, 1);
+
+          // If we can read a position, this is likely a working robot port
+          if (testPosition !== null) {
+            matchedPort = port;
+            connected = true;
+            onMessage?.(`✅ Connected to ${config.robotId}`);
+            break;
+          } else {
+            throw new Error("No motor response - not a robot port");
+          }
         } catch (portError) {
           // This port didn't work, try next one
           console.log(

src/lerobot/web/robots/robot.ts

@@ -1,7 +1,6 @@
 /**
  * Base Robot class for Web platform
  * Uses Web Serial API for serial communication
- * Mirrors Python lerobot/common/robots/robot.py but adapted for browser environment
  */
 
 import type { RobotConfig } from "../../node/robots/config.js";

src/lerobot/web/robots/so100_config.ts

@@ -1,6 +1,5 @@
 /**
  * SO-100 specific hardware configuration
- * Matches Node.js SO-100 config structure and Python lerobot exactly
  */
 
 import type { RobotHardwareConfig } from "../types/robot-config.js";
@@ -35,7 +34,7 @@ export const SO100_CONFIG = {
     "gripper",
   ],
   motorIds: [1, 2, 3, 4, 5, 6],
-  // Python lerobot uses drive_mode=0 for all SO-100 motors
+  // All SO-100 motors use drive_mode=0
   driveModes: [0, 0, 0, 0, 0, 0],
 };
 

src/lerobot/web/teleoperate.ts

@@ -82,7 +82,7 @@ export class WebTeleoperationController {
   } = {};
   private onStateUpdate?: (state: TeleoperationState) => void;
 
-  // Movement parameters (matches Node.js)
+  // Movement parameters
   private readonly STEP_SIZE = 8;
   private readonly UPDATE_RATE = 60; // 60 FPS
   private readonly KEY_TIMEOUT = 600; // ms - longer than browser keyboard repeat delay (~500ms)
@@ -100,7 +100,7 @@ export class WebTeleoperationController {
   }
 
   async initialize(): Promise<void> {
-    // Read current positions using proven utilities
+    // Read current motor positions
     for (const config of this.motorConfigs) {
       const position = await readMotorPosition(this.port, config.id);
       if (position !== null) {
@@ -213,7 +213,7 @@ export class WebTeleoperationController {
       );
     }
 
-    // Send motor commands using proven utilities
+    // Send motor commands
     Object.entries(targetPositions).forEach(([motorName, targetPosition]) => {
       const motorConfig = this.motorConfigs.find((m) => m.name === motorName);
       if (motorConfig && targetPosition !== motorConfig.currentPosition) {
@@ -273,7 +273,7 @@ export class WebTeleoperationController {
 }
 
 /**
- * Main teleoperate function - simple API matching calibrate pattern
+ * Main teleoperate function - simple API
  * Handles robot types internally, creates appropriate motor configurations
  */
 export async function teleoperate(
@@ -290,11 +290,11 @@ export async function teleoperate(
     );
   }
 
-  // Create web serial port wrapper (same pattern as calibrate.ts)
+  // Create web serial port wrapper
   const port = new WebSerialPortWrapper(robotConnection.port);
   await port.initialize();
 
-  // Get robot-specific configuration (same pattern as calibrate.ts)
+  // Get robot-specific configuration
   let config: RobotHardwareConfig;
   if (robotConnection.robotType.startsWith("so100")) {
     config = createSO100Config(robotConnection.robotType);
@@ -322,7 +322,7 @@ export async function teleoperate(
   );
   await controller.initialize();
 
-  // Wrap controller in process object (matches calibrate pattern)
+  // Wrap controller in process object
   return {
     start: () => {
       controller.start();

src/lerobot/web/types/calibration.ts

@@ -3,7 +3,7 @@
  */
 
 /**
- * Calibration results structure matching Python lerobot format exactly
+ * Calibration results structure
  */
 export interface WebCalibrationResults {
   [motorName: string]: {

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

@@ -1,43 +0,0 @@
-/**
- * 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

@@ -24,7 +24,7 @@ export interface TeleoperationState {
 }
 
 /**
- * Teleoperation process control object (matches calibrate pattern)
+ * Teleoperation process control object
  */
 export interface TeleoperationProcess {
   start(): void;

src/lerobot/web/utils/motor-calibration.ts

@@ -12,7 +12,7 @@ import {
 } from "./motor-communication.js";
 
 /**
- * Reset homing offsets to 0 for all motors (matches Node.js exactly)
+ * Reset homing offsets to 0 for all motors
  */
 export async function resetHomingOffsets(
   port: MotorCommunicationPort,
@@ -115,7 +115,7 @@ export async function writeHomingOffsetsToMotors(
 }
 
 /**
- * Set homing offsets with immediate writing (matches Node.js exactly)
+ * Set homing offsets with immediate writing
  */
 export async function setHomingOffsets(
   port: MotorCommunicationPort,

src/lerobot/web/utils/motor-communication.ts

@@ -1,6 +1,6 @@
 /**
  * Motor Communication Utilities
- * Proven patterns for STS3215 motor reading and writing operations
+ * STS3215 motor reading and writing operations
  */
 
 import { STS3215_PROTOCOL } from "./sts3215-protocol.js";
@@ -15,15 +15,14 @@ export interface MotorCommunicationPort {
 }
 
 /**
- * Read single motor position with PROVEN retry logic
- * Extracted from calibrate.ts with all proven timing and retry patterns
+ * Read single motor position with retry logic
  */
 export async function readMotorPosition(
   port: MotorCommunicationPort,
   motorId: number
 ): Promise<number | null> {
   try {
-    // Create Read Position packet using proven pattern
+    // Create Read Position packet
     const packet = new Uint8Array([
       0xff,
       0xff, // Header
@@ -45,23 +44,23 @@ export async function readMotorPosition(
       ) & 0xff;
     packet[7] = checksum;
 
-    // PROVEN PATTERN: Professional Feetech communication with retry logic
+    // Retry communication with timeouts
     let attempts = 0;
 
     while (attempts < STS3215_PROTOCOL.MAX_RETRIES) {
       attempts++;
 
-      // CRITICAL: Clear any remaining data in buffer first (from calibration lessons)
+      // Clear any remaining data in buffer first
       try {
         await port.read(0); // Non-blocking read to clear buffer
       } catch (e) {
         // Expected - buffer was empty
       }
 
-      // Write command with PROVEN timing
+      // Write command
       await port.write(packet);
 
-      // PROVEN TIMING: Arduino library uses careful timing - Web Serial needs more
+      // Wait for motor response
       await new Promise((resolve) =>
         setTimeout(resolve, STS3215_PROTOCOL.WRITE_TO_READ_DELAY)
       );
@@ -82,7 +81,7 @@ export async function readMotorPosition(
         // Read timeout, retry
       }
 
-      // PROVEN TIMING: Professional timing between attempts
+      // Wait between retry attempts
       if (attempts < STS3215_PROTOCOL.MAX_RETRIES) {
         await new Promise((resolve) =>
           setTimeout(resolve, STS3215_PROTOCOL.RETRY_DELAY)
@@ -98,8 +97,7 @@ export async function readMotorPosition(
 }
 
 /**
- * Read all motor positions with PROVEN patterns
- * Exactly matches calibrate.ts readMotorPositions() function
+ * Read all motor positions
  */
 export async function readAllMotorPositions(
   port: MotorCommunicationPort,
@@ -120,7 +118,7 @@ export async function readAllMotorPositions(
       motorPositions.push(fallback);
     }
 
-    // PROVEN PATTERN: Professional inter-motor delay
+    // Delay between motor reads
     await new Promise((resolve) =>
       setTimeout(resolve, STS3215_PROTOCOL.INTER_MOTOR_DELAY)
     );
@@ -167,7 +165,6 @@ export async function writeMotorPosition(
 
 /**
  * Generic function to write a 2-byte value to a motor register
- * Matches calibrate.ts writeMotorRegister() exactly
  */
 export async function writeMotorRegister(
   port: MotorCommunicationPort,
@@ -200,7 +197,7 @@ export async function writeMotorRegister(
     ) & 0xff;
   packet[8] = checksum;
 
-  // Simple write then read like calibration
+  // Write register value
   await port.write(packet);
 
   // Wait for response (silent unless error)

src/lerobot/web/utils/robot-connection-manager.ts

@@ -1,168 +0,0 @@
-/**
- * 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 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
- */
-class RobotConnectionManagerImpl implements RobotConnectionManager {
-  private port: SerialPort | null = null;
-  private state: RobotConnectionState = { isConnected: false };
-  private stateChangeCallbacks: Set<(state: RobotConnectionState) => void> =
-    new Set();
-
-  getState(): RobotConnectionState {
-    return { ...this.state };
-  }
-
-  async connect(
-    port: SerialPort,
-    robotType: string,
-    robotId: string,
-    serialNumber: string
-  ): Promise<void> {
-    try {
-      // Validate port is open
-      if (!port.readable || !port.writable) {
-        throw new Error("Port is not open");
-      }
-
-      // Update connection state
-      this.port = port;
-      this.state = {
-        isConnected: true,
-        robotType: robotType as "so100_follower" | "so100_leader",
-        robotId,
-        serialNumber,
-        lastError: undefined,
-      };
-
-      this.notifyStateChange();
-      console.log(
-        `🤖 Robot connected: ${robotType} (${robotId}) - ${serialNumber}`
-      );
-    } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : "Connection failed";
-      this.state = {
-        isConnected: false,
-        lastError: errorMessage,
-      };
-      this.notifyStateChange();
-      throw error;
-    }
-  }
-
-  async disconnect(): Promise<void> {
-    this.port = null;
-    this.state = { isConnected: false };
-    this.notifyStateChange();
-    console.log("🤖 Robot disconnected");
-  }
-
-  getPort(): SerialPort | null {
-    return this.port;
-  }
-
-  async writeData(data: Uint8Array): Promise<void> {
-    if (!this.port?.writable) {
-      throw new Error("Robot not connected or port not writable");
-    }
-
-    const writer = this.port.writable.getWriter();
-    try {
-      await writer.write(data);
-    } finally {
-      writer.releaseLock();
-    }
-  }
-
-  async readData(timeout: number = 1000): Promise<Uint8Array> {
-    if (!this.port?.readable) {
-      throw new Error("Robot not connected or port not readable");
-    }
-
-    const reader = this.port.readable.getReader();
-
-    try {
-      const timeoutPromise = new Promise<never>((_, reject) => {
-        setTimeout(() => reject(new Error("Read timeout")), timeout);
-      });
-
-      const readPromise = reader
-        .read()
-        .then((result: { 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 {
-      reader.releaseLock();
-    }
-  }
-
-  onStateChange(callback: (state: RobotConnectionState) => void): () => void {
-    this.stateChangeCallbacks.add(callback);
-
-    // Return unsubscribe function
-    return () => {
-      this.stateChangeCallbacks.delete(callback);
-    };
-  }
-
-  private notifyStateChange(): void {
-    this.stateChangeCallbacks.forEach((callback) => {
-      try {
-        callback(this.getState());
-      } catch (error) {
-        console.warn("Error in state change callback:", error);
-      }
-    });
-  }
-}
-
-// Singleton instance
-const robotConnectionManager = new RobotConnectionManagerImpl();
-
-/**
- * Get the singleton robot connection manager
- * This is the single source of truth for robot connections
- */
-export function getRobotConnectionManager(): RobotConnectionManager {
-  return robotConnectionManager;
-}
-
-/**
- * Adapter to make robot connection manager compatible with motor-communication utilities
- * Provides the MotorCommunicationPort interface for the singleton manager
- */
-export class RobotConnectionManagerAdapter implements MotorCommunicationPort {
-  private manager: RobotConnectionManager;
-
-  constructor(manager: RobotConnectionManager) {
-    this.manager = manager;
-  }
-
-  async write(data: Uint8Array): Promise<void> {
-    return this.manager.writeData(data);
-  }
-
-  async read(timeout?: number): Promise<Uint8Array> {
-    return this.manager.readData(timeout);
-  }
-}

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

@@ -5,7 +5,6 @@
 
 /**
  * Web Serial Port wrapper - direct write/read with immediate lock release
- * Follows Chrome documentation exactly for proper Web Serial API usage
  */
 export class WebSerialPortWrapper {
   private port: SerialPort;

src/lerobot/web/utils/sts3215-protocol.ts

@@ -26,7 +26,7 @@ export const STS3215_PROTOCOL = {
   MIN_POSITION_LIMIT_LENGTH: 2,
   MAX_POSITION_LIMIT_LENGTH: 2,
 
-  // Communication timing (proven from calibration)
+  // Communication timing
   WRITE_TO_READ_DELAY: 10,
   RETRY_DELAY: 20,
   INTER_MOTOR_DELAY: 10,