Added scheduling

This commit is contained in:
Joren de Graaf
2026-10-10 16:03:44 +02:00
parent 7f5ef0b61b
commit c35ac005fb
24 changed files with 896 additions and 39 deletions
@@ -0,0 +1,24 @@
# Detection parity with the browser listener
Reference: `django/frontend/src/scripts/burst-listener-worklet.js` in the same project. The firmware processes each mono PCM sample with the same level-window and trigger state machine. The browser code was not changed.
| Behaviour | Browser reference | ESP32 firmware |
| --- | --- | --- |
| Input | `Float32` mono samples, nominally -1 to +1, at the `AudioContext` rate | ES8311 16-bit stereo at 16 kHz; configured mic slot divided by 32768, then scaled by hardware calibration and the local sensitivity factor |
| Level window | `round(sampleRate / 30)` samples | `round(16000 / 30)` = 533 samples |
| RMS / peak | Square root of mean squared samples; maximum absolute sample in window | Same calculation in normalised units |
| Starting baseline | 0.01 | 0.01 |
| Baseline update | `0.98 * baseline + 0.02 * min(rms, baseline * 2)` while listening and not triggered | Same |
| Trigger | After more than 1 s and more than 3 s since last trigger: `rms > max(0.075, baseline * 5)` **and** `peak > 0.16` | Same sample counts and strict comparisons |
| Tail / clip | 2 s tail, final clip is at most the latest 10 s | 2 s tail, up to 8 s preceding the trigger plus tail, maximum 10 s |
| Resume | User resumes or discards; clears ring and baseline, starts 3 s cooldown | Automatically resumes after saving to SD; clears ring and baseline, starts 3 s cooldown |
The prior firmware used 256-frame (16 ms) windows, independent RMS **or** peak gates, an RMS and peak noise estimate, 3 s boot warmup, 1.5 s cooldown, and 2.5 s before/after the trigger. Those rules have been removed from detection. Its offline queue, upload receipt checks, and WAV format are unchanged.
## Hardware calibration
Shared browser constants are in `boomcast_config.h`. Hardware-only values are in `boomcast_audio_calibration.h`: the Waveshare example's ES8311 input gain is 45 dB, and the additional detection input multiplier starts at 1.0. The local sensitivity control scales the normalised detection input by `setting / 55`; its default 55 means unity. It does not alter the recorded WAV or browser thresholds. Change the hardware multiplier only after measuring representative ambient sound and fireworks on the actual V2 board. Avoid extra noise suppression, which could erase distant impulses.
The browser asks only for one channel in `getUserMedia`; it does not fix sample rate, echo cancellation, noise suppression, or automatic gain control. Browser support and selected values vary by device; [MediaStreamTrack.getSettings()](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getSettings) can expose the actual settings during a physical comparison. Safari/iPhone may apply processing that the ES8311 path does not. The browser's actual track settings and iPhone microphone level/clipping need a device measurement. The firmware's fixed mic slot, codec gain, acoustic response, and clipping also need verification with real V2 recordings. Equal PCM samples prove algorithm timing, not equal acoustic sensitivity.
Run `PATH=/path/to/node:$PATH python -m unittest discover -s arduino/tests -p 'test_detector_parity.py' -v` from the project root for deterministic traces. The test feeds identical 16-bit PCM samples to the compiled C++ detector and the actual unchanged browser worklet, comparing trigger, clip-start, and clip-end sample positions and final baseline across silence, a startup impulse, low-level kitchen activity, one impulse, repeated impulses, and overlap. Physical calibration remains separate.
@@ -0,0 +1,84 @@
# Scheduled monitoring — 0.4.0-concept
Version changes from **0.3.0-concept → 0.4.0-concept**. Scheduling is disabled by default, preserving continuous monitoring until enabled in local management.
## Available behavior
The authenticated management page adds weekday/weekend hours, a saved enable switch, Wi-Fi power preference and a temporary monitoring duration (1–1440 minutes, default 30). Suggested windows are Monday–Friday 12:00–01:00 and Saturday–Sunday 12:00–02:00. Settings are stored as one versioned NVS record. Invalid saved settings fail open to continuous monitoring.
Hours use Europe/Amsterdam and the current EU DST rule. Intervals belong to their starting day: Friday's window ends Saturday at 01:00; Sunday's ends Monday at 02:00. Equal times mean a full calendar day. Overlapping windows form a union, without unnecessary stop/start transitions. A nonexistent spring time moves forward by the skipped hour; an ambiguous autumn start uses its first occurrence and an end its last occurrence. Timezone legislation changes require updating `TZ_INFO` and its tests.
States exposed by `/api/status` under `monitoring`:
- `MONITORING`: listening requested, including while an active recording finishes before suspension. `microphoneActive` separately describes usable microphone input.
- `SCHEDULED_IDLE`: audio task has acknowledged suspension; local management remains available.
- `MANUAL_OVERRIDE`: temporary monitoring requested. The UI shows remaining seconds rounded to minutes. Override expiry uses monotonic time and is unaffected by NTP corrections. Overrides are intentionally not persisted across reboot.
- `SCHEDULED_SLEEP`: reserved; **not entered in this release**. `hardwareSleepSupported` is false.
A normal BOOT click while idle requests an override; during monitoring it still switches display pages. The web page can start an override or return immediately to the schedule. This is resume from idle, not remote wake from hardware sleep. PWR and BOOT-at-reset flashing behavior are not reassigned.
## Time and RTC
NTP uses `configTzTime` so synchronization does not replace Amsterdam with UTC. An NTP callback marks the clock trusted and writes UTC to PCF85063. A persisted `rtc_utc` marker distinguishes this firmware's NTP-set RTC from Waveshare example dates. Reboot restores UTC only if this marker, oscillator integrity, 24-hour/run mode, BCD fields and date are valid. Untrusted time keeps monitoring active and surfaces a fault. Once trusted, scheduling does not require Wi-Fi. Periodic SNTP updates refresh the RTC; failure to write RTC is reported while the current boot's NTP clock remains usable.
TLS still requires this boot's NTP synchronization through the existing uploader check. No CA, credentials or TLS-verification changes are made by this feature.
## Audio and power sequence
1. The main loop requests suspension, but the audio task owns codec operations. An active two-second tail and synchronous SD save complete first.
2. Both record and playback handles are closed. The pinned codec data driver disables both I2S DMA directions, and its ES8311 enable callback requests codec standby. Handles and PSRAM buffers stay allocated for reuse; `deinit_codec()` would also destroy the shared RTC I2C bus and is therefore unsuitable here.
3. The audio task acknowledges suspension and waits 200 ms between checks. The main loop reduces CPU frequency to 80 MHz; Wi-Fi modem sleep is optional. The radio remains connected, so SD uploads can continue during idle.
4. The display renders the static BoomCast/Zzz/SLAAPSTAND layout once, then stops its 5 ms LVGL tick timer. The display task checks at 500 ms; ordinary status refreshes are suppressed while idle. Display power gating is not enabled: the pinned driver lacks a public panel-sleep API, and safely gating SPI pins requires board verification.
5. On resume, CPU frequency is restored before audio is requested. The task reopens both streams, restores gain, clears rolling audio/trigger state, drains one second of input, then applies the detector's existing three-second cooldown. Detection thresholds and event clip lengths are unchanged.
Repeated read failures close/reopen the streams; failed opens retry once per second. Initial driver/task/PSRAM setup failure is diagnosed and requires a reboot using the existing management control. Automatic full driver teardown is deliberately avoided because the RTC shares its bus. The vendor close wrapper does not propagate all lower-level errors; actual DMA/codec shutdown and reopening still need hardware verification.
The existing uploader remains retry-safe and keeps files until a valid receipt. Bulk sends start no further item after a 30-second batch budget; an in-flight request may finish later. Individual transport phases have deadlines (TCP 5 s, TLS handshake 15 s, file transfer 30 s plus an in-progress write, response 60 s). Scheduler checks run between chunks and during response/NTP waits. A synchronous DNS/connect/write or display refresh can still delay a transition; timing is not a hard real-time guarantee. There is no wait for the whole SD queue before suspending audio. No queue entries are discarded by scheduling.
## Hardware inspection and deferred hardware sleep
Reviewed the pinned official Waveshare commit `aaf395c1bbd86f7c5b7a2f9f0401241ff5c44956`, Arduino `11_RTC_Sleep_Test`, including `user_app.cpp`, `src/power/board_power_bsp.cpp`, `user_config.h`, and its SensorPCF85063 driver. Sources:
- https://docs.waveshare.com/ESP32-S3-ePaper-1.54
- https://github.com/waveshareteam/ESP32-S3-ePaper-1.54/tree/aaf395c1bbd86f7c5b7a2f9f0401241ff5c44956/02_Example/Arduino/11_RTC_Sleep_Test
The V2 example identifies PCF85063 INT GPIO 5, BOOT GPIO 0 and PWR GPIO 18 as active-low EXT1 wake sources. It also drives GPIO 17 high before sleeping, holds it, and drops that hold on its PWR wake path. This is materially different from BoomCast's existing GPIO-17 initialization; it cannot be treated as merely an unused measurement rail when implementing hardware sleep. The example alarm helpers overwrite the calendar with a fixed 2025 test date and must not be copied into production scheduling.
Deep sleep, light sleep and RTC alarm programming are **not implemented/enabled** pending a physical V2 power-hold and button validation. RTC calendar retention is implemented; RTC alarms are not used for idle transitions. The ESP32 system clock supplies deadlines while awake. No alarm-success claim is exposed. Deep sleep must eventually combine verified RTC alarm setup/readback/clearing, GPIO wake diagnostics, a timer safety wake, safe SD/display shutdown, and a boot path that restores monitoring. Radio-off sleep cannot offer web wake.
The installed ESP32 core 3.3.12 S3 `qio_opi` SDK configuration does not enable `CONFIG_PM_ENABLE` or tickless idle. This release uses explicit idle CPU scaling and reduced task wake-ups; it does not pretend automatic light sleep is available, change global FreeRTOS configuration, or suspend a CPU core.
Current firmware has no independent heartbeat sender. Django's heartbeat endpoint records last-seen time but has no planned-sleep/expected-wake fields. No Django changes are made. Before radio-off sleep is enabled, extend that contract and its offline presentation; idle in this release remains network-accessible.
## Automated and browser verification
Run from the `arduino` directory:
```sh
g++ -std=c++17 -Wall -Wextra -Werror tests/schedule_test.cpp -o /tmp/boomcast-schedule-test
/tmp/boomcast-schedule-test
g++ -std=c++17 -Wall -Wextra -Werror tests/audio_session_test.cpp -o /tmp/boomcast-audio-session-test
/tmp/boomcast-audio-session-test
python3 tests/test_detector_parity.py
python3 tests/preview_management.py
```
Calendar tests cover weekday/weekend boundaries, overnight attribution, equal-time schedules, spring gaps, autumn repeated hours, disabled scheduling, trusted offline time, invalid time, override policy and reboot-time calculation. The production RTC decoder is checked against stopped/12-hour clocks, oscillator faults, malformed BCD and impossible calendar dates. The actual audio-task lifecycle policy and detector are tested over 100 simulated cycles: capture-drain gating, failed-open retry decisions, repeated read failure, startup input discard and cooldown-spike rejection. These are host simulations, not I2S/SD/NVS hardware tests.
Playwright checks the exact embedded HTML with the preview server's **simulated responses**, at desktop, intermediate and mobile widths. Save, override, return, reload, invalid-time validation, overflow and browser errors are checked. The preview does not execute firmware HTTP handlers or prove device persistence. Native time inputs displayed AM/PM in the browser locale; explicit validated HH:MM inputs fixed that observed issue.
## Physical validation still required — no board flashed
No current draw, wake accuracy or wake-to-listening latency has been measured. No ePaper rendering or physical capture-cycle validation is claimed. Before deployment:
- Flash only with the owner's authorization. Measure active and scheduled-idle current on battery and USB; record board revision and settings. Light/deep-sleep currents are N/A until implemented.
- Run at least 100 idle/resume cycles, inspect playable WAVs, stale-buffer/startup-spike behavior, heap and largest free block, codec/I2S stop/restart, and task watchdog behavior.
- End a window during recording and verify SD file/metadata integrity. Leave queued files through idle, reboot and connectivity loss; verify upload receipts and deduplication after reconnecting.
- Verify NVS persistence across power loss, PCF85063 retention/oscillator-stop detection, offline reboot, NTP recovery, and DST transitions using a controlled clock.
- Measure boundary-to-listening latency and actual recovery after codec initialization/read faults. Do not equate the designed settling/cooldown intervals with a measured wake latency.
- Inspect the 200×200 sleep screen, next-wake legibility, normal-screen restoration, BOOT override, and PWR behavior on the exact non-touch V2.
Final Arduino CLI compile (ESP32 core 3.3.12, ESP32S3 Dev Module, 8 MB flash,
OPI PSRAM, `default_8MB`) succeeded: **1,543,240 bytes / 3,342,336 (46%)**
program storage; **102,032 bytes / 327,680 (31%)** global dynamic memory.
Runtime heap, stack margins and power consumption are not established by this result.
@@ -2,8 +2,9 @@
- [ ] Confirm non-touch V2 marking, 8 MB flash and 8 MB PSRAM, and boot stability.
- [ ] Verify ES8311 microphone initialization and the actual slot assignment using known speech and impulse recordings.
- [ ] Capture and play a five-second WAV; check 16 kHz mono PCM header and duration.
- [ ] Verify 2.5-second pre-trigger and post-trigger content and startup short-preroll behavior.
- [ ] Capture and play a triggered WAV; check 16 kHz mono PCM header and actual duration (up to 10 seconds).
- [ ] Verify up to 8 seconds of pre-trigger content, the 2-second tail, and startup short-preroll behavior.
- [ ] Compare quiet room, kitchen activity, distant fireworks, and close impulses against iPhone Safari at the default sensitivity; note clipping and missed or false triggers before adjusting hardware calibration.
- [ ] Interrupt power during both WAV and metadata writes; verify recovery and that incomplete files never upload.
- [ ] Fill SD card near the configured reserve and confirm a visible error without overwriting queued clips.
- [ ] Verify ePaper listening, recording, queued/offline, uploading, success, retry, and error states.
@@ -13,4 +14,4 @@
- [ ] Disable Wi-Fi during capture and restore it; confirm automatic queue drain and no lost clip.
- [ ] Repeat capture/upload/outage cycles while measuring free heap, PSRAM, largest free PSRAM block, and recovery after failures.
No physical-board test has been performed in this workspace.
This detector revision has not been physically checked in this workspace.