Skip to content

Communication Protocols

Jump to bottom
Marc Sanchis edited this page Jun 8, 2025 · 1 revision

Communication Protocols

This section provides comprehensive documentation for all communication protocols used in the Hyperloop Control Station system.

Overview

The Control Station uses a three-layer communication architecture designed for real-time pod monitoring and control:

┌─────────────┐    Binary Protocol     ┌─────────────┐    WebSocket API    ┌─────────────┐
│   Vehicle   │ ◄─────────────────────► │   Backend   │ ◄─────────────────► │  Frontend   │
│   Systems   │   TCP/UDP + TFTP       │   Server    │      JSON/WS        │ Applications │
└─────────────┘                        └─────────────┘                     └─────────────┘

Protocol Layers

1. Vehicle ↔ Backend Communication

  • Transport: TCP (reliable), UDP (fast), TFTP (files)
  • Encoding: Binary packets with little-endian byte order
  • ADJ-Defined: Message structures defined by JSON specifications
  • Real-Time: Sub-10ms latency for critical safety messages

2. Backend ↔ Frontend Communication

  • Transport: WebSocket over HTTP
  • Encoding: JSON with topic-based routing
  • Bidirectional: Real-time updates and command sending
  • Type-Safe: Structured schemas for all message types

3. Backend Internal Architecture

  • Message Broker: Topic-based routing system
  • Component Integration: Vehicle management, data logging, WebSocket clients
  • Concurrent Processing: Go routines for real-time performance

Message Types

Data Packets

Purpose: Continuous sensor telemetry from vehicle boards

  • Frequency: 10-100 Hz per measurement
  • Content: Pressure, temperature, position, status values
  • Safety: Real-time validation against safe ranges

Protection Packets

Purpose: Safety alerts and fault notifications

  • Types: Fault (critical), Warning (attention), OK (recovery)
  • Response: Immediate propagation to operators
  • Logging: Persistent storage for analysis

Order Packets

Purpose: Commands sent from operators to vehicle

  • Types: State changes, parameter updates, emergency stops
  • Validation: Parameter checking before transmission
  • Acknowledgment: Vehicle confirmation required

File Operations

Purpose: Firmware updates and configuration management

  • Protocol: TFTP for reliable file transfers
  • Types: Firmware binaries, configuration files, logs
  • Security: Checksum validation and access control

Network Configuration

Port Assignments

  • TCP Client: 50401 (Backend → Vehicle)
  • TCP Server: 50500 (Vehicle → Backend)
  • UDP Data: 8000 (Bidirectional)
  • TFTP Files: 69 (Bidirectional)
  • WebSocket API: 8080 (Frontend → Backend)

IP Address Scheme

  • Backend: 127.0.0.9 (configurable)
  • Vehicle Boards: Per-board IPs in ADJ configuration
    • VCU: 127.0.0.6 (Vehicle Control Unit)
    • BCU: 127.0.0.7 (Brake Control Unit)
    • LCU: 127.0.0.8 (Levitation Control Unit)

Safety and Reliability

Error Handling

  • Network Failures: Automatic reconnection with backoff
  • Protocol Errors: Graceful degradation and logging
  • Data Validation: Range checking and type verification

Fault Tolerance

  • Redundant Connections: Multiple transport protocols
  • Message Queuing: Buffering during disconnections
  • State Recovery: Automatic resynchronization

Real-Time Guarantees

  • Priority Queuing: Critical messages processed first
  • Deterministic Latency: Bounded response times
  • Watchdog Timers: Connection health monitoring

Performance Characteristics

Throughput

  • Data Rate: 1000+ measurements/second
  • Concurrent Clients: 10+ frontend connections
  • Packet Processing: 500+ packets/second per board

Latency

  • Vehicle → Frontend: < 20ms typical
  • Command Response: < 50ms typical
  • Protection Alerts: < 5ms critical path

Development and Testing

Protocol Testing

  • Packet Sender: Simulation tool for development
  • Network Monitoring: Real-time traffic analysis
  • Load Testing: Performance validation under stress

Documentation Maintenance

  • Schema Validation: Automated checking of message formats
  • Version Control: Tracked changes to protocol specifications
  • Backward Compatibility: Migration support for legacy systems

Detailed Specifications

For complete technical details, see the individual protocol specifications:

This documentation is maintained alongside the codebase. For the latest specifications, refer to the docs/architecture/ directory in the software repository.

Clone this wiki locally