# 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**

```bash
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**

```ini
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**

```cpp
#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
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**

```bash
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**

```bash
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)

```bash
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).