From 033df26f9d5ce73a3cd2a75f9507eab8c06d18db Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 2 Jan 2026 04:25:17 +0000 Subject: [PATCH 1/3] Initial plan From ada865d12b3eaae521748b4edbc60b11657e29fb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 2 Jan 2026 04:33:15 +0000 Subject: [PATCH 2/3] Add Bruce Firmware sideload support with manifest, installers, docs, and CI workflow Co-authored-by: Crashkeyz <186653592+Crashkeyz@users.noreply.github.com> --- .github/workflows/bruce-firmware-package.yml | 195 +++++++++++++++ README.md | 24 ++ bruce_manifest.json | 33 +++ docs/BRUCE_FIRMWARE_SIDELOAD.md | 239 +++++++++++++++++++ docs/QUICK_START_BRUCE.md | 110 +++++++++ docs/README.md | 2 + install-bruce-sideload.bat | 181 ++++++++++++++ install-bruce-sideload.sh | 164 +++++++++++++ 8 files changed, 948 insertions(+) create mode 100644 .github/workflows/bruce-firmware-package.yml create mode 100644 bruce_manifest.json create mode 100644 docs/BRUCE_FIRMWARE_SIDELOAD.md create mode 100644 docs/QUICK_START_BRUCE.md create mode 100644 install-bruce-sideload.bat create mode 100755 install-bruce-sideload.sh diff --git a/.github/workflows/bruce-firmware-package.yml b/.github/workflows/bruce-firmware-package.yml new file mode 100644 index 0000000..0124b5a --- /dev/null +++ b/.github/workflows/bruce-firmware-package.yml @@ -0,0 +1,195 @@ +name: Build and Package for Bruce Firmware + +on: + push: + branches: [ main, cleanup/add-sideload-access ] + 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 }} diff --git a/README.md b/README.md index c6e4aad..1ee6451 100644 --- a/README.md +++ b/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 diff --git a/bruce_manifest.json b/bruce_manifest.json new file mode 100644 index 0000000..472f2f6 --- /dev/null +++ b/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" +} diff --git a/docs/BRUCE_FIRMWARE_SIDELOAD.md b/docs/BRUCE_FIRMWARE_SIDELOAD.md new file mode 100644 index 0000000..44f3721 --- /dev/null +++ b/docs/BRUCE_FIRMWARE_SIDELOAD.md @@ -0,0 +1,239 @@ +# Bruce Firmware Sideload Guide + +This guide explains how to use the Ultimatum Cardputer firmware as a sideloadable application through Bruce Firmware. + +## What is Bruce Firmware? + +Bruce Firmware is a popular multi-tool firmware for M5Stack Cardputer that provides various utilities and supports sideloading other firmware applications. It allows you to run multiple firmware applications without completely replacing the base firmware. + +## Prerequisites + +- M5Stack Cardputer with Bruce Firmware installed +- microSD card (formatted as FAT32) +- USB-C cable for connecting to your computer +- Built firmware binary files (see Building section) + +## Building the Firmware for Sideload + +### Option 1: Download Pre-built Binary + +If available, download the latest release from the [Releases](https://github.com/Crashkeyz/UltimatumCardputerKey/releases) page. + +### Option 2: Build from Source + +1. Install PlatformIO: + ```bash + pip install platformio + ``` + +2. Clone the repository: + ```bash + git clone https://github.com/Crashkeyz/UltimatumCardputerKey.git + cd UltimatumCardputerKey + ``` + +3. Build the firmware: + ```bash + pio run -e m5stack-cardputer + ``` + +4. The firmware binary will be created at: + ``` + .pio/build/m5stack-cardputer/firmware.bin + ``` + +## Installation on Bruce Firmware + +### Quick Installation (Recommended) + +Use the provided installation scripts for automatic setup: + +**Linux/macOS:** +```bash +./install-bruce-sideload.sh /path/to/sdcard +``` + +**Windows:** +```cmd +install-bruce-sideload.bat E: +``` +(Replace `E:` with your SD card drive letter) + +The script will: +- ✅ Verify all required files exist +- ✅ Create the proper directory structure +- ✅ Copy firmware files to the correct location +- ✅ Create a helpful README on the SD card +- ✅ Provide clear next-step instructions + +### Manual Installation + +If you prefer manual installation: + +#### Step 1: Prepare Your SD Card + +1. Format your microSD card as FAT32 (if not already formatted) +2. Insert the SD card into your computer + +#### Step 2: Create Firmware Directory + +Create the following directory structure on your SD card: +``` +SD:/ +├── firmware/ +│ └── ultimatum/ +│ ├── firmware.bin +│ ├── manifest.json +│ └── default_16MB.csv +``` + +#### Step 3: Copy Firmware Files + +1. Copy the built `firmware.bin` to `SD:/firmware/ultimatum/` +2. Copy `bruce_manifest.json` from the repository root to `SD:/firmware/ultimatum/manifest.json` +3. Copy `default_16MB.csv` from the repository to `SD:/firmware/ultimatum/` + +#### Step 4: Insert SD Card and Boot + +1. Safely eject the SD card from your computer +2. Insert the SD card into your M5Stack Cardputer +3. Power on or restart your device with Bruce Firmware + +#### Step 5: Load via Bruce Firmware Menu + +1. Navigate to Bruce Firmware's menu system +2. Look for "Sideload" or "Apps" option +3. Select "Ultimatum Cardputer" from the list +4. Bruce Firmware will load and run the Ultimatum firmware + +## Directory Structure Reference + +Complete directory structure on SD card: +``` +SD:/ +├── firmware/ +│ └── ultimatum/ +│ ├── firmware.bin # Main firmware binary +│ ├── manifest.json # Metadata for Bruce Firmware +│ └── default_16MB.csv # Partition table (optional but recommended) +└── data/ # Your data files (used by Ultimatum firmware) +``` + +## Manifest File Format + +The `manifest.json` file contains metadata about the firmware: + +```json +{ + "name": "Ultimatum Cardputer", + "version": "1.0.0", + "description": "Advanced firmware for M5Stack Cardputer", + "device": "M5Stack Cardputer", + "binary": "firmware.bin", + "partition": "default_16MB.csv", + "flash_size": "16MB" +} +``` + +## Features Available in Sideload Mode + +When running as a sideload through Bruce Firmware, you'll have access to: + +- ✅ Full keyboard support +- ✅ LCD display control +- ✅ SD card access for data storage +- ✅ USB serial debugging +- ✅ All M5Unified library features +- ✅ Optimized partition scheme for 16MB flash +- ✅ OTA update capability + +## Troubleshooting + +### Firmware Not Appearing in Bruce Menu + +1. Check that files are in the correct directory: `SD:/firmware/ultimatum/` +2. Verify `manifest.json` is valid JSON (use a JSON validator) +3. Ensure `firmware.bin` exists and is not corrupted +4. Restart Bruce Firmware after copying files + +### Device Not Booting After Sideload + +1. Power off the device completely +2. Remove and reinsert the SD card +3. Power on and try loading again +4. If issues persist, check Bruce Firmware documentation for compatibility + +### SD Card Not Detected + +1. Ensure SD card is formatted as FAT32 +2. Try a different SD card (some cards may be incompatible) +3. Check that SD card is properly inserted +4. Some SD cards work better at lower speeds + +### Memory Issues + +1. Make sure you're using the provided `default_16MB.csv` partition table +2. Use an SD card for storing data instead of internal flash +3. Verify your device has 16MB flash and 8MB PSRAM + +### Installation Script Errors + +**Linux/macOS:** +- Ensure the script is executable: `chmod +x install-bruce-sideload.sh` +- Check SD card mount point: `df -h` or `mount | grep SD` +- Verify you have write permissions to the SD card + +**Windows:** +- Run Command Prompt as Administrator if permission errors occur +- Verify the drive letter is correct in "This PC" +- Ensure the SD card is not write-protected + +## Returning to Bruce Firmware + +To exit Ultimatum firmware and return to Bruce Firmware: + +1. Power off your M5Stack Cardputer +2. Power it back on normally +3. Bruce Firmware will load as the base firmware +4. You can sideload Ultimatum again from the menu when needed + +## Verification Steps + +After installation, verify everything is correct: + +1. **Check Directory Structure:** + ```bash + # On your computer (with SD card mounted) + ls -la /path/to/sdcard/firmware/ultimatum/ + ``` + Should show: `firmware.bin`, `manifest.json`, `default_16MB.csv`, `README.txt` + +2. **Check File Sizes:** + - `firmware.bin`: Should be several MB (typically 1-3 MB) + - `manifest.json`: Small file (~1 KB) + - `default_16MB.csv`: Small file (<1 KB) + +3. **Verify JSON:** + ```bash + cat /path/to/sdcard/firmware/ultimatum/manifest.json + ``` + Should be valid JSON with proper structure + +## Further Resources + +- [Bruce Firmware GitHub](https://github.com/pr3y/Bruce) - Multi-tool firmware for M5Stack devices +- [UltimatumCardputerKey GitHub](https://github.com/Crashkeyz/UltimatumCardputerKey) +- [M5Stack Cardputer Official Docs](https://docs.m5stack.com/en/core/Cardputer) +- [Quick Start Guide](QUICK_START_BRUCE.md) - Fast 3-step installation + +## Support + +If you encounter issues: + +1. Check the [Issues](https://github.com/Crashkeyz/UltimatumCardputerKey/issues) page +2. Review Bruce Firmware documentation for sideload requirements +3. Open a new issue with details about your problem + +## License + +This firmware is provided under the same license as the main project. See LICENSE file for details. diff --git a/docs/QUICK_START_BRUCE.md b/docs/QUICK_START_BRUCE.md new file mode 100644 index 0000000..d92b827 --- /dev/null +++ b/docs/QUICK_START_BRUCE.md @@ -0,0 +1,110 @@ +# Quick Start: Bruce Firmware Sideload + +## Visual Overview + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Your Computer │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Build │ -> │ Install │ -> │ SD Card │ │ +│ │ Firmware │ │ Script │ │ Ready! │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + | + v + ┌──────────────────┐ + │ Insert SD Card │ + │ into Cardputer │ + └──────────────────┘ + | + v +┌─────────────────────────────────────────────────────────────┐ +│ M5Stack Cardputer │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Boot │ -> │ Select │ -> │ Ultimatum │ │ +│ │ Bruce │ │ Ultimatum │ │ Running! │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +## TL;DR - Fast Installation + +### Prerequisites +- M5Stack Cardputer with Bruce Firmware installed +- microSD card (FAT32 formatted) +- Built firmware (see below) + +### 3-Step Installation + +1. **Build or Download Firmware** + ```bash + pio run -e m5stack-cardputer + ``` + Or download from [Releases](https://github.com/Crashkeyz/UltimatumCardputerKey/releases) + +2. **Run Installation Script** + + **Linux/macOS:** + ```bash + ./install-bruce-sideload.sh /path/to/sdcard + ``` + + **Windows:** + ```cmd + install-bruce-sideload.bat E: + ``` + (Replace `E:` with your SD card drive letter) + +3. **Load in Bruce Firmware** + - Insert SD card into Cardputer + - Boot Bruce Firmware + - Navigate to Sideload/Apps menu + - Select "Ultimatum Cardputer" + +## Manual Installation (No Scripts) + +If you prefer to do it manually: + +1. Create directory on SD card: `SD:/firmware/ultimatum/` +2. Copy these files to that directory: + - `.pio/build/m5stack-cardputer/firmware.bin` + - `bruce_manifest.json` (rename to `manifest.json`) + - `default_16MB.csv` +3. Insert SD card and boot Bruce Firmware +4. Load from sideload menu + +## Directory Structure on SD Card + +``` +SD:/ +└── firmware/ + └── ultimatum/ + ├── firmware.bin + ├── manifest.json + └── default_16MB.csv +``` + +## Troubleshooting + +**Problem:** Firmware not showing in Bruce menu +- **Solution:** Check folder is at `SD:/firmware/ultimatum/` exactly + +**Problem:** Build failed +- **Solution:** Run `pio run --target clean` then rebuild + +**Problem:** SD card not detected +- **Solution:** Format as FAT32, try different card + +**Problem:** Script permission denied (Linux/macOS) +- **Solution:** Run `chmod +x install-bruce-sideload.sh` + +**Problem:** Installation script can't find files +- **Solution:** Run script from project root directory where `platformio.ini` is located + +## Full Documentation + +For detailed instructions, see [BRUCE_FIRMWARE_SIDELOAD.md](BRUCE_FIRMWARE_SIDELOAD.md) + +## Support + +Issues? Visit: https://github.com/Crashkeyz/UltimatumCardputerKey/issues diff --git a/docs/README.md b/docs/README.md index 03b2c2b..2264091 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,4 +4,6 @@ This directory contains documentation and setup instructions for the UltimatumCa ## Available Guides +- **[Quick Start: Bruce Firmware](QUICK_START_BRUCE.md)** - Fast 3-step guide for sideloading through Bruce Firmware +- **[Bruce Firmware Sideload Guide](BRUCE_FIRMWARE_SIDELOAD.md)** - Complete guide for using this firmware as a sideloadable application through Bruce Firmware - **[SD Card Setup Guide](SD_CARD_SETUP.md)** - Complete guide for setting up SD card storage to avoid flash memory issues \ No newline at end of file diff --git a/install-bruce-sideload.bat b/install-bruce-sideload.bat new file mode 100644 index 0000000..3705119 --- /dev/null +++ b/install-bruce-sideload.bat @@ -0,0 +1,181 @@ +@echo off +REM Installation script for Bruce Firmware sideload (Windows) +REM Usage: install-bruce-sideload.bat DRIVE_LETTER: + +setlocal EnableDelayedExpansion + +echo ====================================================================== +echo Ultimatum Cardputer - Bruce Firmware Sideload Installer +echo ====================================================================== +echo. + +if "%~1"=="" ( + echo [X] Error: No SD card drive letter provided + echo. + echo Usage: install-bruce-sideload.bat DRIVE_LETTER: + echo. + echo Example: install-bruce-sideload.bat E: + echo ^(where E: is your SD card drive letter^) + echo. + echo To find your SD card drive letter: + echo 1. Open 'This PC' or 'My Computer' + echo 2. Look for your SD card ^(usually shows as Removable Disk^) + echo 3. Note the drive letter ^(e.g., D:, E:, F:^) + echo. + pause + exit /b 1 +) + +set SD_PATH=%~1 +set FIRMWARE_DIR=%SD_PATH%\firmware +set TARGET_DIR=%FIRMWARE_DIR%\ultimatum + +REM Check if SD card path exists +if not exist "%SD_PATH%\" ( + echo [X] Error: SD card drive not found: %SD_PATH% + echo. + echo Please check that: + echo 1. SD card is inserted into your computer + echo 2. Drive letter is correct ^(check in 'This PC'^) + echo 3. You included the colon ^(e.g., E: not E^) + echo. + pause + exit /b 1 +) + +echo [OK] SD card found at: %SD_PATH% +echo. + +REM Check if firmware files exist locally +if not exist ".pio\build\m5stack-cardputer\firmware.bin" ( + echo [X] Error: Firmware binary not found! + echo. + echo Please build the firmware first: + echo pio run -e m5stack-cardputer + echo. + echo Or download a pre-built release from: + echo https://github.com/Crashkeyz/UltimatumCardputerKey/releases + echo. + pause + exit /b 1 +) + +if not exist "bruce_manifest.json" ( + echo [X] Error: bruce_manifest.json not found! + echo Please ensure you're running this script from the project root directory. + pause + exit /b 1 +) + +if not exist "default_16MB.csv" ( + echo [X] Error: default_16MB.csv not found! + echo Please ensure you're running this script from the project root directory. + pause + exit /b 1 +) + +REM Create firmware directory structure +echo Creating directory structure... +if not exist "%FIRMWARE_DIR%" mkdir "%FIRMWARE_DIR%" +if !ERRORLEVEL! NEQ 0 ( + echo [X] Error: Could not create firmware directory + pause + exit /b 1 +) + +if not exist "%TARGET_DIR%" mkdir "%TARGET_DIR%" +if !ERRORLEVEL! NEQ 0 ( + echo [X] Error: Could not create directory: %TARGET_DIR% + pause + exit /b 1 +) + +echo [OK] Directory created: %TARGET_DIR% +echo. + +REM Copy firmware files +echo Copying firmware files... + +copy /Y ".pio\build\m5stack-cardputer\firmware.bin" "%TARGET_DIR%\" >nul +if !ERRORLEVEL! NEQ 0 ( + echo [X] Error: Failed to copy firmware.bin + pause + exit /b 1 +) +echo [OK] Copied firmware.bin + +copy /Y "bruce_manifest.json" "%TARGET_DIR%\manifest.json" >nul +if !ERRORLEVEL! NEQ 0 ( + echo [X] Error: Failed to copy manifest.json + pause + exit /b 1 +) +echo [OK] Copied manifest.json + +copy /Y "default_16MB.csv" "%TARGET_DIR%\" >nul +if !ERRORLEVEL! NEQ 0 ( + echo [X] Error: Failed to copy default_16MB.csv + pause + exit /b 1 +) +echo [OK] Copied default_16MB.csv + +REM Create README in target directory +( +echo Ultimatum Cardputer Firmware - Bruce Firmware Sideload Package +echo ================================================================ +echo. +echo This firmware can be loaded through Bruce Firmware's sideload menu. +echo. +echo To Use: +echo 1. Ensure this folder is at: SD:/firmware/ultimatum/ +echo 2. Boot your M5Stack Cardputer with Bruce Firmware +echo 3. Navigate to the sideload or apps menu +echo 4. Select "Ultimatum Cardputer" +echo 5. The firmware will load +echo. +echo To Return to Bruce Firmware: +echo - Simply restart your device +echo. +echo Files: +echo - firmware.bin: Main firmware binary +echo - manifest.json: Metadata for Bruce Firmware loader +echo - default_16MB.csv: Partition table for proper memory management +echo - README.txt: This file +echo. +echo For more information: +echo https://github.com/Crashkeyz/UltimatumCardputerKey/blob/main/docs/BRUCE_FIRMWARE_SIDELOAD.md +echo. +echo Version: 1.0.0 +) > "%TARGET_DIR%\README.txt" + +if !ERRORLEVEL! NEQ 0 ( + echo [X] Warning: Failed to create README.txt +) + +echo. +echo ====================================================================== +echo Installation Complete! +echo ====================================================================== +echo. +echo Files installed to: %TARGET_DIR% +echo. +echo Directory contents: +dir /B "%TARGET_DIR%" +echo. +echo Next Steps: +echo 1. Safely eject your SD card from the computer +echo ^(Right-click on the drive in 'This PC' and select 'Eject'^) +echo 2. Insert the SD card into your M5Stack Cardputer +echo 3. Power on or restart your device ^(should be running Bruce Firmware^) +echo 4. Navigate to Bruce Firmware's sideload/apps menu +echo 5. Select 'Ultimatum Cardputer' from the list +echo 6. The firmware will load and run +echo. +echo To return to Bruce Firmware, simply restart your device. +echo. +echo For detailed instructions and troubleshooting: +echo https://github.com/Crashkeyz/UltimatumCardputerKey/blob/main/docs/BRUCE_FIRMWARE_SIDELOAD.md +echo. +pause +exit /b 0 diff --git a/install-bruce-sideload.sh b/install-bruce-sideload.sh new file mode 100755 index 0000000..f0e1d2a --- /dev/null +++ b/install-bruce-sideload.sh @@ -0,0 +1,164 @@ +#!/bin/sh +# Installation script for Bruce Firmware sideload +# Usage: ./install-bruce-sideload.sh /path/to/sdcard + +set -e # Exit on error +set -u # Exit on undefined variable + +echo "======================================================================" +echo " Ultimatum Cardputer - Bruce Firmware Sideload Installer" +echo "======================================================================" +echo "" + +# Usage function +usage() { + echo "Usage: $0 /path/to/sdcard" + echo "" + echo "Examples:" + echo " macOS: $0 /Volumes/SDCARD" + echo " Linux: $0 /media/user/SDCARD" + echo " Windows: Use install-bruce-sideload.bat instead" + echo "" + exit 1 +} + +# Check if SD card path is provided +if [ $# -eq 0 ]; then + echo "❌ Error: No SD card path provided" + echo "" + usage +fi + +SD_PATH="$1" +FIRMWARE_DIR="$SD_PATH/firmware" +TARGET_DIR="$FIRMWARE_DIR/ultimatum" + +# Check if SD card path exists +if [ ! -d "$SD_PATH" ]; then + echo "❌ Error: SD card path not found: $SD_PATH" + echo "" + echo "Please check that:" + echo " 1. SD card is inserted and mounted" + echo " 2. Path is correct (check with 'ls /Volumes/' on macOS or 'ls /media/' on Linux)" + echo "" + exit 1 +fi + +echo "✓ SD card found at: $SD_PATH" +echo "" + +# Check if SD card is writable +if [ ! -w "$SD_PATH" ]; then + echo "❌ Error: SD card is not writable: $SD_PATH" + echo "Please check permissions or try running with appropriate privileges" + exit 1 +fi + +# Create firmware directory if it doesn't exist +echo "Creating directory structure..." +mkdir -p "$TARGET_DIR" || { + echo "❌ Error: Could not create directory: $TARGET_DIR" + exit 1 +} + +echo "✓ Directory created: $TARGET_DIR" +echo "" + +# Check if firmware files exist locally +if [ ! -f ".pio/build/m5stack-cardputer/firmware.bin" ]; then + echo "❌ Error: Firmware binary not found!" + echo "" + echo "Please build the firmware first:" + echo " pio run -e m5stack-cardputer" + echo "" + echo "Or download a pre-built release from:" + echo " https://github.com/Crashkeyz/UltimatumCardputerKey/releases" + echo "" + exit 1 +fi + +if [ ! -f "bruce_manifest.json" ]; then + echo "❌ Error: bruce_manifest.json not found!" + echo "Please ensure you're running this script from the project root directory." + exit 1 +fi + +if [ ! -f "default_16MB.csv" ]; then + echo "❌ Error: default_16MB.csv not found!" + echo "Please ensure you're running this script from the project root directory." + exit 1 +fi + +# Copy firmware files +echo "Copying firmware files..." + +cp .pio/build/m5stack-cardputer/firmware.bin "$TARGET_DIR/" || { + echo "❌ Error: Failed to copy firmware.bin" + exit 1 +} + +cp bruce_manifest.json "$TARGET_DIR/manifest.json" || { + echo "❌ Error: Failed to copy manifest.json" + exit 1 +} + +cp default_16MB.csv "$TARGET_DIR/" || { + echo "❌ Error: Failed to copy default_16MB.csv" + exit 1 +} + +# Create a README in the target directory +cat > "$TARGET_DIR/README.txt" << 'EOF' +Ultimatum Cardputer Firmware - Bruce Firmware Sideload Package +================================================================ + +This firmware can be loaded through Bruce Firmware's sideload menu. + +To Use: +1. Ensure this folder is at: SD:/firmware/ultimatum/ +2. Boot your M5Stack Cardputer with Bruce Firmware +3. Navigate to the sideload or apps menu +4. Select "Ultimatum Cardputer" +5. The firmware will load + +To Return to Bruce Firmware: +- Simply restart your device + +Files: +- firmware.bin: Main firmware binary +- manifest.json: Metadata for Bruce Firmware loader +- default_16MB.csv: Partition table for proper memory management +- README.txt: This file + +For more information: +https://github.com/Crashkeyz/UltimatumCardputerKey/blob/main/docs/BRUCE_FIRMWARE_SIDELOAD.md + +Version: 1.0.0 +EOF + +echo "✓ Files copied successfully!" +echo "" +echo "======================================================================" +echo " Installation Complete!" +echo "======================================================================" +echo "" +echo "Files installed to: $TARGET_DIR" +echo "" +echo "Directory contents:" +ls -lh "$TARGET_DIR" 2>/dev/null || ls -l "$TARGET_DIR" +echo "" +echo "Next Steps:" +echo " 1. Safely eject your SD card from the computer" +echo " 2. Insert the SD card into your M5Stack Cardputer" +echo " 3. Power on or restart your device (should be running Bruce Firmware)" +echo " 4. Navigate to Bruce Firmware's sideload/apps menu" +echo " 5. Select 'Ultimatum Cardputer' from the list" +echo " 6. The firmware will load and run" +echo "" +echo "To return to Bruce Firmware, simply restart your device." +echo "" +echo "For detailed instructions and troubleshooting:" +echo " https://github.com/Crashkeyz/UltimatumCardputerKey/blob/main/docs/BRUCE_FIRMWARE_SIDELOAD.md" +echo "" + +exit 0 From 1fac4bdaff3a6681528300c4927443a6cbe73470 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 2 Jan 2026 04:38:55 +0000 Subject: [PATCH 3/3] Address code review feedback: improve shell scripts and workflow config Co-authored-by: Crashkeyz <186653592+Crashkeyz@users.noreply.github.com> --- .github/workflows/bruce-firmware-package.yml | 2 +- install-bruce-sideload.bat | 14 ++++++-------- install-bruce-sideload.sh | 5 ++--- 3 files changed, 9 insertions(+), 12 deletions(-) diff --git a/.github/workflows/bruce-firmware-package.yml b/.github/workflows/bruce-firmware-package.yml index 0124b5a..f619e24 100644 --- a/.github/workflows/bruce-firmware-package.yml +++ b/.github/workflows/bruce-firmware-package.yml @@ -2,7 +2,7 @@ name: Build and Package for Bruce Firmware on: push: - branches: [ main, cleanup/add-sideload-access ] + branches: [ main ] tags: - 'v*' pull_request: diff --git a/install-bruce-sideload.bat b/install-bruce-sideload.bat index 3705119..159ca14 100644 --- a/install-bruce-sideload.bat +++ b/install-bruce-sideload.bat @@ -2,8 +2,6 @@ REM Installation script for Bruce Firmware sideload (Windows) REM Usage: install-bruce-sideload.bat DRIVE_LETTER: -setlocal EnableDelayedExpansion - echo ====================================================================== echo Ultimatum Cardputer - Bruce Firmware Sideload Installer echo ====================================================================== @@ -77,14 +75,14 @@ if not exist "default_16MB.csv" ( REM Create firmware directory structure echo Creating directory structure... if not exist "%FIRMWARE_DIR%" mkdir "%FIRMWARE_DIR%" -if !ERRORLEVEL! NEQ 0 ( +if %ERRORLEVEL% NEQ 0 ( echo [X] Error: Could not create firmware directory pause exit /b 1 ) if not exist "%TARGET_DIR%" mkdir "%TARGET_DIR%" -if !ERRORLEVEL! NEQ 0 ( +if %ERRORLEVEL% NEQ 0 ( echo [X] Error: Could not create directory: %TARGET_DIR% pause exit /b 1 @@ -97,7 +95,7 @@ REM Copy firmware files echo Copying firmware files... copy /Y ".pio\build\m5stack-cardputer\firmware.bin" "%TARGET_DIR%\" >nul -if !ERRORLEVEL! NEQ 0 ( +if %ERRORLEVEL% NEQ 0 ( echo [X] Error: Failed to copy firmware.bin pause exit /b 1 @@ -105,7 +103,7 @@ if !ERRORLEVEL! NEQ 0 ( echo [OK] Copied firmware.bin copy /Y "bruce_manifest.json" "%TARGET_DIR%\manifest.json" >nul -if !ERRORLEVEL! NEQ 0 ( +if %ERRORLEVEL% NEQ 0 ( echo [X] Error: Failed to copy manifest.json pause exit /b 1 @@ -113,7 +111,7 @@ if !ERRORLEVEL! NEQ 0 ( echo [OK] Copied manifest.json copy /Y "default_16MB.csv" "%TARGET_DIR%\" >nul -if !ERRORLEVEL! NEQ 0 ( +if %ERRORLEVEL% NEQ 0 ( echo [X] Error: Failed to copy default_16MB.csv pause exit /b 1 @@ -149,7 +147,7 @@ echo. echo Version: 1.0.0 ) > "%TARGET_DIR%\README.txt" -if !ERRORLEVEL! NEQ 0 ( +if %ERRORLEVEL% NEQ 0 ( echo [X] Warning: Failed to create README.txt ) diff --git a/install-bruce-sideload.sh b/install-bruce-sideload.sh index f0e1d2a..90d3198 100755 --- a/install-bruce-sideload.sh +++ b/install-bruce-sideload.sh @@ -2,8 +2,7 @@ # Installation script for Bruce Firmware sideload # Usage: ./install-bruce-sideload.sh /path/to/sdcard -set -e # Exit on error -set -u # Exit on undefined variable +set -eu # Exit on error or undefined variable echo "======================================================================" echo " Ultimatum Cardputer - Bruce Firmware Sideload Installer" @@ -145,7 +144,7 @@ echo "" echo "Files installed to: $TARGET_DIR" echo "" echo "Directory contents:" -ls -lh "$TARGET_DIR" 2>/dev/null || ls -l "$TARGET_DIR" +ls -l "$TARGET_DIR" echo "" echo "Next Steps:" echo " 1. Safely eject your SD card from the computer"