Aggiornamenti OTA (Over-The-Air)

Tempo di lettura: ~6 minuti · Tempo di esecuzione: ~3-5 minuti per device · Pubblico: chi ha già Controller e/o Dosometrica configurati e online sul portale, e deve aggiornarne il firmware

🔵 Guida avanzata (tecnica) — non parte del percorso onboarding 01-08. Usa questa per aggiornare un device già in uso. Per la prima installazione o per il recovery di un device "bricked" devi passare dal flash USB (vedi guida 16).

1. Cosa stai per fare

L'OTA (Over-The-Air, "via etere") è il metodo per aggiornare il firmware di un device senza cavi, direttamente dal portale. Niente PC, niente cavo USB, niente smontare la centralina dal mobile sotto la vasca. Clicchi un bottone e in pochi minuti il device si aggiorna da solo.

In dettaglio: quando JoyReef rilascia una nuova versione di firmware (Controller o Dosometrica) il portale se ne accorge e ti propone l'aggiornamento nella pagina di modifica del device, con un badge rosso "Update disponibile". Cliccando "Avvia OTA":

1. Il portale genera una URL temporanea firmata (valida 30 minuti) verso il binario del firmware
2. Manda al device 2 comandi MQTT: "ecco l'URL del nuovo firmware" + "scaricalo e installalo"
3. Il device scarica il binario via HTTP, lo scrive in memoria flash, e si riavvia con il nuovo firmware
4. Torna online dopo pochi secondi con la versione aggiornata

Tutto questo automaticamente, senza che tu debba fare nulla oltre cliccare il bottone.

In questa guida:

• Capisci quando puoi usare l'OTA e quando devi usare l'USB
• Vedi come avviare un OTA dal portale
• Sai come diagnosticare se qualcosa va male

2. Quando si può usare l'OTA

L'OTA funziona solo se:

• ✅ Il device è online sul portale (vedi indicatore stato nella pagina /devices). Se è offline, il messaggio MQTT non gli arriva
• ✅ Il device ha già un firmware JoyReef funzionante (anche vecchio): se è completamente vergine o "bricked" (firmware corrotto, non parte), l'OTA non può comunicare con lui → devi passare dal flash USB
• ✅ È un Controller o una Dosometrica: le smart plug Tasmota hanno il loro sistema di aggiornamento separato (dalla loro pagina amministrativa, non da JoyReef)
• ✅ C'è una versione più recente disponibile rispetto a quella installata (se sei già all'ultima, il bottone non compare)

In tutti questi casi → puoi e dovresti usare l'OTA.

Quando devi invece passare dall'USB (guida 16)

• ❌ Device mai flashato (nuovo di pacca)
• ❌ Device non si avvia (firmware corrotto da un OTA fallito o altro)
• ❌ Device offline da settimane e non riesci a farlo tornare online
• ❌ Vuoi forzare un firmware specifico (downgrade, versione di test, fork custom)

3. Apri la pagina del device da aggiornare

Dal portale JoyReef:

1. Menu di sinistra → "Dispositivi" (oppure Config → Dispositivi)
2. Trova il device da aggiornare nell'elenco
3. Clicca sulla riga → si apre la pagina di modifica device (/devices/{id}/edit)

Scorri fino alla sezione "Firmware".

🖼️ Immagine da inserire qui (Sezione Firmware nella pagina device): screenshot della sezione "Firmware" dell'edit device, con badge "Update disponibile" rosso, "Attuale: 1.2.3" e "Ultima disponibile: 1.3.0" visibili.

4. Leggi la sezione Firmware

La sezione mostra:

Pillola di stato

• 🔴 "Update disponibile" = c'è una versione più recente per questo device
• 🟢 "Aggiornato" = sei già all'ultima

Versioni

• Attuale: vX.Y.Z = la versione installata sul device adesso
• Ultima disponibile: vX.Y.W = l'ultima pubblicata da JoyReef per questo tipo di device

