Software per valvola termostatica TM3030 con estensione wifi- Progetto Walvola - SW

Questo post descrive il software da far girare sulla valvola TM3030 

con estensione wifi descritta in questo articolo [Come aggiungere il controllo wireless ad una valvola termostatica TM3030 - Progetto Walvola - HW]

Software

Sul mio github e' disponibile tutto il progetto Walvola, ed in particolare il software di  controllo della valvola e' disponibile [qui]

Chiaramente il software e' aperto e disponbile a tutti. Inoltre il software e' 'as is', cioe' proprio in base alla natura aperta io condvido il software che ho sviluppato per le mie esigenze.

Ovviamente supporto l'idea di accettare contributi esterni. Quindi chiunqe trovi il softyware utile e voglia contrbuie con delle miglorie e' il ben accetto.

Architettura

Il sistema di controllo remoto dell'impianto di riscaldamneto (valvole termostatiche e caldaia) adotta un'architettura flessibile e scalabile basata sullo scambio di messaggi MQTT.

L'architettura non prevede l'utilizzo e l'intermediazione di un controllore centrale ma e' totalmente distribuita.

Elementi Architetturali

I suoi elementi costituenti sono:

• Walvola: elemento montato direttamente sul termosifone che ha il compito di azionare il motore della valvola che comanda un pistoncino che permette o impedisce il flusso dell'acqua calda all'interno del termosifone

• IRB: elemento montato nel vano caldaia che ha il compito di attivare/disattivare il bruciatore della caldaia murale

• MQTT Broker: message broker che implementa il protocollo machine-to-machine MQTT implementando il pattern Publisher/Subscriber 

• iHeating: un'applicazione web mobile basata su framework7 che permette il controllo remoto da un qualsiasi dispositivo mobile o web browser

Funzionamento

Come detto sopra, il sistema di comunicazione si basa su un'architettura pub/sub in cui gli elementi che comunicano tra di loro (le valvole ed le applicazioni mobili) non sono fortemente connessi.

In particolare l'applicazione mobile viene a conoscenza dell'esistenza di una o piu' valvole tramite un semplice meccanismo di advertising. Cio' signigica che non e' necessaria nessuna configurazione particolare dell'applicazione mobile quando si aggiunge/rimuove una valvola, ma la lista delle valvole disponibili viene creata ed aggiornata dinamicamente.

Il software della valvola e' architetturalmente semplice ed implementa la funzione di:

• Subscriber: rimane in ascolto di messaggi pubblicati dai publisher e in caso di ricezione li processa andando as eseguire il comando inviato

• Publisher: informa gli altri elementi dell'architettura sul proprio stato interno tramite lo scambio di messaggi MQTT

Organizzazioe Topic MQTT

A questo punto e' chiaro che lo scambio di messaggio tra le varie valvole e le applicazioni mobili avviene tramite il protocollo MQTT. Piu' in particolare tale protocollo si basa sul concetto di topic, che in sostanza e' un canale di comunicazione tra uno/molto publisher ed uno/molti subscriber.

Nel software di controllo in questione i topic sono creati dinamicamente dal software non necessitano di nessuna configurazione iniziale.

Nel dettaglio i topic sono organizzati nel seguente modo:

Ogni valvola riceve i messaggi MQTT su un topic di ingresso ad essa dedicatao. Allo stesso modo ogni valvola pubblica messaggi MQTT verso i destinatari su un topic di uscita dedicato.

I topic in ingresso seguono la seguiente naming convention:

• <nome del topic>/in/<label valvola>

Mentre i topic in uscita seguono la seguiente naming convention:

• <nome del topic>/out/<label valvola>

dove:

• <nome del topic>: e' il nome del topic univoco comune per un intero sistema
• <label valvola>: e' il nome univoco di ogni valvola o IRB

Funzionalita' e comandi supportati

Il software e' attualmente alla sua release 1.3 e supporta una serie di comandi base ed implementa alcune funzionalita' di monitoring e controllo.

Piu' in dettaglio le funzionalita' attualemente supportate sono:

• ricezione comandi da apllicazione mobile
• GET_STATUS: comando di richiesta stato valvola. Quando la valvola riceve sul suo topic di ingresso tale comando, legge il suo stato interno lo posta sul topic di uscita a lei dedeicato

• SET_STATUS: comando di variazione stato valvola. Un applicazione di controllo puo' richiedere alla valvola, tramite questo comando, di cambiare il suo stato in uno dei seguenti:

• WALVOLA_ON:  stato di valvola aperta. Una volta che la valvola e' tutta aperta il pistoncino e' completamente ritratto e quindi permette il flusso d'acqua massimo attraverso il termosifone

