Merge board-detect: firmware-identifying beacon, version-aware install, multi-board builds (v0.6.0)

Author: tarikbc

.github/workflows/build.yml

@@ -36,7 +36,7 @@ jobs:
           path: flipper/flytrap/dist/flytrap.fap
 
   esp32-firmware:
-    name: Build ESP32-S2 firmware
+    name: Build ESP32 firmware (S2, WROOM, C5)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -45,23 +45,52 @@ jobs:
           mkdir -p "$HOME/bin"
           curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR="$HOME/bin" sh
           echo "$HOME/bin" >> "$GITHUB_PATH"
-      - name: Install esp32 core + async libs
+      - name: Fetch async libs (maintained ESP32Async forks)
+        # The unmaintained me-no-dev forks don't build on the 3.x core the C5 needs.
+        # The ESP32Async forks build on both the pinned 2.0.17 (S2/WROOM) and 3.x (C5).
+        run: |
+          mkdir -p esp32/libs
+          git clone --depth 1 --branch v3.3.2 https://github.com/ESP32Async/AsyncTCP.git esp32/libs/AsyncTCP
+          git clone --depth 1 --branch v3.6.0 https://github.com/ESP32Async/ESPAsyncWebServer.git esp32/libs/ESPAsyncWebServer
+      - name: Install esp32 core 2.0.17 (S2/WROOM)
         run: |
           arduino-cli config init --overwrite
           arduino-cli config set board_manager.additional_urls https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
           arduino-cli core update-index
           arduino-cli core install esp32:esp32@2.0.17
-          mkdir -p esp32/libs
-          git clone --depth 1 https://github.com/me-no-dev/AsyncTCP.git esp32/libs/AsyncTCP
-          git clone --depth 1 https://github.com/me-no-dev/ESPAsyncWebServer.git esp32/libs/ESPAsyncWebServer
-      - name: Compile firmware
+      - name: Compile S2 + WROOM (core 2.0.17)
+        # These stay pinned to 2.0.17 (different WiFi/USB behaviour on 3.x). The C5
+        # install below REPLACES this core, so these must build first. The S2 images
+        # go to build/ (flat) because build-fap.sh and the fap bundle that exact path.
         run: |
           arduino-cli compile \
             --fqbn esp32:esp32:esp32s2:PartitionScheme=huge_app \
             --libraries esp32/libs \
             --output-dir esp32/flytrap-fw/build \
             esp32/flytrap-fw
+          arduino-cli compile \
+            --fqbn esp32:esp32:esp32 \
+            --libraries esp32/libs \
+            --output-dir esp32/flytrap-fw/build-wroom \
+            esp32/flytrap-fw
+      - name: Compile C5 (core 3.3.11)
+        # The C5 only exists in the 3.x line. Installing it REPLACES 2.0.17, so this
+        # runs after the S2/WROOM builds. This is the guard that keeps the firmware
+        # 3.x-clean (see onStaIp's ESP_ARDUINO_VERSION_MAJOR branch). CDCOnBoot stays
+        # default so Serial is UART0 -- the pins the Flipper talks to.
+        run: |
+          arduino-cli core install esp32:esp32@3.3.11
+          arduino-cli compile \
+            --fqbn esp32:esp32:esp32c5:PartitionScheme=huge_app,CDCOnBoot=default \
+            --libraries esp32/libs \
+            --output-dir esp32/flytrap-fw/build-c5 \
+            esp32/flytrap-fw
       - uses: actions/upload-artifact@v4
