ATOMS3 MacroPad
Node-based macro keyboard firmware and programmer for the M5Stack AtomS3.
Scripts
python/GUI.bat — Macro Editor
Launches the graphical macro editor. Use this to create, edit, and upload macro programs to the device. The GUI handles connecting to the device automatically.
compile.bat — Compile Firmware
Compiles the Arduino firmware without uploading. Useful for verifying that the
firmware builds cleanly after making code changes. Output is saved to build.log.
compile.bat # standard build
compile.bat --clean # force a full rebuild from scratch
upload.bat — Upload Firmware
Compiles and uploads firmware to the device. The device must already be in download mode (ROM bootloader) before running this. Requires a COM port argument.
upload.bat COM4
To enter download mode: hold the side button on the AtomS3 while plugging in USB,
or send {"cmd":"bootloader"} to the device over serial if firmware is already running.
wipe_device.bat — Wipe Device
Sends the bootloader command to the running firmware, then erases both the NVS (settings) and LittleFS (macros) flash partitions, leaving the device in a completely fresh state. Run this before uploading firmware to ensure a clean slate.
wipe_device.bat # auto-detect COM port
wipe_device.bat COM3 # use a specific COM port
test_serial.bat — Serial Communication Test
Runs a quick ping/reconnect test against the device to verify serial communication
is working correctly. Useful for diagnosing connection issues. Output is saved to
serial_test.log.
test_serial.bat
Uploading New Firmware
Follow these steps any time you want to flash updated firmware onto the device.
Step 1 — Verify the build
compile.bat
Check the output for BUILD SUCCESSFUL and no errors. Fix any compile errors before
continuing. The full output is saved to build.log.
Step 2 — Wipe the device and enter download mode
wipe_device.bat
This will:
- Auto-detect the device on its normal COM port (e.g. COM3)
- Send a reboot-to-bootloader command
- Wait for the device to re-enumerate as a USB-Serial/JTAG port (e.g. COM4)
- Erase the settings (NVS) and macro storage (LittleFS) partitions
Note: This erases all saved macros. Re-upload them from the GUI afterwards.
Step 3 — Flash the firmware
upload.bat COM4
Replace COM4 with whatever download-mode port appeared in Step 2. If you are
unsure, check Device Manager — the download-mode port is listed under
Universal Serial Bus devices as USB JTAG/serial debug unit.
The script compiles, erases the full flash, and uploads the firmware. After it finishes the device will reboot and re-enumerate on its normal COM port (e.g. COM3).
Step 4 — Re-upload macros
python/GUI.bat
Open the editor, connect to the device, and click Upload All to restore your macros.
Typical Workflow
First-time setup or clean firmware update:
wipe_device.bat— wipe the deviceupload.bat COM4— flash fresh firmware (use the download mode COM port)
Code change / firmware-only update:
compile.bat— verify the buildwipe_device.bat— wipe and enter download modeupload.bat COM4— flash updated firmware
Editing macros:
python/GUI.bat— open the editor, connect, and upload macros
Device COM Ports
The AtomS3 enumerates as two different COM ports depending on its state:
| State | Port | Description |
|---|---|---|
| Normal (firmware running) | e.g. COM3 | TinyUSB CDC — used by the GUI and wipe script |
| Download mode (bootloader) | e.g. COM4 | USB-Serial/JTAG — used by upload.bat and esptool |
The active port number can vary between machines. Check Device Manager if unsure.