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:

Android App: Initiator van de update, bevat de nieuwe firmware binary.
SylDa_Server (Central/Server): Fungeert als informatiepunt (broker) tussen App en Client.
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

Bootstrapping:
- Client verbindt met Server.
- Client schrijft zijn UUID en Versie naar CLIENT_REGISTRY op de Server.
Update Detectie:
- App verbindt met Server.
- App leest CLIENT_REGISTRY en ziet dat Client v5 draait (App heeft v6).
Update Trigger:
- App stuurt 0x10 (Update Available) naar CLIENT_CONTROL (Target: Client UUID).
- Server stuurt Notify naar Client.
Client Voorbereiding:
- Client ontvangt notificatie.
- Client start NimBLEServer en begint te adverteren.
- Client schrijft 0x20 (Ready) naar CLIENT_CONTROL op de Server.
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.
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.
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.

4.3 KiB Raw Blame History