From b90739d2a258ec9e1fd12dc8514e73424da9a020 Mon Sep 17 00:00:00 2001
From: Stephen Waits <steve@waits.net>
Date: Thu, 26 Mar 2026 21:07:30 -0600
Subject: [PATCH] fix: use espflash for ESP32, add prereq checks with install
 instructions

- flash command uses espflash for Xtensa boards, probe-rs for ARM
  (ESP32-S3 has a USB-serial bootloader, not a debug probe)
- Pre-flight checks before flash: missing tools get a clear error with
  the exact install command instead of a cryptic failure
- Pre-flight check for esp toolchain before build/clippy too

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 Justfile | 42 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/Justfile b/Justfile
index aae6b734..00276e88 100644
--- a/Justfile
+++ b/Justfile
@@ -45,6 +45,7 @@ clippy board:
     @read -r feat target chip <<< "$(just _info {{board}})"; \
     env=""; extra=""; \
     case "$target" in xtensa-*) \
+        just _require_esp_toolchain; \
         [ -f "$HOME/export-esp.sh" ] && . "$HOME/export-esp.sh"; \
         env="RUSTC=$(rustup which rustc --toolchain esp)"; extra="+nightly -Zbuild-std=core";; \
     esac; \
@@ -55,11 +56,15 @@ build board profile="release":
     @just _cargo {{board}} "build --{{profile}}"
     @just _copy_firmware {{board}} {{profile}}
 
-# Build and flash a board via probe-rs
+# Build and flash a board (espflash for Xtensa, probe-rs for ARM)
 flash board:
+    @just _require_flash_tool {{board}}
     @just build {{board}} release
     @read -r feat target chip <<< "$(just _info {{board}})"; \
-    probe-rs run --chip $chip "{{firmware_dir}}/lora-dongle-{{board}}-release.elf"
+    case "$target" in \
+        xtensa-*) espflash flash --monitor "{{firmware_dir}}/lora-dongle-{{board}}-release.elf" ;; \
+        *) probe-rs run --chip $chip "{{firmware_dir}}/lora-dongle-{{board}}-release.elf" ;; \
+    esac
 
 # Show binary size for a release build
 size board:
@@ -74,12 +79,13 @@ _cargo board cmd:
     @read -r feat target chip <<< "$(just _info {{board}})"; \
     env=""; extra=""; \
     case "$target" in xtensa-*) \
+        just _require_esp_toolchain; \
         [ -f "$HOME/export-esp.sh" ] && . "$HOME/export-esp.sh"; \
         env="RUSTC=$(rustup which rustc --toolchain esp)"; extra="+nightly -Zbuild-std=core";; \
     esac; \
     eval $env cargo $extra {{cmd}} --target $target --features $feat
 
-# Check if a board's toolchain is available
+# Check if a board's toolchain is available (silent, for build-all/check-all skipping)
 [private]
 _can_build board:
     @read -r feat target chip <<< "$(just _info {{board}})"; \
@@ -88,6 +94,36 @@ _can_build board:
         *) rustup target list --installed | grep -q "^$target$" || rustup target add "$target" >/dev/null 2>&1 ;; \
     esac
 
+# Verify the flash tool is installed for a board, with install instructions if not
+[private]
+_require_flash_tool board:
+    @read -r feat target chip <<< "$(just _info {{board}})"; \
+    case "$target" in \
+        xtensa-*) \
+            if ! command -v espflash >/dev/null 2>&1; then \
+                echo "error: espflash is required to flash ESP32 boards" >&2; \
+                echo "  install: cargo install espflash" >&2; \
+                exit 1; \
+            fi ;; \
+        *) \
+            if ! command -v probe-rs >/dev/null 2>&1; then \
+                echo "error: probe-rs is required to flash ARM boards" >&2; \
+                echo "  install: cargo install probe-rs-tools" >&2; \
+                exit 1; \
+            fi ;; \
+    esac
+
+# Verify the esp toolchain is installed, with install instructions if not
+[private]
+_require_esp_toolchain:
+    @if ! rustup toolchain list | grep -q "^esp"; then \
+        echo "error: ESP toolchain not found" >&2; \
+        echo "  install:" >&2; \
+        echo "    cargo install espup" >&2; \
+        echo "    espup install --toolchain-version 1.82.0.3" >&2; \
+        exit 1; \
+    fi
+
 [private]
 _copy_firmware board profile:
     @mkdir -p {{firmware_dir}}