Skip to content

Message Structure Reference

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

Message Structure Reference

This document provides a comprehensive reference for all message structures used in the Hyperloop Control Station system.

Data Types

Primitive Types

Type Size Range Description
uint8 1 byte 0 to 255 Unsigned 8-bit integer
uint16 2 bytes 0 to 65,535 Unsigned 16-bit integer
uint32 4 bytes 0 to 4,294,967,295 Unsigned 32-bit integer
uint64 8 bytes 0 to 18,446,744,073,709,551,615 Unsigned 64-bit integer
int8 1 byte -128 to 127 Signed 8-bit integer
int16 2 bytes -32,768 to 32,767 Signed 16-bit integer
int32 4 bytes -2,147,483,648 to 2,147,483,647 Signed 32-bit integer
int64 8 bytes -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 Signed 64-bit integer
float32 4 bytes ±1.4e-45 to ±3.4e38 IEEE 754 single-precision
float64 8 bytes ±4.9e-324 to ±1.8e308 IEEE 754 double-precision
bool 1 byte 0 (false) or 1 (true) Boolean value
enum varies depends on base type Enumerated value

String Encoding

  • Character Set: ASCII
  • Termination: Null-terminated for binary protocol
  • Encoding: UTF-8 for JSON protocol

Vehicle Message Structures

Data Packet

Binary Layout:

Offset: 0      2      4+
       |======|======|========|
       | ID   | Data Values   |
       |======|======|========|

Go Structure:

type DataPacket struct {
    ID        uint16                    // Packet identifier
    Values    map[string]Value          // Measurement values
    Enabled   map[string]bool           // Measurement enabled flags
    Timestamp time.Time                 // Reception timestamp
}

JSON Representation:

{
    "board_id": 0,
    "packet_id": 211,
    "packet_name": "vcu_regulator_packet",
    "timestamp": "2024-01-15T10:30:45.123Z",
    "measurements": {
        "valve_state": {
            "value": "open",
            "type": "enum",
            "enabled": true
        }
    }
}

Protection Packet

Binary Layout:

Offset: 0      2      4      5      6      7+
       |======|======|======|======|======|========|
       | ID   | Type | Kind | Name String... |
       |======|======|======|======|======|========|
       |          Protection Data              |
       |======|======|======|======|======|========|
       |Counter|Counter|Second|Minute| Hour | Day  |
       |======|======|======|======|======|========|
       |Month |    Year     |
       |======|======|======|

Go Structure:

type ProtectionPacket struct {
    ID        uint16              // Packet identifier
    Type      uint8               // Data type being protected
    Kind      uint8               // Protection condition
    Name      string              // Protection name
    Data      ProtectionData      // Type-specific data
    Timestamp ProtectionTimestamp // RTC timestamp
    Severity  string              // fault/warning/ok
}

JSON Representation:

{
    "board_id": 0,
    "severity": "fault",
    "protection_type": "above", 
    "measurement_name": "brake_pressure",
    "current_value": 105.0,
    "threshold_value": 100.0,
    "message": "Brake pressure above safe limit",
    "timestamp": "2024-01-15T10:30:45.123Z"
}

Order Packet

Binary Layout:

Offset: 0      2      4      6+
       |======|======|======|========|
       | ID   |Count | Order IDs... |
       |======|======|======|========|

Go Structure:

type OrderPacket struct {
    ID     uint16   // Packet identifier
    Action string   // "add" or "remove"
    Orders []uint16 // List of order IDs
}

JSON Representation:

{
    "board_id": 0,
    "order_name": "brake_engage",
    "parameters": {
        "target_pressure": 85.0
    }
}

State Space Packet

Binary Layout:

Offset: 0      2      4+
       |======|======|========|
       | ID   | State Matrix  |
       |======|======|========|

Go Structure:

type StateSpacePacket struct {
    ID    uint16         // Packet identifier
    State [8][15]float32 // Control state matrix
}

Matrix Encoding: 8x15 matrix in row-major order

  • Total size: 480 bytes (8 * 15 * 4 bytes per float32)
  • Each element is little-endian IEEE 754 float32

Measurement Definitions

Standard Measurements

Pressure Measurements

{
    "id": "brake_pressure",
    "name": "Brake Pressure",
    "type": "float32",
    "podUnits": "bar",
    "displayUnits": "PSI", 
    "safeRange": [0.0, 10.0],
    "warningRange": [8.0, 9.5]
}

Temperature Measurements

{
    "id": "motor_temperature",
    "name": "Motor Temperature",
    "type": "float32",
    "podUnits": "ºC",
    "displayUnits": "ºC",
    "safeRange": [-40.0, 85.0],
    "warningRange": [70.0, 80.0]
}

Boolean Measurements

{
    "id": "emergency_stop",
    "name": "Emergency Stop",
    "type": "bool"
}

Enum Measurements

{
    "id": "valve_state",
    "name": "Valve State", 
    "type": "uint8",
    "enumValues": ["closed", "open", "error"]
}

Unit Conversions

From general_info.json:

