Manuale collegamento e formato dati WiFi/HTTP GSM/HTTP e WiFi/MQTT
Seguendo poche semplici regole si possono leggere dati da TXdata, TXtemp, TXsoil, TXloop e passare dati a ControlHUB, DisplayRX, RXTXeasy... oppure alla propria automazione HTTP o MQTT; allo stesso modo strumenti terzi possono seguire queste regole per "parlare" a ControlHUB, RXTXeasy eccetera...
|
Questo breve manuale è interessante per prima cosa per capire come ricevere dati da TXdata TXtemp TXsoil e TXloop.
TXtemp TXdata TXsoil TXloop e anche
RXTXeasy quando ritrasmette i dati seguono le specifiche di questa pagina, che sono un'applicazione molto di base degli standard
HTTP e
MQTT (per cui oltre a usarli con i nostri display e controller, li puoi integrare in qualsiasi automazione nuova o esistente).
Il manuale è interessante anche per capire come mandare i dati in modo che essi possano essere ricevuti ed elaborati da
DisplayRX,
RXTXeasy e in particolare dal controllore multifunzione
ControlHUB, specialmente per la parte
HTTP (vedere anche il rispettivo
manuale di ControlHUB visto dal lato di chi riceve). Vista la grande quantità di dispositivi che ControlHUB già supporta, hobbisti e professionisti possono trovare interessante interfacciare le loro cose (per non dover reinventare la ruota) e trasmettere dati allo stesso modo.
HTTP ha vantaggi di semplicità e risposta immediata; MQTT è supportato dalla maggior parte degli hub e/o Home Assistant e ci sono trucchetti per usarlo con dispositivi che non lo supportano "direttamente".
Comunicazione HTTP <<<
La comunicazione HTTP, per l'immediatezza e per il fatto di poter essere usata facilmente anche tramite GSM, è stata la nostra prima scelta. Non è comoda solo per
TXtemp TXdata e
TXsoil ma è una scelta intelligente per qualsiasi nuovo sensore si voglia usare con
RXTXeasy oppure interfacciare a un hub multifunzione come
ControlHUB.
Per prima cosa abbiamo inserito questo standard in tutti i nostri dispositivi, ma lo rendiamo pubblico visto che per diverse funzioni è comunque una scelta molto pratica ed efficiente.
Ricezione comandi WiFi/HTTP (/c)
I comandi si possono mandare a TXtemp/soil/data tramite una richesta HTTP GET fatta a:
- http://wfeasy.com/c (se sei connesso al wifi interno di TXdata/temp/soil)
- oppure qualcosa come http://192.168.1.20/c (se hai collegato TXtemp/soil/data al tuo WiFi; l'IP che abbiamo esemplificato con 192.168.1.20 è di solito assegnato dal router, TXtemp lo scrive in calce a tutte le pagine una volta collegato; e volendo si può fissare dentro alle opzioni di configurazione del tuo router, così che non cambi; tipicamente si fa in un menù tipo DHCP utilites o Avanzate DHCP).
Si possono mandare a TXdata/temp/soil dei comandi nel formato classico delle richieste GET (e quindi usando il simbolo & per inserire parametri multipli e separarli, e usando il classico "URLencode" per gestire i caratteri non alfanumerici).
I comandi disponibili sono nel seguito.
Esempio: http://wfeasy.com/c?cm=STATE restituisce lo stato (che include temperatura o altri dati....)
Se usi l'IP, sarà (per esempio) http://192.168.1.4/c?cm=STATE e così via.
Tutto questo lo si può provare per esempio collegandosi al WiFi interno con un PC e scrivendo queste cose sulla barra del browser (Safari, Chrome, Firefox, Explorer); ovviamente lo si può fare anche con Mac, Raspberry o altri dispositivi...
Comando cm=
permette tutte le azioni consentite dai comandi MQTT, con gli stessi comandi (vedi sotto)
Esempio:
http://wfeasy.com/c?cm=STATE
restituisce lo stato di TXdata/temp/soil, il che comprende lo stato del sensore, ovvero temperatura, umidità e/o altri dati
http://wfeasy.com/c?cm=MEM:0
questo funziona solo con RXTXeasy e restituisce lo stato memorizzato per il canale RF 0 in ingresso a RXTXeasy (quello che sarebbe ritrasmesso come a0)
http://wfeasy.com/c?cm=MEM:100
questo funziona solo con RXTXeasy e restituisce lo stato memorizzato per il canale WiFi 0 in ingresso a RXTXeasy (quello che sarebbe ritrasmesso come a100)
Invio dati da TXdata, TXtemp, TXsoil, TXloop e anche RXTXeasy in WiFi/HTTP (/x)
Per poter inviare i dati in formato HTTP, TXdata TXtemp TXloop o TXsoil devono essere configurati nelle
Impostazioni (vedi il loro manuale veloce nelle rispettive pagine:
TXtemp TXdata TXsoil TXloop) in modo da collegarsi al tuo WiFi - WiFi che può essere un
WiFi "vero" collegato a Internet oppure può anche essere un
WiFi virtuale con server Web virtuale creato da una qualche apparecchiatura (smartphone, PC, Mac, microcontrollore, Hub home assistant,
ControlHUB, ecc.).
Sempre nelle
Impostazioni, la configurazione normalmente preselezionata è quella per l'invio HTTP agli altri prodotti VisualVision (
SuperClock,
DisplayRX,
ControlHUB e
RXTXeasy GSM); se vuoi usare un tuo script sul tuo server Web va scelta l'opzione successiva che permette di inserire la URL di uno script personalizzato (deve incominciare con http:// e usare la porta standard, 80); questa opzione va anche bene per inviare dati a un
ControlHUB affacciato sul web.
Genericamente lo script può essere qualcosa come http://www.aserver.com/nicescript.php o www.aserver.com/nicescript.php. Oppure nicescript.pl o nicescript.py ecc. - qualsiasi linguaggio di programmazione del server che supporti una richiesta HTTP POST nel normale standard CGI andrà bene.
Il nome e il path dello script sul tuo server è a tua scelta.
Se il server Web è in realtà un
ControlHUB "affacciato" su web, lo script dovrà essere
/x (quello predefinito), ovvero la URL sarà tipo:
http://nomedeldominio_o_ip/x
Parametri inviati via WiFi/HTTP POST CGI e compresi da DisplayRX, ControlHUB (/x)
Tutto questo è anche spiegato nel manuale di ControlHUB (visto dal lato di chi riceve).
TXtemp TXdata TXsoil TXloop (e/o qualsiasi strumento che voglia comunicare via HTTP con
DisplayRX ControlHUB ecc), invia, ad ogni trasmissione, delle richieste HTTP in standard CGI (che sono poi le stesse che si inviano quando si scrive qualcosa sulla barra del browser es. Firefox, Chrome, Safari, Explorer) alla URL indicata, GET o POST, con questi parametri:
id (unique identifier; preset when the source device is assembled)
pw (password set in the Settings page)
b (battery charge in % - if less than 25 batteries should be replaced)
w (TXdata/temp/soil -> http/wifi Channell)
z (RXRXeasy -> http/wifi Channell)
n (name - optional, can be omitted)
dm (current frequency / transmission interval: >0 minutes <0 days)
r (Generic JSON-> {"Temperature":20.1,"Humidity":50,"Pressure":1013.2,"Wind":20.4} ) VEDI SOTTO E MQTT
r (TXdata -> current readings, in plain text as HEX to Ascii; TXtemp/soil -> t & h as HexAscii; RXTXeasy -> no)
a0 (RXTXeasy only -> readings retransmitted from 433 Channell #0 format here...)
a1 (RXTXeasy " -> readings retransmitted from 433 Channell #1)
...
a100 (RXTXeasy " -> readings retransmitted from WiFi Channell #0)
a101 (RXTXeasy " -> readings retransmitted from WiFi Channell #1)
...
t (legacy TXtemp only-> current temperature * 100; new see r/Generic below)
h (legacy TXtemp only -> current humidity if available; new see r/Generic below)
Esempio per comunicazione a
Orologio/SuperClock (con Ch WiFi 0, password pippo, gli altri dati li capite):
http://wfeasy.com/x?pw=pippo&w=0&r={"Temperature":20.1,"Humidity":50,"Pressure":1013.2,"Wind":20.4}
Se ci fossero spazi o segni strani ci va l'urlencode.
Inoltre ControlHUB ha una funzione speciale per la memorizzazione automatica dell'IP di periferiche in variabili automatiche di sistema, utilizzabili poi comodamente per fare Azioni, questo è utilizzato nei nostri prodotti e teoricamente lo può sfruttare chiunque in un proprio prodotto/in un'automazione HTTP, basta usare la modalità Generic di r= e aggiungere nel JSON i campi IP e CHname; per esempio si può mandare un messaggio di stato con tante cose e poi IP e CHname:
r={"Relay1":1,"NiceVar":"nice good","IP":192.168.1.12,"CHname":"salotto"}
L'esempio sopra farebbe creare in automatico a CHUB la variabile $i_salotto$ assegnandogli il valore 192.168.1.12.
Si possono prendere anche le altre variabili creando un'Azione/Lettura che usa come sorgente il canale WiFi usato.
Il server DEVE rispondere con un breve testo di risposta (qualsiasi risposta verrà effettivamente letta come testo; righe terminate da LF), che include:
- Pass KO if the password is wrong
- RXOK if all right
Il server inoltre può inviare queste righe seguite da LF (\n):
sms=+393475556667
newdm=10
newdm=-2
Significato: sms=+4432321321321 dice di inviare immediatamente un SMS al numero indicato; newdm=10 (newdayminute) setta la frequenza di trasmissione a 10 minuti; newdm=-2 setta a 2 giorni (se c'è una frequenza di trasmissione)
Ricordiamo che oltre a poter usare questo sistema HTTP per comunicare con uno script con un vostro server Web, e per comunicare a un
ControlHUB collegato direttamente o in una rete locale, questo sistema può anche essere usato da
TXtemp/soil/data o altre apparecchiature in versione GSM per mandare i dati a un
ControlHUB affacciato su Internet (vedi info...).
Servirà attivare il funzionamento con script custom e lo script sarà quello predefinito ovvero qualcosa come http://2.34.44.39/x o http://qualcosa.dyndns.com/x
Legacy: cose specifiche per TXtemp TXdata TXsoil
Per un canale che riceve un
TXtemp, i dati in
r sono 2 o 3 bytes in HexAscii, (B1) (B2) (B3):
- temperatura=((B1)*256+(B2)) / 100
- (se c'è) umidità=(B3)
Esempio: r=090A sarebbe temperatura 23.14°C oppure r=090A15 sarebbe temperatura 23.14°C e umidità 21%
Per un canale che riceve un
TXdata, i dati in
r sono i bytes in HexAscii che il TXdata riceve dalla sua azione (per esempio una risposta a comando/comandi ModBus)
Per un canale che riceve un
TXsoil, i dati in
r sono 2 bytes in HexAscii, (B1) (B2):
- (B1) = 6F (esadecimale)
- umidità=(B2)
Dati generici in JSON (r Generic)
Per un canale che riceve uno strumento generico, i dati in r oltre che poter essere bytes in HexAscii, possono essere una stringa in formato JSON ovvero quello con le graffe, es. {Temperature:20.3} o anche {Energy:20,Volt:220,Ampere:0.34} oppure {"abc":"something good"}
Ora tutti i dispositivi, TXtemp TXsoil TXdata TXloop trasmettono in questo modo; notare che Date e Time sono omessi se non si attiva l'NTP (del resto quasi sempre il ricevente già conosce data e ora).
Esempi:
{"B":77,"Temperature":17.27,"Date":20230520,"Time":1432,"Name":"T595","D":"TXtemp"}
{"B":85,"Temperature":20.34,"Humidity":96,"Date":20230520,"Time":1201,"Name":"S68","D":"TXsoil"}
{"B":92,"Val":0.01,"Date":20230520,"Time":1423,"Name":"L802","D":"TXloop"}
Script python di esempio
Oppure, per chi volesse provarlo sul proprio server (richiede Python),
questo script di esempio si può scaricare da
http://wfeasy.com/txtest.zip
In PERL o altri linguaggi è tutto molto simile, basta saper prendere dati da uno script CGI.
Comunicazione MQTT <<<
Le informazioni qui nel seguito sono specifiche per
TXtemp TXdata o
TXsoil - comunque sia
DisplayRX che
ControlHUB possono interpretare una gran quantità di fonti MQTT, purché il messaggio nel topic MQTT sia in testo, oppure JSON, oppure HexAscii.
Per avere disponibili i dati di
TXtemp TXdata o
TXsoil su un canale/Topic MQTT, ci si deve collegare a un WiFi che abbia accesso a un
Broker MQTT; per esempio ci si può collegare al Wifi di laboratorio/casa/ufficio o al WiFi di un
ControlHUB. Questo si fa dalle
Impostazioni, come illustrato nel manuale veloce. Sempre in
Impostazioni alla voce MQTT si inserirà:
- l'IP o il nome del server dove gira il Broker MQTT (se lasciato vuoto,
TXtemp TXdata TXsoil ecc. non useranno MQTT)
- eventualmente username e password del Broker, se li necessita
Il dispositivo mostra nella voce MQTT il nome dei topic di default usati per la pubblicazione/out e da usare per ricevere comandi/cmd; inoltre è possibile specificare un prefisso se ti serve (alcuni Broker gratuiti richiedono che i topic incomincino per esempio con tuousername/feeds/ o cose del genere), altrimenti lascia le caselle "prefix" vuote.
Quindi si clicca Salva e TXeasy si collegherà al Broker, e dopo qualche secondo comincerà a poter funzionare anche in MQTT. Se il collegamento è OK scriverà OK dopo la parola MQTT; e già da subito nella stessa pagina puoi vedere i nomi dei Topic da usare per comandare e per ricevere i messaggi di
TXtemp TXdata e
TXsoil.
Ti suggeriamo
per sicurezza di utilizzare un Broker installato su un tuo dispositivo (PC o altro; si può scaricare e installare e far girare un programma Broker come Mosquitto anche su un semplice PC Windows) e possibilmente di NON utilizzare cloud esterni / Broker gratuiti esterni perché se lo fai stai potenzialmente mettendo le tue cose in mani di estranei. Se il sistema non è molto grande si può usare il broker interno di
ControlHUB.
Topic MQTT di Risposta/Pubblicazione
Quando rispondono ai comandi, oppure quando vogliono dire qualcosa,
TXtemp TXdata o
TXsoil pubblicano un messaggio sul topic
tx-o-nome (dove Nome è il nome dato al dispositivo un po' più in basso sempre nelle Impostazioni).
L'automazione deve mettersi in ascolto su questo Topic per poter leggere la temperatura e/o gli altri dati.
La risposta/payload è un testo, questo è il testo inviato periodicamente a ogni misura della temperatura da TXtemp (questo formato con le graffe si chiama JSON):
{"B":77,"Temperature":17.27,"Date":20230520,"Time":1432,"Name":"T595","D":"TXtemp"}
Se c'è l'umidità, ci sarà anche un parametro
"Humidity" che è trasmesso come primo parametro da
TXsoil; mentre
TXloop
trasmette invece il suo valore come "Val". Per TXdata temperatura e umidità non ci sono. Per risparmiare dati se non è settato un NTP non è nemmeno trasmesso Time, e tutti i dati vanno nel settore H ovvero HexAscii (il significato della parte HexAscii per TXtemp è lo stesso che per HTTP). B è la carica della batteria in %; C il canale WiFi scelto (anche se si capisce già dal nome del Topic quale sia il TXtemp / data / soil che manda i dati, quindi non è indispensabile settarlo).
Se si accende
TXtemp TXdata o
TXsoil o
TXloop manualmente, per es. per la configurazione, su questo Topic viene pubblicato invece un messaggio tipo {"ON":1,"C":0,"Time":"2020-05-22 14:30.04","H":""}
Topic di Comando/Ascolto
TXeasy quando acceso dall'utente (e non durante l'accensione automatica) rimane in ascolto sul topic tx-c-nome (dove Nome è il nome che avete dato al vostro dispositivo un po' più in basso sempre nelle Impostazioni).
Per parlargli l'hub (o chiunque a mano tramite programmi di invio messaggi MQTT) può pubblicare su tale Topic di comando questo messaggio/payload (che tra l'altro è utile solo nel caso vogliate tenere un
TXtemp TXdata o
TXsoil permanentemente acceso):
STATE
|
restituisce lo stato globale, fornendo temperatura, umidità ecc.
|
{"MEM":123}
|
(solo RXTXeasy) restituisce i dati memorizzati per a123 (ovvero il canale Wifi numero 23); numeri disponibili sono 0..15 (i 16 canali RF, se presenti) e 100..199 (che sono i canali WiFi da 0 a 99)
|
NOTA: è possibile che questa funzione di comando/ascolto venga eliminata per i TX****.
Come noto, per
MQTT è necessario un sistema locale o remoto (accessibile via Internet) che faccia il
Broker MQTT.
Se stai facendo un'automazione con
TXtemp TXdata e
TXsoil si può semplificare, ed evitare questa necessità utilizzando anziché MQTT dei semplici comandi HTTP / Web, spiegati a inizio pagina.
Hardware e software professionale e facile da usare, dal 1996