+        # Only the S2 images are consumed downstream: the flipper-app job unpacks this
+        # artifact straight into esp32/flytrap-fw/build/ and build-fap.sh bundles the S2
+        # images from there. The WROOM/C5 compiles above are 3.x/board build guards --
+        # release.yml is what ships their images. Keep this S2-only so the artifact root
+        # stays esp32/flytrap-fw/build (a multi-dir upload would nest it and break the fap).
         with:
           name: flytrap-firmware
           path: esp32/flytrap-fw/build/*.bin

.github/workflows/release.yml

@@ -17,9 +17,10 @@ jobs:
       - uses: actions/checkout@v4
 
       # ESP build runs first, on the runner's system Python (which has pyserial
-      # for the core's esptool). A setup-python before this would shadow it and
-      # break esptool with "No module named 'serial'".
-      - name: Build ESP32-S2 firmware
+      # for the core's esptool elf2image step). A setup-python before this would
+      # shadow it and break arduino-cli's image step with "No module named 'serial'".
+      # tools/merge-image.py is stdlib-only, so the merges below are unaffected.
+      - name: Build ESP32 firmware (S2, WROOM, C5)
         run: |
           mkdir -p "$HOME/bin"
           curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR="$HOME/bin" sh
@@ -28,14 +29,53 @@ jobs:
           arduino-cli config set board_manager.additional_urls https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
           arduino-cli core update-index
           arduino-cli core install esp32:esp32@2.0.17
+          # Maintained ESP32Async forks build on both the pinned 2.0.17 (S2/WROOM)
+          # and the 3.x core the C5 needs; the me-no-dev forks don't build on 3.x.
           mkdir -p esp32/libs
-          git clone --depth 1 https://github.com/me-no-dev/AsyncTCP.git esp32/libs/AsyncTCP
-          git clone --depth 1 https://github.com/me-no-dev/ESPAsyncWebServer.git esp32/libs/ESPAsyncWebServer
+          git clone --depth 1 --branch v3.3.2 https://github.com/ESP32Async/AsyncTCP.git esp32/libs/AsyncTCP
+          git clone --depth 1 --branch v3.6.0 https://github.com/ESP32Async/ESPAsyncWebServer.git esp32/libs/ESPAsyncWebServer
+
+          # S2 (core 2.0.17): the fap-bundled board. Build into build/ (flat) so the
+          # bundle step below and build-fap.sh find it, then merge into one 0x0 image.
           arduino-cli compile \
             --fqbn esp32:esp32:esp32s2:PartitionScheme=huge_app \
             --libraries esp32/libs \
             --output-dir esp32/flytrap-fw/build \
             esp32/flytrap-fw
+          BOOT_APP0="$HOME/.arduino15/packages/esp32/hardware/esp32/2.0.17/tools/partitions/boot_app0.bin"
+          python3 tools/merge-image.py esp32/flytrap-fw/build/flytrap-s2-merged.bin \
+            0x1000  esp32/flytrap-fw/build/flytrap-fw.ino.bootloader.bin \
+            0x8000  esp32/flytrap-fw/build/flytrap-fw.ino.partitions.bin \
+            0xe000  "$BOOT_APP0" \
+            0x10000 esp32/flytrap-fw/build/flytrap-fw.ino.bin
+
+          # WROOM (core 2.0.17, plain esp32 FQBN), merged the same way.
+          arduino-cli compile \
+            --fqbn esp32:esp32:esp32 \
+            --libraries esp32/libs \
+            --output-dir esp32/flytrap-fw/build-wroom \
+            esp32/flytrap-fw
+          python3 tools/merge-image.py esp32/flytrap-fw/build-wroom/flytrap-wroom-merged.bin \
+            0x1000  esp32/flytrap-fw/build-wroom/flytrap-fw.ino.bootloader.bin \
+            0x8000  esp32/flytrap-fw/build-wroom/flytrap-fw.ino.partitions.bin \
+            0xe000  "$BOOT_APP0" \
+            0x10000 esp32/flytrap-fw/build-wroom/flytrap-fw.ino.bin
+
+          # C5 (core 3.3.11): the chip does not exist in 2.0.17. Installing the 3.x
+          # core REPLACES 2.0.17 (and its esptool), so this runs last. NOTE the C5
+          # bootloader offset is 0x2000, not the 0x1000 the other boards use.
+          arduino-cli core install esp32:esp32@3.3.11
+          C5_BOOT_APP0="$HOME/.arduino15/packages/esp32/hardware/esp32/3.3.11/tools/partitions/boot_app0.bin"
+          arduino-cli compile \
+            --fqbn esp32:esp32:esp32c5:PartitionScheme=huge_app,CDCOnBoot=default \
+            --libraries esp32/libs \
+            --output-dir esp32/flytrap-fw/build-c5 \
+            esp32/flytrap-fw
+          python3 tools/merge-image.py esp32/flytrap-fw/build-c5/flytrap-c5-merged.bin \
+            0x2000  esp32/flytrap-fw/build-c5/flytrap-fw.ino.bootloader.bin \
+            0x8000  esp32/flytrap-fw/build-c5/flytrap-fw.ino.partitions.bin \
+            0xe000  "$C5_BOOT_APP0" \
+            0x10000 esp32/flytrap-fw/build-c5/flytrap-fw.ino.bin
 
       - uses: actions/setup-python@v5
         with:
@@ -64,14 +104,19 @@ jobs:
           TAG: ${{ github.ref_name }}
           REPO: ${{ github.repository }}
         run: |
-          # Two artifacts: the fap (one-step install; bundles portal + firmware)
-          # and the firmware bundle zip (all images + boot_app0 + flash.txt
-          # manifest) for computer/esptool flashing or manual SD flasher setup.
-          # The loose .bin images are redundant with the zip (and incomplete —
-          # they omit boot_app0), so they're no longer attached.
+          # Attachments:
+          #  - the fap (one-step install; bundles the portal + the S2 firmware)
+          #  - the S2 firmware bundle zip (images + boot_app0 + flash.txt manifest)
+          #    for the on-device flasher / manual SD setup
+          #  - one merged .bin per board (S2/WROOM/C5), each flashable at 0x0 with
+          #    esptool from a computer: what WROOM and C5 owners use, and what
+          #    issue #1 asked for.
           gh release create "$TAG" \
             --repo "$REPO" \
             --title "Flytrap $TAG" \
             --generate-notes \
             flipper/flytrap/dist/flytrap.fap \
-            flytrap-firmware-bundle.zip
+            flytrap-firmware-bundle.zip \
+            esp32/flytrap-fw/build/flytrap-s2-merged.bin \
+            esp32/flytrap-fw/build-wroom/flytrap-wroom-merged.bin \
+            esp32/flytrap-fw/build-c5/flytrap-c5-merged.bin

.gitignore

@@ -13,6 +13,8 @@ build/
 *.o
 *.a
 esp32/**/build/
