Skip to content

feat(esp): evidence-based loopTask stack bound + ADR-034 (closes #276) - #280

Draft
cofade wants to merge 1 commit into
mainfrom
fix/276-loop-task-stack-evidence
Draft

feat(esp): evidence-based loopTask stack bound + ADR-034 (closes #276)#280
cofade wants to merge 1 commit into
mainfrom
fix/276-loop-task-stack-evidence

Conversation

@cofade

@cofade cofade commented Sep 2, 2026

Copy link
Copy Markdown
Collaborator

Completes issue #276: the stack-budget fix merged in #277 cleared the observed overflow, but 16384 was an unmeasured bound. This branch turns it into an evidence-backed, permanently instrumented budget.

What ships

  • Firmware instrumentation (ESP32-CAM.ino) — permanent [stack] loopTask high-water-mark log line after every heavy stage: ota_manifest, geolocation, register, boot_heartbeat, setup_complete, and first_upload (loop()). uxTaskGetStackHighWaterMark(NULL) reports the running minimum of the loopTask, so each stage's line both records and attributes the peak.
  • Measured evidence (real hardware) — bench ESP32-CAM (MAC 68:09:47:60:33:08), production URLs, miner seq 9, on 2026-09-02:
  • ADR-034 — decision: one global loopTask budget + per-boot instrumentation, not a per-call-site dedicated TLS task.
  • Docs — esp-reliability section 9 measured numbers; firmware-release checklist re-verify now greps the [stack] lines (with the first_upload success-only caveat); chapter 10 names the hardware smoke-flash as the only gate for this defect class; chapter-11 lesson updated from "not a measured bound" to measured; troubleshooting healthy-boot signature includes the watermark.

Gates

  • pio run -e esp32cam: green
  • pio test -e native: 291/291 (WSL host gcc)
  • check-doc-citations: 0 problems; check-agent-context: OK
  • Senior-reviewer: 3 rounds, clean (no P0/P1), explicitly no further rounds needed

Not in this PR

Manual test needed: none beyond the hardware measurement already performed; the release checklist's bench-boot re-verify covers the ongoing tripwire.

The SET_LOOP_TASK_STACK_SIZE(16384) fix (#276) cleared the observed
overflow but was an unmeasured bound. Add permanent per-stage
uxTaskGetStackHighWaterMark(NULL) instrumentation printed after every heavy
setup() stage and the first loop() upload, and record the measured evidence:

- hardware: bench ESP32-CAM 68:09:47:60:33:08, production URLs, miner seq 9
- watermark reached 6428 of 16384 bytes free during the OTA-manifest TLS
  fetch (the #276 crasher); no later stage took it lower (live Google TLS
  handshake, registration, boot heartbeat, first upload)
- TLS path runs ~3.6 KB deeper than the no-TLS baseline (10048 free)
- ~9.96 KB peak, ~6.4 KB headroom -> 16384 stays, now evidence-backed

Also ships ADR-034 (one global loopTask budget, no dedicated TLS task),
esp-reliability section 9 with the measured numbers, a release-checklist
re-verify step that greps the [stack] lines, chapter-10 acknowledgement
that only a hardware smoke-flash gates this defect class, an updated
chapter-11 lesson, and a healthy-boot signature extension in
troubleshooting.

No SEQUENCE/VERSION bump: reaching the field is the separate
SEQUENCE-bumped OTA release (firmware-release.md), part of the #231
package; this instrumentation rides it.

For #276.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant