Aggiornamento del firmware

Gli aggiornamenti portano nuove funzionalità, un supporto più ampio dei contatori, correzioni di bug e di sicurezza. Ogni versione ha il suo registro delle modifiche.

I file di aggiornamento sono pubblicati su https://fw.ziggymeter.com.

WARNING

Il downgrade non è possibile. Il dispositivo accetta solo firmware più recente di quello in esecuzione. Consentire il downgrade permetterebbe di reinstallare una versione con vulnerabilità note e di aggirare le correzioni di sicurezza — un attacco di rollback.

Verifica la versione attuale

Dove	Come
Interfaccia web	System → Software Version
Zigbee	L'attributo file version. Il nome varia a seconda del coordinatore; di solito vedi solo il numero di build, per es. 320 per la versione 1.0.320-release.
API	GET /api/v1/system/version
Console seriale	Stampata all'avvio

Numerazione delle versioni

Tre numeri separati da punti, seguiti da un suffisso — per esempio 1.2.320-release:

Parte	Esempio	Significato
Major	1	Aumenta per modifiche che rompono la compatibilità: comportamento cambiato, funzioni rimosse, configurazione incompatibile.
Minor	2	Aumenta per miglioramenti retrocompatibili — nuove funzioni che non richiedono nulla da parte tua.
Build	320	Aumenta a ogni singolo rilascio. Identifica in modo univoco la build esatta ed è la versione comunicata al coordinatore Zigbee.
Suffisso	-release	Il tipo di build. Il firmware pubblicato è sempre -release.

File di aggiornamento

I file seguono una convenzione di denominazione fissa, così capisci a colpo d'occhio a cosa serve un file:

XXXX-YYYY-00320-20250324T195250-ZiggyMeter-1.2.320-release.ota

Parte	Significato
XXXX	Codice del produttore
YYYY	Codice del prodotto
00320	Numero di build, che è anche la versione del file per Zigbee
20250324T195250	Data e ora della build, AAAAMMGGThhmmss
ZiggyMeter	Nome del prodotto
1.2.320-release	Versione del firmware, suffisso del tipo di build incluso
.ota	Estensione del file di aggiornamento

I file di aggiornamento sono cifrati e firmati digitalmente. Un file modificato anche di un solo byte non supera la verifica della firma e il dispositivo lo rifiuta.

Quale metodo usare

Metodo	Velocità	Ideale per
Interfaccia web (Wi-Fi)	Il più veloce	Quasi tutti
Zigbee OTA	Molto lento	Installazioni a batterie senza Wi-Fi
REST API	Veloce	Automazione, parchi di dispositivi, manutenzione remota

INFO

Un aggiornamento fallito non può rendere il dispositivo permanentemente inutilizzabile. Se il processo si interrompe — mancanza di corrente, connessione caduta — ripristina l'alimentazione e riprova con qualsiasi metodo.

Prima di iniziare

• Garantisci al dispositivo un'alimentazione stabile per tutta la durata del processo. Si consiglia l'USB-C.
• Verifica di passare a una versione più recente.

WARNING

Dopo un aggiornamento riuscito il dispositivo si riavvia e resta brevemente irraggiungibile. Il trasferimento del file in sé non interrompe il normale funzionamento.

Interfaccia web

Il metodo più veloce e consigliato.

1. Collega ZiggyMeter alla tua rete Wi-Fi.
2. Apri l'interfaccia web e vai in System → Upgrade.
3. Seleziona CHECK FOR UPDATES per cercare online un firmware più recente.
4. Se è disponibile un aggiornamento, seleziona UPGRADE FROM WEB.
5. Oppure seleziona UPGRADE FROM FILE per caricare un file scaricato da te — è il metodo da usare quando sei collegato al punto di accesso del dispositivo.
6. Attendi il trasferimento e il riavvio.
7. Verifica la nuova versione in System → Software Version.

TIP

Per cercare gli aggiornamenti solo il tuo browser ha bisogno di internet. ZiggyMeter non deve raggiungere internet — esattamente ciò che vuoi per un dispositivo in una rete isolata.

Zigbee OTA

Zigbee trasferisce il file in tanti piccoli blocchi su un collegamento radio a banda stretta, quindi richiede molto tempo — conta ore, non minuti.

1. Assicurati che ZiggyMeter sia associato e abbia una buona qualità del collegamento.
2. Posizionalo vicino al coordinatore o a un router con segnale forte.
3. Nel software del coordinatore, trova il dispositivo e avvia un aggiornamento firmware OTA.
4. Tieni il dispositivo alimentato e a portata fino al completamento.
5. Al termine verifica la versione.

Se il trasferimento si blocca, di solito si risolve migliorando il collegamento radio: posizione più vicina, più router nella rete mesh, meno interferenze.

Sia Zigbee2MQTT sia Home Assistant possono essere configurati per trovare automaticamente il firmware di ZiggyMeter:

Zigbee2MQTT OTAIndice OTA remoto per gli aggiornamenti automatici.Home Assistant ZHA OTAConfigurazione del provider zigpy.

REST API

Usa questo metodo per automatizzare le distribuzioni o gestire i dispositivi da remoto.

1. Assicurati che il dispositivo sia raggiungibile in rete.
2. Ottieni un token, poi invia il file .ota con una POST a /api/v1/system/ota.
3. Attendi che il dispositivo lo verifichi e lo installi.
4. Interroga di nuovo la versione per conferma.

curl -X POST \
  https://<host>/api/v1/system/ota \
  -H "Authorization: Bearer <token>" \
  --data-binary "@XXXX-YYYY-00320-20250324T195250-ZiggyMeter-1.2.320-release.ota" \
  --limit-rate 128k

WARNING

Limita la velocità di invio. Il dispositivo non riesce a ricevere il file a piena velocità e segnala un errore se lo invii troppo in fretta. --limit-rate nell'esempio qui sopra non è facoltativo.

128k è un valore collaudato: un'immagine da 2,4 MB si trasferisce in circa 20 secondi. Se il dispositivo segnala un errore, scendi: un collegamento Wi-Fi più debole o un dispositivo occupato possono richiedere meno.

Se l'aggiornamento viene rifiutato

Messaggio	Causa
Old firmware version	Il file ha la stessa versione o una precedente. I downgrade vengono rifiutati.
Not firmware upgrade / Invalid firmware file	Il file non è un .ota di ZiggyMeter, oppure è per un altro prodotto.
Corrupted upgrade data	Il file non ha superato i controlli di firma o decifratura — scaricalo di nuovo.
Flash write error	Problema di memoria. Riprova; se persiste, contatta l'assistenza.