# 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.