Comprehensive architecture diagrams for the complete system, from XR interactions to physical robot control.
- High-Level System Architecture
- XR Interaction Layer
- Unity Integration Architecture
- Python Backend Architecture
- Keyframe Animation Pipeline
- Voice AI Architecture
- Communication Protocols
- Data Flow Diagrams
Complete end-to-end system from user interaction to robot execution:
┌─────────────────────────────────────────────────────────────────────────┐
│ User Interaction Layer │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Samsung GalaxyXR Headset │ │
│ │ • Hand Tracking (OpenXR) │ │
│ │ • Eye Tracking (Gaze) │ │
│ │ • Voice Input (Microphone) │ │
│ │ • UI Interactions (Passthrough UI) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Unity XR Application Layer │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ XR Event Handlers │ │
│ │ • Hand tracking events │ │
│ │ • Gaze interaction events │ │
│ │ • UI button events │ │
│ │ • Voice input events │ │
│ └───────────────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────▼───────────────────────────────────────────┐ │
│ │ Unity C# Integration Components │ │
│ │ • BoosterRobotService (HTTP client) │ │
│ │ • BoosterRobotController (MonoBehaviour) │ │
│ │ • ExampleRobotXRIntegration (Event handlers) │ │
│ │ • GeminiLiveAudioClient (WebSocket voice) │ │
│ └───────────────────────┬───────────────────────────────────────────┘ │
└──────────────────────────┼───────────────────────────────────────────────┘
│ HTTP / WebSocket
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Python Backend Services Layer │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ FastAPI Server (Port 5000) │ │
│ │ • /generate_from_prompt │ │
│ │ • /execute_sequence │ │
│ │ • /stock_animations │ │
│ │ • /health, /status, /get_state │ │
│ └───────────────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────▼───────────────────────────────────────────┐ │
│ │ LLM Provider Abstraction Layer │ │
│ │ • GeminiProvider (Gemini 2.0 Flash) │ │
│ │ • OpenAIProvider (GPT-4) │ │
│ │ • AnthropicProvider (Claude) │ │
│ │ • Structured output parsing │ │
│ └───────────────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────▼───────────────────────────────────────────┐ │
│ │ Keyframe Processing Layer │ │
│ │ • PostureGenerator (Workspace validation) │ │
│ │ • KeyframeController (Execution management) │ │
│ │ • StockAnimationsService (Pre-defined animations) │ │
│ └───────────────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────▼───────────────────────────────────────────┐ │
│ │ Booster Robotics SDK (Python API) │ │
│ │ • B1LocoClient (High-level API) │ │
│ │ • End-effector control (MoveHandEndEffectorV2) │ │
│ │ • Automatic IK computation │ │
│ │ • Mode management (Prepare, Locomotion, etc.) │ │
│ └───────────────────────┬───────────────────────────────────────────┘ │
└──────────────────────────┼───────────────────────────────────────────────┘
│ DDS (FastDDS) - Real-time pub/sub
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Booster K1 Robot (Physical) │
│ • 22 Degrees of Freedom (DoF) │
│ • 4-DOF arms (Left/Right: shoulder pitch/roll, elbow, wrist) │
│ • 2-DOF head (pitch, yaw) │
│ • 12-DOF legs (locomotion system) │
└─────────────────────────────────────────────────────────────────────────┘
Detailed architecture of XR input processing:
┌─────────────────────────────────────────────────────────────────┐
│ Samsung GalaxyXR (Android XR) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ OpenXR Runtime │ │
│ │ • Hand Tracking API │ │
│ │ • Eye Tracking API │ │
│ │ • Face Tracking API │ │
│ │ • Passthrough API │ │
│ │ • Scene Mesh API │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ Unity XR Interaction Toolkit │ │
│ │ • XR Hand Interactor │ │
│ │ • XR Ray Interactor (Gaze) │ │
│ │ • XR UI Interactor │ │
│ │ • Event System │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ Custom XR Integration Scripts │ │
│ │ • ExampleRobotXRIntegration.cs │ │
│ │ - OnPinchDetected() │ │
│ │ - OnGazeSelect() │ │
│ │ - OnUIButtonPressed() │ │
│ │ • Hand tracking → Robot commands │ │
│ │ • Gaze → Robot selection │ │
│ │ • UI → Robot actions │ │
│ └──────────────┬───────────────────────────────────────────┘ │
└─────────────────┼───────────────────────────────────────────────┘
│
▼
BoosterRobotController
(Executes robot commands)
Unity C# layer connecting XR to backend services:
┌─────────────────────────────────────────────────────────────────┐
│ Unity Scene Components │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ ExampleRobotXRIntegration (MonoBehaviour) │ │
│ │ • Listens to XR events │ │
│ │ • Handles hand tracking, gaze, UI │ │
│ │ • Invokes robot commands │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ BoosterRobotController (MonoBehaviour) │ │
│ │ • Inspector-configurable server URL │ │
│ │ • State management │ │
│ │ • Command execution methods │ │
│ │ - GenerateFromPrompt() │ │
│ │ - ExecuteSequence() │ │
│ │ - PlayStockAnimation() │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ BoosterRobotService (Static Service) │ │
│ │ • HTTP request handling │ │
│ │ • JSON serialization/deserialization │ │
│ │ • Async/await support │ │
│ │ • Error handling │ │
│ │ • Methods: │ │
│ │ - GenerateFromPromptAsync() │ │
│ │ - ExecuteSequenceAsync() │ │
│ │ - GetStockAnimationsAsync() │ │
│ └──────────────┬───────────────────────────────────────────┘ │
└─────────────────┼───────────────────────────────────────────────┘
│ HTTP REST API
▼
FastAPI Server (Python)
Detailed architecture of the Python backend services:
┌─────────────────────────────────────────────────────────────────┐
│ FastAPI Server (Port 5000) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ API Endpoints (api_server.py) │ │
│ │ • POST /generate_from_prompt │ │
│ │ • POST /generate_keyframes │ │
│ │ • POST /execute_sequence │ │
│ │ • GET /get_state │ │
│ │ • POST /stop │ │
│ │ • GET /status │ │
│ │ • GET /health │ │
│ │ • GET /k1_urdf │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ Request Processing Layer │ │
│ │ • Pydantic models for validation │ │
│ │ • Error handling and HTTP exceptions │ │
│ │ • CORS middleware │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ LLM Provider Layer (llm_providers.py) │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ GeminiProvider │ │ │
│ │ │ • google-generativeai library │ │ │
│ │ │ • Structured outputs (JSON schema) │ │ │
│ │ │ • Gemini 2.0 Flash model │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ OpenAIProvider │ │ │
│ │ │ • openai library │ │ │
│ │ │ • GPT-4 model │ │ │
│ │ │ • Function calling for structured outputs │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ AnthropicProvider │ │ │
│ │ │ • anthropic library │ │ │
│ │ │ • Claude model │ │ │
│ │ │ • Structured outputs │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ Posture Generator (posture_generator.py) │ │
│ │ • Parse LLM JSON response │ │
│ │ • Validate workspace bounds │ │
│ │ • Clamp out-of-bounds poses │ │
│ │ • Generate smooth keyframe sequences │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ Keyframe Controller (keyframe_controller.py) │ │
│ │ • Execute sequences on robot │ │
│ │ • Smooth interpolation between keyframes │ │
│ │ • Timing and duration management │ │
│ │ • State tracking and progress monitoring │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ Booster Robotics SDK (Python API) │ │
│ │ • B1LocoClient (High-level API) │ │
│ │ • MoveHandEndEffectorV2() (End-effector control) │ │
│ │ • Automatic IK computation │ │
│ │ • DDS communication layer (C++ via pybind11) │ │
│ └──────────────┬───────────────────────────────────────────┘ │
└─────────────────┼───────────────────────────────────────────────┘
│ DDS (FastDDS)
▼
Booster K1 Robot
Complete flow from natural language to robot execution:
┌─────────────────────────────────────────────────────────────────┐
│ User Input │
│ • Natural language prompt: "Wave your right hand" │
│ • Voice command via Gemini Live │
│ • UI button selection │
│ • XR gesture │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Unity → FastAPI Request │
│ POST /generate_from_prompt │
│ { │
│ "prompt": "Wave your right hand", │
│ "provider": "gemini", │
│ "max_keyframes": 8 │
│ } │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ LLM Provider Processing │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 1. Build prompt with robot constraints │ │
│ │ 2. Send to LLM (Gemini/OpenAI/Claude) │ │
│ │ 3. Receive structured JSON response │ │
│ │ 4. Parse keyframe data │ │
│ └───────────────────────────┬───────────────────────────────┘ │
└──────────────────────────────┼───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Posture Generator Processing │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 1. Parse LLM JSON → KeyframeSequence │ │
│ │ 2. Validate workspace bounds: │ │
│ │ - X: 0.15-0.5m (forward/backward) │ │
│ │ - Y: ±0.4m (left/right) │ │
│ │ - Z: -0.1-0.5m (up/down) │ │
│ │ 3. Clamp out-of-bounds poses │ │
│ │ 4. Generate smooth interpolation │ │
│ └───────────────────────────┬───────────────────────────────┘ │
└──────────────────────────────┼───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Keyframe Sequence (Validated) │
│ [ │
│ { │
│ "right_hand": { │
│ "position": [0.3, -0.2, 0.25], │
│ "orientation": [0, 0.5, 0] │
│ }, │
│ "duration_ms": 1000 │
│ }, │
│ ... (8 keyframes total) │
│ ] │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Optional: React Frontend Preview │
│ • 3D visualization of keyframe sequence │
│ • Interactive playback controls │
│ • Workspace bounds visualization │
│ • Keyframe trajectory display │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Execution Request │
│ POST /execute_sequence │
│ { │
│ "sequence": { ... }, │
│ "blocking": false │
│ } │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Keyframe Controller │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 1. Convert keyframes to SDK calls │ │
│ │ 2. Execute via B1LocoClient.MoveHandEndEffectorV2() │ │
│ │ 3. SDK handles automatic IK │ │
│ │ 4. Smooth interpolation between keyframes │ │
│ │ 5. Real-time progress tracking │ │
│ └───────────────────────────┬───────────────────────────────┘ │
└──────────────────────────────┼───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Booster SDK → Robot │
│ • DDS communication (FastDDS) │
│ • Real-time pub/sub │
│ • Low-latency control │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
Robot Executes Animation
Two separate voice AI implementations:
┌─────────────────────────────────────────────────────────────────┐
│ GalaxyXR Headset │
│ • Microphone captures voice │
│ • Unity processes audio │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ GeminiLiveAudioClient.cs (Unity) │
│ • WebSocket client │
│ • Audio capture and streaming │
│ • Real-time bidirectional communication │
└───────────────────────────┬─────────────────────────────────────┘
│ WebSocket
▼
┌─────────────────────────────────────────────────────────────────┐
│ Node.js Proxy Server │
│ • gemini-live-proxy-server.js │
│ • Unity ↔ Gemini Live API bridge │
│ • Error handling and reconnection │
└───────────────────────────┬─────────────────────────────────────┘
│ WSS (WebSocket Secure)
▼
┌─────────────────────────────────────────────────────────────────┐
│ Google Gemini Live API │
│ • Real-time voice AI │
│ • Bidirectional audio streaming │
│ • Text responses │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Response Processing (Unity) │
│ • Parse text response │
│ • Extract robot commands │
│ • Call BoosterRobotController methods │
│ • Execute robot animations │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ GalaxyXR Headset │
│ • Microphone captures voice │
│ • Unity processes audio │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ VoiceConciergeController.cs (Unity) │
│ • Main orchestrator │
│ • State management │
│ • UI coordination │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────┴───────────────────┐
│ │
▼ ▼
┌───────────────────────┐ ┌──────────────────────────────┐
│ GeminiLiveClient.cs │ │ MoodDetector.cs │
│ • WebSocket client │ │ • Emotion detection │
│ • Audio streaming │ │ • Sentiment analysis │
└───────────┬───────────┘ └──────────────┬───────────────┘
│ │
│ WebSocket │
▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ Google Gemini Live API │
│ • Real-time voice AI │
│ • Bidirectional audio streaming │
│ • Text and audio responses │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Response Processing (Unity) │
│ • Audio playback │
│ • Transcript display │
│ • Mood visualization │
│ • Spatial UI updates │
└─────────────────────────────────────────────────────────────────┘
Detailed protocol stack:
┌─────────────────────────────────────────────────────────────────┐
│ Application Layer │
│ • Unity C# scripts │
│ • Python FastAPI server │
│ • React frontend │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ HTTP/REST │ │ WebSocket │ │ DDS (FastDDS)│
│ Protocol │ │ Protocol │ │ Protocol │
│ │ │ │ │ │
│ • JSON format │ │ • Binary audio│ │ • Real-time │
│ • RESTful API │ │ • JSON text │ │ pub/sub │
│ • Port 5000 │ │ • Port 8080 │ │ • Low latency │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ TCP/IP │ │ TCP/IP │ │ UDP/IP │
│ (Reliable) │ │ (WebSocket) │ │ (FastDDS) │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
└───────────────────┼───────────────────┘
│
▼
Network Layer (Ethernet/WiFi)
Protocol Details:
-
HTTP/REST (Unity ↔ Python Server)
- Protocol: HTTP/1.1 over TCP
- Format: JSON
- Port: 5000
- Use case: Keyframe generation, execution commands, status queries
-
WebSocket (Unity ↔ Gemini Live)
- Protocol: WebSocket (WSS for production)
- Format: Binary audio + JSON text
- Port: 8080 (proxy server)
- Use case: Real-time bidirectional voice streaming
-
DDS (FastDDS) (Python SDK ↔ Robot)
- Protocol: DDS (Data Distribution Service)
- Transport: UDP/IP
- Use case: Real-time robot control, low-latency commands
- Features: Pub/sub, QoS policies, reliable delivery
User Input (Text/Voice)
│
▼
┌─────────────────────────────────────┐
│ Unity: BoosterRobotService │
│ GenerateFromPromptAsync() │
└──────────────┬──────────────────────┘
│ HTTP POST
▼
┌─────────────────────────────────────┐
│ FastAPI: /generate_from_prompt │
│ • Receive prompt │
│ • Select LLM provider │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ LLM Provider │
│ • Build prompt with constraints │
│ • Call LLM API │
│ • Receive structured JSON │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ PostureGenerator │
│ • Parse JSON → KeyframeSequence │
│ • Validate workspace bounds │
│ • Clamp invalid poses │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Response to Unity │
│ • Validated keyframe sequence │
│ • Metadata (count, duration) │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Unity: ExecuteSequenceAsync() │
└──────────────┬──────────────────────┘
│ HTTP POST
▼
┌─────────────────────────────────────┐
│ FastAPI: /execute_sequence │
│ • Receive sequence │
│ • Queue for execution │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ KeyframeController │
│ • Convert to SDK calls │
│ • Execute with interpolation │
└──────────────┬──────────────────────┘
│ SDK API calls
▼
┌─────────────────────────────────────┐
│ Booster SDK (Python) │
│ • MoveHandEndEffectorV2() │
│ • Automatic IK │
└──────────────┬──────────────────────┘
│ DDS
▼
Robot Executes
User Voice: "Wave your arms"
│
▼
┌─────────────────────────────────────┐
│ GeminiLiveAudioClient (Unity) │
│ • Capture audio │
│ • Stream to WebSocket │
└──────────────┬──────────────────────┘
│ WebSocket
▼
┌─────────────────────────────────────┐
│ Node.js Proxy Server │
│ • Forward to Gemini Live API │
└──────────────┬──────────────────────┘
│ WSS
▼
┌─────────────────────────────────────┐
│ Google Gemini Live API │
│ • Process voice │
│ • Generate text response │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Response: "I'll wave the arms" │
│ (Text + Audio) │
└──────────────┬──────────────────────┘
│ WebSocket
▼
┌─────────────────────────────────────┐
│ Unity: Parse Response │
│ • Extract intent: "wave arms" │
│ • Call GenerateFromPromptAsync() │
└──────────────┬──────────────────────┘
│
▼
(Continues as Natural Language flow)
User Pinches Hand in XR
│
▼
┌─────────────────────────────────────┐
│ OpenXR Hand Tracking │
│ • Detect pinch gesture │
│ • Generate event │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ ExampleRobotXRIntegration │
│ • OnPinchDetected() handler │
│ • Map to robot command │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ BoosterRobotController │
│ • MoveForward() (example) │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ BoosterRobotService │
│ • Send HTTP request │
└──────────────┬──────────────────────┘
│ HTTP POST
▼
┌─────────────────────────────────────┐
│ FastAPI Server │
│ • Process command │
│ • Execute via SDK │
└──────────────┬──────────────────────┘
│
▼
Robot Executes Command
| Component | Unity | FastAPI | LLM | SDK | Robot | Frontend |
|---|---|---|---|---|---|---|
| Unity | - | HTTP | - | - | - | - |
| FastAPI | HTTP | - | HTTPS | Python API | - | HTTP |
| LLM | - | HTTPS | - | - | - | - |
| SDK | - | Python API | - | - | DDS | - |
| Robot | - | - | - | DDS | - | - |
| Frontend | - | HTTP | - | - | - | - |
┌─────────────────────────────────────────────────────────────────┐
│ Development Machine │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Unity Editor │ │
│ │ • Running on localhost │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ Python FastAPI Server │ │
│ │ • localhost:5000 │ │
│ │ • Visualization-only mode (no robot) │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ React Frontend (Vite) │ │
│ │ • localhost:3000 │ │
│ │ • 3D visualization │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ GalaxyXR Headset │
│ • Unity app running │
│ • Connects to laptop IP │
└───────────────────────────┬─────────────────────────────────────┘
│ WiFi Network
▼
┌─────────────────────────────────────────────────────────────────┐
│ Development Laptop │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Python FastAPI Server │ │
│ │ • 192.168.1.100:5000 (laptop IP) │ │
│ │ • Connected to robot via network │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ Node.js Proxy Server │ │
│ │ • 192.168.1.100:8080 │ │
│ │ • Gemini Live API proxy │ │
│ └───────────────────────────────────────────────────────────┘ │
└───────────────────────────┬─────────────────────────────────────┘
│ Network (DDS)
▼
┌─────────────────────────────────────────────────────────────────┐
│ Booster K1 Robot │
│ • Robot IP: 192.168.1.50 (example) │
│ • DDS communication │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ GalaxyXR Headset │
│ • Unity app running │
└───────────────────────────┬─────────────────────────────────────┘
│ Network
▼
┌─────────────────────────────────────────────────────────────────┐
│ Booster K1 Robot │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Python FastAPI Server (on robot) │ │
│ │ • Robot IP: 192.168.1.50:5000 │ │
│ │ • Direct SDK access │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ Booster SDK (Python) │ │
│ │ • Local DDS communication │ │
│ └──────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────────────────────────────┐ │
│ │ Robot Hardware │ │
│ │ • Motors, sensors, actuators │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────┐
│ Idle │
└──────┬──────┘
│ execute_sequence()
▼
┌─────────────┐
│ Executing │──┐
└──────┬──────┘ │
│ │ (loop through keyframes)
│ │
│ │
│ stop() │
│ │
└─────────┘
│
│ (sequence complete)
▼
┌─────────────┐
│ Completed │
└─────────────┘
┌─────────────┐
│ Disconnected│
└──────┬──────┘
│ connect()
▼
┌─────────────┐
│ Connecting │
└──────┬──────┘
│
│ (success)
▼
┌─────────────┐
│ Connected │
└──────┬──────┘
│
│ (error/timeout)
▼
┌─────────────┐
│ Error │
└─────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Error Sources │
│ • Network failures (HTTP, WebSocket, DDS) │
│ • LLM API errors (rate limits, invalid responses) │
│ • Robot connection failures │
│ • Invalid keyframes (out of bounds) │
│ • SDK errors │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Error Handling Layers │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Unity Layer │ │
│ │ • Try-catch blocks │ │
│ │ • HTTP error handling │ │
│ │ • User-friendly error messages │ │
│ └───────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────▼───────────────────────────────┐ │
│ │ FastAPI Layer │ │
│ │ • HTTPException for API errors │ │
│ │ • Validation errors (Pydantic) │ │
│ │ • LLM provider error handling │ │
│ └───────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────▼───────────────────────────────┐ │
│ │ SDK Layer │ │
│ │ • Connection retry logic │ │
│ │ • DDS error handling │ │
│ │ • Robot state validation │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
User Action → Robot Response
│
├─ XR Input Processing: ~10-20ms
├─ Unity Event Handling: ~5-10ms
├─ HTTP Request (local): ~5-15ms
├─ FastAPI Processing: ~10-50ms
├─ LLM API Call (if needed): ~500-2000ms
├─ Keyframe Generation: ~50-100ms
├─ SDK Processing: ~10-20ms
├─ DDS Communication: ~5-10ms
└─ Robot Execution: ~10-50ms
───────────────────────────────────────
Total (with LLM): ~600-2200ms
Total (pre-generated): ~60-180ms
- Keyframe Generation: ~1-2 requests/second (LLM rate limits)
- Robot Execution: ~10-20 commands/second (SDK/DDS limits)
- Voice Streaming: Real-time bidirectional (WebSocket)
- HTTP API: ~100+ requests/second (FastAPI capability)
┌─────────────────────────────────────────────────────────────────┐
│ Security Layers │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ API Key Management │ │
│ │ • Environment variables (.env) │ │
│ │ • Never commit keys to git │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Network Security │ │
│ │ • Local network only (development) │ │
│ │ • HTTPS/WSS for production │ │
│ │ • Firewall configuration │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Robot Safety │ │
│ │ • Workspace bounds validation │ │
│ │ • Emergency stop endpoint │ │
│ │ • Command rate limiting │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
- One Unity client → One FastAPI server → One robot
- Suitable for: Development, demos, single-user scenarios
- Multiple Robots: Multiple FastAPI server instances, robot pool management
- Multiple Clients: Load balancing, session management
- Cloud Deployment: API server in cloud, robots via VPN/tunnel
- Edge Computing: Robot-local processing, reduced latency
- Booster Robotics:
docs/BOOSTER_ROBOTICS.md- Detailed robot control system - Robot Integration:
docs/ROBOT_INTEGRATION.md- Integration flows - Tech Stack:
docs/TECH_STACK.md- Technology details - Keyframe Animation:
Assets/BoosterRobotics/booster_robotics_sdk/example/high_level/keyframe_animation/docs/ARCHITECTURE.md- Detailed keyframe system architecture