SPEC.md

# Robot USB Connection System - Summary

## Core Components

### USBProducer (Output)
**Purpose**: Sends software commands to control physical robot hardware
- Receives normalized joint commands from software
- Converts normalized values to raw servo positions
- Sends position commands to physical servos
- Locks servos for precise software control

### USBConsumer (Input) 
**Purpose**: Reads physical robot movements and translates to software commands
- Continuously monitors physical servo positions
- Converts raw servo values to normalized percentages
- Detects movement changes and broadcasts updates
- Keeps servos unlocked for manual manipulation

## Key Features

### Calibration System (`USBCalibrationPanel.svelte`)
- **Requirement**: All USB connections must be calibrated before use
- **Process**: Records min/max physical range for each servo by manual movement
- **Result**: Establishes mapping between raw servo values (0-4095) and normalized values

### Normalized Communication Protocol
- **Standard Joints**: -100% to +100% range (bipolar)
- **Gripper/Jaw**: 0% to +100% range (unipolar) 
- **Benefits**: Consistent software interface across different robots
- **Conversion**: Automatic normalization/denormalization based on calibration data

### Multi-Port Support
- **Capability**: Multiple independent USB connections simultaneously
- **Independence**: Each connection has its own calibration and configuration
- **Use Case**: Control multiple robots or multiple connections to same robot

### Batch Operations
- **Sync Read**: Read multiple servo positions simultaneously
- **Sync Write**: Send commands to multiple servos in batched operations
- **Performance**: Reduces USB communication overhead and latency

## Key Constraints

### Connection Exclusivity
- **Input**: Only one consumer (input source) active per robot at a time
- **Output**: Multiple producers (output destinations) can be active simultaneously
- **Rationale**: Prevents conflicting input commands while allowing broadcast to multiple destinations

### Servo Locking Strategy
- **Consumer Mode**: Servos unlocked → manual movement possible + position reading
- **Producer Mode**: Servos locked → software control only, no manual movement
- **Safety**: Prevents mechanical conflicts between manual and software control

### Calibration Dependency
- **Mandatory**: USB connections cannot establish without valid calibration
- **Per-Connection**: Each USB port requires independent calibration
- **Safety**: Prevents commanding impossible positions or damaging hardware

## Additional System Requirements (from SPEC.md analysis)

### Connection Management
- **Auto-Detection**: System should detect available USB ports automatically
- **Status Monitoring**: Real-time connection health and error reporting
- **Graceful Disconnection**: Safe servo unlocking on disconnect/error

### Error Handling & Recovery
- **Port Conflicts**: Queue management to prevent "Port is busy" errors
- **Retry Logic**: Automatic retry with backoff for failed servo commands
- **Connection Recovery**: Automatic reconnection attempts after USB disconnect

### User Interface Integration
- **Modal Management**: Unified connection setup through calibration panels
- **Status Display**: Visual indicators for connection state and calibration status
- **Manual Control**: Direct joint manipulation when no input consumer active

### Performance Optimizations
- **Polling Rates**: Configurable update frequencies for different use cases
- **Change Detection**: Only broadcast updates when values actually change
- **Queueing**: Serial command processing to prevent USB port conflicts

## System Architecture Concepts

### Bidirectional Data Flow
```
Physical Robot ←→ USB Hardware ←→ Calibration Layer ←→ Normalized Interface ←→ Software
```

### Connection Patterns
- **Teaching Mode**: USB Consumer only (read robot movements)
- **Control Mode**: USB Producer only (software controls robot)  
- **Bidirectional**: Both consumer and producer (full interaction)
- **Broadcasting**: Multiple producers (send to hardware + remote systems)

### Value Transformation Pipeline
```
Raw Servo (0-4095) ←→ Calibrated Range ←→ Normalized (-100/+100) ←→ Software Commands
```

This system provides a robust, safe, and flexible interface for robot hardware control while maintaining consistency across different robot configurations and use cases.