Files
FireworksApp/SENSOR_FIRMWARE_VALIDATION.md
T

4.8 KiB

Waveshare firmware validation — concept archive

Reviewed BoomCast_Waveshare_Arduino_v0.1.0-concept.zip as supplied. The README targets the non-touch ESP32-S3-ePaper-1.54 V2, but the physical board revision has not been inspected. Waveshare states that V1 and V2 example programs are not interchangeable. Confirm the V2 marking on the PCB before flashing. The official V2 has 8 MiB PSRAM, 8 MiB flash, ES8311 codec, microphone, and microSD slot. The firmware's SDMMC pins 39/40/41 match Waveshare's published pinout for this board.

Source review

  • Microphone and capture: boomcast_audio.cpp uses Waveshare's audio_bsp wrapper and a 16 kHz stereo read, selecting the louder slot per frame for mono. That slot selection is a heuristic; verify actual channel mapping and recorded playback on the board. A 2.5-second PSRAM ring and 2.5-second post-trigger buffer make an intended 5-second capture. The detector uses RMS/peak thresholds and cooldown. The first capture after boot can contain less pre-roll. Return values from audio_playback_read are not checked, so failed or short reads could enter recordings.
  • WAV and storage: boomcast_queue.cpp writes RIFF PCM mono 16-bit headers and a 16 kHz sample rate. Header arithmetic matches the intended sample count. The queue is on FAT microSD, but files are written directly to their final .wav names without a temporary file and atomic rename. Power loss or a full card can leave a truncated item that appears queued; fwrite, fflush, and fclose results are not checked.
  • Network and uploads: boomcast_network.cpp reconnects Wi-Fi and starts NTP. boomcast_uploader.cpp sends a conventional multipart body with CRLF boundaries and a file part. It sends a Bearer header if a token is set. The current fields are event_id, trigger_type, optional detected_at, and file; this does not satisfy the new /api/pending/ contract's sensor_id, captured_at, duration_seconds, or firmware_version. It still targets /fireworks/classify/.
  • TLS and credentials: TLS_ALLOW_INSECURE defaults to true, and the HTTPS client has no CA certificate configured when it is false. SENSOR_TOKEN is in committed-style boomcast_config.h; move it into an ignored local header or provisioned NVS and configure a trusted CA before deployment. The setup AP also uses a fixed prototype password.
  • Retries and duplicate safety: the SD item remains after non-2xx or transport failure, and filename-derived event_id is stable across retries. The main loop only calls the uploader after an explicit local UI sync request; it does not automatically drain the queue after reconnection. The uploader treats any 2xx response as success without parsing the submission ID or status, and deletes the file immediately. Add bounded retry scheduling with backoff, parse the JSON receipt, and delete only after a matching accepted or duplicate receipt.
  • Display and memory: the ePaper shows capture and queue count, plus a transient upload message on the owner screen. It lacks distinct persistent queued, uploading, success, and failure indicators on the display. The upload path allocates the whole WAV plus multipart framing in PSRAM for each request; there is no measured heap or fragmentation data. Measure free and largest contiguous PSRAM before/after repeated uploads and Wi-Fi outages.

Required firmware changes before an end-to-end trial

  1. Confirm the physical V2 revision and use its matching official support files. Do not copy Atom Echo GPIO assignments.
  2. Point at /api/pending/ and send sensor_id, stable event_id, UTC captured_at, measured duration_seconds, firmware_version, and file. Do not send a timestamp until NTP or the RTC is valid; preserve a reliable capture time with the queued file.
  3. Configure CA-backed HTTPS and store the sensor token outside committed source. Reject HTTP on deployed builds.
  4. Write queue items atomically, detect SD write errors, auto-retry with backoff, validate the JSON receipt, and retain files on ambiguous responses.
  5. Show distinct recording, queued, uploading, success, and failure states; log I2S read failures and memory metrics.

Verification status

Automated Django tests cover authenticated submission, storage, classification response handling, duplicate retry, invalid token/sensor/audio, conflict, and classifier outage. A temporary local Django instance was inspected with Playwright at desktop and 390 px mobile width; its Pending Review sensor detail rendered and showed no console errors. No physical Waveshare board was flashed or tested. Microphone fidelity, trigger timing, HTTPS certificate validation, firmware build, offline queue recovery, and on-device RAM stability remain hardware test items. Use a real recording and a controlled Wi-Fi outage for final acceptance.