# Reproducing the v24 build ## Pinned environment | Component | Version | |---|---| | M5Stack ESP32 core | 3.3.9 | | Board FQBN | m5stack:esp32:m5stack_atoms3r | | M5Unified | 0.2.25 | | M5GFX | 0.2.32 | | M5Unit-GESTURE | 0.2.0 | | M5UnitUnified | 0.5.8 | | M5Utility | 0.3.1 | | M5HAL | 0.1.4 | The original development used Arduino IDE 2.3.10 on Windows. The board package supplies the compiler, ESP32 core and built-in BLE library. This project uses that library's **NimBLE backend**, not a separately installed NimBLE-Arduino package. ## Arduino IDE 1. Add this Boards Manager URL in Preferences: `https://static-cdn.m5stack.com/resource/arduino/package_m5stack_index.json` 2. Install M5Stack core 3.3.9 and select **M5AtomS3R**. 3. Install the six pinned libraries above through Library Manager. 4. Open `src/MediaGestureController/MediaGestureController.ino`. 5. Verify, choose the actual serial port, then upload. First builds can take several minutes. If the board needs download mode, hold its **side Reset** about two seconds until the internal green LED lights, then release. See the [official AtomS3R instructions](https://docs.m5stack.com/en/core/AtomS3R). ## PowerShell + Arduino CLI ```powershell ./scripts/setup.ps1 ./scripts/build.ps1 ./scripts/upload.ps1 -Port COM4 ``` `setup.ps1` installs the pinned board and libraries into your normal Arduino locations. `build.ps1` only compiles. `upload.ps1` uploads the current `build/` result and replaces the board's application; it does not erase all flash. Use `-Cli 'path/to/arduino-cli.exe'` if CLI is not in PATH. On Windows the standard Arduino IDE bundled CLI is also detected. Use `-ConfigFile 'path/to/arduino-cli.yaml'` to reuse an existing board-manager/sketchbook configuration. The default config is this repository's `config/arduino-cli.yaml`, which contains only the public board-manager URL. Equivalent CLI build: ```text arduino-cli --config-file config/arduino-cli.yaml compile --fqbn m5stack:esp32:m5stack_atoms3r --jobs 4 --build-path build src/MediaGestureController ``` ## BLE compatibility history The bundled 3.3.9 BLEService implementation dropped later characteristic objects sharing UUID `0x2A4D`. A local patch was needed for the combined keyboard/media layouts in v18–v20. See `patches/ble-service-duplicate-uuid.patch`. **v24 has only one HID report and does not require this duplicate-report patch.** The public build script does not modify the installed core. Do not apply the historical patch to a different library version without reviewing its source. ## Rebuild expectations The v24 main sketch and headers match the tested archive; the manifest records source hashes and the historical application-image hash. A new firmware image can differ due to compiler, build time or other metadata. This repository does not distribute a full-device flash image, NVS or pairing database. The optional v25 patch is outside the default build. Do not combine it with a v24 validation claim.