piGarden: gestione driver

Dalla versione 0.5.0 piGarden ha ricevuto un importante aggiornamento che permette di controllare le elettrovalvole e sensori tramite schede di terze parti oltre che, come è stato fino ad ora, dai semplici gpio integrati nel Rapberry.

E’ stato infatti aggiunto il supporto per il controllo di apparati esterni gestibili tramite driver opportunamente scritti.

Potremo quindi collegare una o più boards come la spb16ch per controllare le nostre elettrovalvole andando oltre il limite fisico dei gpio presente sul nostro raspberry.

I driver sono posizionato nella cartella drv di piGarden ( /home/pi/piGarden/drv/ ). Al suo interno sono presenti altre sottocartelle, ognuna di queste conterrà un driver specifico e il nome del driver corrisponderà al nome della sotto cartella. Ogni driver presenta un file README.md dove vengono riportate le dipendenze, pacchetti aggiuntivi o quant’altro necessario per il corretto funzionamento. Allo stato attuale sono presenti soltanto due driver che sono i seguenti:

Nome driver	Descrizione
sample	Fake driver utilizzato per eseguire il testing del codice di piGarden e da usare come modello per la realizzazione di altri driver.
spb16ch	Driver utilizzato per pilotare le schede spb16ch. Permette di gestire fino a 8 spb16ch collegati contemporaneamente, per un massimo di 128 relé (zone) configurabili. Per i dettagli guarda qui.
remote	Driver utilizzato per controllare da un'installazione master, le elettrovalvole configurate su una o più installazioni slave. Per dettagli guarda qui.
sonoff_tasmota_http	Driver utilizzato per pilotare i moduli Sonoff con firmware Tasmota tramite protocollo. Per i dettagli guarda qui.
openweathermap	Driver utilizzato per controllare le condizioni meteo grazie alle api di OpenWeatherMap
wunderground	Driver utilizzato per controllare le condizioni meteo grazie alle api di Wunderground

Utilizzo dei driver

Per configurare piGarden con l’utilizzo di uno o più driver basterà indicare, all’interno del file di configurazione ( /etc/piGarden.conf ), l’apposito riferimento nelle variabili presenti al posto del numero di gpio attualmente presente, rispettando il seguente modello:

NOME_VARIABILE=”drv:nome_driver[:prm1[:prm2[…]]]”

La stringa drv iniziale indica l’utilizzo di un driver, successivamente viene riportato il nome del driver utilizzato (corrispondente al nome della relativa cartella presente in /home/pi/piGarden/drv/ ). A seguire possono essere indicati uno o più id che serviranno al driver per identificare le parti (es: relè) da attivare. Ogni parte deve essere separata dal carattere dei due punti (:). Per esempio:

EV5_GPIO=”drv:spb16ch:2”

L’esempio sopra indicato configura l’elettrovalvola numero 5 per utilizzare il relè numero 2 gestito dalla board gestita dal driver spb16ch.

Di seguito riporto le variabili contenute nel file di configurazione che supportano l’utilizzo dei driver:

Nome variabile	Descrizione
EVx_GPIO	Variabili utilizzate per la configurazione delle varie elettrovalvole. Es: EV1_GPIO, EV2_GPIO, EV3_GPIO, ....
SUPPLY_GPIO_1 SUPPLY_GPIO_2	Configurazione dei due relè utilizzati per gestire l'inversione di polarità che comanda l'apertura/chiusura delle elettrovalvole di tipo bi-stabili.
RAIN_GPIO	Configurazione pgio collegato al sensore di rilevamento pioggia. E' possibile inserire qui dentro il relativo riferimento ad un gestore alternativo da utilizzare per il rilevamento pioggia.

Oltre al controllo delle elettrovalvole, sono stati implementati alcuni driver anche per il controllo delle condizioni meteo grazie alle api che alcuni servizi online mettono a disposizione (openweathermap e wunderground). Per l’utilizzo di questa tipologia di driver basterà indicare quello scelto indicandone il nome nella variabile WEATHER_SERVICE.

Linee guida per la realizzazione di un driver

Per chi volesse cimentarsi nella realizzazione di un driver per gestire una particolare scheda, servizio o sensore di rilevamento pioggia può seguire le linee guida che riporto qui di seguito.

Ogni driver deve essere contenuto in una propria cartella. Il nome del driver verrà identificato dal nome della cartella stessa. A sua volta la cartella del driver dovrà essere una sottocartella di drv in piGarden. Per esempio la cartella /home/pi/piGarden/drv/remoterele/ conterrà un ipotetico driver nominato remoterele.

Ogni driver sarà formato da uno o più file che obbligatoriamente dovranno avere dei nomi ben precisi. In ogni file dovranno essere contenute delle funzioni bash anche queste con nomi ben precisi. Non tutti i file sono obbligatori, per esempio se il driver gestirà un sensore di rilevamento pioggia dovrà contenere il file rainsensor.include.sh ma non necessariamente dovrà essere presente il file rele.include.sh. L’unico file che deve essere obbligatoriamente definito è init.include.sh.

Di seguito la tabella con i file bash che compongono un driver:

