# 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.