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

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

// 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

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

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

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

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

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

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

🔄 Command Flow Architecture

Command Structure

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

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

Manual Commands

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

Command Execution

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

🎮 Usage Examples

Basic Master-Slave Setup

// 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

// 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

// 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 ✅

• Master-Slave interfaces
• Robot class with dual management
• RobotManager orchestration
• MockSequenceMaster with demo patterns
• 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)

// Single driver per robot
const driver = new USBRobotDriver(config);
await robot.setDriver(driver);
await robot.updateJointValue('joint', 45);

New Architecture (v2.0)

// 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.