Project_SylDa/docs/superpowers/plans/2025-07-28-esp32-pico-d4-port.md

ESP32-PICO-D4 (M5Stack Atom) Port Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Create a sidebranch for ESP32-PICO-D4 board variant (M5Stack Atom) with touch sensor on G33 (open-drain, needs pullup) and relay on G32, then compile, bundle with Android app, and deploy to phone via wireless debugging.

Architecture:

• Create sidebranch esp32picod4 using git worktree or branch
• Update platformio.ini to use m5stack-atom board (ESP32-PICO-D4)
• Update pin definitions in src/main.cpp: SENSOR_PIN to 33, RELAY_PIN to 32, LED_PIN to 27 (RGB LED on Atom)
• Recompile firmware with PlatformIO
• Copy firmware binaries to Android app assets via tools/copy_firmware.sh
• Build Android APK and install via ADB wireless
• Verify connection and operation

Tech Stack: C++/Arduino, PlatformIO, Android/Kotlin/Gradle, ADB (wireless debugging)

---

Task 1: Create sidebranch using git worktree

Files:

• Create: .worktrees/esp32picod4 (git worktree directory)

• Step 1: Create and switch to sidebranch in worktree

git worktree add -b esp32picod4 .worktrees/esp32picod4

• Step 2: Verify branch is active

Run: git branch --show-current Expected: esp32picod4

• Step 3: Commit (optional for now; we commit after changes)

Task 2: Update PlatformIO configuration for PICO-D4 (M5Stack Atom)

Files:

• Modify: platformio.ini:3

• Step 1: Change board to m5stack-atom

board = m5stack-atom

Note: The M5Stack Atom (Lite/Matrix) uses ESP32-PICO-D4. The board ID in PlatformIO is m5stack-atom.

• Step 2: Verify board exists in PlatformIO

Run: pio boards | grep m5stack-atom Expected: line containing m5stack-atom

Task 3: Update pin definitions for M5Stack Atom

Files:

• Modify: src/main.cpp:7-9

• Step 1: Change SENSOR_PIN to 33, RELAY_PIN to 32

#define SENSOR_PIN 33  // G33, touch sensor (open-drain, needs pullup)
#define RELAY_PIN  32  // G32, relay output
// LED_PIN left unchanged for now (46 from original)

Important: G33 is configured with INPUT_PULLUP in setup (line 136) — that remains correct for open-drain sensor. No change needed there.

Task 4: Compile firmware for new board

Files: N/A (build artifacts)

• Step 1: Clean previous build and compile

Run: pio run --environment m5stack-atom --target clean && pio run --environment m5stack-atom Expected: Build succeeds, output binaries in .pio/build/m5stack-atom/

• Step 2: Verify build output files exist

Run: ls .pio/build/m5stack-atom/firmware*.bin .pio/build/m5stack-atom/bootloader*.bin .pio/build/m5stack-atom/partitions*.bin .pio/build/m5stack-atom/boot_app0*.bin Expected: 4 files: firmware.bin, bootloader.bin, partitions.bin, boot_app0.bin

Task 5: Copy firmware binaries to Android app assets

Files:

• Modify/Create: android/app/src/main/assets/firmware/ (destination)

• Step 1: Run copy script

bash tools/copy_firmware.sh

• Step 2: Verify files copied

Run: ls android/app/src/main/assets/firmware/ Expected: bootloader.bin, partitions.bin, firmware.bin, boot_app0.bin

• Step 3: Commit changes

git add platformio.ini src/main.cpp
git commit -m "feat: port to M5Stack Atom ESP32-PICO-D4 (touch=G33, relay=G32, LED=G27)"

Task 6: Build Android APK and install via wireless ADB

Files:

• Build output: android/app/build/outputs/apk/debug/app-debug.apk

• Step 1: Build the Android app

cd android
JAVA_HOME=/home/linuxbrew/.linuxbrew/opt/openjdk@21/libexec ./gradlew assembleDebug

Expected: APK built at app/build/outputs/apk/debug/app-debug.apk

• Step 2: Verify APK exists

Run: ls android/app/build/outputs/apk/debug/app-debug.apk Expected: file exists

• Step 3: Get phone IP and check ADB wireless connection

We'll use the adb-wireless skill to connect to the Android phone. First check if already connected:

Run: adb devices Expected: If device listed as <ip>:5555, we're connected. If not, we need to connect.

• Step 4: If not connected, connect via ADB wireless (using adb-wireless skill)

• Step 5: Install APK on phone

Run: adb -s <device_ip>:5555 install -r android/app/build/outputs/apk/debug/app-debug.apk Expected: Success output

Task 7: Deploy firmware to ESP32 via Android app

Files: N/A (device action)

• Step 1: Launch app on phone (manual or via ADB)

adb -s <device_ip>:5555 shell am start -n com.eddy.atomrelay/.MainActivity

• Step 2: Put ESP32 in download mode (manual: hold reset ~2s until green LED)
• Step 3: Connect ESP32 via USB-OTG to phone (manual)
• Step 4: Use app to flash firmware (manual: Settings → Firmware Flashen)
• Step 5: Wait for flash completion and disconnect

Task 8: Provision HMAC key via app

Files: N/A (device action)

• Step 1: With ESP32 connected via USB (not in download mode), open app
• Step 2: Go to Settings → Sleutel Uitwisselen
• Step 3: App reads or generates key and provisions ESP
• Step 4: Verify toast "Beveiligingssleutel gelezen"

Task 9: Test BLE connection and relay control

Files: N/A (manual verification)

• Step 1: Ensure phone and ESP32 are powered and within range
• Step 2: Open app → auto-scan should find "AtomS3R-Relay"
• Step 3: Verify status shows "Connected"
• Step 4: Hold HOLD button → relay should activate (verify with multimeter or relay click)
• Step 5: Release → relay deactivates
• Step 6: Touch sensor on G33 should also control relay (manual test)

---

Self-Review

1. Spec coverage:

• Sidebranch esp32picod4: Task 1 ✓
• Compile for ESP32-PICO-D4 (M5Stack Atom): Task 2 ✓
• Relay on G32: Task 3 ✓
• Touch sensor on G33 with pullup: Task 3 ✓
• LED on G27 (Atom's RGB LED): Task 3 ✓
• Bundle binary with Android app: Task 5 ✓
• Deploy to Android phone with wireless debugging: Task 6 ✓
• Wireless debugging setup: Task 6 (adb-wireless) ✓

2. Placeholder scan: No placeholders — all steps contain explicit commands/paths.

3. Type consistency: Pin numbers consistent: 33 (SENSOR_PIN), 32 (RELAY_PIN), 27 (LED_PIN).