Update README for USB key provisioning architecture

- Unified toast message to 'Beveiligingssleutel gelezen' throughout
- Updated key management section with bidirectional provisioning flow
- Added provisioning flow diagram (ASCII sequence)
- Updated security analysis: key no longer in APK, extracted from
  SharedPreferences requiring root; added USB key extraction risk
  and NVS wiping notes
- Added serial monitor example for unprovisioned ESP (no-key case)
- Added factory reset instructions (pio run -t erase)
- Added setup scenarios: existing ESP + new phone, new ESP + existing phone
- Updated projectstructuur: removed stale usb-serial-for-android references
- Updated technische notities: raw USB API justification, CDC control
  interface setup, retry behavior

README.md

@@ -53,7 +53,7 @@ De relay is beveiligd tegen ongeautoriseerde toegang via twee onafhankelijke lag
 
 Omdat BLE Just Works geen MITM-bescherming biedt, is er een tweede laag toegevoegd:
 
-- Zowel de ESP firmware als de Android app bevatten een **32-byte shared secret** (HMAC key)
+- Zowel de ESP firmware als de Android app delen een **32-byte shared secret** (HMAC key), die via USB provisioning op beide apparaten terechtkomt
 - Elk commando wordt ondertekend met `HMAC-SHA256(key, command || sequence)`
 - De ESP verifieert de handtekening voordat het relais schakelt
 - Een **sequence counter** voorkomt replay-aanvallen: elk packet moet een strikt oplopend volgnummer hebben
@@ -71,12 +71,14 @@ De sequence counter reset naar 0 bij elke (re)connectie op de ESP. De app start
 
 #### Key management
 
-- De HMAC key wordt **niet meer meegecompileerd** — de ESP start zonder key en wordt geprovisioneerd via USB
+- De HMAC key wordt **niet meegecompileerd** — de ESP start zonder key en wordt geprovisioneerd via USB
-- De key wordt opgeslagen in **NVS** (Non-Volatile Storage) op de ESP via de Arduino `Preferences` library
+- De key wordt opgeslagen in **NVS** (Non-Volatile Storage) op de ESP via de Arduino `Preferences` library (survives reboots en power-cycles)
-- **USB auto-provisioning:** Sluit de ESP via USB-OTG aan op de telefoon → de app stuurt `KEY?\n`. Als de ESP nog geen key heeft, antwoordt hij met `NO_KEY`. De app genereert dan een willekeurige 32-byte key (via `SecureRandom`), stuurt `SET_KEY:<hex>\n` naar de ESP, en slaat de key both op de ESP (NVS) als lokaal (SharedPreferences) op.
+- De app slaat de key op in **SharedPreferences** (overleeft app-herstarts)
-- Als de ESP al wel een key heeft, antwoordt hij met `HMAC_KEY:<hex>` en de app slaat die op
+- **USB auto-provisioning:** Sluit de ESP via USB-OTG aan op de telefoon. De app stuurt `KEY?\n`:
+  - Als de ESP al een key heeft → ESP antwoordt `HMAC_KEY:<hex>` → app slaat op lokaal op
+  - Als de ESP nog geen key heeft → ESP antwoordt `NO_KEY` → app genereert willekeurige 32-byte key via `SecureRandom` → stuurt `SET_KEY:<hex>\n` → ESP slaat op in NVS en antwoordt `OK` → app slaat op lokaal op
+  - Beide paden tonen dezelfde toast: **"Beveiligingssleutel gelezen"**
 - Handmatige invoer: via het instellingenscherm in de Android app (64-teken hex string)
-- De app slaat de key op in SharedPreferences (overleeft app-herstarts)
 - Zo kan dezelfde app gebruikt worden voor meerdere ESP modules — each met een eigen key
 
 #### USB Serial Protocol
@@ -92,6 +94,27 @@ ESP → App:  OK\n                        (bevestiging)
 
 De ESP luistert in `loop()` voor USB serial data. Bij `KEY?\n` antwoordt hij met de hex key (`HMAC_KEY:<hex>`) of `NO_KEY`. Bij `SET_KEY:<64-hex>\n` slaat hij de key op in NVS en antwoordt `OK`. De Android `UsbKeyReceiver` (manifest-geregistreerde `BroadcastReceiver`) vangt `USB_DEVICE_ATTACHED` op, filtert op Espressif (vendor 0x303a), vraagt USB-permission, opent een CDC-ACM serial connectie, en handelt het hele provisioning-proces automatisch af.
 
