Add Bruce Firmware sideload support

[Copilot]

Enables running Ultimatum firmware through Bruce Firmware's sideload mechanism without replacing the base firmware. Cleanly implements functionality from PR #49 with atomic commits.

Core Files

• bruce_manifest.json - Metadata for Bruce's loader (name, version, device, binary paths)
• install-bruce-sideload.sh - POSIX installer with set -eu, validates files exist and SD card is writable
• install-bruce-sideload.bat - Windows equivalent with ERRORLEVEL checks

Documentation

• docs/BRUCE_FIRMWARE_SIDELOAD.md - Complete installation guide with troubleshooting
• docs/QUICK_START_BRUCE.md - 3-step visual workflow
• README.md - Added sideload option to installation methods
• docs/README.md - Updated index

CI/CD

• .github/workflows/bruce-firmware-package.yml - Builds firmware, packages with installers, creates artifacts:
  • ultimatum-bruce-package-zip/tar - Complete package with scripts
  • ultimatum-firmware-bin - Standalone binary
  • Release attachments on tag push

Usage

# Build and install
pio run -e m5stack-cardputer
./install-bruce-sideload.sh /Volumes/SDCARD  # macOS/Linux
install-bruce-sideload.bat E:                 # Windows

# Creates SD:/firmware/ultimatum/{firmware.bin,manifest.json,default_16MB.csv}
# Load via Bruce Firmware sideload menu

Scripts validate prerequisites, create directory structure, copy files with error handling, and provide clear next-step instructions.

Related: Original implementation in #49

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• api.registry.nm1.platformio.org
  • Triggering command: /home/REDACTED/.local/bin/pio pio run -e m5stack-cardputer (dns block)
  • Triggering command: /home/REDACTED/.local/bin/pio pio run -e m5stack-cardputer --verbose (dns block)
• api.registry.platformio.org
  • Triggering command: /home/REDACTED/.local/bin/pio pio run -e m5stack-cardputer (dns block)
  • Triggering command: /home/REDACTED/.local/bin/pio pio run -e m5stack-cardputer --verbose (dns block)
• collector.platformio.org
  • Triggering command: /home/REDACTED/.local/bin/pio pio run -e m5stack-cardputer (dns block)
  • Triggering command: /home/REDACTED/.local/bin/pio pio run -e m5stack-cardputer --verbose (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Create a new clean branch named cleanup/add-sideload-access from the main branch and open a pull request that cleanly implements the intended changes from PR #49 (#49) without the repeated merge commits. Goal: produce a tidy, reviewable PR that adds Bruce Firmware sideload support and fixes script/CI/docs issues present in the original copilot branch.

Tasks to perform on the new branch (cleanup/add-sideload-access):

1. Recreate and add the core files from PR Add Bruce Firmware sideload support #49 with cleaned content and singular commits (do NOT copy merge commits):
   • bruce_manifest.json: add a validated manifest with required fields (name, version, device, features, paths to firmware.bin and default_16MB.csv). Validate JSON formatting.
   • install-bruce-sideload.sh: add a hardened POSIX shell installer with:
     • set -euo pipefail and informative logging
     • argument validation (target mount path)
     • verify required files exist in the project build output or packaged release
     • safe copying to the mount and error handling
     • exit codes and usage help
   • install-bruce-sideload.bat: add a Windows installer with robust checks and clear error messages; avoid unsafe assumptions.
2. Documentation files:
   • docs/BRUCE_FIRMWARE_SIDELOAD.md: cleaned, step-by-step installation guide with troubleshooting and verification steps.
   • docs/QUICK_START_BRUCE.md: 3-step quick start.
   • README.md and docs/README.md: update to reference the sideload option and link to the docs.
   • Remove the long firewall debug blob from the PR body and ensure the PR description is concise.
3. CI/CD improvements:
   • .github/workflows/bruce-firmware-package.yml: add a robust workflow that builds, packages, and creates release artifacts. Ensure it fails visibly when network access to PlatformIO is blocked and surface helpful logs. Upload packaged artifacts (zip/tar) containing the installation scripts and manifest.
4. Packaging and SD layout documentation: include the SD card structure example and a simple example install command.
5. Clean commits: make a small number of atomic commits grouped logically (manifest, installers, docs, CI) rather than many merge commits.
6. PR metadata:
   • Title: Add Bruce Firmware sideload support (cleaned)
   • Body: Explain this PR reproduces the intended changes from PR Add Bruce Firmware sideload support #49 but with a cleaned commit history. List files added/changed, how to use the installers, where CI artifacts are produced, how to test locally, and link to the original PR: Add Bruce Firmware sideload support #49
   • Set the PR as draft if appropriate.
7. Do NOT modify other unrelated files in the repository or include any prebuilt firmware binaries in the repo.

Please create the branch, commit the cleaned files, push the branch, and open a pull request from cleanup/add-sideload-access → main in repository Crashkeyz/UltimatumCardputerKey using the title and body described. Do not squash or rebase other branches; keep this PR separate and reviewable.

Note: this change should be safe to push; it does not rewrite main history. If any validation or formatting errors are detected (JSON, YAML), fix them before committing.

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.