Improve partition file handling and add comprehensive debugging

Critical improvements for partition "spiffs" not found errors:

- Update prepare-firmware.sh with robust bootloader detection:
  - Check standard location: BUILD_DIR/bootloader.bin
  - Check alternative location: BUILD_DIR/bootloader/bootloader.bin
  - ESP-IDF v4+ may use subdirectory structure

- Add comprehensive error checking:
  - Fail build if bootloader.bin or partitions.bin are missing
  - Display detailed error messages with file locations
  - Show build directory contents to aid debugging
  - Display partition table hex dump for verification

- Add partition file verification in CI workflow:
  - Verify bootloader.bin exists before boot check
  - Verify partitions.bin exists before boot check
  - Display hexdump of partitions.bin (shows table structure)
  - Fail fast if required files are missing

- Update README with comprehensive troubleshooting:
  - New section: "Filesystem/partition errors"
  - Step-by-step diagnosis for "partition not found" errors
  - Commands to verify partition files and configuration
  - Explanation of why bootloader and partitions are critical
  - Instructions for rebuilding if files are missing

These changes ensure that missing partition files are detected early
with clear error messages, rather than causing runtime filesystem
errors in the simulator.

Co-authored-by: softhack007 <91616163+softhack007@users.noreply.github.com>

Author: Copilot

.github/workflows/wokwi-test.yml

@@ -105,14 +105,37 @@ jobs:
             echo "⚠️  firmware.elf not found (optional for simulation)"
           fi
           
+          # Verify bootloader and partitions exist (required for filesystem)
+          if [ -f "bootloader.bin" ]; then
+            echo "✅ bootloader.bin found ($(du -h bootloader.bin | cut -f1))"
+          else
+            echo "❌ ERROR: bootloader.bin not found - filesystem will not work!"
+            echo "Available files:"
+            ls -la
+            exit 1
+          fi
+          
+          if [ -f "partitions.bin" ]; then
+            echo "✅ partitions.bin found ($(du -h partitions.bin | cut -f1))"
+          else
+            echo "❌ ERROR: partitions.bin not found - filesystem will not work!"
+            echo "Available files:"
+            ls -la
+            exit 1
+          fi
+          
           # Verify firmware can be read and has valid ESP32 header
           echo ""
           echo "Firmware file details:"
-          ls -lh firmware.bin firmware.elf 2>/dev/null || true
+          ls -lh firmware.bin firmware.elf bootloader.bin partitions.bin 2>/dev/null || true
           echo ""
           echo "Firmware.bin first 64 bytes (hex):"
           hexdump -C firmware.bin | head -4 || echo "Cannot read firmware.bin"
           echo "Note: ESP32 firmware should start with magic byte 0xe9"
+          echo ""
+          echo "Partitions.bin first 64 bytes (hex):"
+          hexdump -C partitions.bin | head -4 || echo "Cannot read partitions.bin"
+          echo "Note: Partition table defines flash layout including SPIFFS filesystem"
           
           echo ""
           echo "Running quick boot check scenario (15 seconds)..."

test/wokwi/README.md

@@ -218,6 +218,56 @@ To add more tests:
 - Ensure firmware was copied: `ls -lh test/wokwi/firmware.bin`
 - Check firmware build logs for errors
 
+### Filesystem/partition errors
+**Error:** `partition "spiffs" could not be found`
+
+**Cause:** Missing or incorrect partition table configuration
+
+**Solutions:**
+1. Verify bootloader.bin and partitions.bin are present:
+   ```bash
+   ls -lh test/wokwi/bootloader.bin test/wokwi/partitions.bin
+   ```
+
+2. Check that prepare-firmware.sh copied all files:
+   ```bash
+   ./test/wokwi/prepare-firmware.sh esp32_V4_wokwi_debug
+   ```
+
+3. Verify partitions.bin content:
+   ```bash
+   hexdump -C test/wokwi/partitions.bin | head -4
+   ```
+
+4. Check the partition table source CSV file:
+   ```bash
+   # The esp32_V4_wokwi_debug build uses:
+   cat tools/WLED_ESP32_4MB_256KB_FS.csv
+   # Should include a line with: spiffs, data, spiffs, ...
+   ```
+
+5. Rebuild firmware to regenerate partition files:
+   ```bash
+   pio run -e esp32_V4_wokwi_debug --target clean
+   pio run -e esp32_V4_wokwi_debug
+   ```
+
+6. Check wokwi.toml flash configuration:
+   ```toml
+   [wokwi]
+   partitions = "partitions.bin"
+   
+   [[wokwi.flashFiles]]
+   offset = 0x1000
+   file = "bootloader.bin"
+   
+   [[wokwi.flashFiles]]
+   offset = 0x8000
+   file = "partitions.bin"
+   ```
+
+**Note:** The bootloader and partition table are essential for filesystem support. Without them, SPIFFS cannot mount and the firmware will show "partition not found" errors.
+
 ### Web server not accessible
 - Wait 30-60 seconds for the ESP32 to boot and start WiFi
 - Check that port 9080 is not already in use

