From 0a969ef4c6ac5eafdc468fb63ea85a7dd8dd4c65 Mon Sep 17 00:00:00 2001
From: DeFiDude <59237470+DeFiDude@users.noreply.github.com>
Date: Tue, 10 Mar 2026 22:59:01 -0600
Subject: [PATCH] Add merged single .bin output for M5Burner compatibility

Add post-build script that produces ratdeck-merged.bin with bootloader,
partitions, boot_app0, and firmware at correct offsets. CI now attaches
the merged binary as a standalone release asset alongside the existing
multi-part ZIP.
---
 .github/workflows/build.yml | 30 ++++++++++++++++++++++++++++--
 merge_firmware.py           | 31 +++++++++++++++++++++++++++++++
 platformio.ini              |  2 ++
 3 files changed, 61 insertions(+), 2 deletions(-)
 create mode 100644 merge_firmware.py

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 194b962..91a63cd 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -24,6 +24,16 @@ jobs:
       - name: Build firmware
         run: pio run -e ratdeck_915
 
+      - name: Merge single .bin for M5Burner
+        run: |
+          esptool.py --chip esp32s3 merge_bin \
+            --flash_mode qio --flash_size 16MB \
+            -o ratdeck-merged.bin \
+            0x0000 .pio/build/ratdeck_915/bootloader.bin \
+            0x8000 .pio/build/ratdeck_915/partitions.bin \
+            0xe000 ~/.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin \
+            0x10000 .pio/build/ratdeck_915/firmware.bin
+
       - name: Package firmware ZIP
         run: |
           mkdir -p ratdeck-firmware
@@ -31,6 +41,7 @@ jobs:
           cp .pio/build/ratdeck_915/partitions.bin ratdeck-firmware/
           cp ~/.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin ratdeck-firmware/
           cp .pio/build/ratdeck_915/firmware.bin ratdeck-firmware/
+          cp ratdeck-merged.bin ratdeck-firmware/
           cat > ratdeck-firmware/manifest.json << 'MANIFEST'
           {
             "chipFamily": "ESP32-S3",
@@ -51,7 +62,9 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: ratdeck-firmware
-          path: ratdeck-firmware.zip
+          path: |
+            ratdeck-firmware.zip
+            ratdeck-merged.bin
 
   release:
     needs: build
@@ -73,6 +86,16 @@ jobs:
       - name: Build firmware
         run: pio run -e ratdeck_915
 
+      - name: Merge single .bin for M5Burner
+        run: |
+          esptool.py --chip esp32s3 merge_bin \
+            --flash_mode qio --flash_size 16MB \
+            -o ratdeck-merged.bin \
+            0x0000 .pio/build/ratdeck_915/bootloader.bin \
+            0x8000 .pio/build/ratdeck_915/partitions.bin \
+            0xe000 ~/.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin \
+            0x10000 .pio/build/ratdeck_915/firmware.bin
+
       - name: Package firmware ZIP
         run: |
           mkdir -p ratdeck-firmware
@@ -80,6 +103,7 @@ jobs:
           cp .pio/build/ratdeck_915/partitions.bin ratdeck-firmware/
           cp ~/.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin ratdeck-firmware/
           cp .pio/build/ratdeck_915/firmware.bin ratdeck-firmware/
+          cp ratdeck-merged.bin ratdeck-firmware/
           cat > ratdeck-firmware/manifest.json << 'MANIFEST'
           {
             "chipFamily": "ESP32-S3",
@@ -99,5 +123,7 @@ jobs:
       - name: Create Release
         uses: softprops/action-gh-release@v2
         with:
-          files: ratdeck-firmware.zip
+          files: |
+            ratdeck-firmware.zip
+            ratdeck-merged.bin
           generate_release_notes: true
diff --git a/merge_firmware.py b/merge_firmware.py
new file mode 100644
index 0000000..1432102
--- /dev/null
+++ b/merge_firmware.py
@@ -0,0 +1,31 @@
+"""Post-build script: merge bootloader + partitions + boot_app0 + firmware
+into a single .bin for M5Burner and one-step flashing."""
+
+Import("env")
+
+import os
+
+
+def merge_bin(source, target, env):
+    build_dir = env.subst("$BUILD_DIR")
+    project_dir = env.subst("$PROJECT_DIR")
+
+    # boot_app0.bin lives in the Arduino framework tools
+    framework_dir = env.PioPlatform().get_package_dir("framework-arduinoespressif32")
+    boot_app0 = os.path.join(framework_dir, "tools", "partitions", "boot_app0.bin")
+
+    output = os.path.join(project_dir, "ratdeck-merged.bin")
+
+    env.Execute(
+        "esptool.py --chip esp32s3 merge_bin "
+        "--flash_mode qio --flash_size 16MB "
+        f"-o {output} "
+        f"0x0000 {build_dir}/bootloader.bin "
+        f"0x8000 {build_dir}/partitions.bin "
+        f"0xe000 {boot_app0} "
+        f"0x10000 {build_dir}/firmware.bin"
+    )
+    print(f"\n** Merged firmware written to: {output}")
+
+
+env.AddPostAction("$BUILD_DIR/firmware.bin", merge_bin)
diff --git a/platformio.ini b/platformio.ini
index c7273ae..7c939a7 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -38,6 +38,8 @@ lib_deps =
 
 lib_archive = false
 
+extra_scripts = post:merge_firmware.py
+
 monitor_speed = 115200
 upload_speed = 460800
 upload_flags = --no-stub