Changelog (se aggiornamento disponibile)

Se è disponibile un nuovo firmware, sotto i numeri di versione vedi il changelog della nuova release: cosa è cambiato (bug fix, nuove feature, breaking change). Leggilo prima di aggiornare: a volte ci sono note importanti tipo "richiede ricalibrazione sonda" o "ATO impostazioni vanno riconfigurate".

Bottone "Avvia OTA"

Compare solo se c'è davvero un aggiornamento disponibile. Se sei già all'ultima versione, il bottone non c'è (badge verde "Aggiornato" lo dice).

5. Step 1 — Avvia l'OTA

Click sul bottone "Avvia OTA".

Vedi un breve messaggio di conferma "Comando inviato" o simile. Da questo momento:

1. Per ~30 secondi non vedi cambiare nulla nella pagina (il device sta scaricando)
2. Poi il device si riavvia da solo → nel monitor MQTT/eventi (se hai la pagina /events aperta) vedi un breve "Device offline" / "Device online"
3. Ricarica la pagina (F5): la sezione Firmware ora mostra: - Badge verde "Aggiornato" - "Attuale: vX.Y.W" (nuova versione) - Bottone scomparso

Hai aggiornato. ✅

Quanto dura?

Tipico: 2-5 minuti totali dalla pressione del bottone al device di nuovo online con il nuovo firmware. I tempi dipendono da:

• Velocità WiFi del device (binari da 1-2 MB)
• Carico del server che hosta il binario
• Dimensione del firmware (a volte le release sono più "pesanti")

6. Step 2 — Verifica che tutto funzioni dopo l'aggiornamento

Dopo l'OTA, fai un check rapido:

• ✅ Vai in /devices → il device deve essere Online
• ✅ Vai in /events filtro "Sensori" → le letture sensori devono arrivare con timestamp recenti
• ✅ Se è un Controller: la pagina /ato / temperature / cambio acqua deve mostrare ancora il monitor live attivo (= stato real-time delle automazioni)
• ✅ Se è una Dosometrica: vai in /dosers/{id}, prova una dose manuale piccola per verificare che funzioni

Se tutto va bene, fine. Se qualcosa sembra strano, vai alla sez. "Se qualcosa non va".

💡 Le impostazioni di automazioni / calibrazioni / programmazioni sono persistenti attraverso gli aggiornamenti OTA. Non devi riconfigurare nulla dopo un aggiornamento normale. Eccezione: aggiornamenti major che cambiano lo schema dati (rari, in genere lo annunciamo nel changelog).

7. Aggiornare più device in sequenza

Se hai più device da aggiornare (1 Controller + 1 Dosometrica, o setup multi-vasca):

1. Aggiorna uno alla volta, aspettando che ciascuno torni online prima di passare al successivo
2. Tra un OTA e l'altro, lascia almeno 1-2 minuti di "respiro" al WiFi/MQTT broker

Non aggiornare tutto in parallelo: l'OTA usa parecchia banda WiFi locale e MQTT bandwidth. Con 3-4 download paralleli rischi che qualcuno fallisca per timeout.

💡 Suggerimento ordine: prima i device meno critici (Dosometrica), poi i più critici (Controller). Se la Dosometrica ha un problema con la nuova versione, l'ATO e i sensori sono ancora attivi sul Controller. Aggiornando prima il Controller invece, se ci sono problemi resti senza ATO finché non rifletti.

8. Quando il portale rileva nuovi firmware?

Il portale controlla periodicamente se ci sono nuove versioni dei firmware pubblicate da JoyReef. Tipicamente:

• L'indice viene aggiornato ogni volta che apri la pagina /devices o /devices/{id}/edit
• Se hai la pagina aperta e nel frattempo viene rilasciata una nuova versione, devi ricaricare (F5) per vederla

