# BoomCast Waveshare ESP32-S3-ePaper-1.54 V2 firmware Arduino sketch for the **non-touch V2** board. This folder started from the owner's `v0.1.0-concept` prototype and has been updated for the BoomCast sensor API. Its original source was supplied by the project owner; no upstream copyright notice was present in the archive. Official Waveshare support is fetched separately and retains its own attribution and component licenses. **Hardware status:** The owner has run earlier firmware on the V2 board. This detector revision has only been checked with synthetic PCM traces and compilation; its microphone sensitivity still needs a physical check. See [physical validation checklist](docs/validation-checklist.md). ## Features - ES8311 microphone capture at 16 kHz through pinned Waveshare support; one fixed stereo slot is selected for mono. The slot assignment still requires playback validation on the real V2 board. - Browser-worklet-aligned RMS/peak sound trigger, up to 8 seconds of rolling pre-trigger audio and a 2-second tail. Early startup captures contain the available pre-roll and keep the intended tail. See [detection parity and calibration](docs/detection-parity.md). - 16-bit mono PCM WAVs saved on microSD with a metadata sidecar. A `.meta` file is the queue commit marker; incomplete or invalid WAVs are not upload eligible. Interrupted commits with valid `.meta.tmp` are recovered on startup. FAT cannot guarantee full power-loss atomicity of multi-file transactions; inspect the queue after hard power cuts. - Wi-Fi setup AP, local owner UI, two ePaper screens, automatic upload retry with bounded backoff, and confirmed-receipt deletion. - CA-verified HTTPS using the ESP32 core's built-in public CA bundle and an ignored local credentials header. No insecure TLS mode is enabled. ## Build and flash 1. Install Arduino IDE 2.x and Espressif ESP32 Arduino core **3.3.12** (the verified version with a built-in CA bundle). 2. Install **ArduinoJson 7.4.3** and Waveshare's `lvgl8/lvgl` **8.4.0** library from the pinned support commit below. Install LVGL 8 only for this sketch. 3. Run `./prepare_from_waveshare.sh`. It fetches only `02_Example/Arduino/08_Audio_Test` from Waveshare commit `aaf395c1bbd86f7c5b7a2f9f0401241ff5c44956`, or accepts a local checkout at that exact commit. The helper copies the board support locally. See [hardware and dependency notes](docs/hardware.md). 4. Copy `boomcast_config.local.example.h` to `boomcast_config.local.h`. Set the HTTPS origin, registered `sensor_id`, and token. This local file is ignored by Git; no certificate needs to be pasted into it. 5. In Arduino IDE **Tools**, select board **ESP32S3 Dev Module**, **Flash Size → 8MB (64Mb)**, **Partition Scheme → 8M with spiffs (3MB APP/1.5MB SPIFFS)**, and **PSRAM → OPI PSRAM**. All four settings are required for this board; the default 4 MB partition allows only a 1.2 MB app and reports `text section exceeds available space in board`. Open `BoomCast_Waveshare_Arduino.ino`, compile, flash, and monitor serial at 115200 baud. An Arduino CLI 1.5.1 compile passed in this workspace with ESP32 core 3.3.12 and these settings; no board was flashed. ## HTTPS trust and renewal The uploader uses `WiFiClientSecure::useBuiltinCACertBundle()` from Espressif's Arduino ESP32 core 3.3.12. The core's public CA bundle is compiled into the firmware, separate from `boomcast_config.local.h` credentials. TLS verifies both the certificate chain and the server hostname. Uploads wait for a successful NTP synchronization after boot, so an unset clock cannot invalidate certificate date checks. If NTP is unavailable, the WAV remains queued for retry. Normal Caddy/Let's Encrypt server-certificate renewals need no firmware change as long as the renewed chain ends at a root in the installed bundle. If Caddy changes to a CA whose root is absent from that bundle, update the Espressif core and recompile/reflash the firmware with its newer bundle after checking that the new core still builds the sketch. Do not put a leaf certificate or private key in the credentials header. Arduino IDE's `HTTPClient` can fall back to insecure TLS when used without a CA; this uploader uses `WiFiClientSecure` directly with the built-in bundle instead. The firmware has not yet been converted to PlatformIO: Waveshare's Arduino support uses a sketch-relative source layout, and a guessed PlatformIO configuration would not be reproducible without a verified V2 build. The pinned preparation script and library versions provide an explicit Arduino build starting point. ## Initial provisioning On first boot, the device generates unique setup-AP and local-management passwords and stores them in NVS. They are printed on USB serial at 115200 baud on boot; keep physical access to the serial port controlled. The sensor token is loaded from the ignored local header, or from an NVS `token` value if provisioned separately. Rotate the sensor token in Django, update the local header, and reflash, or provision the new NVS value through a trusted local maintenance process. Tokens are never logged by this firmware. The local management UI uses HTTP Basic Auth on the device LAN and setup AP. Use trusted local networks; Basic Auth does not encrypt traffic. The Upload queue section can play a queued WAV locally, discard one recording, or clear the backlog after confirmation. Audio preview is authenticated and streams from SD; it does not upload the clip. Discarded clips are permanently removed from the SD card and will not reach Pending Review. Discarding a recording dated today reduces the ePaper's "Vandaag" count; successful uploads still count as captures. Clips saved without a valid clock cannot be matched to a day, so **Reset today count** can clear an old or stale total without deleting recordings. The public ePaper screen retains the short privacy message and gives the today count its own line, while the owner screen shows connectivity, queue count, capture/upload state, and diagnostic counters. The local management UI shows the firmware version reported by the device. ## Server and queue behavior See [API contract](docs/api-contract.md). The firmware sends multipart PCM WAV to `POST /api/pending/`, with sensor ID, stable event ID, captured time or explicit unknown-time state, duration, firmware version, and timing metadata. Files are deleted only after a parseable JSON receipt echoes the exact event ID, a submission UUID, and a valid status. HTTP 200 duplicates are accepted only when `duplicate: true` is present. Outages and ambiguous responses retain the queue item for a later retry. Permanent 4xx responses use a one-hour retry interval so a corrected server configuration can eventually recover. Queue filenames are stable across reboot. The queue selects the oldest eligible filename across the whole directory rather than trusting directory iteration order. It refuses new captures when the configured event limit or SD free-space reserve is reached; it does not overwrite unsent recordings. Free heap and PSRAM metrics are logged before and after acknowledged uploads. ## Known limits The Waveshare codec read API returns an error status but no byte count. A failed read is discarded and aborts an active clip; a successful short read cannot be measured through this wrapper. The selected microphone slot and actual recording quality must be checked on a V2 board. Uploads run in the main loop and may pause the local web UI while a slow request is in progress. FAT multi-file commits and SD flush durability need interruption testing. Physical acceptance remains pending. ### Scheduled monitoring (0.4.0-concept) The local management page now offers persistent weekday/weekend schedules, Amsterdam DST handling, temporary monitoring and a dedicated idle screen. Scheduling defaults to off. Outside configured hours, audio stops and CPU/Wi-Fi power use is reduced while web management stays reachable. Hardware light/deep sleep remains unavailable pending V2 power-hold validation; no board was flashed. See [scheduled monitoring](docs/scheduled-monitoring.md) for behavior, tests and physical validation still required.