Skip to content

ADJ Configuration Format

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

ADJ Configuration Format

ADJ (Automatic Data Junction) is the JSON-based configuration system that defines board configurations, measurements, and communication protocols for the Hyperloop Control Station.

Overview

The ADJ system uses a distributed collection of JSON files to define:

  • Board Configurations: IP addresses, IDs, and file references
  • Measurement Definitions: Data types, units, and validation ranges
  • Packet Structures: Communication message formats
  • System Configuration: Ports, addresses, and global settings

File Structure

adj/
├── general_info.json      # System-wide configuration
├── boards.json           # Board list and path mappings
└── boards/               # Board-specific configurations
    └── {board_name}/
        ├── {board_name}.json           # Main board configuration
        ├── {board_name}_measurements.json  # Board measurements
        ├── packets.json                # Data packets
        └── orders.json                 # Order packets

Configuration Files

1. General Info (general_info.json)

System-wide configuration including network settings and unit definitions.

{
    "ports": {
        "TCP_CLIENT": 50401,
        "TCP_SERVER": 50500,
        "UDP": 8000,
        "SNTP": 123,
        "TFTP": 69
    },
    "addresses": {
        "backend": "127.0.0.9"
    },
    "units": {
        "V": "*1",
        "A": "*1",
        "ºC": "+273.15",
        "m": "*1",
        "mm": "/1000",
        "deg": "/57.2957",
        "Hz": "*1",
        "m/s": "*1",
        "m/ss": "*1",
        "G": "*9.8",
        "rad": "*1",
        "km/h": "*3.6",
        "mrad": "/1000"
    },
    "message_ids": {
        "info": 1,
        "fault": 2,
        "warning": 3,
        "blcu_ack": 4,
        "add_state_order": 5,
        "remove_state_order": 6,
        "state_space": 7
    }
}

Field Descriptions:

  • ports: Network port assignments for different protocols
  • addresses: IP addresses for system components
  • units: Unit conversion formulas (operation applied to raw values)
  • message_ids: Reserved packet IDs for system messages

2. Board List (boards.json)

Mapping of board names to their configuration directories.

{
    "VCU": "boards/VCU/VCU.json",
    "BCU": "boards/BCU/BCU.json", 
    "LCU": "boards/LCU/LCU.json",
    "OBCCU": "boards/OBCCU/OBCCU.json"
}

3. Board Configuration ({board_name}.json)

Main configuration for each vehicle board.

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

Field Descriptions:

  • board_id: Unique 32-bit unsigned integer identifier
  • board_ip: IPv4 address for network communication
  • measurements: Array of measurement definition file paths
  • packets: Array of packet definition file paths

4. Measurements ({board_name}_measurements.json)

Detailed measurement definitions for data validation and display.

[
    {
        "id": "reference_pressure",
        "name": "Reference Pressure",
        "type": "float32",
        "podUnits": "bar",
        "displayUnits": "bar",
        "safeRange": [0, 10],
        "warningRange": [8, 9.5]
    },
    {
        "id": "valve_state",
        "name": "Valve State",
        "type": "uint8",
        "enumValues": ["closed", "open", "error"]
    },
    {
        "id": "emergency_stop",
        "name": "Emergency Stop",
        "type": "bool"
    }
]

Field Descriptions:

  • id: Unique string identifier for the measurement
  • name: Human-readable display name
  • type: Data type (see Data Types section)
  • podUnits: Units used by the pod (references general_info.units)
  • displayUnits: Units for display (references general_info.units)
  • safeRange: [min, max] safe operating range (optional)
  • warningRange: [min, max] warning thresholds (optional)
  • enumValues: Array of enumeration values for discrete measurements (optional)

5. Data Packets (packets.json)

Definitions for telemetry and status packets sent by the vehicle.

[
    {
        "id": 211,
        "name": "vcu_regulator_packet",
        "type": "data",
        "variables": [
            "valve_state",
            "reference_pressure", 
            "actual_pressure"
        ]
    },
    {
        "id": 212,
        "name": "vcu_reed_packet", 
        "type": "data",
        "variables": [
            "reed1",
            "reed2",
            "reed3",
            "reed4"
        ]
    }
]

6. Order Packets (orders.json)

Definitions for command packets sent to the vehicle.

[
    {
        "name": "vcu_orders",
        "type": "order",
        "variables": [
            "new_reference_pressure"
        ]
    }
]

Field Descriptions:

  • id: 32-bit unsigned integer packet identifier (optional for orders)
  • name: Human-readable packet name
  • type: Packet type ("data" or "order")
  • variables: Array of measurement IDs included in this packet

Data Types

Supported Types

Type Size Description Example Values
uint8 1 byte Unsigned 8-bit integer 0, 255
uint16 2 bytes Unsigned 16-bit integer 0, 65535
uint32 4 bytes Unsigned 32-bit integer 0, 4294967295
uint64 8 bytes Unsigned 64-bit integer 0, 18446744073709551615
int8 1 byte Signed 8-bit integer -128, 127
int16 2 bytes Signed 16-bit integer -32768, 32767
int32 4 bytes Signed 32-bit integer -2147483648, 2147483647
int64 8 bytes Signed 64-bit integer Large signed integers
float32 4 bytes IEEE 754 single-precision 3.14159, -273.15
float64 8 bytes IEEE 754 double-precision High-precision decimals
bool 1 byte Boolean value true, false
enum varies Enumerated value Based on underlying type

