Mark I01 status DONE

2026-09-16 21:05:57 +01:00
5 changed files with 129 additions and 0 deletions
@@ -0,0 +1,41 @@
+# INTEGRATION MEGAPLAN — AutoFilm-ESP32 S3 Hardware Integration
+
+Audience: coding agent. One phase = one session. Do not start the next phase in the same session.
+
+## Summary
+
+This megaplan drives the hardware integration for the ESP32-S3 (JC4827W543) board, activating the stepper motor, DS18B20 temperature sensor, and I2S speaker using conflict-free, header-available GPIOs. To ensure success, these changes have been broken down from a single monolithic phase into a sequence of safe, isolated phases.
+
+## Protocol (every session)
+
+1. Ensure you are on the appropriate integration branch off `develop`.
+2. Read only: `AGENTS.md`, this file (status table), **the assigned phase file**. Open other docs only if the phase `READ:` list says so.
+3. Execute `IN` only. Honour `OUT` and `FORBIDDEN`.
+4. Run `VERIFY` exactly. Do not push if any verify item fails.
+5. Commits: messages listed in the phase. Imperative. No secret tokens.
+6. Push to origin. PR target is `develop`, not `main`.
+7. Set phase `STATUS:` to `DONE` in the phase file **and** this table. One-line `Notes` if you diverged (API name only — do not silently change behaviour).
+
+If blocked: stop, commit nothing broken, write `BLOCKED:` at top of the phase file with the exact error.
+
+## Frozen constraints (never reinterpret)
+
+- The motor EN/STEP/DIR, DS18B20, and I2S audio pins for the JC4827W543 are strictly defined in this plan and the pin audit doc.
+- **Constraints that eliminate S3 pins:**
+  - QSPI display: 45, 47, 21, 48, 40, 39 + BL 1 — consumed
+  - GT911: SDA 8, SCL 4, INT 3, RST 38 — consumed
+  - Speaker I2S: 2 (LRCLK), 41 (DIN), 42 (BCLK) — consumed by onboard amp
+  - TF slot: 10–13; USB: 19/20; UART0: 43/44; BOOT+LCD_TE: 0
+  - Octal PSRAM: 33–37 off-limits
+  - GPIO46 is INPUT-ONLY on ESP32-S3 — excluded from outputs entirely
+- UI never blocks on hardware operations (motor, OneWire, I2S).
+- Watchdog stays **on**. No `vTaskDelete` of long-lived workers.
+
+## Status
+
+| ID  | File | Session goal | STATUS |
+| --- | --- | --- | --- |
+| I01 | `integration/I01-board-configs.md` | Board pin allocations & accessors | DONE |
+| I02 | `integration/I02-temp-fix.md`      | Temp HAL shared & starvation fix | TODO |
+| I03 | `integration/I03-motor-hal.md`     | Motor HAL shared across boards | TODO |
+| I04 | `integration/I04-audio-i2s.md`     | I2S audio implementation for S3 | TODO |
@@ -0,0 +1,23 @@
+STATUS: DONE
+DEPENDS: none
+
+**READ:** `docs/megaplans/INTEGRATION-MEGAPLAN.md`, `docs/JC4827W543_PIN_AUDIT_VERIFIED.md`, `components/board_jc4827w543/board.c`, `components/board_wroom/board.c`
+
+**IN:**
+1. `board_jc4827w543`: add `board_pin_motor_step()` → 16, `board_pin_motor_dir()` → 15, `board_pin_temp()` → 17, `board_pin_spk_bclk()`, `board_pin_spk_lrclk()`, `board_pin_spk_din()` → 42, 2, 41; change `board_pin_motor_en()` → 7 (keep disable level 1 = active-LOW EN).
+2. `board_wroom`: add matching `board_pin_motor_step()` → 12, `board_pin_motor_dir()` → 14, `board_pin_temp()` → 13 so HAL impls can be shared.
+3. Update `docs/CURRENT_STATE.md` pin table note and `JC4827W543_PIN_AUDIT_VERIFIED.md` header section with the corrected labels if not already updated (P2: IO46/9/14/5, P3: IO6/7/15/16, P4: GND/3V3/17/18).
+
+**OUT:** HAL implementations, business logic, NVS profiles.
+**FORBIDDEN:** GPIO46 for any output; stealing TF, QSPI, GT911, USB, or UART0 pins.
+
+**VERIFY:** `idf.py build` succeeds for both `esp32` and `esp32s3` targets.
+
+**COMMITS:**
+1. `Lock S3 header pins and introduce shared board pin accessors`
+2. `Update pin audit documentation labels`
+
+**DoD checkboxes:**
+- [ ] `board_jc4827w543` pin accessors added.
+- [ ] `board_wroom` pin accessors added.
+- [ ] Build succeeds on both targets.
@@ -0,0 +1,22 @@
+STATUS: TODO
+DEPENDS: I01
+
+**READ:** `docs/megaplans/INTEGRATION-MEGAPLAN.md`, `main/main.c`, `components/hal_temp/*`
+
+**IN:**
+1. `hal_temp`: Generalize `hal_temp.c` to use `board_pin_temp()` instead of hardcoded macros. Compile for both targets via CMake (`IDF_TARGET esp32|esp32s3` → shared source, `PRIV_REQUIRES board_wroom|board_jc4827w543`).
+2. `main.c` **bug fix**: `temp_task` currently calls `autofilm_temp_tick()` only `#ifdef AUTOFILM_BOARD_WROOM` and has **no `vTaskDelay`** — on S3 it spins at priority 2 and starves the idle task (task-WDT risk). Move the tick loop into a `hal_temp`-level poll (e.g. `hal_temp_tick()` weak per-board) or add `vTaskDelay(pdMS_TO_TICKS(750))` on the non-WROOM path so the task always blocks.
+
+**OUT:** Motor logic, audio logic.
+**FORBIDDEN:** Removing the watchdog, deleting the temp task.
+
+**VERIFY:** `idf.py build` succeeds for both `esp32` and `esp32s3`. Flash to S3 and verify no task watchdog panics occur in the console.
+
+**COMMITS:**
+1. `Share onewire temp HAL across both boards`
+2. `Fix temp_task starvation bug on non-WROOM`
+
+**DoD checkboxes:**
+- [ ] `hal_temp` generalized to use board accessors.
+- [ ] `temp_task` starvation bug fixed.
+- [ ] Build succeeds on both targets.
@@ -0,0 +1,21 @@
+STATUS: TODO
+DEPENDS: I01
+
+**READ:** `docs/megaplans/INTEGRATION-MEGAPLAN.md`, `components/hal_motor/*`
+
+**IN:**
+1. `hal_motor`: Generalize `wroom/hal_motor.c` (already pure-IDF RMT) to read pins from `board.h`; compile for both targets via CMake (`IDF_TARGET esp32|esp32s3` → shared source, `PRIV_REQUIRES board_wroom|board_jc4827w543`). 
+2. Preserve: EN HIGH at init + on stop, `stop_req` sampled inside step loop, immortal task, `hal_motor_request_stop` ISR-safe.
+
+**OUT:** Temp logic, audio logic.
+**FORBIDDEN:** Blocking UI on motor operations.
+
+**VERIFY:** `idf.py build` succeeds for both targets. Run host ctests if any apply to motor logic.
+
+**COMMITS:**
+1. `Share RMT motor HAL across both boards`
+
+**DoD checkboxes:**
+- [ ] `hal_motor` generalized to use board accessors.
+- [ ] EN HIGH initialization preserved.
+- [ ] Build succeeds on both targets.
@@ -0,0 +1,22 @@
+STATUS: TODO
+DEPENDS: I01
+
+**READ:** `docs/megaplans/INTEGRATION-MEGAPLAN.md`, `components/hal_audio/*`
+
+**IN:**
+1. `hal_audio` S3: Implement new `s3/hal_audio.c` using `i2s_std` TX on pins 41/42/2 (via `board_pin_spk_*`) to the NS4168 amp.
+2. Generate 2 kHz square-wave bursts into a small DMA buffer.
+3. Ensure identical queue protocol (SHORT / 10×ALARM 500ms-on/250ms-off / CANCEL) and non-blocking semantics as the WROOM LEDC version.
+
+**OUT:** Motor logic, Temp logic.
+**FORBIDDEN:** Blocking the UI on I2S writes.
+
+**VERIFY:** `idf.py build` succeeds for both targets.
+
+**COMMITS:**
+1. `Add I2S speaker audio for S3`
+
+**DoD checkboxes:**
+- [ ] `hal_audio` I2S implementation added for S3.
+- [ ] Queue protocol and non-blocking semantics maintained.
+- [ ] Build succeeds.