📘 Guide JoyReef
← Indice 📄 Scarica PDF

Installazione firmware via USB

Tempo di lettura: ~8 minuti · Tempo di esecuzione: ~10 minuti (flash + verifica) · Pubblico: chi deve installare o aggiornare il firmware di un device JoyReef (Controller, Dosometrica, pH o Mangiatoia)

🔵 Guida avanzata (tecnica) — non parte del percorso onboarding 01-08. Si usa quando: - Ricevi un nuovo controller/dosometrica vergine da flashare la prima volta - Recuperi un device che ha avuto problemi firmware (recovery / re-flash) - Vuoi forzare l'installazione di una versione specifica (downgrade, build di test)

⚠️ Per il normale aggiornamento periodico di un device già funzionante e online sul portale, NON serve l'USB: usa la più comoda procedura OTA dal portale descritta nella guida 17. Niente cavi, niente PC.

1. Cosa stai per fare

I dispositivi JoyReef (Controller principale e Dosometrica) sono basati su ESP32 e accettano firmware caricato via porta USB. Tradizionalmente questo richiede un tool desktop (esptool, Arduino IDE, PlatformIO). JoyReef ti permette di farlo direttamente dal browser, senza installare nulla, usando una tecnologia standard chiamata Web Serial.

Il flusso è:

  1. Apri la pagina /usb-flash del portale
  2. Scegli quale firmware vuoi (Controller, Dosometrica, pH o Mangiatoia)
  3. Colleghi il device via cavo USB al PC
  4. Il browser si "aggancia" alla porta seriale
  5. Il flash avviene in pochi minuti
  6. Riavvii il device → nuovo firmware attivo

Niente download di file .bin da gestire a mano, niente tool da configurare. Funziona anche per utenti che non hanno mai aperto una shell.

ℹ️ Quando NON usare questa guida: per la configurazione WiFi del controller appena flashato (= dirgli a quale rete connettersi), vedi la guida 03. Questa guida si ferma al flash del firmware.

2. Cosa ti serve

Hardware

Software

💡 Come capire quale driver ti serve? Senza driver, il device collegato non comparirà nella lista delle porte seriali del browser. Se la lista è vuota, è quasi sempre un problema di driver: - Vai sul sito del produttore della scheda (CH340 → wch-ic.com, CP210x → silabs.com) - Cerca il driver per il tuo sistema operativo - Installa, riavvia, riprova

Accesso al portale

⚠️ HTTPS o localhost obbligatori: per motivi di sicurezza, il browser permette Web Serial solo su pagine sicure. Se accedi a JoyReef tramite https://portal.joy-reef.com sei a posto. Se per qualche motivo stai usando una URL http:// non locale, le Web Serial saranno bloccate.

3. Apri la pagina USB Flash

Dal portale JoyReef:

  1. Menu di sinistra → "USB Flash" o "Firmware via USB" (può essere in Config)
  2. Oppure vai a portal.joy-reef.com/usb-flash

Si apre la pagina "Installa firmware via USB" con sezioni:

Se vedi un banner rosso del tipo "Web Serial non è disponibile in questo browser" → stai usando un browser non supportato. Apri Chrome/Edge.

Se vedi "Il browser blocca Web Serial su pagine non sicure" → stai su http:// non-localhost. Vai su https://portal.joy-reef.com.

Usb Flash Page

4. Step 1 — Scegli il firmware corretto

Nella sezione "Firmwares" vedi un box per ciascun tipo di device (Controller, Dosometrica, pH, Mangiatoia):

Controller

Il firmware del Controller principale JoyReef. Gestisce:

Dosometrica

Il firmware della Pompa dosometrica 6 canali JoyReef. Gestisce:

⚠️ Flashare un firmware sbagliato sul device sbagliato (es. firmware Controller su Dosometrica) non rompe permanentemente il device, ma lo lascia in uno stato non funzionante. Devi solo riflashare quello corretto. Però fai attenzione a non confonderti: i due firmware sono incompatibili.

Sotto ogni box vedi 3 elementi:

Per il 99% dei casi clicca solo "Connetti e flasha".

5. Step 2 — Collega il device via USB

Prima di cliccare "Connetti e flasha":

  1. Spegni l'alimentazione esterna del device (se collegata): durante il flash sarà alimentato dal cavo USB
  2. Collega il cavo USB dal PC al device. Vedrai un LED accendersi sul device → segno che riceve corrente dal cavo
  3. Aspetta 3-5 secondi per dare tempo al PC di "riconoscere" il device e caricare i driver

💡 Verifica che il PC veda il device (opzionale ma utile per pre-diagnosticare): - Linux: apri terminale, lancia ls /dev/ttyUSB* (per CH340) o ls /dev/ttyACM* (per altri chip). Devi vedere almeno /dev/ttyUSB0 o simile - Windows: Gestione dispositivi → sezione "Porte (COM e LPT)" → devi vedere "USB Serial Device (COMx)" o "USB-SERIAL CH340 (COMx)" - Mac: terminale → ls /dev/cu.* → devi vedere /dev/cu.usbserial-XXXX o /dev/cu.SLAB_USBtoUART

Se non vedi nulla, è problema di driver (sez. 2) o cavo (è ricarica only?).