• WALVOLA_OFF: stato di valvola chiusa. Una volta che la valvola e' tutta chiusa il pistoncino e' completamente esteso e quindi impedisce il flusso d'acqua attraverso il termosifone

• WALVOLA_OTA: stato di valvola in upgrade software. Quando la valvola e' in questo stato non esplica le sue normali funzioni, ma rimane in attesa del caricamento Over The Air di una nuova versione del software. Importante notare che al termine del caricamento del software la valvola viene resettata.

• RELAY_ON: stato di relay aperto. Apre il relay collegato alla caldaia attivando il bruciatore.

• RELAY_OFF: stato di relay chiuso. Chiude il relay collegato alla caldaia disattivando il bruciatore.

• GET_INFO: un applicazione di controllo richiede informazioni relative alla valvola che riceve tale comando. La valvola fornisce sul suo topic di uscita dedicato informazioni relative a:
• versione software
• voltaggio alimentazione (batterie)
• indirizzo IP assegnato

• UPDATE: comando di aggiornamento software della valvola. Il software implementa a funzionalita' di update Over The Air [qui piu' informazioni] permettendo l'aggiornamento della valvola senza doverla smontare dal termosifone. Nota: OTA e' difficilmente implementabile su di un modulo EPS8266-01 a causa delle dimensioni limitate della RAM. Questa modalita' e' supportata dal modulo ESP8266-12 e da altri moduli di tale famiglia.

• due modalita' operative:
• Walvola: il software svolge le funzionalita' di controllore di una valvola termostatica per termosifone
• IRB:il software svolge funzionalita' di controllo di un relay per accensione/spegnimento bruciatore

• due modalita' di risparmio energetico (piu' info [qui]):
• DEEP SLEEP:  polling periodico del topic MQTT di ingresso con funzionalita' deep sleep per risparmio energetico.
• MODEM SLEEP:  per i moduli che non supportano il deep sleep, implementazione della modalita' modem sleep. Nota: il modulo EPS8266-01 non supporta direttamente la modalita' deep sleep causa mancanza di una connessione tra due pin specifici del chip Espressif. E' possibile modificare il modulo ESP8266-01 in modo che possa supportare il deep sleep. L'operazione richiede una certa manualita' con il saldatura. In ogni caso [qui] le informazioni correlate

• software upgrade in loco OTA: come menzionato in caso di utilizzo del modulo EPS8266-12 e' possibile aggiornare tramite web browser il software della valvola senza dover smontare la valvola dal termosifone.

• monitoraggio carica batterie: la valvola periodicamente legge il voltaggio ai piedini di alimentazione e ne posta il risultato su un servizio cloud chiamato kee disponibile [qui]. Questo mi permette di monitorare il consumo delle valvole e di ottenre dei grafici di scarica delle batterie

• notifica telegram: la valvola notifica il cambio del proprio status inviando un messaggio telegram. In tal modo ricevo delle notifiche push sul mio cellulare per sapere sempre lo stato del mio sistema di riscaldamento. Nota:  nella versione attuale il messaggio telegram e' disabilitato causa di un bug nella libreria SSL. Sto debuggando il problema ed faro' un commit su github con il fix quanto prima

Organizzazione del software

Il software e' uno sketch Arduino basato sui seguenti file:

• Walvola.ino/h: file principale dello sketch. Contiene i classici setup e loop
• wifi.cpp/h: contiene le funzioni relative alla connettivita' wifi e all'implementazione del model sleep
• timeapi.cpp/h: contine le funzioni per interfacciarsi con il serivizo http://www.timeapi.org/ per ottenere la data e l'orario aggiornati (chi mi segue sa' che non sono un supporter del RTC)
• telegram.cpp/h: funzioni per l'invio di messaggi telegram. Nota:  nella versione attuale il messaggio telegram e' disabilitato causa di un bug nella libreria SSL. Sto debuggando il problema ed faro' un commit su github con il fix quanto prima
• mqtt.cpp/h: funzioni per la gestione della connettivita' MQTT e per il processamento dei comandi
• misc.cpp/h: funzioni generali di supporto
• keen.cpp/h: funzioni per l'invio della lettura del voltaggio batterie versio il servizio https://keen.io/
• json.cpp/h: funzioni per la gestione dei messaggi JSON ricevuti dall'applicazione controller

Configurazione del software

Il software necessita di una serie di parametri configurazione da scpecificare prima della compilazione e delle generazione del binario da caricare sul modulo ESP8266.

Vediamo qui in dettaglio quali parametri sono configurabili e dove sono disponibili.

