docs: add spec for client BLE OTA via broker server

docs/superpowers/specs/2026-08-04-client-ble-ota-spec.md

@@ -0,0 +1,86 @@
+# Spec: Client BLE OTA via Broker Server
+
+**Status:** Draft
+**Datum:** 2026-08-04
+**Auteur:** opencore (AI Agent)
+
+## 1. Introductie
+Dit document beschrijft de architectuur en het protocol voor het uitvoeren van een Firmware Over-The-Air (OTA) update op de SylDa_Client (ESP32) via de SylDa_Server (ESP32) als broker.
+
+## 2. Architectuur
+Het systeem bestaat uit drie componenten:
+1.  **Android App:** Initiator van de update, bevat de nieuwe firmware binary.
+2.  **SylDa_Server (Central/Server):** Fungeert als informatiepunt (broker) tussen App en Client.
+3.  **SylDa_Client (Central/Client):** Ontvanger van de update. Gaat in een "Dual-Role" (Central + Server) tijdens de update procedure.
+
+## 3. BLE Interface (SylDa_Server)
+De Server breidt zijn bestaande service (`4fafc201-1fb5-459e-8fcc-c5c9c331914b`) uit met de volgende characteristics:
+
+### 3.1 CLIENT_REGISTRY (`beb5483e-36e1-4688-b7f5-ea07361f26dd`)
+*   **Eigenschappen:** Read, Notify
+*   **Beveiliging:** AES/GCM encrypted
+*   **Payload (37 bytes totaal):**
+    *   `[0:3]` Seq (4 bytes)
+    *   `[4:11]` Nonce Random (8 bytes)
+    *   `[12]` Ciphertext: `[UUID (16b) | Version (2b) | Status (1b)]`
+    *   `[13:28]` Auth Tag (16 bytes)
+*   **Status codes:**
+    *   `0x00`: Normaal / Idle
+    *   `0x01`: Ready for OTA (Advertising)
+    *   `0x02`: Updating (Transfer bezig)
+
+### 3.2 CLIENT_CONTROL (`beb5483e-36e1-4688-b7f5-ea07361f26de`)
+*   **Eigenschappen:** Write, Notify
+*   **Beveiliging:** AES/GCM encrypted
+*   **Payload (37 bytes totaal):**
+    *   `[0:3]` Seq (4 bytes)
+    *   `[4:11]` Nonce Random (8 bytes)
+    *   `[12]` Ciphertext: `[TargetUUID (16b) | Action (1b)]`
+    *   `[13:28]` Auth Tag (16 bytes)
+*   **Action codes:**
+    *   `0x10`: `NOTIFY_UPDATE_AVAILABLE` (Server -> Client)
+    *   `0x20`: `CLIENT_READY_FOR_OTA` (Client -> Server -> App)
+
+## 4. BLE Interface (SylDa_Client OTA Mode)
+Wanneer de Client in OTA-modus gaat, start hij een eigen BLE Server met de volgende gegevens:
+*   **Device Name:** `SylDa_Client_OTA_[Last-4-chars-UUID]`
+*   **Service UUID:** `4fafc201-1fb5-459e-8fcc-c5c9c331914b` (Gelijk aan Server)
+*   **OTA Characteristic:** `beb5483e-36e1-4688-b7f5-ea07361f26da` (Gelijk aan Server)
+*   **UUID Characteristic:** `beb5483e-36e1-4688-b7f5-ea07361f26d9` (Bevat eigen UUID ter verificatie)
+
+## 5. Sequence Diagram
+
+1.  **Bootstrapping:**
+    *   Client verbindt met Server.
+    *   Client schrijft zijn UUID en Versie naar `CLIENT_REGISTRY` op de Server.
+2.  **Update Detectie:**
+    *   App verbindt met Server.
+    *   App leest `CLIENT_REGISTRY` en ziet dat Client v5 draait (App heeft v6).
+3.  **Update Trigger:**
+    *   App stuurt `0x10` (Update Available) naar `CLIENT_CONTROL` (Target: Client UUID).
+    *   Server stuurt Notify naar Client.
+4.  **Client Voorbereiding:**
+    *   Client ontvangt notificatie.
+    *   Client start `NimBLEServer` en begint te adverteren.
+    *   Client schrijft `0x20` (Ready) naar `CLIENT_CONTROL` op de Server.
+5.  **App Verbinding naar Client:**
+    *   App ontvangt `0x20` notificatie van de Server.
+    *   App (na gebruikersbevestiging) scant naar `SylDa_Client_OTA` met de juiste UUID.
+    *   App verbindt direct met de Client.
+6.  **OTA Transfer:**
+    *   App voert de standaard OTA-procedure uit (Start command, chunks, SHA256 verify, End confirm).
+    *   Client verwerkt de OTA en voert zijn relais-taken uit zolang de transfer niet is gestart.
+7.  **Finalisatie:**
+    *   Client herstart na succesvolle OTA.
+    *   Client verbindt opnieuw met Server en rapporteert de nieuwe versie.
+
+## 6. Beveiliging en Foutafhandeling
+*   **Encryptie:** Alle "Broker" communicatie op de Server verloopt via de bestaande AES/GCM laag met de gedeelde PSK.
+*   **UUID Pinning:** De App MOET de UUID van de Client verifiëren via de `UUID_CHAR_UUID` voordat de OTA start.
+*   **Timeouts:** De Client stopt de OTA-modus (Server-rol) na een succesvolle update of een handmatige reset. (Gebruiker behoudt controle via de App).
+*   **Relais:** De Client blijft operationeel tot het moment dat de OTA-transfer daadwerkelijk begint.
+
+## 7. Rollen en Verantwoordelijkheden
+*   **Server:** Passief doorgeefluik van status en notificaties. Slaat geen firmware op.
+*   **Client:** Verantwoordelijk voor het veilig flashen van de eigen firmware en het rapporteren van de status.
+*   **App:** Verantwoordelijk voor het orkestreren van het proces en het leveren van de firmware.