Spaces:
Running
Running
| # 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. |