From b3d449342faeebe71ccfbeb67985a1885285f574 Mon Sep 17 00:00:00 2001 From: eddy Date: Tue, 4 Aug 2026 21:46:33 +0200 Subject: [PATCH] docs: add spec for client BLE OTA via broker server --- .../specs/2026-08-04-client-ble-ota-spec.md | 86 +++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-04-client-ble-ota-spec.md diff --git a/docs/superpowers/specs/2026-08-04-client-ble-ota-spec.md b/docs/superpowers/specs/2026-08-04-client-ble-ota-spec.md new file mode 100644 index 0000000..219c097 --- /dev/null +++ b/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.