ROBOT_ARCHITECTURE.md

# Robot Control Architecture v2.0 - Master/Slave Pattern

This document describes the revolutionary new **Master-Slave Architecture** that enables sophisticated robot control with clear separation between command sources (Masters) and execution targets (Slaves).

## 🏗️ Architecture Overview

The new architecture follows a **Master-Slave Pattern** with complete separation of concerns:

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   UI Panel      │    │  Robot Manager   │    │    Masters      │
│                 │◄──►│                  │◄──►│                 │
│ • Manual Control│    │ • Master/Slave   │    │ • Remote Server │
│ • Monitoring    │    │ • Command Router │    │ • Mock Sequence │
│ (disabled if    │    │ • State Sync     │    │ • Script Player │
│  master active) │    └──────────────────┘    └─────────────────┘
└─────────────────┘             │
                                ▼
                       ┌──────────────────┐    ┌─────────────────┐
                       │   Robot Model    │◄──►│     Slaves      │
                       │                  │    │                 │
                       │ • URDF State     │    │ • USB Robots    │
                       │ • Joint States   │    │ • Mock Hardware │
                       │ • Command Queue  │    │ • Simulations   │
                       └──────────────────┘    └─────────────────┘
```

## 🎯 Key Concepts

### Masters (Command Sources)
- **Purpose**: Generate commands and control sequences
- **Examples**: Remote servers, predefined sequences, scripts
- **Limitation**: Only 1 master per robot (exclusive control)
- **Effect**: When active, disables manual panel control

### Slaves (Execution Targets)  
- **Purpose**: Execute commands on physical/virtual robots
- **Examples**: USB robots, mock robots, simulations
- **Limitation**: Multiple slaves per robot (parallel execution)
- **Effect**: All connected slaves execute the same commands

### Control Flow
1. **No Master**: Manual panel control → All slaves
2. **With Master**: Master commands → All slaves (panel disabled)
3. **Bidirectional**: Slaves provide real-time feedback

## 📁 File Structure

```
src/lib/
├── robot/
│   ├── Robot.svelte.ts              # Master-slave robot management
│   ├── RobotManager.svelte.ts       # Global orchestration
│   └── drivers/
│       ├── masters/
│       │   ├── MockSequenceMaster.ts    # Demo sequences
│       │   ├── RemoteServerMaster.ts    # HTTP/WebSocket commands
│       │   └── ScriptPlayerMaster.ts    # Script execution
│       └── slaves/
│           ├── MockSlave.ts             # Development/testing
│           ├── USBSlave.ts              # Physical USB robots
│           └── SimulationSlave.ts       # Physics simulation
├── types/
│   └── robotDriver.ts               # Master/Slave interfaces
└── components/
    ├── scene/
    │   └── Robot.svelte             # 3D visualization
    └── panel/
        └── RobotControlPanel.svelte # Master/Slave connection UI
```

## 🔧 Core Components

### RobotManager
**Central orchestrator with master-slave management**

```typescript
import { robotManager } from '$lib/robot/RobotManager.svelte';

// Create robot
const robot = await robotManager.createRobot('my-robot', urdfConfig);

// Connect demo sequence master (disables manual control)
await robotManager.connectDemoSequences('my-robot', true);

// Connect mock slave (executes commands)  
await robotManager.connectMockSlave('my-robot', 50);

// Connect USB slave (real hardware)
await robotManager.connectUSBSlave('my-robot');

// Disconnect master (restores manual control)
await robotManager.disconnectMaster('my-robot');
```

### Robot Class
**Individual robot with master-slave coordination**

```typescript
// Master management
await robot.setMaster(sequenceMaster);
await robot.removeMaster();

// Slave management
await robot.addSlave(usbSlave);
await robot.addSlave(mockSlave);
await robot.removeSlave(slaveId);

// Control state
robot.controlState.hasActiveMaster    // true when master connected
robot.controlState.manualControlEnabled  // false when master active
robot.controlState.lastCommandSource     // "master" | "manual" | "none"

