From cbbdd25ebb59b81455187188a5ede3ab576d2908 Mon Sep 17 00:00:00 2001 From: Peter Woolery Date: Thu, 16 Apr 2026 22:06:59 -0700 Subject: [PATCH] docs(spec): document server-push runtime tuning in design spec Reflects the feature shipped on this branch: backend can push per-device CV tuning in the heartbeat response, device validates + persists to NVS. Removes the stale line_offset row from the operator-provisioning table (moved into CVTuning, server-managed). Also adds .agent/, firmware/.pio/, and graphify-out/ to .gitignore so local working dirs and build artifacts don't get accidentally tracked. Co-Authored-By: Claude Opus 4.7 (1M context) --- .gitignore | 3 +++ docs/superpowers/specs/2026-04-13-door-counter-design.md | 9 +++++++-- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index e458ed5..6e2b65e 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,4 @@ .worktrees/ +.agent/ +firmware/.pio/ +graphify-out/ diff --git a/docs/superpowers/specs/2026-04-13-door-counter-design.md b/docs/superpowers/specs/2026-04-13-door-counter-design.md index aca28f4..f0d8235 100644 --- a/docs/superpowers/specs/2026-04-13-door-counter-design.md +++ b/docs/superpowers/specs/2026-04-13-door-counter-design.md @@ -12,7 +12,7 @@ ``` [TimerCamera-F Device] ├── Provisioning module — captive portal AP on first boot - ├── Config store — NVS: device_id, location_id, HMAC secret, WiFi creds, line_offset + ├── Config store — NVS: device_id, location_id, HMAC secret, WiFi creds, CV tuning (server-pushed) ├── Camera + CV module — captures frames, runs line-crossing counter ├── BLE scanner — continuous passive scan (WiFi coexistence mode) ├── Report buffer — accumulates counts in RAM, flushes hourly @@ -65,7 +65,12 @@ Writes directly to NVS over serial. WiFi credentials are optional — if omitted | `hmac_secret` | Operator | Yes | | `wifi_ssid` | User/operator | Yes | | `wifi_pass` | User/operator | Yes | -| `line_offset` | Default 50% | No | + +CV tuning (`cv_diff`, `cv_blob`, `cv_move`, `cv_miss`, `cv_line`, `cv_ver`) lives in the same namespace but is set at runtime by the backend via heartbeat-response push — see §2.1. On first boot with no pushed config, compiled defaults apply. + +### 2.1 Runtime tuning (server push) + +The backend may include a `config` object in the `POST /api/v1/heartbeat` response to update per-device CV parameters. The device validates, persists to NVS, and applies atomically under mutex. Stale (`cfg_version ≤ stored`), malformed, or out-of-range updates are rejected. See `README.md` → "Runtime Configuration" for the full wire contract, field ranges, and trust-model caveat (plain HTTP; HMAC signs requests only). ### Factory reset