BoomCast Waveshare ESP32-S3-ePaper-1.54 V2 firmware
Arduino sketch for the non-touch V2 board. This folder is the imported v0.1.0-concept prototype, 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. The top-level arduino/ folder is outside the current Django Git repository (django/), so include this firmware folder when establishing a project-wide repository or firmware repository.
Hardware status: The owner has confirmed V2, but no physical board has been flashed or tested in this workspace. See physical validation checklist.
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.
- RMS/peak sound trigger, approximately 2.5 seconds of rolling pre-trigger audio and 2.5 seconds of post-trigger audio. Early startup captures contain the available pre-roll and keep the intended post-trigger interval.
- 16-bit mono PCM WAVs saved on microSD with a metadata sidecar. A
.metafile is the queue commit marker; incomplete or invalid WAVs are not upload eligible. Interrupted commits with valid.meta.tmpare 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
- Install Arduino IDE 2.x and Espressif ESP32 Arduino core 3.3.12 (the verified version with a built-in CA bundle).
- Install ArduinoJson 7.4.3 and Waveshare's
lvgl8/lvgl8.4.0 library from the pinned support commit below. Install LVGL 8 only for this sketch. - Run
./prepare_from_waveshare.sh. It fetches only02_Example/Arduino/08_Audio_Testfrom Waveshare commitaaf395c1bbd86f7c5b7a2f9f0401241ff5c44956, or accepts a local checkout at that exact commit. The helper copies the board support locally. See hardware and dependency notes. - Copy
boomcast_config.local.example.htoboomcast_config.local.h. Set the HTTPS origin, registeredsensor_id, and token. This local file is ignored by Git; no certificate needs to be pasted into it. - 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. OpenBoomCast_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 discard one recording or clear the backlog after confirmation; 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, while the owner screen shows connectivity, queue count, capture/upload state, and diagnostic counters.
Server and queue behavior
See API contract. 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.