// Manual control (only when no master)
await robot.updateJointValue('joint_1', 45);
```

## 🔌 Master Drivers

### Mock Sequence Master
**Predefined movement sequences for testing**

```typescript
const config: MasterDriverConfig = {
  type: "mock-sequence",
  sequences: DEMO_SEQUENCES,  // Wave, Scan, Pick-Place patterns
  autoStart: true,
  loopMode: true
};

await robotManager.connectMaster('robot-1', config);
```

**Demo Sequences:**
- **Wave Pattern**: Greeting gesture with wrist roll
- **Scanning Pattern**: Horizontal sweep with pitch variation  
- **Pick and Place**: Complete manipulation sequence

### Remote Server Master *(Planned)*
**HTTP/WebSocket command reception**

```typescript
const config: MasterDriverConfig = {
  type: "remote-server",
  url: "ws://robot-server:8080/ws",
  apiKey: "your-api-key",
  pollInterval: 100
};
```

### Script Player Master *(Planned)*
**JavaScript/Python script execution**

```typescript
const config: MasterDriverConfig = {
  type: "script-player", 
  scriptUrl: "/scripts/robot-dance.js",
  variables: { speed: 1.5, amplitude: 45 }
};
```

## 🤖 Slave Drivers

### Mock Slave
**Perfect simulation for development**

```typescript
const config: SlaveDriverConfig = {
  type: "mock-slave",
  simulateLatency: 50,      // ms response delay
  simulateErrors: false,    // random failures
  responseDelay: 20         // command execution time
};

await robotManager.connectSlave('robot-1', config);
```

**Features:**
- ✅ Perfect command execution (real = virtual)
- ✅ Configurable latency and errors
- ✅ Real-time state feedback
- ✅ Instant connection

### USB Slave *(Planned)*
**Physical robot via feetech.js**

```typescript
const config: SlaveDriverConfig = {
  type: "usb-slave",
  port: "/dev/ttyUSB0",     // auto-detect if undefined
  baudRate: 115200
};
```

**Features:**
- ✅ Direct hardware control
- ✅ Position/speed commands
- ✅ Real servo feedback  
- ✅ Calibration support

### Simulation Slave *(Planned)*
**Physics-based simulation**

```typescript
const config: SlaveDriverConfig = {
  type: "simulation-slave",
  physics: true,
  collisionDetection: true
};
```

## 🔄 Command Flow Architecture

### Command Structure
```typescript
interface RobotCommand {
  timestamp: number;
  joints: {
    name: string;
    value: number;      // degrees for revolute, speed for continuous
    speed?: number;     // optional movement speed
  }[];
  duration?: number;    // optional execution time
  metadata?: Record<string, unknown>;
}
```

### Command Sources

#### Master Commands
```typescript
// Continuous sequence from master
master.onCommand((commands) => {
  // Route to all connected slaves
  robot.slaves.forEach(slave => slave.executeCommands(commands));
});
```

#### Manual Commands  
```typescript
// Only when no master active
if (robot.manualControlEnabled) {
  await robot.updateJointValue('shoulder', 45);
}
```

### Command Execution
```typescript
// All slaves execute in parallel
const executePromises = robot.connectedSlaves.map(slave => 
  slave.executeCommand(command)
);
await Promise.allSettled(executePromises);
```

## 🎮 Usage Examples

### Basic Master-Slave Setup
```typescript
// 1. Create robot
const robot = await robotManager.createRobot('arm-1', urdfConfig);

// 2. Add slaves for execution
await robotManager.connectMockSlave('arm-1');      // Development
await robotManager.connectUSBSlave('arm-1');       // Real hardware

// 3. Connect master for control
await robotManager.connectDemoSequences('arm-1');  // Automated sequences

// 4. Monitor status
const status = robotManager.getRobotStatus('arm-1');
console.log(`Master: ${status.masterName}, Slaves: ${status.connectedSlaves}`);
```

### Multiple Robots with Different Masters
```typescript
// Robot 1: Demo sequences
await robotManager.createRobot('demo-1', armConfig);
await robotManager.connectDemoSequences('demo-1', true);
await robotManager.connectMockSlave('demo-1');

