108 lines
4.2 KiB
Markdown
108 lines
4.2 KiB
Markdown
README - TWANG ESP32
|
|
=====================
|
|
|
|
Scopo
|
|
-----
|
|
|
|
Repository per il gioco TWANG su ESP32. Ho migrato il controllo LED da FastLED a NeoPixelBus per evitare problemi specifici su ESP32. Questo README spiega come verificare che la build funzioni e come testare la striscia LED e gli input.
|
|
|
|
Checklist rapida (stato)
|
|
------------------------
|
|
|
|
- Migrazione FastLED -> NeoPixelBus: Done
|
|
- Rimozione build flags FastLED: Done
|
|
- `LedController` aggiornato per NeoPixelBus: Done
|
|
- `GameEngine` aggiornato per usare `RgbColor`: Done
|
|
- Correzione `Level::reset` signature: Done
|
|
- Build PlatformIO: PASS (firmware generato)
|
|
|
|
File modificati / aggiunti
|
|
-------------------------
|
|
|
|
- `platformio.ini` — dipendenza aggiornata a `makuna/NeoPixelBus` e rimozione flags FastLED
|
|
- `src/hardware/LedController.h` — nuova implementazione con NeoPixelBus
|
|
- `src/game/GameEngine.cpp` — sostituiti i riferimenti `CRGB` -> `RgbColor`
|
|
- `src/game/Level.h` — `reset(Player &p)` ora chiama `p.reset()` senza argomenti
|
|
- `docs/CONTROLS.md` — piccola correzione heading
|
|
- `README.md` — questo file
|
|
|
|
Come verificare la build (locale)
|
|
--------------------------------
|
|
|
|
Apri una PowerShell (pwsh) nella cartella del progetto (root dove c'è `platformio.ini`) e lancia:
|
|
|
|
```powershell
|
|
# compilazione
|
|
platformio run
|
|
|
|
# upload (se la board è collegata e vuoi flashare)
|
|
platformio run --target upload
|
|
|
|
# apertura seriale per test realtime (115200)
|
|
platformio device monitor --baud 115200
|
|
```
|
|
|
|
Cosa controllare dopo la build
|
|
-----------------------------
|
|
|
|
1. `platformio run` termina con "SUCCESS" e viene generato `firmware.bin`.
|
|
2. Non devono comparire errori di link o simboli non definiti.
|
|
3. Se vuoi verificare comportamento LED prima di caricare, puoi comunque aprire il serial monitor e inviare comandi (vedi sotto).
|
|
|
|
Test runtime (veloce)
|
|
---------------------
|
|
|
|
1. Collega l'ESP32 al PC via USB.
|
|
2. Apri il monitor seriale:
|
|
|
|
```powershell
|
|
platformio device monitor --baud 115200
|
|
```
|
|
|
|
1. Invia il comando `debug` seguito da invio: questo attiva la modalità debug nel gioco e dovrebbe mostrare un pixel bianco che si muove lungo la striscia.
|
|
|
|
Comandi seriali disponibili
|
|
--------------------------
|
|
|
|
- `debug` — entra in modalità debug (pattern di prova)
|
|
- `restart` — riavvia la board
|
|
- `a`, `d`, `w`, `s` — movimenti/azioni (utili per test da seriale)
|
|
- `status` — stampa stato (placeholder)
|
|
|
|
Controlli fisici
|
|
----------------
|
|
|
|
- `BUTTON_LEFT` -> GPIO 15
|
|
- `BUTTON_RIGHT` -> GPIO 2
|
|
- `BUTTON_ATTACK`-> GPIO 4
|
|
- `BUTTON_START` -> GPIO 5
|
|
|
|
Nota hardware sui LED
|
|
---------------------
|
|
|
|
- Usa resistenza 330-470 Ω sul line DATA tra ESP32 e prima LED consigliata.
|
|
- Usa condensatore 1000 µF vicino alla strip tra +V e GND per stabilizzare alimentazione.
|
|
- Assicurati che l'alimentazione della strip supporti il numero di LED (circa 60mA per LED a piena intensità RGB).
|
|
|
|
Cose da verificare se qualcosa va storto
|
|
--------------------------------------
|
|
|
|
- Errori in compilazione: controlla l'output di `platformio run` e cerca file/righe menzionate.
|
|
- Problemi con LED che non accendono: verifica pin `DATA_PIN` in `src/config.h` e il cablaggio fisico.
|
|
- Striscia parzialmente corretta o colori sbagliati: prova a cambiare `NeoGrbFeature` in `LedController.h` (alcuni LED usano GRB o RGB) — apertura possibile modifica: `NeoRgbFeature`/`NeoGrbFeature`.
|
|
- Problemi di crash o reset: verifica consumo memoria (PlatformIO log mostra RAM/Flash) e alimentazione.
|
|
|
|
Note tecniche rilevanti
|
|
----------------------
|
|
|
|
- `LedController` usa `new NeoPixelBus<>` dinamico per evitare static init order problems; non ci sono delete espliciti perché la durata è quella della app.
|
|
- `fadeAll` è implementato manualmente leggendo `GetPixelColor` e scalando componenti.
|
|
- `Player::reset()` non accetta parametri: ogni chiamata nel progetto è stata adattata per usare la versione senza argomenti (correzioni in `Level.h`).
|
|
|
|
Miglioramenti possibili
|
|
----------------------
|
|
|
|
- Aggiungere un semplice pattern di test automatico all'avvio per diagnosticare la strip senza interazione seriale.
|
|
- Implementare un piccolo unit-test harness (non comune per Arduino, ma possibile con framework) per la logica core.
|
|
|
|
Se vuoi che proceda con l'upload automatico o ad aggiungere il pattern di test all'avvio, dimmelo e lo aggiungo subito.
|