test/wokwi/prepare-firmware.sh

@@ -19,9 +19,20 @@ ENV_NAME=$1
 BUILD_DIR="$PROJECT_ROOT/.pio/build/$ENV_NAME"
 FIRMWARE_BIN="$BUILD_DIR/firmware.bin"
 FIRMWARE_ELF="$BUILD_DIR/firmware.elf"
+
+# PlatformIO stores bootloader and partitions in the build directory
+# but they might be in subdirectories depending on the platform version
 BOOTLOADER_BIN="$BUILD_DIR/bootloader.bin"
 PARTITIONS_BIN="$BUILD_DIR/partitions.bin"
 
+# Alternative locations for bootloader (ESP-IDF v4+ might use different paths)
+if [ ! -f "$BOOTLOADER_BIN" ]; then
+    ALT_BOOTLOADER="$BUILD_DIR/bootloader/bootloader.bin"
+    if [ -f "$ALT_BOOTLOADER" ]; then
+        BOOTLOADER_BIN="$ALT_BOOTLOADER"
+    fi
+fi
+
 # Check if firmware exists
 if [ ! -f "$FIRMWARE_BIN" ]; then
     echo "Error: Firmware binary not found at $FIRMWARE_BIN"
@@ -42,21 +53,57 @@ else
 fi
 
 # Copy bootloader and partitions (required for filesystem support)
+MISSING_FILES=""
+
 if [ -f "$BOOTLOADER_BIN" ]; then
     cp "$BOOTLOADER_BIN" "$WOKWI_DIR/bootloader.bin"
-    echo "✓ Copied bootloader.bin"
+    echo "✓ Copied bootloader.bin from $(basename $(dirname "$BOOTLOADER_BIN"))/$(basename "$BOOTLOADER_BIN")"
 else
-    echo "⚠ Warning: bootloader.bin not found at $BOOTLOADER_BIN"
+    echo "❌ ERROR: bootloader.bin not found!"
+    echo "   Checked: $BOOTLOADER_BIN"
+    echo "   Also checked: $BUILD_DIR/bootloader/bootloader.bin"
+    MISSING_FILES="${MISSING_FILES}bootloader.bin "
+    # List build directory contents to help debug
+    echo "   Build directory contents:"
+    ls -la "$BUILD_DIR" | head -20
 fi
 
 if [ -f "$PARTITIONS_BIN" ]; then
     cp "$PARTITIONS_BIN" "$WOKWI_DIR/partitions.bin"
     echo "✓ Copied partitions.bin"
+    # Display partition table contents for verification
+    echo "   Partition table contents:"
+    python3 -c "
+import sys
+try:
+    with open('$WOKWI_DIR/partitions.bin', 'rb') as f:
+        data = f.read()
+    print(f'   Size: {len(data)} bytes')
+    print(f'   First 32 bytes (hex): {data[:32].hex()}')
+except Exception as e:
+    print(f'   Could not read: {e}')
+" || true
 else
-    echo "⚠ Warning: partitions.bin not found at $PARTITIONS_BIN"
+    echo "❌ ERROR: partitions.bin not found at $PARTITIONS_BIN"
+    MISSING_FILES="${MISSING_FILES}partitions.bin "
+    # List build directory contents to help debug
+    echo "   Build directory contents:"
+    ls -la "$BUILD_DIR" | head -20
+fi
+
+if [ -n "$MISSING_FILES" ]; then
+    echo ""
+    echo "❌ ERROR: Missing required files: $MISSING_FILES"
+    echo ""
+    echo "These files are generated by PlatformIO/ESP-IDF during the build process."
+    echo "To fix this issue:"
+    echo "1. Ensure the build completed successfully"
+    echo "2. Check that 'pio run -e $ENV_NAME' completed without errors"
+    echo "3. Verify the partition table is correctly specified in platformio.ini"
+    exit 1
 fi
 
 echo ""
-echo "Firmware prepared successfully!"
+echo "✅ Firmware prepared successfully!"
 echo "Files in $WOKWI_DIR:"
 ls -lh "$WOKWI_DIR"/*.bin "$WOKWI_DIR"/*.elf 2>/dev/null || true