6. Step 3 — Avvia il flash

  1. Nel box del firmware corretto, clicca "Connetti e flasha"
  2. Il browser apre un popup: "joy-reef.com vorrebbe connettersi a una porta seriale"
  3. Nell'elenco vedi tutte le porte seriali disponibili sul tuo PC. Scegli quella corrispondente al tuo device (di solito è l'unica, oppure l'ultima collegata)
  4. Clicca "Connetti" nel popup del browser

Il tool di flash si attiva. Vedi una progress bar che mostra le fasi:

Durante il Writing, non staccare il cavo USB e non chiudere la scheda del browser. Un'interruzione a metà può rovinare il flash (recuperabile rifacendolo da zero, ma fastidio).

📷 PLACEHOLDER-USB-FLASH-PROGRESS

🖼️ Immagine da inserire qui (Flash in corso): screenshot del tool di flash con progress bar a ~60% (Writing), percentuale visibile.

7. Step 4 — Riavvia il device

Quando vedi "Done!" o "Flash completato":

  1. Stacca il cavo USB dal device
  2. Ricollega l'alimentazione esterna (alimentatore 5V o 12V a seconda del device)
  3. Il device parte con il nuovo firmware

Vedrai:

💡 Tip importante per gli aggiornamenti: il flash non cancella la configurazione WiFi salvata (a meno che tu non abbia spuntato "Erase" prima di partire). Quindi un aggiornamento di firmware si limita a "sostituire il software", mantenendo le credenziali WiFi. Se vuoi un reset completo, devi forzare un "Erase" durante il flash (alcuni tool lo fanno automaticamente).

8. Se qualcosa non va

Il browser dice "Web Serial non è disponibile"

La lista porte è vuota quando clicco "Connetti e flasha"

Vedi sez. 2 sui driver. Cause più probabili in ordine:

  1. Driver mancanti (Windows / Mac) → installa CH340 o CP210x
  2. Cavo USB di solo ricarica → cambia cavo (test rapido: prova con un cavo che usi normalmente per scambiare file con il cellulare)
  3. Porta USB del PC malfunzionante → prova un'altra porta USB
  4. Device alimentato esternamente ma con USB instabile → stacca l'alimentazione esterna, lascia solo USB
  5. Device hardware difettoso (raro, ma capita) → contatta supporto

"Failed to open serial port"

Il browser vede la porta ma non riesce ad aprirla. Cause comuni:

  1. Porta già occupata da un altro programma → chiudi IDE/Arduino/PlatformIO/monitor seriale che hai aperto, anche da altre schede del browser
  2. Driver corrotto → reinstalla i driver USB-seriale
  3. Cavo USB cattivo → ancora cavo
  4. Replug del device → stacca e ricollega il cavo USB, riprova selezionando di nuovo la porta

Il flash si blocca a metà (es. al 50% Writing)

Cause più probabili:

  1. Cavo che si è mosso → ricollega bene e ricomincia
  2. PC che è andato in sospensione → disabilita sleep durante il flash
  3. Tab del browser che ha perso il focus → tieni la scheda di flash visibile, non passare ad altre app
  4. Device che ha perso alimentazione → cavo USB difettoso o porta USB sottoalimentata. Prova un'altra porta o un cavo di qualità migliore

In tutti i casi: ricomincia il flash da zero. Il device potrebbe essere in stato inconsistente ma riflashare risolve sempre.

"Device non riconosciuto" dopo il flash

Il flash è andato a buon fine ma il device non parte:

Funziona solo dal browser? Posso usare esptool?

Sì. Clicca "Scarica .bin" nel box del firmware → ottieni il file binario. Poi usa esptool.py da terminale:

esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash 0x0 firmware.bin

Sostituisci /dev/ttyUSB0 con la tua porta. Se anche esptool fallisce, il problema è hardware/driver/porta, non del tool del browser.

9. Quando aggiornare il firmware

Non c'è un obbligo: se la tua vasca è stabile e tutto funziona, non serve aggiornare per il gusto di aggiornare. Aggiorna quando:

⚠️ Per gli aggiornamenti di routine non usare l'USB: usa l'OTA dal portale (guida 17). Molto più rapido e non richiede di smontare il device. L'USB di questa guida serve per: prima installazione, recovery, downgrade, versioni custom.

💡 Aggiornamenti distinti: portale (Vue/Laravel) e firmware (Controller/Dosometrica) sono indipendenti. Il portale si aggiorna da solo (sei sempre sulla versione più recente quando apri il sito). I firmware non si aggiornano da soli: devi attivare l'aggiornamento tu, via OTA (guida 17) o via USB (questa guida).

⚠️ Prima di un aggiornamento importante: annota le impostazioni delle automazioni (ATO, temperatura, ecc.) — di solito vengono mantenute, ma in caso di reset totale (es. nuova versione major con schema dati cambiato) potresti dover riconfigurare.

10. Conclusione

Hai gli strumenti per gestire il firmware dei tuoi device JoyReef in autonomia. Se è la prima installazione, ora il device è pronto per la configurazione WiFi:

➡️ Torna alla Guida 03 — Firmware + WiFi per dire al device a quale rete WiFi connettersi.

Se invece era un aggiornamento di un device già configurato, sei a posto: appena il device riparte, lo vedrai automaticamente ricomparire online nella pagina /devices.

💡 Per chiunque arrivi qui sentendosi insicuro: il flash via USB è una delle operazioni più solide e reversibili del mondo embedded. Se sbagli, riflashi. Non rompi nulla. Il tempo peggiore di flash sbagliato che ti possa capitare è 10 minuti di "qualcosa non funziona, riproviamo".