From bb9701dac506b453be0a8f5ca3f04e7a370cbaae Mon Sep 17 00:00:00 2001
From: eddy <eddy@macmini.local>
Date: Sun, 2 Aug 2026 18:15:09 +0200
Subject: [PATCH] docs: LED stable connection design spec (#4)

---
 ...2026-08-02-led-stable-connection-design.md | 97 +++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-02-led-stable-connection-design.md

diff --git a/docs/superpowers/specs/2026-08-02-led-stable-connection-design.md b/docs/superpowers/specs/2026-08-02-led-stable-connection-design.md
new file mode 100644
index 0000000..04ff8e0
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-02-led-stable-connection-design.md
@@ -0,0 +1,97 @@
+# LED-signalering: stabiele verbinding
+
+**Issue:** [#4](https://git.eddydevink.nl/eddy/Project_SylDa/issues/4) — Leds mogen uit na een minuut stabiele verbinding
+**Datum:** 2026-08-02
+**Status:** goedgekeurd
+
+## Doel
+
+Uniforme LED-signalering voor zowel server als client. De LED dient als debug-indicator tijdens opstarten en bij verbindingsproblemen. Na 60 seconden continue stabiele verbinding schakelt de LED uit.
+
+## Kleurenschema
+
+Identiek voor server (`main.cpp`) en client (`client.cpp`):
+
+| State | LED | Prioriteit |
+|-------|-----|-----------|
+| OTA in progress | Groen knipperend (100ms interval) | 1 (hoogst) |
+| OTA completed, waiting confirm | Geel vast | 1 |
+| Geen verbinding | Rood | 2 |
+| Verbinding actief (< 60s) | Geel | 3 |
+| Verbinding stabiel (>= 60s) | **Uit** | 4 (laagst) |
+| Relais-flash (overlay) | Groen 150ms | overlay |
+
+Relais-flash is een overlay: toont kort groen bij verandering in relais-status, daarna keert LED terug naar de kleur die hoort bij de huidige verbindingsstatus.
+
+## Timer-logica
+
+- Timer (`connectionStableMs`) start zodra de **eerste** verbinding tot stand komt
+- `connectionStableMs` telt op zolang er minstens 1 verbinding is (connectedCount > 0 voor server, connected == true voor client)
+- Nieuwe verbindingen die later bijkomen resetten de timer **niet**
+- Bij disconnect van een verbinding terwijl er nog andere verbindingen zijn: timer loopt door
+- Pas als **alle** verbindingen wegvallen: `connectionStableMs` = 0, LED direct rood
+- Drempel: `STABLE_LED_TIMEOUT_MS = 60000`
+
+### Server-specifiek
+
+- `connectedCount`: aantal actieve BLE-clients (0-2)
+- Timer loopt als `connectedCount > 0`
+- Alle clients disconnect = reset
+
+### Client-specifiek
+
+- `connected`: boolean, of client verbonden is met server
+- Timer loopt als `connected == true`
+- Disconnect = reset
+
+## Relais-flash mechanisme
+
+- Detectie: vergelijk huidige relais-state met vorige loop-iteratie
+- Bij verandering: zet `relayFlashUntil = millis() + 150`
+- Zolang `millis() < relayFlashUntil`: LED groen (overschrijft verbindingskleur)
+- Flash reset de 60s timer **niet**
+- **Server:** detecteert verandering in `relay1State || relay2State` (combinatie van touch, button, en BLE-commands)
+- **Client:** detecteert verandering in `relay1State || relay2State` (alleen touch/button)
+
+## OTA (beide firmwares)
+
+OTA heeft hoogste prioriteit en override alle andere LED-states:
+
+- **OTA in progress** (`otaInProgress == true`): groen knipperend, 100ms interval
+- **OTA completed, waiting confirm** (`otaEnded == true && !otaConfirmed`): geel vast
+- **OTA confirm timeout** of **OTA error**: valt terug naar normale verbindings-LED
+- **OTA success + reboot**: groen vast, dan reboot
+
+Client heeft OTA-logica nog niet geïmplementeerd, maar de LED-code wordt alvast voorbereid met dezelfde OTA-override structuur zodat toekomstige OTA-implementatie direct past.
+
+## LED-update volgorde in loop()
+
+```
+1. Bepaal base-kleur op basis van verbindingsstatus (rood/geel/uit)
+2. Controleer relais-flash: als actief -> groen
+3. Controleer OTA-override: als actief -> OTA-kleur
+4. FastLED.show()
+```
+
+## Wijzigingen per bestand
+
+### `src/main.cpp` (server)
+
+- Toevoegen: `STABLE_LED_TIMEOUT_MS`, `connectionStableMs`, `relayFlashUntil`, `lastRelayActive`
+- Aanpassen: LED-logica in `loop()` — base-kleur uit `connectionStableMs` i.p.v. `connectedCount > 0`
+- Toevoegen: relais-flash detectie
+- Behouden: OTA LED-override (werkt al, prioriteit blijft hoogst)
+- Verwijderen: setup LED-blinks (drie groene knipperingen) — vervangen door rood (geen verbinding)
+
+### `src/client.cpp` (client)
+
+- Toevoegen: `STABLE_LED_TIMEOUT_MS`, `connectionStableMs`, `relayFlashUntil`, `lastRelayActive`
+- Aanpassen: LED-logica in `loop()` — base-kleur uit `connectionStableMs`, geen aparte relais-kleur meer
+- Toevoegen: relais-flash detectie
+- Toevoegen: OTA-override structuur (placeholder, `otaInProgress` default `false`)
+- Setup: LED rood i.p.v. direct rood (blijft rood, maar nu als onderdeel van uniform schema)
+
+### `src/version.h`
+
+- Server versie bump naar "16"
+- Client versie bump naar "2"