docs/planning/001_find_usb_ports.md

User Story 001: Find USB Ports

Story

As a robotics developer setting up SO-100 robot arms
I want to identify which USB ports my robot arms are connected to
So that I can configure my robot arms without manually testing each port

Background

When setting up SO-100 robot arms (or any robotics hardware), users need to identify which USB/serial ports correspond to their robot controllers. The Python lerobot provides a find_port.py script that:

1. Lists all available serial ports
2. Asks the user to disconnect a specific device
3. Detects which port disappeared
4. Identifies that port as belonging to the disconnected device

We need to replicate this functionality in Node.js for lerobot.js.

Acceptance Criteria

Core Functionality

• Port Discovery: List all available serial/USB ports on the system
• Interactive Detection: Guide user through disconnect/reconnect process
• Port Identification: Detect which port corresponds to which robot arm
• Cross-Platform: Work on Windows, macOS, and Linux
• CLI Interface: Provide npx lerobot find-port command identical to Python version

User Experience

• Clear Instructions: Provide step-by-step guidance to user
• Error Handling: Handle cases where no ports are found or detection fails
• Progress Feedback: Show current status during detection process
• Results Display: Clearly show which port belongs to which device

Technical Requirements

• Node.js Native: Use Node.js serial port libraries (no Python dependencies)
• TypeScript: Fully typed implementation following our conventions
• CLI Tool: Executable via npx lerobot find-port (matching Python version)
• snake_case: File naming follows lerobot conventions

Expected User Flow

$ npx lerobot find-port

Finding all available ports for the MotorsBus.
Ports before disconnecting: ['COM3', 'COM4']
Remove the USB cable from your MotorsBus and press Enter when done.

The port of this MotorsBus is 'COM3'
Reconnect the USB cable.

For multiple arms, run separately:

# First arm
$ npx lerobot find-port
# Follow prompts...

# Second arm
$ npx lerobot find-port
# Follow prompts...

Implementation Details

File Structure

src/lerobot/
└── find_port.ts                   # Direct port of Python script

src/cli/
└── index.ts                       # Main CLI entry point with find-port command

Key Dependencies

• serialport: For cross-platform serial port detection and management
• readline: Node.js built-in for simple input() equivalent

Core Functions to Implement

// find_port.ts (matching Python naming)
async function findAvailablePorts(): Promise<string[]>;
async function findPort(): Promise<void>; // Main interactive function

Technical Considerations

Cross-Platform Serial Ports

• Windows: COM ports (COM1, COM2, etc.)
• macOS: /dev/cu._ or /dev/tty._
• Linux: /dev/ttyUSB*, /dev/ttyACM*

Error Scenarios to Handle

• No serial ports detected
• Multiple ports disconnected simultaneously
• Port permissions issues
• User cancels detection process
• Same port reconnected to different device

Performance & UX

• Fast port scanning (< 1 second)
• Clear progress indicators
• Timeout handling for user input
• Graceful interrupt handling (Ctrl+C)

Definition of Done

• Functional: Successfully identifies robot arm ports on Windows/macOS/Linux
• Tested: Unit tests for core logic, integration tests with mock serial ports
• Documented: README section explaining usage
• CLI Ready: Installable and runnable as CLI tool
• Type Safe: Full TypeScript coverage with strict mode
• Follows Conventions: snake_case files, proper architecture