piGarden: le a.p.i.

In questo articolo vorrei approfondire e fare più chiarezza sulle api (Application Program Interface) che piGarden mette a disposizione e con le quali può interfacciarsi con altri software esterni.

Le api vengono esposte tramite socket server già da tempo e più recentemente invece possono essere utilizzate anche tramite protocollo mqtt.

Tramite l’utilizzo delle api è possibile conoscere lo stato di piGardem, aprire o chiudere le elettrovalvole, creare schedulazioni e molto altro.

Socket Server

Come detto precedentemente, le api vengono esposte al mondo esterno tramite socket server. Questo vuole dire che per poterle utilizzare è necessario instaurare una connessione tcp verso l’host che ospita piGarden sulla porta indicata nel file di configurazione. Questo è anche il sistema che viene utilizzato da piGardenWeb per interfacciarsi con piGarden.

Per maggiori informazioni sulla configurazione del socket server di piGarden vi rimando all’articolo nel quale veniva annunciato, piGarden 2.0 Ester Egg, e più in particolare a quello relativo all’installazione e configurazione di piGarden.

Come dicevo prima, per utilizzare le api, dobbiamo instaurare una connessione tcp con il server socket di piGarden. Instaurata la connessione sarà possibile inviare il comando api più appropriato in base a quello che vogliamo ottenere. L’invio del comando avviene scrivendo una semplice stringa (contenente il comando stesso) seguita dal carattere carriage return e line feed (cr+lf).

Se piGarden è stato configurato in modo che il socket server sia sottoposto ad autenticazione, prima del comando api, sarà necessario inviare le credenziali corrette, indicando prima lo username e poi sulla password.

Una volta ricevuto il comando, piGarden lo eseguirà e successivamente restituirà in output un json contenente lo stato attuale dell’applicazione. Nel caso che il comando o le credenziali di autenticazioni siano errate verrà restituito sempre un json ma questa volta contenente un codice di errore.

Per renderci meglio conto su come funziona, possiamo utilizzare la shell del nostro Raspberry e usare il comando telnet per instaurare una connessione verso il socket server ed inviare un comando a piGarden.

Tenendo conto che il socket server sia in ascolto sulla porta 8084 del Raspberry su cui stiamo operando, possiamo instaurare la connessione localmente con il seguente comando:

telnet 127.0.0.1 8084

se tutto va per il verso giusto, verranno emesso in output le seguenti stringhe che indicheranno che è avvenuta la connessione:

Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.

Arrivati a questo punto possiamo impartire il comando api che vogliamo, preceduto da utente e password se il socket server è soggetto ad autenticazione. Scrivete quanto segue per impartire il comando status. Questo farà si che venga restituito un json contenente lo stato di piGarden.

username_socket_server
password_socket_server
status

o molto più semplicemente come segue se il socket server non ha autenticazione

status

in output verrà emesso un json tipo il seguente:

{"version":{"ver":0,"sub":5,"rel":12},"timestamp": 1546366100,"event": {"event": "", "alias": ""},"zones":{"Giardino_Posteriore_DX":{"name":"Giardino_Posteriore_DX","state":0},"Giardino_Posteriore_CN":{"name":"Giardino_Posteriore_CN","state":0},"Giardino_Posteriore_SX":{"name":"Giardino_Posteriore_SX","state":0}},"last_weather_online":{
  "display_location": {
    "city": "Pieve a Nievole"
  },
  "observation_epoch": "1546363200",
  "local_epoch": "1546363200",
  "local_tz_long": "Europe/Rome",
  "weather": "Clear",
  "temp_c": "6.78",
  "relative_humidity": "80%",
  "wind_dir": "ENE",
  "wind_degrees": "60",
  "wind_kph": "1.5",
  "wind_gust_kph": "--",
  "pressure_mb": "1024",
  "dewpoint_c": "--",
  "feelslike_c": "--",
  "icon_url": "http://icons.wxug.com/i/c/k/nt_clear.gif"
},"error":{"code":0,"description":""},"info":"","warning":"","success":"","last_rain_online":"1545907800","last_rain_sensor":"1546366082","cron":{},"cron_open_in":{}}

Il comando state è utile per capire lo stato di piGarden, ma se invece vogliamo avviare l’irrigazione aprendo un’elettrovalvola ci basterà utilizzare il comando open seguito dall’alias dell’elettrovalvola:

telnet 127.0.0.1 8084
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.
open Giardino_Posteriore_DX
{"version":{"ver":0,"sub":5,"rel":12},"timestamp": 1546381436,"event": {"event": "ev_open_after", "alias": "Giardino_Posteriore_DX"},"zones":{"Giardino_Posteriore_DX":{"name":"Giardino_Posteriore_DX","state":1},"Giardino_Posteriore_CN":{"name":"Giardino_Posteriore_CN","state":0},"Giardino_Posteriore_SX":{"name":"Giardino_Posteriore_SX","state":0}},"last_weather_online":{
  "display_location": {
    "city": "Pieve a Nievole"
  },
  "observation_epoch": "1546379400",
  "local_epoch": "1546379400",
  "local_tz_long": "Europe/Rome",
  "weather": "Scattered Clouds",
  "temp_c": "5",
  "relative_humidity": "80%",
  "wind_dir": "",
  "wind_degrees": "null",
  "wind_kph": "0.5",
  "wind_gust_kph": "--",
  "pressure_mb": "1021",
  "dewpoint_c": "--",
  "feelslike_c": "--",
  "icon_url": "http://icons.wxug.com/i/c/k/nt_cloudy.gif"
},"error":{"code":0,"description":""},"info":"","warning":"","success":"Solenoid open","last_rain_online":"1545907800","last_rain_sensor":"","cron":{},"cron_open_in":{"open_in": {"Giardino_Posteriore_DX": ""},"open_in_stop": {"Giardino_Posteriore_DX": ""}}}
Connection closed by foreign host.

