Carica il firmware e collega al WiFi

Tempo di lettura: ~15 minuti · Tempo di esecuzione: 20-30 minuti · Pubblico: chi ha appena finito di assemblare il controller seguendo la guida 02

🟢 Guida fondamentale — percorso di onboarding obbligatorio. Senza di essa il sistema non parte.

🗺️ Il tuo percorso JoyReef:

1. Shopping list
2. Montaggio del controller
3. Firmware + WiFi ← SEI QUI
4. Configurazione vasca e sensori
5. Prese smart Tasmota
6. Automazioni (ATO, ecc.)

1. Prima di iniziare

Per questa guida ti serve:

• ✅ Il controller già assemblato come nella guida 02: NodeMCU sulla basetta, sonda + display + galleggianti collegati
• ✅ Il cavo micro-USB dati (deve passare i dati, non solo la corrente — vedi shopping list)
• ✅ Un computer (Windows, macOS o Linux) — non un telefono, per questa parte serve un PC vero
• ✅ Google Chrome o Microsoft Edge installati sul computer (Safari e Firefox non funzionano per il caricamento del firmware)
• ✅ Una rete WiFi a 2,4 GHz disponibile in casa (le moderne 5 GHz dei router più recenti non sono supportate dal controller)
• ✅ Un telefono o lo stesso computer, per il passaggio della configurazione WiFi (più avanti)

⚠️ WiFi 2,4 GHz è obbligatorio: il chip WiFi del NodeMCU (modello ESP8266) non supporta le reti a 5 GHz, è una limitazione hardware del chip e non si può aggirare. La maggior parte dei router moderni offre entrambe le bande contemporaneamente; se il tuo router le ha unite in un'unica rete (funzione chiamata "band steering" o "WiFi unificato"), il controller potrebbe non riuscire a connettersi. In caso di problemi, dalla pagina di configurazione del router disabilita temporaneamente la rete a 5 GHz — il controller troverà subito quella a 2,4 GHz. Una volta che è connesso, puoi riattivare il 5 GHz: il controller resta agganciato alla rete da cui ha imparato a connettersi. In dubbio, chiedi al tuo provider Internet.

2. Crea il tuo account JoyReef

Prima di caricare il firmware sul controller devi avere un account JoyReef: il portale è il "cervello" che riceve i dati dal controller e ti permette di vederli da qualsiasi telefono o computer.

Registrazione

1. Apri portal.joy-reef.com in Chrome o Edge
2. Clicca "Registrati" in alto a destra (oppure vai direttamente a portal.joy-reef.com/register)
3. Compila il form: - Email: quella che userai per accedere - Password: scegline una sicura, almeno 8 caratteri - Conferma password: stessa di sopra
4. Clicca Registrati

Verifica email

Subito dopo la registrazione il portale ti chiederà di verificare l'email:

1. Controlla la tua casella di posta (anche in Spam/Indesiderata — capita che il primo messaggio finisca lì)
2. Apri il messaggio "Verifica il tuo indirizzo email"
3. Clicca sul link di verifica

Una volta verificata l'email sei dentro: vedrai la dashboard del portale, per ora vuota — è normale, riceverà i dati appena il controller sarà connesso.

💡 Importante: l'email e la password che hai appena scelto sono anche le credenziali del tuo controller. Quando dovrai configurarlo (più avanti in questa stessa guida) userai esattamente gli stessi dati. Non servono "credenziali MQTT" separate da recuperare da qualche altra parte.

⚠️ Non ricevi l'email di verifica? Aspetta 1-2 minuti, controlla la cartella Spam. Se non arriva proprio, dal portale puoi cliccare "Reinvia email di verifica". Se ancora niente, scrivici a supporto@joy-reef.com.

3. Carica il firmware sul controller

Cos'è il firmware? È il software che gira dentro il NodeMCU e gli "insegna" come leggere i sensori, come parlare con il portale, ecc. Senza firmware, il NodeMCU è una scheda vuota che non fa nulla.

Il caricamento avviene direttamente dal browser — non devi installare programmi.

Passo 1: apri la pagina di flash

Apri portal.joy-reef.com/usb-flash in Chrome o Edge.

Vedrai due colonne: a sinistra i requisiti (devono essere tutti spuntati in verde), a destra l'elenco dei firmware disponibili.

Passo 2: collega il controller al computer