+# per-board release build dirs (build-wroom, build-c5)
+esp32/**/build-*/
 # ...but the firmware-bundle boot_app0 is a shipped asset, not a build artifact
 !esp32/flytrap-fw/boot_app0.bin
 

CHANGELOG.md

@@ -2,6 +2,51 @@
 
 All notable changes to Flytrap are documented here.
 
+## [0.6.0] — 2026-09-11
+
+Board detection now keys off a firmware-identifying beacon, and the flasher UI is
+simplified around the embedded firmware.
+
+### Protocol
+- The liveness beacon is now **`PING FTRP <ver>`** (was a bare `PING`). The `FTRP`
+  magic identifies *Flytrap* firmware so the app won't adopt a board flashed with
+  something else, and `<ver>` is the wire-protocol version. Detection now **parses**
+  the beacon (magic-matched) instead of treating "any bytes received" as a board —
+  the latter let foreign firmware slip through. **Requires reflashing the ESP**
+  (Start Portal will prompt for it automatically).
+
+### Flipper app
+- **Version-aware install/update.** Start Portal has three outcomes: no magic beacon
+  → *"Firmware needed"* (install); magic but an older `<ver>` → *"Update firmware?"*;
+  current → it proceeds. The prompt is phrased around the **firmware**, not the
+  board's presence (an off/absent/foreign board are indistinguishable).
+- **Handshake watchdog.** A start that detects the board but never reaches
+  broadcasting within ~8 s drops back to the install prompt instead of hanging on
+  "Starting portal…".
+- **"Reinstall firmware"** replaces the old **Flash Firmware** menu item — it flashes
+  the firmware bundled in the fap directly (no SD file picker, so no stale-folder
+  clutter). Start Portal's auto-install/update uses the same bundled image.
+- `deploy-to-flipper.py` no longer pushes a firmware bundle to the SD (it rides
+  inside the fap and extracts to `apps_assets`).
+- **Flasher tells you to reset.** The "Flashed!" screen now says *"Tap RESET on the
+  board to run it, then Continue"* — the board stays in the download bootloader
+  after flashing (the app can't drive the S2's reset line), so it needs a manual
+  RESET to boot the new firmware. (Was mislabeled "Board rebooting…".)
+
+### Boards
+- **WROOM and C5 builds** alongside the S2. Releases now attach one merged image per
+  board (`flytrap-s2-merged.bin`, `flytrap-wroom-merged.bin`, `flytrap-c5-merged.bin`),
+  each flashable at `0x0` with `esptool` from a computer, so nothing has to be compiled
+  to get running. The fap still bundles the S2 image alone, so the on-device
+  Install/Update path stays S2-only.
+- The firmware is **3.x-core clean**. `onStaIp()` resolved a station's MAC through
+  `esp_netif_get_sta_list()`, which esp-idf 5 removed, so the sketch would not compile
+  on the 3.x core at all. On 3.x the assign event carries the MAC directly, so the two
+  paths now sit behind an `ESP_ARDUINO_VERSION_MAJOR` check. The C5 needs 3.x (the chip
+  does not exist in 2.0.17); S2 and WROOM stay pinned to 2.0.17. Fixes #1.
+- Async libraries moved to the maintained **ESP32Async** forks (AsyncTCP v3.3.2,
+  ESPAsyncWebServer v3.6.0). The unmaintained me-no-dev forks do not build on 3.x.
+
 ## [0.5.0] — 2026-07-17
 
 Flash the ESP firmware from the Flipper — no computer.

