docs: prepare api contract for lilygo transition

2026-06-09 15:05:29 -06:00
parent 90c4490a3d
commit f2966518da
6 changed files with 131 additions and 0 deletions
@@ -122,3 +122,64 @@ When possible, future changes should add fields rather than rename or remove exi
 Dashboard firmware should tolerate unknown fields.

 Cargo ESP firmware should preserve stable field names once dashboard implementation begins.
+
+## Output Hardware Profiles
+
+The Cargo ESP API should describe outputs generically instead of assuming a fixed relay board.
+
+Current active hardware:
+
+- Generic ESP32 with 2-channel relay board
+- Used for ongoing development and testing
+
+Ordered/future hardware:
+
+- LILYGO T-Relay-S3 6-way
+- Intended to trigger the 6 relays on the WUPP fuse/relay block
+- Not active firmware target until hardware arrives and is bench tested
+
+API clients should not assume exactly 2 outputs or exactly 6 outputs.
+
+Instead, clients should read the output list exposed by the Cargo ESP and render whatever outputs are available.
+
+Expected output object fields:
+
+- `id`
+- `name`
+- `role`
+- `enabled`
+- `state`
+- `requested_state`
+- `available`
+- `hardware_channel`
+- `hardware_profile`
+
+Example 2-channel profile:
+
+    {
+      "hardware_profile": "generic_esp32_2ch_relay",
+      "outputs": [
+        {"id": 1, "name": "Fridge", "role": "fridge", "hardware_channel": 1},
+        {"id": 2, "name": "Starlink", "role": "starlink", "hardware_channel": 2}
+      ]
+    }
+
+Example future 6-channel profile:
+
+    {
+      "hardware_profile": "lilygo_t_relay_s3_6ch_wupp",
+      "outputs": [
+        {"id": 1, "name": "Fridge", "role": "fridge", "hardware_channel": 1},
+        {"id": 2, "name": "Starlink", "role": "starlink", "hardware_channel": 2},
+        {"id": 3, "name": "Lights", "role": "lights", "hardware_channel": 3},
+        {"id": 4, "name": "Spare 1", "role": "spare", "hardware_channel": 4},
+        {"id": 5, "name": "Spare 2", "role": "spare", "hardware_channel": 5},
+        {"id": 6, "name": "Spare 3", "role": "spare", "hardware_channel": 6}
+      ]
+    }
+
+Compatibility rule:
+
+- The API should support the current 2-channel board while allowing a future 6-output profile without changing dashboard/client assumptions.
+- Clients should render outputs dynamically from the API response.
+- Clients should not hardcode relay count.