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:

# 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

platformio run termina con "SUCCESS" e viene generato firmware.bin.
Non devono comparire errori di link o simboli non definiti.
Se vuoi verificare comportamento LED prima di caricare, puoi comunque aprire il serial monitor e inviare comandi (vedi sotto).

Test runtime (veloce)

Collega l'ESP32 al PC via USB.
Apri il monitor seriale:

platformio device monitor --baud 115200

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.

4.2 KiB Raw Permalink Blame History