• Walvola.ino:
• keen_voltage_collection: sostituire il valore YOUR KEEN.IO VOLTAGE COLLECTION con il nome della collezione kee.io su cui postare le letture del voltaggio della batteria. Notare che in cosa nome della collezione viene aggiuno il nome della valvola

• Walvola.h

• WALVOLA_DEEP_SLEEP_MODE: definisce la modalita' di funzionamento DEEP SLEEP. commentare per rimuovere tale funzionalita'
• WALVOLA_MODEM_SLEEP_MODE: definisce la modalita' di funzionamento MODEM SLEEP. commentare per rimuovere tale funzionalita'
• WALVOLA_ROLE: definisce la modalita' operativa Walvola e quindi il modulo si comporta di conseguenza (attivazione motore/pistoncino)
• IRB_ROLE: definisce la modalita' operativa IRBe quindi il modulo si comporta di conseguenza (attivazione relay)
• OTA_MODE:  abilita il supporto all'upgrade software in modalita' OTA via browser
• DEBUG: abilita' i messaggi di debug su seriale
• MQTT_DEBUG: abilita' il post dei messaggi di debug su uno specifico topic chiamato (<nome del topic>/out/<label valvola>/debug)
• WALVOLA_DELAY_ON: numero di millisecondi in cui il motore viene attivato per aprire la valvola e ritrarre il pistoncino
• WALVOLA_DELAY_OFF: numero di millisecondi in cui il motore viene attivato per chiudere la valvola ed estendere il pistoncino
• WALVOLA_LABEL: nome della valvola
• WALVOLA_ID: id univoco della valvola

• kee.h:

• KEEN_PROJECT_ID:   sostituire il valore YOUR KEEN.IO PROJECT ID con l'id univoco del tuo progetto keen.io
• KEEN_MASTER_KEY: sostituire il valore YOUR KEEN.IO MASTER KEY con il valore univoco della tua MASTER KEY relativa al tuo progetto keen.io

• mqtt.h:

• MQTT_UNAME: sostituire il valore YOUR MQTT BROKER ACCOUNT USER NAME con il tuo username per l'accesso al broker MQTT
• MQTT_PASSW: sostituire il valore YOUR MQTT BROKER ACCOUNT PASSWORD con la password per l'accesso al broker MQTT
• MQTT_BROKER_PORT: porta di accesso al tuo broker MQTT


• mqtt.cpp: 

• mqtt_walvolas_topic:sostituire il valoreYOUR TOPIC con il nome del tuo topic univoco per il tuo sistema
• mqtt_controllers_topic:sostituire il valoreYOUR TOPIC con il nome del tuo topic univoco per il tuo sistema
• mqtt_controllers_topic_debug: sostituire il valoreYOUR TOPIC con il nome del tuo topic univoco per il tuo sistema

• wifi.cpp:

• wifi_ssid:  SSID della tu arete wifi
• wifi_passwd: password della tua rete wifi

Conclusioni

Nel post Come aggiungere il controllo wireless ad una valvola termostatica TM3030 - Progetto Walvola - HW abbiamo visto come realizzare la parte Hardware del progetto Walvola. Ho presentato lo schema elettrico ed il PCB del controller della valvola.

Ho anche spiegato come modificare la valvola per sostituire il suo controller originale con quello da me sviluppato.

In questo posto ho messo a disposizione su github il software Walvola da caricare sul modulo precedentemente sviluppato.

Ne ho spiegato l'architettura generale, le funzionalita' base e di comandi attualemente supportati. 

Infine ho descritto tutti i parametri di configurazione in modo che ognuno possa adattare il software al suo ambiente specifico.

Per il monitoring del voltaggio io uso il servizio https://keen.io che chiaramente non e' obbligatorio o puo' essere sostituito con altri servizi simili.

Come broker MQTT io uso https://www.cloudmqtt.com/ che offre un tier gratuito ed e' estremamente affidabile. Ovviamente potete usare un qualsiasi altro broker MQTT.

Se qualcuno trova il software utile si senta libero di utilizzarlo e se vuole contribuire con nuove funzioni sono apertissimo a discuterne.

In ogni caso queste serie di articoli dimostra come con un semplice modulino come ESP8266 si possano realizzare sistemi IoT utili alla vita di tutti i giorni. L'implementazione di tutte le parti richiede una serie di competenze che il lettore puo' gia' possedere o no. In ogni caso ritengo questa serie di post una buona occasione per cimentarsi con una serie di temi che spaziano dalla realizzazione di un PCB, dall'uso di servizi cloud e fino alla realizzazione di un applicazione mobile.

Se volete aiutarmi a migliorare questo progetto e se e' per voi utile lasciate i vostri commenti qui sotto.

Buon divertimento!!!