+#### Provisioning flow (auto)
+
+```
+  Android app                         ESP32 (USB CDC)
+  ───────────                         ───────────────
+  USB device attached ──────────►
+  Request USB permission ◄────── Android dialog
+  Open CDC-ACM connection
+  Send KEY?\n ──────────────────► 
+                                 ┌─ if key in NVS ──► HMAC_KEY:<hex>\n
+                                 │                   App saves to prefs → toast
+                                 │
+                                 └─ if no key ──────► NO_KEY\n
+  Generate 32 random bytes              │
+  Send SET_KEY:<hex>\n ─────────► (store in NVS)
+  ◄──────────────────────────── OK\n
+  App saves to prefs → toast
+```
+
+De `UsbKeyReceiver` doet dit op een achtergrondthread met max 5 retries (1s pauze) om andere USB-apps te overleven die mogelijk het apparaat tijdelijk claimen.
+
 ### Beveiligingsanalyse
 
 | Aanval | Hoe geweerd |
@@ -100,7 +123,9 @@ De ESP luistert in `loop()` voor USB serial data. Bij `KEY?\n` antwoordt hij met
 | **Replay** | Sequence counter — zelfde packet werkt niet 2x |
 | **Ongeautoriseerd device** | HMAC vereist geheime sleutel |
 | **MITM** | Just Works is kwetsbaar voor MITM; HMAC maakt actieve MITM wel moeilijk (aanvaller moet de key kennen) |
-| **Reverse engineering van key** | Sleutel staat in APK — extracteerbaar met reverse engineering. Voor hogere veiligheid: gebruiker ProGuard/R8 obfuscation. |
+| **Reverse engineering van key** | Sleutel staat niet in de APK — wordt pas bij USB provisioning gegenereerd en in SharedPreferences opgeslagen. Extractie vereist fysieke toegang tot de telefoon én root. |
+| **Key extractie via USB** | Fysieke USB-toegang tot de ESP geeft `KEY?\n` de huidige key terug. Bescherming: fysieke toegang tot het board beperken. |
+| **NVS wiping** | `pio run -t erase` wist alle flash waaronder NVS — ESP is daarna leeg en kan opnieuw geprovisioneerd worden. |
 
 ## Firmware
 
@@ -142,10 +167,19 @@ HMAC key loaded from NVS
 HMAC Key: C3F17B...AF
 ```
 
+**Key wissen (factory reset):** Om de ESP terug te zetten naar ongeprovisioneerd:
+
+```bash
+pio run -t erase
+```
+
+Dit wist alle flash inclusief NVS. Na opnieuw flashen start de ESP weer zonder key.
+
 ### Serial monitor
 
-Baudrate: **115200** (USB CDC). De firmware stuurt heartbeat-statussen elke 5 seconden, logt statuswijzigingen, en print de HMAC key (of de afwezigheid ervan) bij opstarten:
+Baudrate: **115200** (USB CDC). De firmware stuurt heartbeat-statussen elke 5 seconden, logt statuswijzigingen, en print de HMAC key (of de afwezigheid ervan) bij opstarten.
 
+**Met geprovisioneerde key:**
 ```
 === Atom VoiceS3R BLE Relay ===
 HMAC key loaded from NVS
@@ -160,12 +194,28 @@ BLE: relay ON (seq=1)
 BLE: relay OFF (seq=2)
 ```
 
+**Zonder key (nieuwe/gewiste ESP):**
+```
+=== Atom VoiceS3R BLE Relay ===
+No HMAC key provisioned — connect USB and run SET_KEY
+LED blink done, starting BLE...
+BLE: advertising started as 'AtomS3R-Relay'
+No HMAC key — use USB SET_KEY to provision
+Setup done.
+```
+
+In deze staat accepteert de ESP wel BLE-verbindingen, maar elk HMAC-packet faalt verificatie omdat er geen key is om mee te vergelijken.
+
 ### Uploaden
 
 > **Download-mode:** Houd de reset-knop ~2 seconden ingedrukt tot de groene LED aangaat, laat dan los. Het board is nu in download-mode.
 
 ```bash
+# Flash firmware (behoudt NVS/key)
 pio run --target upload
