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

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:

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.