overland-controller/docs/cargo-api-contract.md

Cargo ESP API Contract

The Cargo ESP32 is the source of truth for power-system state.

The WebUI, ESP32-S3 dashboard, and future clients should consume this API rather than reading sensors or relay state directly.

Ownership

Cargo ESP32 owns:

• Relay/output state
• DS18B20 temperature readings
• BMS telemetry
• Alarm/fault state
• Local configuration
• WebUI/API service

Dashboard ESP32-S3 consumes:

• Status
• Battery/BMS telemetry
• Temperature telemetry
• Relay/output state
• Alarm/fault state

The dashboard may request relay changes through the API, but the Cargo ESP remains authoritative.

Expected API Areas

System Status

Used by clients to determine whether the Cargo ESP is online and healthy.

Expected data:

• Device name
• Firmware version
• Uptime
• WiFi/AP status
• API version
• Alarm/fault summary

Battery / BMS

Used for house battery display.

Expected data:

• Voltage
• Current
• State of charge
• Charging/discharging state
• Cell data when available
• BMS online/offline status
• Protection/fault state

Temperatures

DS18B20 support is already implemented in the Cargo ESP/WebUI/API path.

Expected data:

• Sensor ID
• Display name
• Enabled state
• Online/offline state
• Temperature value
• Temperature unit
• Role/location, such as fridge, cargo, ambient, or spare

The ESP32-S3 dashboard should display this data from the Cargo ESP API. It should not directly own cargo/fridge DS18B20 sensor wiring for v1.

Relays / Outputs

Used for fridge, Starlink, lights, spare, and future switched outputs.

Expected data:

• Output ID
• Display name
• Enabled state
• Current state
• Requested state
• Fault/lockout state when available
• Optional output type or role

Relay/output writes should go through the Cargo ESP API.

Configuration

Configuration should remain owned by the Cargo ESP.

Expected future areas:

• Output names
• Output enabled/disabled state
• Temperature sensor names
• Temperature sensor roles
• Alarm thresholds
• Network/AP settings
• OTA settings

v1 Client Communication

Current v1 client path:

ESP32-S3 Dashboard
        <-> WiFi / HTTP REST
Cargo ESP32 AP

Not v1 API transport:

• ESP-NOW
• MQTT
• UART dashboard link
• CAN between controllers

Compatibility Rule

When possible, future changes should add fields rather than rename or remove existing fields.

Dashboard firmware should tolerate unknown fields.

Cargo ESP firmware should preserve stable field names once dashboard implementation begins.