+
+# Volledig wissen (incl. NVS/key) + opnieuw flashen
+pio run -t erase && pio run -t upload
 ```
 
 Na het uploaden treedt er een harde reset op. Als het board in download-mode blijft, USB eruit/erin of kort op reset tikken om in run-mode te komen.
@@ -180,7 +230,7 @@ Na het uploaden treedt er een harde reset op. Als het board in download-mode bli
 - **BLE Pairing:** De app initieert bonding (`createBond()`) na connectie; Just Works pairing verloopt zonder gebruikersinteractie
 - **MTU negotiatie:** Vraagt MTU 256 aan na service discovery (voor 37-byte HMAC packets)
 - **HMAC authenticatie:** Elk commando wordt ondertekend met HMAC-SHA256 + sequence counter
-- **USB auto-provisioning:** Bij aansluiten van de ESP via USB-OTG genereert de app een key als de ESP er nog geen heeft, of leest de bestaande key uit (BroadcastReceiver)
+- **USB auto-provisioning:** Bij aansluiten van de ESP via USB-OTG leest de app de bestaande key uit, of genereert een nieuwe key als de ESP er nog geen heeft. Beide scenario's tonen de toast _"Beveiligingssleutel gelezen"_ (BroadcastReceiver, werkt ook als app niet actief is)
 - **Instellingenscherm:** Losse Activity voor het invoeren van de HMAC key (met oog-icoon om de key te tonen/verbergen), "Scan & Verbind" knop, en hint-tekst
 - **Permissies:** Vraagt BLUETOOTH_SCAN, BLUETOOTH_CONNECT en ACCESS_FINE_LOCATION aan (Android 12+)
 
@@ -190,7 +240,7 @@ Na het uploaden treedt er een harde reset op. Als het board in download-mode bli
 2. Tik op het **tandwiel-icoon** rechtsboven
 3. De app toont een hint: _"Voer de HMAC sleutel in of sluit de relaismodule aan op de telefoon."_
 4. **Optie A — handmatig:** Voer de 64-teken hex key in. Tik op het **oog-icoon** om de key te tonen/verbergen. Tik **Opslaan**.
-5. **Optie B — automatisch (aanbevolen):** Sluit de ESP via USB-OTG aan op de telefoon. Android vraagt USB-toestemming (1x). De app leest de key uit of genereert een nieuwe als de ESP er nog geen heeft. Toast bevestigt de actie.
+5. **Optie B — automatisch (aanbevolen):** Sluit de ESP via USB-OTG aan op de telefoon. Android vraagt USB-toestemming (1x). De app leest de key uit (als de ESP er al een heeft) of genereert een nieuwe key en provisioneert de ESP. Toast: _"Beveiligingssleutel gelezen"_.
 6. Tik **Scan & Verbind** om op te slaan en direct BLE scannen te starten.
 
 De key wordt opgeslagen in SharedPreferences en overleeft app-herstarts. Bij geen key toont de hoofdapp "Geen HMAC sleutel - open Instellingen" en wordt er niet gescant.
@@ -247,12 +297,22 @@ adb install -r android/app/build/outputs/apk/debug/app-debug.apk
    - Sluit de ESP via USB-OTG aan op de telefoon
    - Android vraagt USB-toestemming (1x) — tik "Toestaan"
    - De app detecteert dat de ESP geen key heeft, genereert er één, en stuurt deze naar de ESP
-   - Toast: "Nieuwe HMAC sleutel gegenereerd en naar ESP geschreven!"
+   - Toast: _"Beveiligingssleutel gelezen"_
    - Ontkoppel de ESP en zet hem op stroom
 
    **Optie B — handmatig:**
    - Open de app → tandwiel-icoon → voer een 64-teken hex key in → Opslaan
-   - Let op: de ESP moet dan dezelfde key hebben (via USB provisioning of handmatig via serial `SET_KEY:<hex>`)
+   - Let op: de ESP moet dan dezelfde key hebben (via USB provisioning of handmatig via serial `SET_KEY:<hex>\n`)
+
+   **Optie C — bestand ESP, nieuwe telefoon:**
+   - Sluit de ESP via USB-OTG aan op de nieuwe telefoon
+   - De app leest de bestaande key uit de ESP en slaat lokaal op
+   - Toast: _"Beveiligingssleutel gelezen"_
+
+   **Nieuwe ESP, bestaande telefoon:**
+   - Wis de app data (instellingen → apps → Atom Relay → storage → clear) of de-installeer en herinstalleer
+   - Sluit de nieuwe ESP via USB aan → app genereert nieuwe key
+   - Let op: de oude key in de app wordt overschreven
 
 4. **Scan & Verbind:** Tik in instellingen op "Scan & Verbind" (of de app scant automatisch bij terugkeren naar het hoofdscherm)
 
@@ -267,19 +327,19 @@ sylvia-touch-relay/
 │   └── main.cpp                # Firmware (BLE + HMAC + NVS key storage + USB serial + sensor + relais)
 ├── android/
 │   ├── build.gradle            # Root Gradle config
-│   ├── settings.gradle         # JitPack repos voor usb-serial-for-android
+│   ├── settings.gradle         # Gradle settings
 │   ├── gradle.properties
 │   ├── gradlew                 # Gradle wrapper
 │   ├── gradle/wrapper/
 │   │   └── gradle-wrapper.properties
 │   └── app/
-│       ├── build.gradle        # App module config (+ usb-serial-for-android dep)
+│       ├── build.gradle        # App module config
 │       └── src/main/
 │           ├── AndroidManifest.xml
 │           ├── java/com/eddy/atomrelay/
 │           │   ├── MainActivity.kt       # BLE client + HMAC signing
 │           │   ├── SettingsActivity.kt    # HMAC key invoer + scan knop
-│           │   └── UsbKeyReceiver.kt     # USB auto-read BroadcastReceiver
+│           │   └── UsbKeyReceiver.kt     # USB key provisioning (raw USB API)
 │           └── res/
 │               ├── drawable/
 │               │   ├── ic_eye_open.xml        # Oog open icoon
@@ -299,9 +359,12 @@ sylvia-touch-relay/
 - G1 en G2 zitten op de HY2.0-4P Grove poort. G5-G8, G38, G39 zitten op de onderste expantie-header.
 - De firmware gebruikt geen M5Unified library — alleen Arduino core + ESP32 BLE + mbedtls. Dit maakt de serial output betrouwbaarder via USB CDC.
 - `ARDUINO_USB_CDC_ON_BOOT=1` is ingeschakeld voor virtuele serial via USB.
-- De HMAC key wordt opgeslagen in NVS (Non-Volatile Storage) via de Arduino `Preferences` library. De key wordt niet meegecompileerd maar via USB provisioning door de Android app op de ESP gezet.
+- De HMAC key wordt opgeslagen in NVS (Non-Volatile Storage) via de Arduino `Preferences` library. De key wordt niet meegecompileerd maar via USB provisioning door de Android app op de ESP gezet. Sleuteloverdracht werkt in beide richtingen: de app kan een key naar de ESP schrijven (nieuwe ESP) of een bestaande key uitlezen (bestaande ESP op nieuwe telefoon).
 - De app gebruikt `WRITE_TYPE_NO_RESPONSE` voor minimale latency — de encryptie en HMAC verificatie gebeuren op de link layer resp. application layer en zijn onafhankelijk van het write type.
 - De sequence counter start bij 1 (niet 0) om te voorkomen dat het eerste packet na connectie als replay wordt geweerd (`0 <= 0` is true in de `seq <= lastSeq` check).
-- Für meerdere ESP modules met verschillende keys: sluit elke ESP één voor één aan op de telefoon. De app genereert per ESP een eigen key en slaat deze op. De app ondersteunt momenteel slechtséén key tegelijk (opgeslagen in SharedPreferences).
+- Für meerdere ESP modules met verschillende keys: sluit elke ESP één voor één aan op de telefoon. De app genereert per ESP een eigen key en slaat deze op. De app ondersteunt momenteel slechts één key tegelijk (opgeslagen in SharedPreferences). Bij wisselen van ESP: wis app data of sluit de nieuwe ESP aan (overschrijft vorige key).
-- De `UsbKeyReceiver` is een manifest-geregistreerde `BroadcastReceiver` voor `ACTION_USB_DEVICE_ATTACHED`. Hij filtert op Espressif (vendor 0x303a), vraagt USB-permission via `PendingIntent`, opent een CDC-ACM serial connectie (115200), stuurt `KEY?\n`, en slaat de respons op. Werkt ook als de app niet actief is.
+- De `UsbKeyReceiver` is een manifest-geregistreerde `BroadcastReceiver` voor `ACTION_USB_DEVICE_ATTACHED`. Hij filtert op Espressif (vendor 0x303a), vraagt USB-permission via `PendingIntent` (FLAG_MUTABLE voor Android 12+), opent een CDC-ACM serial connectie met raw USB API (geen externe library), configureert CDC control interface (line coding + DTR/RTS), en handelt het volledige provisioning-proces af. Werkt ook als de app niet actief is.
-- De `UsbKeyReceiver` doet serial I/O op een achtergrondthread (max 5s timeout per poging, 5 retries) om ANR's te voorkomen.
+- De `UsbKeyReceiver` gebruikt raw Android USB API (`UsbDeviceConnection.bulkTransfer`) in plaats van een externe serial library. Dit vermijdt compatibiliteitsproblemen met de ESP32-S3 USB-JTAG/serial controller die geen CDC `get_status` requests ondersteunt.
+- CDC control interface setup: line coding (115200 8N1) via SET_LINE_CODING request + DTR/RTS via SET_CONTROL_LINE_STATE. Dit activeert de data-flow op de ESP32-S3 CDC-ACM interface voordat commando's worden gestuurd.
+- De `UsbKeyReceiver` doet serial I/O op een achtergrondthread (max 5s timeout per poging, 5 retries met 1s pauze) om ANR's te voorkomen en andere USB-apps te overleven die mogelijk het apparaat tijdelijk claimen.
+- Bij elke retry wordt het ESP-apparaat opnieuw opgezocht via `UsbManager.deviceList` om apparaat-pad-wijzigingen op te vangen.