nomadnet-ecowitt-plugin

Plugin per nodi NomadNet/Reticulum che espone i dati live di una stazione meteo Ecowitt GW1100A/GW2000A come pagina dinamica in Micron, leggendo i dati direttamente dall'endpoint locale del gateway (/get_livedata_info) — nessun account cloud Ecowitt richiesto.

Compatibilità: testato con gateway Ecowitt GW1100A e GW2000A. Entrambi espongono lo stesso endpoint locale /get_livedata_info con struttura JSON identica, quindi non è richiesta alcuna configurazione specifica per modello: basta impostare GATEWAY_IP con l'IP del proprio dispositivo (vedi Configurazione). Dovrebbe funzionare anche con altri gateway Ecowitt della stessa famiglia (es. GW1000, GW1200) che condividono la stessa API locale, anche se non sono stati testati direttamente.

Cosa fa

• Interroga il gateway Ecowitt sulla rete locale e ne interpreta il JSON (sensori esterni, sensore interno WH25, fulmini, pioggia, CO2).
• Espone una pagina NomadNet dinamica (weatherstation/index.mu) che elenca tutti i sensori disponibili, generata come Micron ad ogni richiesta.
• Mette a disposizione una libreria Python (weather_lib.py) con una cache di 60 secondi, così più visite ravvicinate alla pagina non sovraccaricano il gateway.
• Mantiene uno storico a 72 ore dei sensori (weather_history.py) e lo mostra come grafici sparkline testuali in una seconda pagina dinamica (weatherstation/history.mu) — vedi Storico e grafici.
• Può anche essere usato da riga di comando, indipendentemente da NomadNet (vedi Uso da CLI).

Come funzionano le pagine dinamiche di NomadNet

NomadNet serve le pagine da una directory pages/. Un file .mu normale viene letto come testo statico; se invece ha il bit eseguibile ed è preceduto da uno shebang (es. #!/usr/bin/env python3), NomadNet lo esegue e ne cattura l'output (stdout) come contenuto Micron della pagina. È così che weatherstation/index.mu genera dati sempre aggiornati.

Struttura del repository

weather_lib.py             libreria: fetch, cache, parsing, formattazione
weather_history.py         storico 72h: registrazione campioni e sparkline
weatherstation/index.mu    pagina dinamica NomadNet con tutti i sensori
weatherstation/history.mu  pagina dinamica NomadNet con lo storico/grafici
requirements.txt           dipendenze Python

Installazione

1. Copia il contenuto di questo repository nella directory pages/ del tuo nodo NomadNet, mantenendo weatherstation/ come sottocartella:

   ~/.nomadnetwork/storage/pages/
     weather_lib.py
     weather_history.py
     weatherstation/
       index.mu
       history.mu
   

2. Installa le dipendenze nell'ambiente Python usato dal demone NomadNet:

   pip install -r requirements.txt

3. Rendi eseguibili le pagine dinamiche (obbligatorio, altrimenti NomadNet le serve come testo statico invece di eseguirle):

   chmod +x weatherstation/index.mu weatherstation/history.mu

4. Riavvia/ricarica il nodo NomadNet e visita /page/weatherstation/index.mu.

5. (Opzionale) Per abilitare i grafici storici in /page/weatherstation/history.mu, configura anche il campionamento periodico — vedi Storico e grafici (72h).

Configurazione

Tutta la configurazione si trova in cima a weather_lib.py:

Costante	Default	Significato
GATEWAY_IP	192.168.1.5	IP locale del gateway Ecowitt GW1100A/GW2000A
DATA_ENDPOINT	/get_livedata_info	Endpoint HTTP del gateway
CACHE_TTL	60 (secondi)	Durata della cache prima di re-interrogare il gateway

Il file di cache viene scritto in tempfile.gettempdir() (non dentro la directory delle pagine), così non sporca la struttura servita da NomadNet.

Storico e grafici (72h)

weather_history.py mantiene uno storico a rotazione dei sensori (72 ore, un campione ogni 5 minuti) e lo rende disponibile come grafici sparkline testuali — caratteri a blocchi unicode, leggeri anche su un link LoRa a bassa banda — nella pagina weatherstation/history.mu. Non richiede modifiche a weather_lib.py: riusa fetch_livedata/get_livedata/SENSOR_LABELS da lì per interrogare il gateway ed etichettare i sensori.

Il campionamento non avviene alla visita della pagina: va programmato a parte con un cron esterno, altrimenti lo storico resta vuoto. Aggiungi una riga a crontab -e (adatta i percorsi al tuo ambiente):

*/5 * * * * /usr/bin/python3 ~/.nomadnetwork/storage/pages/weather_history.py --record >> /var/log/nomadnet-ecowitt-history.log 2>&1

Ogni esecuzione registra un campione e scarta quelli più vecchi di 72 ore, così il file di storico converge a una dimensione stabile (~864 campioni) invece di crescere indefinitamente. Come il file di cache di weather_lib.py, anche lo storico viene scritto in tempfile.gettempdir() (nomadnet_ecowitt_history.json): un riavvio del sistema che ripulisce la directory temporanea azzera lo storico, che poi si ripopola da solo nelle 72 ore successive.

Comandi utili da riga di comando:

python weather_history.py --record        # registra un campione ora
python weather_history.py                 # mostra percorso file e numero di campioni presenti
python weather_history.py --record --ip 10.0.0.20   # gateway su un altro IP

La pagina weatherstation/history.mu genera automaticamente un grafico per ogni sensore attualmente in linea (letto da common_list, wh25, co2, rain); se il gateway non risponde ma esiste comunque uno storico salvato, lo mostra ugualmente usando le chiavi grezze come etichetta.

Uso da CLI

weather_lib.py funziona anche come script standalone, indipendentemente da NomadNet:

python weather_lib.py                # riepilogo leggibile
python weather_lib.py --raw          # JSON grezzo del gateway
python weather_lib.py --ip 10.0.0.20 # gateway su un altro IP

Gestione degli errori

Se il gateway non è raggiungibile, la pagina non va in errore: mostra un messaggio ("dati non disponibili") invece di un traceback. Questo è importante perché NomadNet renderizza come Micron tutto ciò che uno script dinamico scrive, inclusi eventuali errori non gestiti — un dettaglio da tenere a mente se si estende questo plugin.

Lo stesso vale per weatherstation/history.mu: se non c'è ancora nessuno storico registrato mostra un messaggio invece di una pagina vuota, e se il gateway non risponde ma esiste comunque uno storico salvato lo mostra comunque, usando le chiavi grezze dei sensori come etichetta.

Contributing

Contributi, segnalazioni di bug e richieste di funzionalità sono benvenuti.

• Bug o proposte: apri una issue descrivendo il problema, il modello di gateway usato e, se possibile, un estratto del JSON restituito da /get_livedata_info.

• Pull request: forka il repository, crea un branch dedicato e apri una PR verso main. Per modifiche a weather_lib.py, verifica prima con:

  python weather_lib.py --raw

  che il parsing regga con i dati reali del tuo gateway.

• Stile: nessun tool di lint/formatter imposto; segui lo stile già presente nel file che stai modificando.

Il progetto è distribuito con licenza MIT.