Add Bruce Firmware sideload support

.github/workflows/bruce-firmware-package.yml

@@ -0,0 +1,195 @@
+name: Build and Package for Bruce Firmware
+
+on:
+  push:
+    branches: [ main ]
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  build-and-package:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Cache PlatformIO
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.platformio
+            .pio
+          key: ${{ runner.os }}-pio-${{ hashFiles('**/platformio.ini') }}
+          restore-keys: |
+            ${{ runner.os }}-pio-
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install PlatformIO
+        run: |
+          python -m pip install --upgrade pip
+          pip install platformio
+          echo "PlatformIO version:"
+          pio --version
+
+      - name: Build Firmware
+        id: build
+        run: |
+          echo "Starting firmware build..."
+          pio run -e m5stack-cardputer --verbose
+
+          # Check if firmware was built successfully
+          if [ ! -f ".pio/build/m5stack-cardputer/firmware.bin" ]; then
+            echo "❌ ERROR: Firmware binary not found after build!"
+            echo "Build may have failed. Check logs above for errors."
+            exit 1
+          fi
+
+          echo "✅ Firmware built successfully"
+          ls -lh .pio/build/m5stack-cardputer/
+        continue-on-error: false
+
+      - name: Create Bruce Firmware Package
+        run: |
+          echo "Creating Bruce Firmware package..."
+
+          # Create packaging directory
+          mkdir -p bruce-package/ultimatum
+
+          # Copy firmware binary
+          cp .pio/build/m5stack-cardputer/firmware.bin bruce-package/ultimatum/
+          echo "✅ Copied firmware.bin"
+
+          # Copy manifest file
+          cp bruce_manifest.json bruce-package/ultimatum/manifest.json
+          echo "✅ Copied manifest.json"
+
+          # Copy partition table
+          cp default_16MB.csv bruce-package/ultimatum/
+          echo "✅ Copied partition table"
+
+          # Create README for the package
+          cat > bruce-package/ultimatum/README.txt << 'EOF'
+          Ultimatum Cardputer Firmware - Bruce Firmware Sideload Package
+          ================================================================
+
+          Installation Instructions:
+          1. Copy the entire "ultimatum" folder to your SD card's "firmware" directory
+          2. Full path should be: SD:/firmware/ultimatum/
+          3. Insert SD card into your M5Stack Cardputer running Bruce Firmware
+          4. Navigate to sideload/apps menu in Bruce Firmware
+          5. Select "Ultimatum Cardputer" to load
+
+          For detailed instructions, visit:
+          https://github.com/Crashkeyz/UltimatumCardputerKey/blob/main/docs/BRUCE_FIRMWARE_SIDELOAD.md
+
+          Files included:
+          - firmware.bin: Main firmware binary
+          - manifest.json: Metadata for Bruce Firmware
+          - default_16MB.csv: Partition table
+          - README.txt: This file
+          EOF
+          echo "✅ Created README.txt"
+
+          # Copy installation scripts
+          cp install-bruce-sideload.sh bruce-package/
+          cp install-bruce-sideload.bat bruce-package/
+          echo "✅ Copied installation scripts"
+
+          echo ""
+          echo "Package contents:"
+          ls -la bruce-package/
+          echo ""
+          echo "Ultimatum folder contents:"
+          ls -la bruce-package/ultimatum/
+
+      - name: Create package archive
+        run: |
+          echo "Creating archives..."
+          cd bruce-package
+          zip -r ../ultimatum-bruce-firmware.zip .
+          cd ..
+          tar -czf ultimatum-bruce-firmware.tar.gz -C bruce-package .
+
+          echo "Archive sizes:"
+          ls -lh ultimatum-bruce-firmware.zip ultimatum-bruce-firmware.tar.gz
+
+      - name: Upload Bruce Firmware Package (ZIP)
+        uses: actions/upload-artifact@v4
+        with:
+          name: ultimatum-bruce-package-zip
+          path: ultimatum-bruce-firmware.zip
+          retention-days: 90
+
+      - name: Upload Bruce Firmware Package (TAR.GZ)
+        uses: actions/upload-artifact@v4
+        with:
+          name: ultimatum-bruce-package-tar
+          path: ultimatum-bruce-firmware.tar.gz
+          retention-days: 90
+
+      - name: Upload Firmware Binary Only
+        uses: actions/upload-artifact@v4
+        with:
+          name: ultimatum-firmware-bin
+          path: .pio/build/m5stack-cardputer/firmware.bin
+          retention-days: 90
+
+      - name: Upload Bootloader
+        uses: actions/upload-artifact@v4
+        with:
+          name: ultimatum-bootloader
+          path: .pio/build/m5stack-cardputer/bootloader.bin
+          retention-days: 30
+          if-no-files-found: warn
+
+      - name: Upload Partitions
+        uses: actions/upload-artifact@v4
+        with:
+          name: ultimatum-partitions
+          path: .pio/build/m5stack-cardputer/partitions.bin
+          retention-days: 30
+          if-no-files-found: warn
+
+      # Create GitHub Release for tags
+      - name: Create Release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            ultimatum-bruce-firmware.zip
+            ultimatum-bruce-firmware.tar.gz
+            .pio/build/m5stack-cardputer/firmware.bin
+          body: |
+            ## Ultimatum Cardputer Firmware Release
+
+            ### Installation Options
+
+            **Option 1: Bruce Firmware Sideload (Recommended)**
+            1. Download `ultimatum-bruce-firmware.zip`
+            2. Extract the contents
+            3. Run the installation script (see README in package)
+            4. Or manually copy `ultimatum` folder to `SD:/firmware/` on your SD card
+
+            **Option 2: Direct Flash**
+            1. Download `firmware.bin`
+            2. Use PlatformIO or esptool to flash directly
+
+            ### Documentation
+            - [Bruce Firmware Sideload Guide](https://github.com/Crashkeyz/UltimatumCardputerKey/blob/main/docs/BRUCE_FIRMWARE_SIDELOAD.md)
+            - [Quick Start Guide](https://github.com/Crashkeyz/UltimatumCardputerKey/blob/main/docs/QUICK_START_BRUCE.md)
+            - [Main README](https://github.com/Crashkeyz/UltimatumCardputerKey/blob/main/README.md)
+
+            ### What's Changed
+            See commit history for detailed changes.
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -2,6 +2,17 @@
 
 Firmware for M5Stack Cardputer ADV (ESP32-S3)
 
+## 🚀 Bruce Firmware Sideload Support
+
+**NEW:** This firmware can now be loaded as a sideloadable application through Bruce Firmware! 
+
+- Run Ultimatum firmware without replacing your base firmware
+- Easy installation via SD card
+- Switch between firmwares on the fly
+
+**📖 Quick Start:** [3-Step Installation Guide](docs/QUICK_START_BRUCE.md)  
+**📖 Full Guide:** [Complete Sideload Documentation](docs/BRUCE_FIRMWARE_SIDELOAD.md)
+
 ## Which Branch to Use?
 
 **Use the `copilot/optimize-flashing-to-sd-card` branch for the latest stable version with SD card support and optimized memory usage.**
@@ -47,6 +58,19 @@ To avoid running out of flash memory:
 
 **📖 For detailed SD card setup instructions, see [docs/SD_CARD_SETUP.md](docs/SD_CARD_SETUP.md)**
 
+### Installation Options
+
+**Option 1: Sideload via Bruce Firmware (Recommended for Testing)**
+- No need to replace your existing firmware
+- Easy to switch between firmwares
+- Keep Bruce Firmware as your base system
+- **📖 [Complete Sideload Guide](docs/BRUCE_FIRMWARE_SIDELOAD.md)**
+
+**Option 2: Direct Flash (Standalone)**
+- Replace existing firmware completely
+- Full control over the device
+- Use instructions below
+
 ### Using PlatformIO CLI
 ```bash
 # Install PlatformIO

bruce_manifest.json

@@ -0,0 +1,33 @@
+{
+  "name": "Ultimatum Cardputer",
+  "version": "1.0.0",
+  "description": "Advanced firmware for M5Stack Cardputer with SD card support and optimized memory management",
+  "author": "Crashkeyz",
+  "device": "M5Stack Cardputer",
+  "mcu": "ESP32-S3",
+  "binary": "firmware.bin",
+  "partition": "default_16MB.csv",
+  "flash_size": "16MB",
+  "requirements": {
+    "flash": "16MB",
+    "psram": "8MB",
+    "sd_card": "recommended"
+  },
+  "features": [
+    "M5Unified library integration",
+    "SD card support for external storage",
+    "Optimized partition scheme",
+    "OTA update capability",
+    "USB CDC serial debugging",
+    "Full keyboard support",
+    "LCD display control"
+  ],
+  "installation": {
+    "method": "sideload",
+    "compatible_loaders": [
+      "Bruce Firmware"
+    ]
+  },
+  "github": "https://github.com/Crashkeyz/UltimatumCardputerKey",
+  "license": "See LICENSE file"
+}