Files
FireworksApp/SENSOR_FIRMWARE_VALIDATION.md
T
2026-10-10 16:03:14 +02:00

33 lines
4.4 KiB
Markdown

# 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 `WiFiClientSecure` with 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_id` in first and duplicate receipts and accepts an explicit `time_state=unknown` when 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.sh` completed 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_detect` Django suite passed: 39 tests. Firmware-shaped unknown-time and receipt fields have focused backend tests.
- Firmware `.gitignore` patterns 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.