|
| 1 | +ESP32‑S3 Matrix — Fast Path for New Games + Debug |
| 2 | + |
| 3 | +This repo lets anyone build a new LED‑matrix game quickly, visualize it in a terminal, and keep hardware + tools in sync. Follow this flow and you’re productive on day one. |
| 4 | + |
| 5 | +1) Configure The Board Once |
| 6 | +- Edit `config/BoardConfig.h` (single source of truth): |
| 7 | + - `MATRIX_WIDTH/HEIGHT` (default 8x8) |
| 8 | + - `LED_PIN` (default 14) and `BRIGHTNESS_LIMIT` (≤ 60) |
| 9 | + - `COLOR_ORDER` (use `RGB` for Waveshare ESP32‑S3‑Matrix) |
| 10 | + - Wiring/orientation: `PANEL_WIRING_SERPENTINE` (0=progressive row‑major), `PANEL_ROTATION`, `PANEL_FLIP_X/Y` |
| 11 | +- All games include this file; change it once and everything follows. |
| 12 | + |
| 13 | +2) Use The Shared Helpers |
| 14 | +- Include in your sketch: |
| 15 | + - `#include "config/BoardConfig.h"` |
| 16 | + - `#include "lib/MatrixUtil/MatrixUtil.h"` |
| 17 | +- What you get: |
| 18 | + - `MU_XY(x,y)`: stable XY→index mapping honoring the board profile |
| 19 | + - `MU_ADD_LEDS(DATA_PIN, leds, count)`: FastLED init using shared `COLOR_ORDER` |
| 20 | + - `MU_PrintMeta()`: prints a one‑time META line (size, wiring, rotation, flips) |
| 21 | + - `MU_SendFrameCSV(leds)`: prints one CSV‑hex frame compatible with the terminal visualizer |
| 22 | + - `MU_DrawCalibration(leds)`: corner markers TL=G, TR=R, BL=B, BR=W |
| 23 | + |
| 24 | +Minimal New‑Game Template |
| 25 | +```cpp |
| 26 | +#include <FastLED.h> |
| 27 | +#include "config/BoardConfig.h" |
| 28 | +#include "lib/MatrixUtil/MatrixUtil.h" |
| 29 | + |
| 30 | +#define NUM_LEDS (MATRIX_WIDTH * MATRIX_HEIGHT) |
| 31 | +CRGB leds[NUM_LEDS]; |
| 32 | + |
| 33 | +void setup() { |
| 34 | + Serial.begin(115200); |
| 35 | + unsigned long t0 = millis(); |
| 36 | + while (!Serial && millis() - t0 < 1500) { delay(10); } // non‑blocking |
| 37 | + if (Serial) MU_PrintMeta(); |
| 38 | + |
| 39 | + MU_ADD_LEDS(LED_PIN, leds, NUM_LEDS); |
| 40 | + FastLED.setBrightness(BRIGHTNESS_LIMIT); |
| 41 | + FastLED.clear(); FastLED.show(); |
| 42 | +} |
| 43 | + |
| 44 | +void loop() { |
| 45 | + FastLED.clear(); |
| 46 | + for (uint8_t y=0; y<MATRIX_HEIGHT; ++y) |
| 47 | + for (uint8_t x=0; x<MATRIX_WIDTH; ++x) |
| 48 | + if ((x+y)&1) leds[MU_XY(x,y)] = CRGB(30,30,30); |
| 49 | + FastLED.show(); |
| 50 | + |
| 51 | + if (Serial) MU_SendFrameCSV(leds); // terminal visualization |
| 52 | + delay(100); |
| 53 | +} |
| 54 | +``` |
| 55 | + |
| 56 | +3) Visualize In Terminal (No GUI) |
| 57 | +- Auto‑detect port, auto‑configure from META: |
| 58 | + - `python3 tools/led_matrix_viz.py --list-ports` |
| 59 | + - `python3 tools/led_matrix_viz.py -p /dev/ttyACM? -b 115200 --stats --verbose` |
| 60 | +- If you don’t print META, pass flags: `--width/--height --input-order xy --wiring progressive --rotate ...` |
| 61 | +- Tips: `--ascii` for plain text, `--flip-x/--flip-y` for quick checks. |
| 62 | + |
| 63 | +4) Build / Flash (ESP32‑S3) |
| 64 | +- In Arduino IDE: Tools → USB CDC On Boot = Enabled (prevents Serial from blocking). |
| 65 | +- Use the bundled CLI at `./bin/arduino-cli`: |
| 66 | + - First‑time setup (once): |
| 67 | + - `./bin/arduino-cli config init` |
| 68 | + - `./bin/arduino-cli core update-index` |
| 69 | + - `./bin/arduino-cli core install esp32:esp32` |
| 70 | + - Compile (example: Snake): |
| 71 | + - `./bin/arduino-cli compile --fqbn esp32:esp32:esp32s3:CDCOnBoot=cdc examples/Snake` |
| 72 | + - Upload: |
| 73 | + - `./bin/arduino-cli upload --fqbn esp32:esp32:esp32s3:CDCOnBoot=cdc --port /dev/ttyACM0 examples/Snake` |
| 74 | + - Monitor: |
| 75 | + - `./bin/arduino-cli monitor --port /dev/ttyACM0 --config baudrate=115200` |
| 76 | + |
| 77 | +5) Proven Debug Workflow |
| 78 | +- Keep Serial optional: short wait, then guard prints with `if (Serial)`. |
| 79 | +- Use `MU_DrawCalibration(leds)` once to prove mapping (TL=G, TR=R, BL=B, BR=W). |
| 80 | +- If colors are wrong on hardware, fix `COLOR_ORDER` in `BoardConfig.h` (Waveshare = `RGB`). |
| 81 | +- If left/right swap on alternating rows, set `PANEL_WIRING_SERPENTINE` to `0` (progressive row‑major). |
| 82 | + |
| 83 | +6) Quick Commands |
| 84 | +- List ports: `python3 tools/led_matrix_viz.py --list-ports` |
| 85 | +- Visualize: `python3 tools/led_matrix_viz.py -p /dev/ttyACM0 -b 115200 --stats` |
| 86 | +- Raw monitor: `python3 tools/monitor_pong.py -p /dev/ttyACM0` |
| 87 | +- Demo (no hardware): `python3 tools/led_matrix_viz.py --demo --width 8 --height 8` |
| 88 | + |
| 89 | +7) Tips For The Next Dev (and agents) |
| 90 | +- Start from the template; draw only via `MU_XY()`. |
| 91 | +- Never hardcode edges; use `MATRIX_WIDTH/HEIGHT`. |
| 92 | +- Limit debug frame rate (≈5–20 FPS) to keep serial stable. |
| 93 | +- Update only `BoardConfig.h` for new panels/orientation; all games + tools follow. |
| 94 | + |
| 95 | +Repo Highlights |
| 96 | +- `config/BoardConfig.h` — board profile (geometry, color order, wiring/orientation, brightness) |
| 97 | +- `lib/MatrixUtil/MatrixUtil.h` — mapping + serial frame helpers |
| 98 | +- `tools/led_matrix_viz.py` — terminal visualizer (reads META to auto‑configure) |
| 99 | +- `examples/` — reference sketches (Snake, tilt‑demo, wifi‑slam) |
| 100 | + |
| 101 | +DEBUGING ISSUES |
| 102 | +- when automatic upload fails, always ask for user to manual put device into bootloader mode, then wait for confirm before reflush again |
| 103 | +- MicroPython Board in FS mode is a pico device (which belong to the internal system), you should see ESP devie when you try lsusb, if not remind user to try replug in usb |
0 commit comments