4.4 KiB
Waveshare V2 firmware integration status
The owner has confirmed a non-touch Waveshare ESP32-S3-ePaper-1.54 V2 board. The firmware now lives at ../arduino/BoomCast_Waveshare_Arduino/; that folder is currently outside the Django Git worktree (django/). Its sketch, build guide, source, pinned preparation script, local-config example, ignore rules, and hardware/API/checklist documents are there.
The official Waveshare support was inspected at commit aaf395c1bbd86f7c5b7a2f9f0401241ff5c44956. The Arduino audio board_cfg.h and explicitly V2 ESP-IDF audio example agree on ES8311 I2S pins. The official Arduino SD example uses CLK/D0/CMD 39/40/41. The firmware uses those pins. Waveshare documents V2 as 8 MB flash and 8 MB PSRAM and says V1/V2 examples are not interchangeable.
Implemented in source
- Audio reads now check the codec return code, clear input buffers first, discard failed blocks, abort a capture after a read error, select one fixed microphone slot, and count read/recording errors. Capture duration uses the available pre-roll plus the requested post-roll; UTC capture-start and trigger timestamps are retained when time is valid.
- SD commits use checked WAV and sidecar writes, flush/fsync/close, WAV length/header validation, final renames, interrupted-commit recovery, a queue commit marker, oldest-first selection across the directory, an event-count cap, and a free-space reserve. Incomplete files are excluded from upload.
- Uploads stream file contents through
WiFiClientSecurewith a trusted CA, require HTTPS, send the actual/api/pending/fields, parse JSON receipts, verify the echoed event ID and submission ID, and retain files after ambiguous responses. Automatic retries use bounded exponential backoff and jitter. Source-embedded token placeholders were replaced with an ignored local header and optional NVS token; shared setup and management passwords were replaced with per-device NVS passwords. - ePaper owner status reflects listening, recording, queue/offline, uploading, successful submission, retry failure, and audio error counters.
- Django now returns
event_idin first and duplicate receipts and accepts an explicittime_state=unknownwhen the device clock was not synchronized. The same Pending Review and classifier pipeline remains in use.
Verification performed
- Official Waveshare pin/support comparison at the pinned commit.
- The pinned
prepare_from_waveshare.shcompleted successfully against a checkout at that commit. - Arduino CLI 1.5.1 compiled the sketch for ESP32-S3 with ESP32 core 3.3.0, 8 MB flash, OPI PSRAM, and the 8 MB partition scheme. The only emitted warnings were in copied Waveshare support and Espressif touch APIs.
- The
fireworks_detectDjango suite passed: 39 tests. Firmware-shaped unknown-time and receipt fields have focused backend tests. - Firmware
.gitignorepatterns were checked for local credentials, copied support, and build artifacts.
Still open
- Firmware compile passed; no flash was performed. Arduino CLI 1.5.1 compiled the sketch with ESP32 core 3.3.0, Waveshare support at the pinned commit, LVGL 8.4.0, ArduinoJson 7.4.3, 8 MB flash, and OPI PSRAM. The build reports 1,350,599 bytes of program storage (40%) and 99,368 bytes of global dynamic memory (30%). Device runtime RAM use is unmeasured.
- No physical V2 test was performed. The fixed microphone slot, actual audio fidelity, short successful codec reads, ePaper refresh, SD power-cut behavior, TLS handshake, and offline recovery need the real board.
- Waveshare's codec API reports read success/failure but not a byte count; a successful short read cannot be detected through the current wrapper.
- FAT does not provide an atomic transaction spanning WAV and sidecar. Valid interrupted commits are recovered; incomplete/orphan files remain on SD for manual inspection rather than being uploaded or overwritten.
- The uploader currently runs synchronously in the main loop. During a slow HTTPS attempt, the local web UI and display update may pause. Verify this on hardware and move upload to a worker task if it affects usability or watchdog health.
- Arduino source is not tracked by the current Django Git repository. Decide on a project-wide repository or a dedicated firmware repository before relying on source control for deployment.
See ../arduino/BoomCast_Waveshare_Arduino/docs/validation-checklist.md for the pending physical acceptance checks. Do not treat this source review or the Django tests as hardware validation.