AutoFilm-ESP32/docs/megaplans/INTEGRATION-MEGAPLAN.md

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