Codey Rocky — FLUID 💧

Simulazione di fluido FLIP (FLuid Implicit Particle) in tempo reale sulla matrice LED 16×8 del Codey Rocky, pilotata dall'accelerometro/giroscopio. Firmware C++ per PlatformIO, senza mBlock.

Binari precompilati: scarica il firmware pronto da flashare dalla pagina Releases (merged-firmware-4MB.bin, un solo file, oppure i singoli .bin per esptool).

Ogni LED acceso è una cella del serbatoio che contiene almeno una particella d'acqua: resa binaria e netta, niente dithering. Inclini il robot e le particelle scendono verso il lato basso, ondeggiando e schizzando come acqua in un contenitore.

Come si gioca

Azione	Effetto
Inclina il robot	l'acqua scorre verso il lato basso, si accumula e ondeggia
Scuoti / muovi di scatto	l'acqua si agita e schizza da sola (l'accelerometro la spinge)
Manopola (knob)	rubinetto: nuove particelle entrano dal bordo in basso
Pulsante A	schizzo: aggiunge un getto di particelle al centro
Pulsante B	scarica un po' d'acqua
Scuoti forte	il LED RGB lampeggia in blu

Tienilo fermo e piatto durante l'accensione: l'IMU si auto-calibra in codey.begin().

Modalità test hardware

Accendi il robot e tieni premuto il pulsante A entro il primo secondo: parte una modalità di test che scorre tutti i tasti e i sensori del dispositivo, una schermata ciascuno (avanza da sola, o premi A per saltare avanti). Alla fine torna alla simulazione.

Schermata	Cosa prova
pattern matrice	pixel morti: tutto acceso, scacchiera, bordo, pixel in scansione
A / B / C	mostra la lettera del tasto premuto + contatore con beep
R G B Y O	LED RGB: cicla rosso/verde/blu/giallo/spento
barra manopola	knob 0-100 (valore + barra)
barra luce	sensore luce
barra suono	microfono
BATT	voltaggio, percentuale e versione hardware
IMU	temperatura + bolla che rotola con pitch/roll
SP	altoparlante: scala di note
IR	invia un frame NEC di prova e lampeggia se riceve qualcosa
OK / OB / NO	base Rocky: collegamento, sensore colore, ostacolo

Nota: per il grilletto viene usato A e non C, perché C è collegata a GPIO0 (boot strap dell'ESP32): tenuta premuta durante il reset farebbe entrare nel bootloader invece di avviare il firmware.

Compilazione e upload

1. Apri questa cartella in VS Code con l'estensione PlatformIO.
2. Collega il Codey Rocky via USB.
3. Upload (nessuna libreria da scaricare: CodeyRocky è già in lib/).

Se l'upload fallisce: tieni premuto il pulsante C, tocca il pulsante di accensione e riprova (GPIO0/pulsante C è il boot strap dell'ESP32).

Monitor seriale a 115200 baud; imposta FLUID_DEBUG 1 in src/main.cpp per statistiche ogni mezzo secondo.

L'algoritmo (copiato da chi l'ha già fatto bene)

Questo firmware è un port C++ del metodo FLIP di Matthias Müller ("Ten Minute Physics" — il solver usato in tantissimi giochi e VFX), nella stessa forma usata dalla flip card di Nicholas L. Johnson: una tessera 21×21 con 250 particelle che si comportano come acqua (Hackaday, 08/2025, github.com/Nicholas-L-Johnson/flip-card).

Step per frame a 60 Hz (griglia staggered 18×10 con bordo solido di 1 cella, ~160 particelle):

1. Integrazione particelle: v += gravità·dt, p += v·dt
2. pushParticlesApart: hash spaziale, separa le particelle più vicine di 2r
3. Collisioni coi muri (posizione bloccata, velocità normale azzerata)
4. P2G: trasferimento velocità particella→griglia con pesi bilineari
5. Incompressibilità: Gauss-Seidel con over-relaxation 1.9 e compensazione del drift verso la densità a riposo delle particelle
6. G2P: trasferimento griglia→particella con blend FLIP/PIC (flipRatio 0.9)
7. Resa: LED acceso dove la cella è FLUID (display.setColumns, un push a frame)

La gravità arriva dall'accelerometro grezzo (ax/ay, non da pitch/roll), come nei progetti di riferimento: così oltre all'inclinazione, scatti e scuotute producono schizzi naturali.

Mappatura: pitch+ (bordo anteriore in basso) → acqua verso il basso dello schermo; roll+ (bordo sinistro in basso) → acqua verso sinistra.

Costanti sintonizzabili (src/main.cpp)

Costante	Effetto
FLIP_RATIO	0 = liscio/viscoso (PIC), 1 = schizzi energici (FLIP); default 0.9
GRAVITY_SCALE	quanto è violenta la risposta a inclinazione e scatti
PRESSURE_ITERS / OVER_RELAXATION	rigidità dell'incompressibilità
MAX_PARTICLES / START_PARTICLES	quantità d'acqua massima / iniziale
FAUCET_MAX	portata del rubinetto a manopola al massimo
PR	raggio particella: piccolo = più fitta, grande = più "spugnosa"
MAX_SPEED	clamp di sicurezza sulla velocità delle particelle
MATRIX_BRIGHTNESS	luminosità matrice 0..8
INVERT_ROLL / INVERT_PITCH	se l'acqua corre dal lato opposto, flippano l'asse (INVERT_ROLL è già 1 di default: asse X corretta sull'hardware reale)

Struttura

codeyrocky-fluid/
├── platformio.ini        config ESP32 (come il firmware upstream)
├── src/main.cpp          la simulazione FLIP
└── lib/CodeyRocky/       libreria (venduta da)
                          github.com/messinamirko99-design/codeyrocky-firmware

Nota: la logica è stata verificata su host (compilando main.cpp contro uno stub che replica l'API della libreria): stabilità, pooling corretto su tutti i lati, rubinetto e pulsanti, zero NaN su minuti di simulazione. Il firmware va comunque flashato e provato sull'hardware.

Licenza

GPL-2.0-or-later, come la libreria CodeyRocky di messinamirko99-design (venduta in lib/, licenza in LICENSE). L'algoritmo FLIP è quello pubblicamente descritto da Matthias Müller (Ten Minute Physics) e dimostrato da N. L. Johnson (flip-card, GPL).