// Robot 2: Remote control
await robotManager.createRobot('remote-1', armConfig);
await robotManager.connectMaster('remote-1', remoteServerConfig);
await robotManager.connectUSBSlave('remote-1');

// Robot 3: Manual control only
await robotManager.createRobot('manual-1', armConfig);
await robotManager.connectMockSlave('manual-1');
// No master = manual control enabled
```

### Master Switching
```typescript
// Switch from manual to automated control
await robotManager.connectDemoSequences('robot-1');
// Panel inputs now disabled, sequences control robot

// Switch back to manual control  
await robotManager.disconnectMaster('robot-1');
// Panel inputs re-enabled, manual control restored
```

## 🚀 Benefits

### 1. **Clear Control Hierarchy**
- Masters provide commands exclusively
- Slaves execute commands in parallel
- No ambiguity about command source

### 2. **Flexible Command Sources**
- Remote servers for network control
- Predefined sequences for automation
- Manual control for testing/setup
- Easy to add new master types

### 3. **Multiple Execution Targets**
- Physical robots via USB
- Simulated robots for testing
- Mock robots for development
- All execute same commands simultaneously

### 4. **Automatic Panel Management**
- Panel disabled when master active
- Panel re-enabled when master disconnected
- Clear visual feedback about control state

### 5. **Safe Operation**
- Masters cannot conflict (only 1 allowed)
- Graceful disconnection with rest positioning
- Error isolation between slaves

### 6. **Development Workflow**
- Test with mock slaves during development
- Add real slaves for deployment
- Switch masters for different scenarios

## 🔮 Implementation Roadmap

### Phase 1: Core Architecture ✅
- [x] Master-Slave interfaces
- [x] Robot class with dual management
- [x] RobotManager orchestration
- [x] MockSequenceMaster with demo patterns
- [x] MockSlave for testing

### Phase 2: Real Hardware
- [ ] USBSlave implementation (feetech.js integration)
- [ ] Calibration system for hardware slaves
- [ ] Error handling and recovery

### Phase 3: Remote Control
- [ ] RemoteServerMaster (HTTP/WebSocket)
- [ ] Authentication and security
- [ ] Real-time command streaming

### Phase 4: Advanced Features
- [ ] ScriptPlayerMaster (JS/Python execution)
- [ ] SimulationSlave (physics integration)
- [ ] Command recording and playback
- [ ] Multi-robot coordination

## 🛡️ Safety Features

### Master Safety
- Only 1 master per robot prevents conflicts
- Master disconnect automatically restores manual control
- Command validation before execution

### Slave Safety  
- Rest positioning before disconnect
- Smooth movement transitions
- Individual slave error isolation
- Calibration offset compensation

### System Safety
- Graceful degradation on slave failures
- Command queuing prevents overwhelming
- Real-time state monitoring
- Emergency stop capabilities *(planned)*

## 🔧 Migration from v1.0

The new architecture is **completely different** from the old driver pattern:

### Old Architecture (v1.0)
```typescript
// Single driver per robot
const driver = new USBRobotDriver(config);
await robot.setDriver(driver);
await robot.updateJointValue('joint', 45);
```

### New Architecture (v2.0)
```typescript
// Separate masters and slaves
await robotManager.connectMaster(robotId, masterConfig);   // Command source
await robotManager.connectSlave(robotId, slaveConfig);     // Execution target

// Manual control only when no master
if (robot.manualControlEnabled) {
  await robot.updateJointValue('joint', 45);
}
```

### Key Changes
1. **Drivers → Masters + Slaves**: Split command/execution concerns
2. **Single Connection → Multiple**: 1 master + N slaves per robot  
3. **Always Manual → Conditional**: Panel disabled when master active
4. **Direct Control → Command Routing**: Masters route to all slaves

The new architecture provides **dramatically more flexibility** while maintaining complete backward compatibility for URDF visualization and joint control.

---

*This architecture enables sophisticated robot control scenarios from simple manual operation to complex multi-robot coordination, all with a clean, extensible design.*