[WIP] Add reliable flashing, minimal firmware, and OTA support

[Copilot]

Thanks for asking me to work on this. I will get started on it and keep this PR's description up to date as I form a plan and make progress.

Original prompt

Goal: Create a clean feature branch and open a pull request that makes flashing reliable, adds a minimal test firmware, OTA support, a boot splash that displays "HACK THE PLANT!!!", and documents build/flash/OTA steps. The PR must be non-destructive (create a new branch off main) and include scripts and CI to build artifacts. Do NOT add any code that bypasses security.

Changes to implement (actionable):

1. Update platformio.ini

• Set a safe default upload_speed for the m5stack-cardputer env to 115200.
• Add an optional fast environment [env:m5stack-cardputer-fast] that keeps upload_speed = 921600 and inherits other settings.
• Ensure board and partition configurations remain for esp32-s3-devkitc-1 and default_16MB.csv.
• Add a comment describing how to enable OTA upload (espota) and note that OTA requires network credentials to be provided at runtime or via build flags.

2. Add reliable esptool flash scripts

• Add scripts/flash_esptool.sh (Linux/macOS) with argument parsing for PORT, BIN, BAUD; erases flash; writes firmware using esptool for esp32s3; verifies write; exits non-zero on error. Make executable and include usage examples.
• Add scripts/flash_esptool.bat (Windows) with analogous commands and usage notes.

3. Add minimal test firmware to verify flashing path

• Create src/test_blink/main.cpp that initializes M5Unified and displays a two-state visual indicator "FLASH OK" on the M5 display for 3 seconds, then toggles. Also print "FLASH OK" to Serial at 115200 for headless testing.
• Ensure it builds under the existing PlatformIO env m5stack-cardputer.

4. Add OTA example firmware

• Create src/ota_update/main.cpp implementing OTA (ArduinoOTA or esp32s3-compatible) with M5Unified initialization. OTA should:
  • Allow Wi-Fi credentials to be provided via a config file (data folder), runtime serial, or PlatformIO build flags (document all methods).
  • Initialize OTA and print status to Serial and display.
  • Allow OTA uploads via Arduino IDE / PlatformIO (espota) or via an OTA tool. Provide example PlatformIO upload command using upload_protocol = espota and how to set upload_port and upload_flags.

5. Add boot splash message

• Update the main firmware entry point (create/modify src/boot_splash/main.cpp or integrate into existing startup) to display "HACK THE PLANT!!!" on the M5 display immediately at boot for ~3 seconds, then continue to normal startup. Also print the message to Serial at 115200 on boot.
• The splash should be configurable via a #define or weak symbol so it can be changed later. Include comments warning that the message is for testing/humor.

6. Add README updates

• Add a new section "Build and Flash" with commands to build (pio run -e m5stack-cardputer), locate binary (.pio/build/m5stack-cardputer/firmware.bin), and flash with PlatformIO or esptool.
• Add a subsection "Use esptool (recommended if M5 Burner stalls)" with exact erase and write commands for esp32s3.
• Add a subsection "M5 Burner notes" recommending 115200 and cable/USB port checks.
• Add "Test firmware" instructions to flash src/test_blink and verify the display or serial output.
• Add "OTA Update" instructions: how to provide Wi-Fi credentials, how to use PlatformIO espota upload or Arduino IDE network upload, and how to recover if OTA fails.

7. Add CI workflow to build firmware and upload artifacts

• Add .github/workflows/build-firmware.yml that triggers on push and PR to main and the new branch, builds the m5stack-cardputer env, and uploads build artifacts (.bin and .elf) for download. Keep workflow minimal and avoid publishing to releases automatically.

8. Branch and PR policy

• Create a new branch named refactor/flash-ota-cleanup from main. Do not modify or delete existing branches.
• Open a pull request from refactor/flash-ota-cleanup into main with a detailed description listing all added/modified files and instructions to test locally.

Testing and verification steps included in PR description

• Build test: pio run -e m5stack-cardputer
• Flash test firmware via esptool: python -m esptool --chip esp32s3 --port /dev/ttyUSB0 --baud 115200 erase_flash; python -m esptool --chip esp32s3 --port /dev/ttyUSB0 --baud 115200 write_flash -z 0x1000 .pio/build/m5stack-cardputer/firmware.bin
• Verify display shows "FLASH OK" from test firmware and serial prints "FLASH OK" at 115200.
• Boot splash verification: boot main firmware and verify splash shows "HACK THE PLANT!!!" for ~3s and boot continues.
• OTA test: document how to configure Wi-Fi and use PlatformIO espota to push an OTA update; verify new firmware runs after OTA.

Notes and constraints

• Do not perform destructive branch operations or delete existing branches.
• Provide clear instructions for how to supply Wi-Fi credentials at build time or runtime.
• Keep code simple and well-commented.

Files to add/modify (explicit list)

• Modify: platformio.ini
• Add: scripts/flash_esptool.sh
• Add: scripts/flash_esptool.bat
• Add: src/test_blink/main.cpp
• Add: src/ota...

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.