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
@@ -277,3 +277,20 @@ The Cargo ESP32 is the source of truth for:
 - Local configuration

 The ESP32-S3 dashboard should consume Cargo ESP API data over WiFi/HTTP REST instead of directly owning cargo sensors or relay state.
+
+## Cargo ESP Hardware Transition Plan
+
+Current active development and testing remains on the existing 2-channel relay board.
+
+A LILYGO T-Relay-S3 6-way board has been ordered as a future Cargo ESP candidate.
+
+Transition strategy:
+
+- Keep current 2-channel board working.
+- Make the Cargo ESP API output-count agnostic.
+- Represent outputs as a list of output objects.
+- Let clients render whatever output list the Cargo ESP exposes.
+- Add a hardware profile/config layer before migrating firmware to LilyGO.
+- Bench test LilyGO relay boot behavior before connecting it to the WUPP block.
+
+The API should not require redesign when moving from 2 outputs to 6 outputs.
@@ -185,3 +185,15 @@ Before making dashboard firmware changes, inspect the current API tests and this
 Before suggesting a release/tag prior to Cargo ESP hardware migration, check `docs/pre-lilygo-baseline-checklist.md`.

 Do not suggest migrating active Cargo ESP firmware to LilyGO hardware until the user explicitly decides to buy/use that board.
+
+## LilyGO Transition Guardrail
+
+The user has ordered a LILYGO T-Relay-S3 6-way board, but it will not arrive for a couple weeks.
+
+Until the user confirms hardware is available and bench tested:
+
+- Keep the existing 2-channel relay board as the active test target.
+- Do not remove 2-channel support.
+- Do not assume LilyGO firmware is active.
+- Prepare API/config/docs for output-count-agnostic operation.
+- Treat LilyGO migration as a future hardware-profile change.
@@ -213,3 +213,25 @@ Current expectation:
 - The Dashboard ESP32-S3 will consume temperature data from the Cargo ESP API.

 Do not move cargo/fridge temperature sensing to the dashboard controller unless the architecture is explicitly changed later.
+
+## Ordered Cargo ESP Hardware: LILYGO T-Relay-S3 6-Way
+
+The LILYGO T-Relay-S3 6-way board has been ordered as a future Cargo ESP candidate.
+
+Current active testing should continue on the existing 2-channel relay board until the LilyGO board arrives and is bench tested.
+
+Planned LilyGO role:
+
+    LILYGO T-Relay-S3 6-way
+            -> low-current control/relay outputs
+    WUPP 6-relay fused block
+            -> fused load switching
+    Fridge / Starlink / lights / spare / spare / spare
+
+Important guardrails:
+
+- Do not migrate active firmware assumptions until the board is physically available.
+- Bench test relay boot behavior before connecting to WUPP or vehicle loads.
+- Confirm relay polarity/state behavior.
+- Confirm available GPIO for DS18B20 and any optional OLED/status hardware.
+- Treat the LilyGO board as the controller, not the high-current load path.
@@ -45,3 +45,9 @@ Archived documents are kept for history, but the primary documents above should
 - `cargo-api-contract.md` - Cargo ESP API ownership and expected API areas for WebUI/dashboard clients.

 - `pre-lilygo-baseline-checklist.md` - Checklist for creating a known-good Cargo ESP 2-channel baseline before future LilyGO migration.
+
+## LilyGO Transition
+
+The LILYGO T-Relay-S3 6-way board has been ordered as a future Cargo ESP candidate.
+
+Current development remains on the 2-channel relay board while the API and docs are prepared for output-count-agnostic operation.
@@ -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.
@@ -250,3 +250,16 @@ This contract should guide future ESP32-S3 dashboard work so dashboard firmware
 ## Pre-LilyGO Baseline

 Before migrating Cargo ESP hardware to a LilyGO T-Relay-S3 or other expanded-output controller, use `docs/pre-lilygo-baseline-checklist.md` to confirm the current 2-channel Cargo ESP baseline is stable enough to tag.
+
+## LilyGO Ordered / Transition Plan
+
+The LILYGO T-Relay-S3 6-way board has been ordered but is not yet the active hardware target.
+
+Current testing continues on the original 2-channel relay board.
+
+Near-term work should prepare the Cargo ESP API and configuration model so the future LilyGO migration is a hardware-profile change instead of an API redesign.
+
+Primary goal:
+
+- Keep 2-channel testing functional now.
+- Support future 6-output rendering/control cleanly through the same API shape.