Volendo interagire con le api da shell senza l’utilizzo di telnet potete usare uno script tipo il seguente:

#!/bin/bash
cmd="$1"
remote_ip="$2"
remote_port="$3"
exec 5<>/dev/tcp/$remote_ip/$remote_port
echo -e "$cmd" >&5
cat <&5

Potrete utilizzarlo fornendo come primo argomento una stringa delimitata da doppi apici contenente le eventuali credenziali seguite dal comando api da impartire. Come secondo e terzo parametro invece dovranno essere indicati hostname/ip e porta del socket server.

Per esempio, se avete chiamato lo script sopra indicato con il nome di pigarden_api.sh, potrete eseguire l’apertura della zona nel seguente modo:

./pigarden_api.sh "username\npassword\nopen Giardino_Posteriore_DX" garden 8084

MQTT

Più recentemente è stato introdotto la possibilità di utilizzare le api di piGarden tramite protocollo mqtt. Questo è possibile utilizzando mqttconnector, uno script python che funziona da proxy tra mqtt e il socket server. Per maggiori dettagli sull’installazione e configurazione di mqtt connector potete consultare l’articolo dedicato “mqttconnector, utilizza le api piGarden e piGuardian tramite mqtt“.

Una volta che mqttconnector sarà avviato, potrete comandare piGarden tramite protocollo mqtt, inviando un messaggio verso il topic pigarden/command. Il payload del messaggio dovrà contenere il comando api che volete utilizzare.

Volendo fare una prova, potete utilizzare l’utility di mosquitto_pub presente nel pacchetto mosquitto-clients. 

mosquitto_pub -h host_broker -p porta_broker -u user_broker -P password_broker -t "pigarden/command" -m "open Giardino_Posteriore_DX"

Con il comando sopra indicato verrà inviato il comando di apertura della zona Giardino_Posteriore_DX.

Una volta eseguito il comando piGarden, se opportunatamente configurato, pubblicherà lo stato in formato json inviando un messaggio mqtt sul topic pigarden/result.

Elenco delle api utilizzabili

Di seguito riporto l’elenco delle api di piGarden con la rispettiva descrizione.

Il json contenente lo stato

Analizziamo ora un po’ più in dettaglio il json contenente lo stato di piGarden, che viene restituito dopo ogni chiamata oppure a seguito del comando state:

{
	"version": {
		"ver": 0,
		"sub": 5,
		"rel": 12
	},
	"timestamp": 1546381436,
	"event": {
		"event": "ev_open_after",
		"alias": "Giardino_Posteriore_DX"
	},
	"zones": {
		"Giardino_Posteriore_DX": {
			"name": "Giardino_Posteriore_DX",
			"state": 1
		},
		"Giardino_Posteriore_CN": {
			"name": "Giardino_Posteriore_CN",
			"state": 0
		},
		"Giardino_Posteriore_SX": {
			"name": "Giardino_Posteriore_SX",
			"state": 0
		}
	},
	"last_weather_online": {
		"display_location": {
			"city": "Pieve a Nievole"
		},
		"observation_epoch": "1546379400",
		"local_epoch": "1546379400",
		"local_tz_long": "Europe/Rome",
		"weather": "Scattered Clouds",
		"temp_c": "5",
		"relative_humidity": "80%",
		"wind_dir": "",
		"wind_degrees": "null",
		"wind_kph": "0.5",
		"wind_gust_kph": "--",
		"pressure_mb": "1021",
		"dewpoint_c": "--",
		"feelslike_c": "--",
		"icon_url": "http://icons.wxug.com/i/c/k/nt_cloudy.gif"
	},
	"error": {
		"code": 0,
		"description": ""
	},
	"info": "",
	"warning": "",
	"success": "Solenoid open",
	"last_rain_online": "1545907800",
	"last_rain_sensor": "",
	"cron": {},
	"cron_open_in": {
		"open_in": {
			"Giardino_Posteriore_DX": ""
		},
		"open_in_stop": {
			"Giardino_Posteriore_DX": ""
		}
	}
}

Il primo elemento che troviamo è version che a sua volta contiene altri tre elementi che vanno ad indicare il numero di versione di piGarden.

A seguire troviamo il timestamp in chi è stato emesso lo stato.

L’elemento event con i suoi due sotto-elementi sta ad indicare l’evento che ha scaturito l’emissione dello stato. Oltre a questo viene anche indicato l’alias della zona sulla quale è intervenuto l’evento.

Se segue l’elemento zones, che va contenere tutte le zone definite in piGarden e per ognuna oltre al nome viene indicato anche lo stato. Lo stato può assumere i seguenti valori: 0=chiuso 1=aperto 2=aperto in modo forzato.

Segue poi last_weather_online che va a indicare le ultime condizioni meteo recuperate dal servizio online.

Continuiamo con error che va indicare eventuali errori riscontrati durante la chiamata alle api indicando un codice di errore e una descrizione.

Seguono i tre elementi info, warning e success che possono contenere dei messaggi testuali descrittivi che piGaden emette a seguito della chiamata alle api.

last_rain_online contiene il timestamp dell’ultima pioggia rilevata dal servizio online.

last_rain_sensor contiene l’ultima pioggia rilevata dal sensore hardware.

cron e cron_open_in vanno a contenere le schedulazioni delle apertura, chiusura e avvio ritardato delle zone.

Conclusioni

Questo articolo si conclude qui e spero possa essere di aiuto per chiunque voglia cercare di interfacciare piGarden con altri software esterni.

Un saluto a tutti e buoni divertimento.