70f004c45b
Also un-ignores docs/ directory so project documentation (specs, plans) is tracked in git. Individual research files remain gitignored.
192 lines
6.4 KiB
Markdown
192 lines
6.4 KiB
Markdown
# 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).
|