Enum Definitions

Enums are defined using enumValues array with string representations:

{
    "id": "connection_status",
    "type": "uint8",
    "enumValues": ["disconnected", "connecting", "connected", "error"]
}

Binary Encoding: Enum values are encoded as their array index (0-based)

  • "disconnected" = 0
  • "connecting" = 1
  • "connected" = 2
  • "error" = 3

Unit System

Unit Conversion Format

Units are defined as mathematical operations applied to raw sensor values:

{
    "units": {
        "V": "*1",           // Multiply by 1 (no conversion)
        "ºC": "+273.15",     // Add 273.15 (Celsius to Kelvin)
        "mm": "/1000",       // Divide by 1000 (millimeters to meters)
        "deg": "/57.2957",   // Divide by 57.2957 (degrees to radians)
        "G": "*9.8"          // Multiply by 9.8 (G-force to m/s²)
    }
}

Supported Operations

  • *N: Multiply by N
  • /N: Divide by N
  • +N: Add N
  • -N: Subtract N

Common Unit Conversions

Pod Units Display Units Conversion Purpose
bar PSI *14.5038 Pressure display
ºC K +273.15 Temperature to Kelvin
mm m /1000 Distance normalization
deg rad /57.2957 Angle normalization
G m/ss *9.8 Acceleration to SI units
km/h m/s /3.6 Velocity to SI units

Validation Rules

File Structure Validation

  1. Naming Convention: Board directories and files must match board names
  2. File References: All file paths relative to board directory
  3. Circular References: Not allowed between configuration files

Data Validation

  1. Measurement References: Packet variables must reference valid measurement IDs
  2. Unit References: podUnits and displayUnits must reference valid units
  3. Type Consistency: Enum values must match measurement type constraints
  4. Range Validation: safeRange and warningRange must be valid for data type

ID Uniqueness

  1. Board IDs: Must be unique across all boards
  2. Packet IDs: Should be unique within packet type (data vs order)
  3. Measurement IDs: Must be unique within board measurements

Configuration Examples

Simple Pressure Sensor

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

Digital Input/Output

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

Multi-State Valve

{
    "id": "main_valve",
    "name": "Main Valve Position", 
    "type": "uint8",
    "enumValues": ["closed", "opening", "open", "closing", "error"]
}

Temperature with Conversion

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

Board Configuration Examples

Vehicle Control Unit (VCU)

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

Brake Control Unit (BCU)

{
    "board_id": 1,
    "board_ip": "127.0.0.7",
    "measurements": ["BCU_measurements.json", "BCU_control_measurements.json"],
    "packets": ["control_packets.json", "orders.json"]
}

Migration and Versioning

ADJ v1 to v2 Migration

  • Automatic Migration: Backend automatically converts v1 to v2 format
  • Backward Compatibility: v1 configurations continue to work
  • Deprecation Warning: v1 format generates warnings in logs

Version Detection

{
    "adj_version": "2.0",
    "format_version": "2024.1"
}

Breaking Changes Policy

  • Additive Changes: New fields can be added without breaking compatibility
  • Field Removal: Deprecated fields maintained for one major version
  • Type Changes: Not allowed for existing fields without migration path

Troubleshooting

Common Configuration Errors

Invalid Measurement Reference

Error: Packet 'brake_data' references unknown measurement 'brake_force'
Solution: Add measurement definition or fix variable name

Missing Unit Definition

Error: Measurement 'pressure_1' uses undefined unit 'Pa'
Solution: Add 'Pa' definition to general_info.json units section

Duplicate Board ID

Error: Board ID 0 used by both VCU and BCU
Solution: Assign unique board IDs to each board

Invalid IP Address

Error: Board VCU has invalid IP address '192.168.1.256'
Solution: Use valid IPv4 address format

Validation Tools

Configuration Validator

# Check ADJ configuration validity
./backend/cmd/backend --validate-adj

JSON Schema Validation

# Validate against JSON schema
jsonschema -i board.json board_schema.json

Best Practices

Configuration Management

  1. Version Control: All ADJ files should be in git
  2. Environment-Specific: Use different configs for dev/test/prod
  3. Documentation: Comment complex configurations in README files
  4. Validation: Run validation before deploying changes

Performance Optimization

  1. Packet Size: Keep packet variable lists reasonable (< 20 measurements)
  2. Update Frequency: Match packet frequency to data rate requirements
  3. Unit Conversion: Minimize complex unit conversions in real-time paths
  4. Enum Usage: Use enums instead of multiple boolean measurements

Safety Considerations

  1. Range Validation: Always define safeRange for critical measurements
  2. Warning Thresholds: Set warningRange before reaching safeRange limits
  3. Emergency Measurements: Use bool type for emergency conditions
  4. Redundancy: Define multiple measurements for critical systems

For the complete ADJ specification and examples, see the adj/ directory in the repository and the official ADJ documentation.

Clone this wiki locally