139 lines
3.8 KiB
Markdown
139 lines
3.8 KiB
Markdown
# 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:
|
|
1. Auto-detect the device on its normal COM port (e.g. COM3)
|
|
2. Send a reboot-to-bootloader command
|
|
3. Wait for the device to re-enumerate as a USB-Serial/JTAG port (e.g. COM4)
|
|
4. 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:**
|
|
1. `wipe_device.bat` — wipe the device
|
|
2. `upload.bat COM4` — flash fresh firmware (use the download mode COM port)
|
|
|
|
**Code change / firmware-only update:**
|
|
1. `compile.bat` — verify the build
|
|
2. `wipe_device.bat` — wipe and enter download mode
|
|
3. `upload.bat COM4` — flash updated firmware
|
|
|
|
**Editing macros:**
|
|
1. `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.
|