{
    "units": {
        "V": "*1",           // Volts (no conversion)
        "A": "*1",           // Amperes (no conversion)
        "ºC": "+273.15",     // Celsius to Kelvin
        "m": "*1",           // Meters (no conversion)
        "mm": "/1000",       // Millimeters to meters
        "deg": "/57.2957",   // Degrees to radians
        "Hz": "*1",          // Hertz (no conversion)
        "m/s": "*1",         // Meters per second
        "m/ss": "*1",        // Meters per second squared
        "G": "*9.8",         // G-force to m/s²
        "rad": "*1",         // Radians (no conversion)
        "km/h": "*3.6",      // Kilometers per hour to m/s
        "mrad": "/1000"      // Milliradians to radians
    }
}

WebSocket Message Structures

Topic Format

Topics follow a hierarchical format: category/action

Categories:

  • data: Measurement data
  • connection: Network status
  • order: Commands and responses
  • protection: Safety alerts
  • logger: Data logging control
  • blcu: Bootloader operations
  • message: System notifications

Standard Message Envelope

{
    "topic": "category/action",
    "payload": {
        // Topic-specific data
    }
}

Data Update Message

{
    "topic": "data/update",
    "payload": {
        "board_id": 0,
        "packet_id": 211,
        "packet_name": "vcu_regulator_packet",
        "timestamp": "2024-01-15T10:30:45.123Z",
        "measurements": {
            "measurement_id": {
                "value": "number|string|boolean",
                "type": "data_type",
                "enabled": true,
                "units": "unit_string"
            }
        }
    }
}

Connection Status Message

{
    "topic": "connection/update",
    "payload": {
        "board_id": 0,
        "board_name": "VCU",
        "ip_address": "127.0.0.6",
        "connected": true,
        "last_seen": "2024-01-15T10:30:45.123Z",
        "packets_received": 1250,
        "connection_quality": "excellent|good|poor|unknown"
    }
}

Order Command Message

{
    "topic": "order/send",
    "payload": {
        "board_id": 0,
        "order_name": "order_identifier",
        "parameters": {
            "parameter_name": "parameter_value"
        }
    }
}

Protection Alert Message

{
    "topic": "protection/alert", 
    "payload": {
        "board_id": 0,
        "severity": "fault|warning|ok",
        "protection_type": "above|below|outofbounds|equals|notequals|errorhandler|timeaccumulation",
        "measurement_name": "measurement_id",
        "current_value": "number",
        "threshold_value": "number",
        "message": "descriptive_text",
        "timestamp": "ISO8601_timestamp",
        "protection_id": "unique_identifier"
    }
}

ADJ Configuration Structures

Board Configuration

{
    "board_id": 0,
    "board_ip": "127.0.0.6",
    "measurements": ["VCU_measurements.json"],
    "packets": ["orders.json", "packets.json"]
}

Packet Definition

{
    "id": 211,
    "name": "vcu_regulator_packet",
    "type": "data",
    "variables": [
        "valve_state",
        "reference_pressure", 
        "actual_pressure"
    ]
}

Measurement Definition

{
    "id": "reference_pressure",
    "name": "Reference Pressure",
    "type": "float32",
    "podUnits": "bar",
    "displayUnits": "bar",
    "safeRange": [0, 10],
    "warningRange": [8, 9.5]
}

Error Message Structures

Network Error

{
    "topic": "error",
    "payload": {
        "error": "connection_lost",
        "message": "Lost connection to board",
        "board_id": 0,
        "timestamp": "2024-01-15T10:30:45.123Z",
        "recovery_action": "reconnecting"
    }
}

Protocol Error

{
    "topic": "error",
    "payload": {
        "error": "invalid_packet",
        "message": "Unknown packet ID received",
        "packet_id": 999,
        "board_id": 0,
        "raw_data": "hex_dump"
    }
}

Validation Error

{
    "topic": "error",
    "payload": {
        "error": "validation_failed",
        "field": "board_id",
        "message": "Invalid board ID",
        "received_value": "invalid_id",
        "expected_type": "integer"
    }
}

Message Size Limits

Binary Protocol

  • Minimum Packet: 2 bytes (packet ID only)
  • Maximum Packet: 1500 bytes (Ethernet MTU)
  • Typical Data Packet: 20-100 bytes
  • Protection Packet: 50-200 bytes
  • State Space Packet: 482 bytes (fixed)

WebSocket Protocol

  • Maximum Message: 1MB (configurable)
  • Typical Data Update: 500-2000 bytes
  • Batch Updates: Up to 64KB
  • BLCU File Transfer: Limited by available memory

Performance Characteristics

Message Frequency

  • Data Packets: 10-100 Hz per measurement
  • Protection Alerts: Event-driven (immediate)
  • Connection Updates: 1 Hz + on-change
  • Order Commands: User-initiated (< 10/second)

Processing Times

  • Binary Decoding: < 1ms per packet
  • JSON Encoding: < 5ms per message
  • WebSocket Transmission: < 10ms local network
  • End-to-End Latency: < 20ms typical

This reference is generated from the codebase and ADJ specifications. For the most current information, refer to the source code and configuration files.

Clone this wiki locally