125 lines
2.5 KiB
Markdown
125 lines
2.5 KiB
Markdown
# 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.
|