Nome file	Obbligatorio	Descrizione
README.md	No	File contenete la descrizione del dirver con le relative dipendenze, pacchetti aggiuntivi e configurazioni necessarie per fare funzionare correttamente il driver.
config.include.sh	No	File contenente eventuali configurazioni o impostazioni del driver. In genere qui vengono inserite le definizioni delle variabili che devono essere visibili da tutte le funzioni del driver.
common.include.sh	No	Include le funzioni globali utilizzate dal driver
init.include.sh	Si	Deve includere la funzione drv_{nomedriver}_ini che verrà invocata nella fase di inizializzazione di piGarden (quando viene eseguito ./piGarden init). Serve per eseguire l'eventuale inizializzazione del hardware con cui si interfaccia il driver.
setup.include.sh	No	Se presente questo file, verrà eseguita la funzione drv_{nomedrver}_setup ad ogni esecuzione dello script.
rele.include.sh	No	Contiene le funzioni adibite al controllo dei relè: inizializzazione, apertura e chiusura.
supply.include.sh	No	Deve contenere le funzioni di gestione dell'alimentazione delle elettrovalvole di tipo bi-stabile: inizializzazione, polarità positiva e polarità negativa.
rainsensor.include.sh	No	Contiene le funzioni per la gestione del sensore di rilevamento pioggia: inizializzazione, lettura dello stato.
rainonline.include.sh	No	Contiene le funzioni che gestiscono l'utilizzo delle api di un servizio online per il controllo delle condizioni meteo.

 

Ogni file dovrà contenere delle funzioni con un nome bene preciso che rispetterà il seguente formato:

drv_{nomedriver}_{nomefunzione}

Per esempio:

drv_spb16ch_init

in questo caso è stata definita la funzione di inizializzazione del driver spb16ch.

Di seguito elenco le funzioni che devono essere definite per ogni singolo file.

Funzioni che devono essere contenute nel file init.include.sh

Nome funzione	Descrizione
drv_{nomedriver}_init	Questa funzione viene invocata dalla funzione "init" di piGarden. In genere dovrebbe contenere il codice per inizializzare l'hardware che il driver gestisce.

 

Funzioni che devono essere contenute nel file setup.include.sh

Nome funzione	Descrizione
drv_{nomedriver}_setup	Questa funzione viene invocata ogni volta che piGarden viene eseguito. Se il driver ha bisogno di assumere particolari impostazioni ad ogni esecuzione di piGarden, questo è il posto giusto dove inserire il relativo codice.

 

Funzioni che devono essere contenute nel file rele.include.sh

Nome funzione	Descrizione
drv_{nomedriver}_rele_init	Questa funzione viene invocata dalla funzione init di piGarden e serve per inizializzare un un relè. Viene passato come primo parametro la stringa identificativa del relè da inizializzare, definita nelle variabili presenti nel file di configurazione (ES: EV1_GPIO).
drv_{nomedriver}_rele_open	Esegue l'apertura di un relè. Viene passato come primo parametro la stringa identificativa del relè da aprire, definita nelle variabili presenti nel file di configurazione (ES: EV1_GPIO).
drv_{nomedriver}_rele_close	Esegue la chiusura di un relè. Viene passato come primo parametro la stringa identificativa del relè da chiudere, definita nelle variabili presenti nel file di configurazione (ES: EV1_GPIO).

 

Funzioni che devono essere contenute nel file supply.include.sh

Nome funzione	Descrizione
drv_{nomedriver}_bistable_init	Questa funzione viene invocata in fase di inizializzazione dei relè che gestiscono l'inversione di polarità per l'alimentazione delle elettrovalvole di tipo bi-stabile. Viene passato come primo parametro la stringa identificativa del relè da inizializzare, definita nelle variabili SUPPLY_GPIO_1 e SUPPLY_GPIO_2 presenti nel file di configurazione.
drv_{nomedriver}_supply_positive	Imposta con tensione positiva l'alimentazione delle elettrovalvole. Viene passato come primo parametro la stringa identificativa del relè da aprire, definita nel file di configurazione (ES: EV1_GPIO).
drv_{nomedriver}_supply_negative	Imposta con tensione negativa l'alimentazione delle elettrovalvole. Viene passato come primo parametro la stringa identificativa del relè da aprire, definita nel file di configurazione (ES: EV1_GPIO).

 

Funzioni che devono essere contenute nel file rainsensor.include.sh

Nome funzione	Descrizione
drv_{nomedriver}_rain_sensor_init	Questa funzione viene invocata in fase di inizializzazione del sensore di rilevamento pioggia. Viene passato come primo parametro la stringa identificativa del gpio che gestisce il sensore, definita nelle variabili RAIN_GPIO presente nel file di configurazione.
drv_{nomedriver}_rain_sensor_get	Viene letto il valore dal sensore e deve essere restituito dalla funzione emettendolo in output. Viene passato come primo parametro la stringa identificativa del gpio che gestisce il sensore, definita nelle variabili RAIN_GPIO presente nel file di configurazione.

Funzioni che devono essere contenute nel file rainonline.include.sh

Nome funzione	Descrizione
drv_{nomedriver}_rain_online_get	Legge le condizioni meteo online crea il json con il dettaglio delle condizioni meteo che successivamente potrà essere letto da piGardenWeb. Ritorna in output il timestamp positivo in caso stia piovendo, altrimenti verrà restituito il timestamp negativo. In caso di errore verrà restituito il valore zero.

In fase di test del driver è possibile fare in modo che tutto l’output eseguito nelle funzioni vada redirezionato in un file di log. Questo può essere utile per eseguire il debugging del driver. Per fare questo basterà definire nel file di configurazione la variabile LOG_OUTPUT_DRV_FILE che dovrà contenere il percorso del file di log da utilizzare.

Spero di essere stato chiaro in queste linee guida. Per qualsiasi dubbio o chiarimento non esitate a scrivere nei commenti.

Mi raccomando, se qualcuno vorrà provare a realizzare un driver, non mancate di condividerlo in modo da poterlo inglobare direttamente in piGarden per renderlo disponibile a tutti.