1. Prendi il cavo micro-USB dati della shopping list
2. Collega un'estremità al NodeMCU (la porta micro-USB visibile sulla basetta) e l'altra al computer
3. Sul NodeMCU si accenderà un LED rosso o blu (è solo l'indicatore di alimentazione, niente di più: a parte questo non succederà nulla finché il firmware non sarà caricato)

Passo 3: avvia il flash

1. Nella pagina del portale, nella sezione "Controller", clicca sul bottone "Install" (o "Installa")
2. Il browser apre una piccola finestra dove ti chiede di scegliere una porta seriale
3. Seleziona quella che corrisponde al tuo NodeMCU. Di solito si chiama "USB-SERIAL CH340", "Silicon Labs CP210x USB to UART" o simili. Se vedi più porte e non sai quale, scollega l'USB, guarda quale scompare, ricollega e seleziona quella
4. Conferma "Connetti"
5. Il flash parte automaticamente — ci vogliono circa 2-3 minuti, vedi una barra di progresso
6. Al termine il controller si riavvia da solo

⚠️ Su Windows e macOS potresti dover installare un driver USB se il browser non vede nessuna porta seriale. Cerca su Google "driver CH340 Windows" o "driver CP2102 macOS" (sono gratuiti, scaricati direttamente dalla casa madre del chip). Su Linux di solito funziona senza installare nulla.

💡 Errore "Connection failed" all'avvio del flash? Scollega il cavo USB, aspetta 5 secondi, ricollegalo e riprova. Capita a volte alla prima connessione.

4. Verifica che il flash sia andato a buon fine

Pochi secondi dopo la fine del flash, il controller si riavvia da solo e il display dovrebbe accendersi.

Cosa vedrai sul display

1. Per 2-3 secondi appare il logo JoyReef che riempie tutto lo schermo
2. Poi compare la schermata di setup, fatta di 3 righe:

WiFi: AP
AP: joyreef-XXXXXX
MQTT: ...

Al posto di XXXXXX ci sarà un codice unico del tuo controller, per esempio joyreef-3f7a92.

🖼️ Immagine da inserire qui (Display in modalità setup): macro del display OLED che mostra le tre righe WiFi: AP / AP: joyreef-XXXXXX / MQTT: .... Conferma visiva di "ecco cosa devi vedere se tutto funziona".

Se vedi questa schermata, il flash è andato bene e il controller sta aspettando di essere configurato (sezione successiva).

Cosa significa "modalità AP"?

Il controller ha creato una sua rete WiFi privata (chiamata appunto joyreef-XXXXXX): serve per permetterti di configurarlo, perché ancora non sa quale sia la tua WiFi di casa. È una rete temporanea che si spegnerà appena gli darai le credenziali del tuo router.

Se qualcosa non va

5. Collega il controller alla tua WiFi di casa

Ora che il controller è in modalità setup, devi:

1. Connettere il telefono (o PC) alla rete joyreef-XXXXXX creata dal controller
2. Aprire il wizard di configurazione del controller nel browser
3. Inserire le credenziali della tua WiFi di casa + email/password del tuo account JoyReef

Passo 1: connettiti alla rete del controller

Dal telefono (o PC):

1. Vai nelle impostazioni WiFi del tuo dispositivo
2. Cerca nell'elenco delle reti una chiamata joyreef-XXXXXX (XXXXXX = codice unico del tuo controller, lo stesso che hai visto sul display)
3. Connettiti: di solito non serve nessuna password

💡 Il telefono potrebbe avvisarti "Internet non disponibile": è normale. Il controller non è ancora collegato a Internet — sta aspettando di essere configurato. Su Android conferma "Resta connesso", su iPhone conferma "Mantieni connessione".

💡 Disattiva i dati mobili prima di continuare: se il telefono ha sia la rete joyreef-XXXXXX che la rete dati mobile attiva, Android e iOS potrebbero "preferire" automaticamente i dati mobili (perché vedono che la WiFi non ha Internet) e fare aprire il browser al loro indirizzo invece che al controller. Dalla tendina delle impostazioni rapide, disattiva i dati mobili per la durata della configurazione — riattivali tranquillamente dopo che il wizard è stato salvato.

Passo 2: apri il wizard di configurazione

Molti telefoni aprono automaticamente la pagina di configurazione (è la funzione "captive portal", la stessa che si usa per esempio negli hotel quando ti chiede di accettare le condizioni d'uso del WiFi).

Se la pagina si apre da sola, salta al Passo 3. Altrimenti:

1. Apri il browser del telefono (Chrome, Safari, Edge — uno qualunque va bene)
2. Digita nella barra dell'indirizzo: 192.168.4.1 e premi Vai
3. Vedrai apparire il wizard di configurazione JoyReef

🖼️ Immagine da inserire qui (Wizard captive portal): screenshot del primo step del wizard (solo "Lingua") visto dal telefono.

Passo 3: compila il wizard

Il wizard ha 3 schermate. Compila e premi Avanti ad ogni passaggio.

Schermata 1 — Lingua

• Lingua: Italiano (o quella che preferisci)
• Premi Avanti

Il fuso orario non si imposta qui: lo gestirai nel tuo profilo JoyReef dopo il primo collegamento. Il controller parte in UTC e si sincronizza automaticamente al collegamento MQTT.

Schermata 2 — La tua WiFi di casa

• WiFi: seleziona la tua rete di casa dall'elenco (deve essere a 2,4 GHz)
• Password WiFi: la password della tua rete
• Premi Prova a connettere: se la connessione riesce, comparirà il pulsante Avanti

Schermata 3 — Credenziali JoyReef

• Username: la email del tuo account JoyReef (sì, l'email, anche se l'etichetta dice "Username")
• Password: la password del tuo account JoyReef
• Premi Prova a connettere: se le credenziali sono giuste, comparirà il pulsante Salva e termina

Passo 4: salva e aspetta

Premi Salva e termina. Il controller a quel punto:

1. Salva le impostazioni nella sua memoria interna
2. Spegne la rete joyreef-XXXXXX
3. Si riavvia e si connette al tuo WiFi di casa
4. Si collega al portale JoyReef (lo verifichi nella sezione successiva)

Il tuo telefono si disconnetterà automaticamente dalla rete del controller (perché si è spenta). Riconnetti il telefono al tuo WiFi di casa per i prossimi passaggi.

⚠️ Se la connessione WiFi fallisce (Schermata 2): prima di tutto ricontrolla la password. Se non è quello il problema, è quasi sempre una questione di banda 5 GHz: il chip ESP8266 del controller non vede quel tipo di rete. Entra nella configurazione del router e disabilita temporaneamente la rete a 5 GHz (o separa le due bande dandogli nomi diversi). Riprova: il controller troverà la 2,4 GHz e si connetterà. Puoi riattivare il 5 GHz subito dopo.

⚠️ Se le credenziali JoyReef falliscono (Schermata 3): ricontrolla che siano esattamente quelle del portale. Se hai aggiornato la password dopo la registrazione, usa la nuova. Se è la prima volta che le usi, accedi prima al portale da PC per confermare che funzionino.

6. Verifica che il controller sia online

Dopo aver salvato il wizard, il controller si riavvia e si collega al tuo WiFi di casa. Devi controllare due cose: il display del controller e il portale.

Controlla il display

Dopo 10-20 secondi dal riavvio, sul display dovresti vedere:

WiFi: OK
IP: 192.168.1.42
MQTT: OK

L'IP che vedi (al posto di 192.168.1.42) è l'indirizzo che il tuo router ha assegnato al controller. Cambia da casa a casa, è normale.

Le tre righe che contano:

• WiFi: OK → il controller è agganciato al tuo router
• IP: ... → ha ricevuto un indirizzo valido
• MQTT: OK → sta parlando col portale JoyReef ✓

Se vedi tutto OK, sei a posto.

Controlla il portale

Sul tuo PC (o telefono, ora riconnesso al WiFi di casa):

1. Apri portal.joy-reef.com e accedi
2. Vai nel menu Devices (o Dispositivi)
3. Dovresti trovare il tuo nuovo controller in lista, con il nome joyreef-XXXXXX (lo stesso codice del display)

Il primo aggancio può richiedere fino a 1-2 minuti: il portale aspetta che il controller mandi il suo primo messaggio prima di mostrarlo.

Se qualcosa non va

7. Hai connesso il controller!

Bravo, hai fatto la parte più difficile. Da ora in poi tutto si configura dal portale dal divano: niente più cavi USB, niente più captive portal.

✅ Stato del tuo sistema in questo momento: hardware ✓, firmware ✓, WiFi ✓, account JoyReef ✓, controller online sul portale ✓.

Cosa manca per avere la dashboard piena di dati utili:

Il controller in questo momento sta già inviando le letture dei suoi sensori al portale, ma JoyReef non sa ancora a cosa servono: la sonda DS18B20 è "la temperatura"? E i 4 galleggianti, quale è il "livello basso ATO" e quale il "livello di sicurezza"? Bisogna dire al portale chi è chi.

📖 Guida 04 — Configura la vasca e assegna i ruoli dei sensori (~10 min)

In quella guida creerai la tua prima vasca virtuale, assegnerai i sensori alle loro funzioni reef-keeping (temperatura tank, livello sump, ecc.) e vedrai apparire la dashboard popolata con i tuoi dati live.

Buon reefing!

Guida JoyReef · v1.0 · Domande? Scrivici a supporto@joy-reef.com