# Sylvia Touch Relay BLE-gestuurde relais-switch voor de M5Stack Atom VoiceS3R (ESP32-S3) met een bijbehorende Android-app. Het relais kan worden bediend via een capacitieve touch-sensor (open-drain) óf via Bluetooth Low Energy vanaf een Android-telefoon. De BLE-verbinding is beveiligd met **twee lagen**: BLE Just Works pairing (link-layer encryptie) en **HMAC-SHA256 authenticatie** (application-level handtekening met replay-protectie). ## Hardware | Component | Details | |---|---| | Board | M5Stack Atom VoiceS3R (SKU: C126-ECHO) | | SoC | ESP32-S3-PICO-1-N8R8 (8MB Flash, 8MB PSRAM) | | Touch sensor | Open-drain sensor op **G38** (3.3V, interne pullup) | | Relais / LED | Op **G1** (3.3V GPIO output) | | Status LED | Op **G46** (knippert 3x bij opstarten) | ### Pinout (Atom VoiceS3R onderste header) ``` G38 G39 3.3V GND 5V G5 G6 G7 G8 ``` - **G38** — Touch sensor input (active LOW, interne pullup ingeschakeld) - **G1** — Relais output (HIGH = aan, LOW = uit) - **G46** — Status LED (3x knipperen bij opstarten, daarna uit) ### Aansluiting ``` Sensor GND → GND Sensor OUT → G38 Sensor VCC → 3.3V Relais + → G1 Relais - → GND ``` > **Let op:** De ESP32-S3 interne pullup is ~45kΩ. Bij lange draden of elektrische ruis een externe 4.7kΩ–10kΩ pullup naar 3.3V plaatsen. ## Beveiliging De relay is beveiligd tegen ongeautoriseerde toegang via twee onafhankelijke lagen: ### 1. BLE Just Works Pairing (link-layer encryptie) - De ESP32 vereist **bonding** voordat de characteristic geschreven kan worden - IO capability: `ESP_IO_CAP_NONE` (Just Works — geen passcode nodig) - Authentication mode: `ESP_LE_AUTH_REQ_SC_BOND` (LE Secure Connections met bonding) - De characteristic heeft `ESP_GATT_PERM_WRITE_ENCRYPTED` — writes worden alleen geaccepteerd over een versleutelde link - Na de eerste keer paren onthoudt de telefoon de bonding; bij herverbinding wordt de link automatisch versleuteld ### 2. HMAC-SHA256 Authenticatie (application-level) Omdat BLE Just Works geen MITM-bescherming biedt, is er een tweede laag toegevoegd: - 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 #### Packet formaat (37 bytes) ``` Offset Grootte Veld Beschrijving 0 1 byte command 0x01 = relais aan, 0x00 = relais uit 1 4 bytes sequence Big-endian uint32, strikt oplopend (start bij 1) 5 32 bytes hmac HMAC-SHA256(key, command || sequence) ``` De sequence counter reset naar 0 bij elke (re)connectie op de ESP. De app start bij 1 om te zorgen dat het eerste packet altijd geaccepteerd wordt (`1 > 0`). Replay van een eerder packet wordt geweerd omdat `seq <= lastSeq`. #### Key management - 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 (survives reboots en power-cycles) - De app slaat de key op in **SharedPreferences** (overleeft app-herstarts) - **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:` → 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:\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) - Zo kan dezelfde app gebruikt worden voor meerdere ESP modules — each met een eigen key #### USB Serial Protocol ``` App → ESP: KEY?\n ESP → App: HMAC_KEY:C3F17B...AF\n (als key bekend) ESP → App: NO_KEY\n (als ESP nog geen key heeft) App → ESP: SET_KEY:C3F17B...AF\n (nieuwe key schrijven) 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:`) 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:\n │ App saves to prefs → toast │ └─ if no key ──────► NO_KEY\n Generate 32 random bytes │ Send SET_KEY:\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 | |---|---| | **Sniffen** | BLE link encrypted (AES-CCM via Just Works) | | **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 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 De firmware is geschreven in C++ met behulp van PlatformIO en de Arduino-framework. BLE wordt verzorgd door de ESP32 BLE library, HMAC door mbedtls (ingebouwd in ESP-IDF). ### Logica Het relais gaat aan als **één van beide** bronnen actief is: | Bron | Voorwaarde | Resultaat | |---|---|---| | Touch sensor | G38 = LOW (aanraken) | Relais aan | | BLE command | App stuurt HMAC-ondertekend `0x01` | Relais aan | | Geen van beide | G38 = HIGH + geen BLE command | Relais uit | De touch sensor en BLE werken onafzankelijk. Als de sensor losgelaten wordt en de BLE-knop niet ingedrukt is, gaat het relais uit. ### BLE GATT | Eigenschap | UUID | |---|---| | Service | `4fafc201-1fb5-459e-8fcc-c5c9c331914b` | | Characteristic | `beb5483e-36e1-4688-b7f5-ea07361f26d8` | De characteristic ondersteunt `WRITE` (encrypted) en `NOTIFY`. Writes vereisen een versleutelde link (bonding) plus HMAC-authenticatie. ### Key provisioning De firmware wordt zonder HMAC key gecompileerd. Bij de eerste opstart print de ESP: ``` No HMAC key provisioned — connect USB and run SET_KEY ``` Sluit de ESP via USB aan op de telefoon met de app geinstalleerd. De app genereert automatisch een willekeurige key en stuurt deze naar de ESP. Na provisioning print de ESP bij opstarten: ``` 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. **Met geprovisioneerde key:** ``` === Atom VoiceS3R BLE Relay === HMAC key loaded from NVS LED blink done, starting BLE... BLE: advertising started as 'AtomS3R-Relay' HMAC Key: C3F17B612B93E82C56B055FA9B04E84664ACE1EC4E889F2763F271B65A5B54AF Setup done. [heartbeat] relay=OFF touch=no ble=disconnected BLE: device connected Relay ON (touch=YES, ble=connected) 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. ## Android App ### Features - **Auto-connect:** De app scant automatisch bij opstarten naar het BLE-apparaat "AtomS3R-Relay" - **Auto-reconnect:** Bij wegvallen van de verbinding wordt na 2 seconden opnieuw gescant - **Hold-to-activate:** Houd de knop ingedrukt voor relais aan, loslaten voor relais uit (zelfde gedrag als de sensor) - **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 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+) ### Instellingenscherm 1. Open de app 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 (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. ### Hoofdscherm UI - **Tandwiel-icoon** rechtsboven → opent instellingenscherm - **HOLD-knop** centrum → houd ingedrukt voor relais aan - **Status tekst** linksonder (14sp) → toont verbindingsstatus ### Bouwen Vereisten: - Android SDK (API 34+) - Java 17+ (Java 26 werkt niet met Gradle 8.5 — gebruik Java 21) - Gradle 8.2.2 (via wrapper) - USB host support (raw Android USB API, geen externe library) ```bash cd android JAVA_HOME=/pad/naar/jdk21 ./gradlew assembleDebug ``` De APK staat na build in `android/app/build/outputs/apk/debug/app-debug.apk`. ### Installeren ```bash adb install -r android/app/build/outputs/apk/debug/app-debug.apk ``` Of via draadloze foutopsporing: ```bash adb connect : adb install -r android/app/build/outputs/apk/debug/app-debug.apk ``` ## Eerste keer setup 1. **Flash de ESP:** ```bash pio run -t upload ``` 2. **Installeer de app op de telefoon:** ```bash adb install -r android/app/build/outputs/apk/debug/app-debug.apk ``` 3. **Provision de HMAC key (kies één):** **Optie A — USB auto-provisioning (aanbevolen):** - 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: _"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:\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) 5. De app scant, paart (Just Works), en verbindt. Houd de HOLD-knop ingedrukt om het relais te schakelen. ## Projectstructuur ``` sylvia-touch-relay/ ├── platformio.ini # PlatformIO configuratie (ESP32-S3) ├── src/ │ └── main.cpp # Firmware (BLE + HMAC + NVS key storage + USB serial + sensor + relais) ├── android/ │ ├── build.gradle # Root Gradle config │ ├── settings.gradle # Gradle settings │ ├── gradle.properties │ ├── gradlew # Gradle wrapper │ ├── gradle/wrapper/ │ │ └── gradle-wrapper.properties │ └── app/ │ ├── 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 key provisioning (raw USB API) │ └── res/ │ ├── drawable/ │ │ ├── ic_eye_open.xml # Oog open icoon │ │ ├── ic_eye_closed.xml # Oog dicht icoon │ │ └── ic_settings.xml # Tandwiel icoon │ ├── layout/ │ │ ├── activity_main.xml # Hoofd UI (FrameLayout) │ │ └── activity_settings.xml # Key invoer + scan UI │ └── values/strings.xml ├── .gitignore └── README.md ``` ## Technische notities - De Atom VoiceS3R gebruikt de ES8311 audio codec op G45/G0/G48/G4/G3/G17/G11, IR TX op G47, en de knop op G41. Deze pinnen zijn niet beschikbaar voor eigen gebruik. - 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. 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). 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` (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` 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.