💡 Vuoi essere notificato dei nuovi rilasci? Per ora non c'è una notifica email automatica per nuove versioni firmware. Le release importanti vengono comunicate sui canali JoyReef (newsletter, sito). Per i nuovi firmware "minor" basta passare ogni tanto da /devices e controllare se ci sono badge rossi.

9. Se qualcosa non va

Il bottone "Avvia OTA" non compare

• Sei già all'ultima versione (badge verde "Aggiornato") → niente da aggiornare
• Device offline → l'OTA non parte se il device non è raggiungibile. Riportalo online prima
• Tipo device non supportato OTA → le smart plug Tasmota non hanno OTA da JoyReef. Devi aggiornarle dalla loro pagina admin (vedi documentazione Tasmota)

Ho cliccato "Avvia OTA" ma non succede niente

• Device offline al momento del click → ricarica la pagina /devices, verifica che il device sia online, riprova
• Comando MQTT perso (raro): aspetta 1 minuto e riprova
• Device sta scaricando ma è lento (WiFi debole, server occupato): aspetta fino a 5 minuti prima di concludere che è fallito

Device offline dopo l'OTA, non torna su

Questo è lo scenario peggiore (raro ma può succedere). Indica che il flash è fallito a metà e il device non ha un firmware funzionante. Devi fare recovery via USB:

1. Stacca alimentazione dal device
2. Collegalo via cavo USB al PC
3. Apri la guida 16 — USB Flash
4. Flasha il firmware più recente (o quello che usavi prima, se preferisci downgrade)
5. Riconfigura WiFi se necessario (di solito è preservato)

💡 Per ridurre il rischio di OTA falliti: assicurati che il device abbia un segnale WiFi solido (RSSI > -70 dBm) prima di lanciare l'OTA. Un OTA che fallisce a metà per perdita di connessione è la causa #1 di "device bricked".

"Nessun firmware disponibile" come errore

Il portale non trova un firmware pubblicato per quel tipo di device. Cause:

• Nuovo tipo di device non ancora supportato dall'indice (problema lato JoyReef, segnala)
• Device con type non riconosciuto nel modello (capita per device legacy importati). Contatta supporto

"Il dispositivo ha già l'ultima versione" ma vedo il bottone OTA

Il portale "vede" un firmware più recente nell'indice, ma il device dice di essere già su quella versione. Cause:

• Version string difference (v1.2.3 vs 1.2.3 vs v1.2.3-stable): il confronto può sbagliarsi
• Device installato di recente con la stessa versione ma con metadata vecchi nel portale: ricarica /devices e il badge si dovrebbe correggere

In ogni caso non c'è rischio: il bottone "Avvia OTA" è idempotente, al massimo riflasha la stessa versione.

Dopo l'OTA le impostazioni sono sparite

Eccezione rara, accade su aggiornamenti major dove cambia lo schema dati. Se questo è il caso, lo abbiamo annunciato nel changelog della release.

Soluzione:

• Riconfigura ATO / temperatura / dosometriche / cambio acqua dalle rispettive pagine (le impostazioni nel portale sono salvate sul server, non sul device — quando salvi vengono rispedite al device)
• Se invece i tuoi dati sul portale sono spariti, è un bug serio → contatta supporto

10. Conclusione

L'OTA è il modo quotidiano per tenere aggiornati i tuoi device JoyReef. L'USB resta come fallback per recovery o prima installazione.

💡 Frequenza consigliata: controlla la pagina /devices ogni 2-3 mesi, o quando ricevi una comunicazione di rilascio. Non c'è ragione per "saltare" volontariamente versioni stabili — gli aggiornamenti includono bug fix che migliorano sempre la situazione.

💡 Strategia conservativa: se hai più vasche separate, aggiorna prima quella "di test" (o la meno preziosa), aspetta 1-2 settimane senza problemi, poi aggiorna le altre. Le release JoyReef sono testate, ma "su due vasche al mondo" è sempre meglio di "tutte insieme".