README.md

@@ -46,9 +46,11 @@ If that's not your use case, this isn't the project for you.
   everything also logged to `capture_<N>.txt` on the SD card.
 - **Live clients** list → detail (MAC, IP, joined time). Joins and leaves update the
   count in real time, so a device that disconnects drops off instead of lingering.
-- **Flash the ESP from the Flipper** — no computer. **Flash Firmware** picks a
-  firmware bundle off the SD, auto-detects the board in download mode, and writes it
-  over the GPIO UART (vendored [esp-serial-flasher](https://github.com/espressif/esp-serial-flasher)).
+- **Flash the ESP from the Flipper** — no computer. The firmware is bundled in the
+  fap; **Start Portal** auto-detects the board and offers to **Install** (or
+  **Update**, when it's behind) and continues once flashed, and a **Reinstall
+  firmware** menu item reflashes on demand. It auto-detects the board in download
+  mode and writes over the GPIO UART (vendored [esp-serial-flasher](https://github.com/espressif/esp-serial-flasher)).
 - **Capture alerts** (haptic / beep / LED) with a **Settings** screen to toggle them.
 - A **Console** view (from the menu during a session) showing the raw serial protocol live.
 - Lightweight enough to run reliably on the SD-less ESP32-S2 dev board.
@@ -59,6 +61,10 @@ If that's not your use case, this isn't the project for you.
   `ufbt` SDK).
 - **Official Flipper WiFi Dev Board (ESP32-S2)** — or any generic ESP32-S2. It mounts on the
   Flipper's GPIO header, which wires the two together over UART.
+- **ESP32-WROOM and ESP32-C5** also run the firmware; releases attach a ready-made image
+  for each. Only the S2 image is bundled in the fap, so those two are flashed once from a
+  computer (see [tools/README.md](tools/README.md)), after which the Flipper drives them
+  the same way.
 
 ## Install
 

docs/PROTOCOL.md

@@ -37,7 +37,7 @@ All line-oriented. The Flipper parser matches on the leading token.
 | `BYE mac=<AA:BB:...>` | A station left the AP — the Flipper drops it from the live client list. |
 | `IP mac=<AA:BB:...> ip=<ip>` | DHCP assigned a station its IP (MAC resolved from the soft-AP table). Falls back to `IP ip=<ip>` when the MAC can't be resolved; the Flipper then pairs it to the most recent client without an IP. |
 | `CRED ip=<ip>&<field>=<val>&...` | A form was submitted — the client IP plus every submitted field, url-encoded. One line per submission. |
-| `PING` | Liveness beacon, emitted ~every 2s. The Flipper uses it to detect an unplugged board (no `PING`/traffic for 5s ⇒ link lost); it's dropped from the console so it doesn't spam. |
+| `PING FTRP <ver>` | Liveness + identity beacon, emitted ~every 2s. The magic `FTRP` marks the board as running Flytrap firmware (detection keys off *this*, not "any bytes", so a board flashed with something else isn't adopted), and `<ver>` is the wire-protocol version — the Flipper prompts an update when it's behind `FLYTRAP_FW_VERSION`. Also drives unplug detection (no beacon/traffic for 5s ⇒ link lost). Dropped from the console so it doesn't spam. |
 
 ## Handshake
 
@@ -57,15 +57,20 @@ Flipper                              ESP
   |  <---- IP mac=... ip=...(DHCP leases it an address)
   |  <---- CRED ip=...&...  (a form is submitted)
   |  <---- BYE mac=...      (the phone leaves)
-  |  <---- PING             (~every 2s, all the while)
+  |  <---- PING FTRP <ver>  (~every 2s, all the while)
   |                                   |
   |  stop\n / reset\n          ----> |   (tear down / reboot)
 ```
 
-If the ESP emits `STATUS boot` mid-session (it rebooted), the Flipper re-sends
-`sethtml` automatically to recover. If `PING` (and all other traffic) stops for
-5s, the Flipper flags the link as lost and the dashboard shows **Board
-disconnected** until the board returns.
+Before the handshake the Flipper first **detects** the board by waiting for a
+magic `PING FTRP` beacon: none ⇒ *"Firmware needed"* (install prompt); magic but
+`<ver>` behind ⇒ *"Update firmware?"*; current ⇒ it proceeds. If the ESP emits
+`STATUS boot` mid-session (it rebooted), the Flipper re-sends `sethtml`
+automatically to recover. If the beacon (and all other traffic) stops for 5s, the
+Flipper flags the link as lost and the dashboard shows **Board disconnected**
+until the board returns. A start that detects the board but never reaches
+`portal_up` within ~8s is treated as a stalled handshake and drops back to the
+install prompt.
 
 ## Notes
 

esp32/flytrap-fw/flytrap-fw.ino

@@ -11,7 +11,8 @@
 //   BYE mac=<mac>    (a station left the AP)
 //   IP mac=<mac> ip=<ip>   (DHCP assigned a station its IP)
 //   CRED <urlencoded>   (all submitted form fields, one line per submission)
-//   PING             (~every 2s liveness beacon so the Flipper detects unplug)
+//   PING FTRP <ver>  (~every 2s liveness beacon; the magic "FTRP" identifies THIS
+//                     firmware to the Flipper and <ver> drives its update prompt)
 //
 // Authorized testing only.
 
@@ -25,6 +26,12 @@
 #define MAX_HTML_SIZE 48000
 #define MAX_SSID 32
 
+// Beacon identity: the magic marks a PING as coming from THIS firmware (so the
+// Flipper won't adopt some other board), and the version drives its update
+// prompt. KEEP IN SYNC with flipper/flytrap/flytrap_i.h.
+#define FW_MAGIC "FTRP"
+#define FW_VERSION 2
+
 static char index_html[MAX_HTML_SIZE + 1] =
     "<html><body><h1>Flytrap</h1><p>Set a portal from the Flipper.</p></body></html>";
 static size_t index_html_len = 0;
@@ -129,15 +136,26 @@ static void onStaDisconnect(WiFiEvent_t event, WiFiEventInfo_t info) {
     emitLine(String("BYE mac=") + mac); // a station left the AP
 }
 
-// DHCP handed a station an IP. The event only carries the IP (no MAC on this
-// IDF), so look the MAC up in the soft-AP station table by matching the IP, and
-// report the pair so the Flipper can attach the IP to the right client. Falls
-// back to an IP-only line if the table lookup can't resolve it.
+// DHCP handed a station an IP. Report the IP, and the MAC when we can resolve it,
+// so the Flipper can attach the IP to the right client. How the MAC is obtained
+// differs by core version (see the #if below), so this stays portable across the
+// 2.0.x core the S2/WROOM build against and the 3.x core the C5 needs.
 static void onStaIp(WiFiEvent_t event, WiFiEventInfo_t info) {
     (void)event;
     uint32_t evip = info.wifi_ap_staipassigned.ip.addr;
     IPAddress ip(evip);
 
+#if ESP_ARDUINO_VERSION_MAJOR >= 3
+    // esp-idf 5+ (Arduino core 3.x, e.g. the C5): the assign event carries the
+    // station's MAC directly, so report the pair with no table lookup. The old
+    // esp_netif_get_sta_list() path this used on 2.0.x was removed in the 3.x core.
+    char mac[18];
+    formatMac(info.wifi_ap_staipassigned.mac, mac);
+    emitLine(String("IP mac=") + mac + " ip=" + ip.toString());
+#else
+    // esp-idf 4.x (Arduino core 2.0.x, the S2/WROOM): the staipassigned event has
+    // no MAC field, so look the MAC up in the soft-AP station table by matching the
+    // IP. Falls back to an IP-only line if the table lookup can't resolve it.
     wifi_sta_list_t wifi_list;
     esp_netif_sta_list_t netif_list;
     if(esp_wifi_ap_get_sta_list(&wifi_list) == ESP_OK &&
@@ -152,6 +170,7 @@ static void onStaIp(WiFiEvent_t event, WiFiEventInfo_t info) {
         }
     }
     emitLine(String("IP ip=") + ip.toString()); // MAC unknown; Flipper pairs by recency
+#endif
 }
 
 static void startPortal() {
@@ -261,6 +280,6 @@ void loop() {
     uint32_t now = millis();
     if(now - lastPing >= 2000) {
         lastPing = now;
-        emitLine("PING");
+        emitLine(String("PING " FW_MAGIC " ") + FW_VERSION);
     }
 }