Initial public release

2026-07-17 15:29:53 -04:00
commit 2d71ce77a1
81 changed files with 32056 additions and 0 deletions
@@ -0,0 +1,138 @@
+# 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.