HOW TO: customize AIRQino IOT Device to work on Snap4City

Air pollution is very difficult to be measured. City administrators normally deploy accurate but very expensive and quite scattered stations to control air quality and related human health. Some important gases and organic volatile compounds that may affect human health are commonly identified and accepted as main air quality indicators. To monitor them, stations use to incorporate sophisticated systems mainly based on ultraviolet fluorescence, quimioluminiscence, ultraviolet photometry and non-dispersive infrared spectrometry among others. As alternatives for building-up low cost monitoring networks, different groups and companies have been working in other technologies and sensor devices. However, because of the many scattered initiatives, information about the usefulness of these low-cost sensors is difficult to be found and a step forward for their evaluation is necessary. In the following table preliminary information on manufacturers and the current state of technology is reported in terms of the gases and parameters that can be targeted with them. To provide adequate information on air quality spatial distribution, the directive also states that those fixed measurements may be supplemented by indicative measurements. Thus, the legislative importance of indicative measurements is to be stressed, as “the results of indicative measurement shall be taken into account for the assessment of air quality with respect to the limit values” (EC, 2008). European Commision (EC), 2008. Directive 2008/50/EC on ambient air quality and cleaner air for Europe, 21/05/2008 Contact: protocollo.ibe@pec.cnr.it

for more information read https://www.snap4city.org/508 AIRQino: Compact low-cost air quality monitoring station, by CNR IBE

Here is reported how it is possible to use AIRQino and our experience. Please contact CNR for more information on the device.

Il passo iniziale è quello di studiare il dispositivo, comprendere i sensori e le misure che possono effettuare, in modo da creare un modello che rappresenti correttamente il dispositivo.

 

 

Tramite la piattaforma Snap4city viene creato un modello. Dopo essersi registrati su Snap4city ed ottenuto il ruolo minimo di “Area Manager”, il quale ha i permessi necessari, è possibile accedere alla lista dei modelli tramite il menu laterale ( IOT Directory and Devices -> IOT Device Models ) e andare a creare un nuovo modello tramite il bottone in alto a destra “New Model”.

Nella finestra che si apre è possibile andare ad inserire tutte le informazioni del modello: le informazioni generali, l’IoT Broker, gli Static Attributes e i Values.

Nella tab sulle informazioni generali si deve inserire oltre a nome e descrizione del modello, il tipo di device che utilizza questo modello, e la tipologia di generazione delle chiavi che serviranno per autenticarsi per controllare il device.

Per quanto riguarda l’IoT broker si deve andare a selezionare uno dei broker presenti sulla piattaforma Snap4city, il tipo di protocollo utilizzato per l’ingestion dei dati e il formato utilizzato per gestirli.

Infine nella tab Values si devono inserire i campi che vogliamo che il modello possieda, per ciascuno di questi oltre al nome dovrà essere specificato il tipo di dato che quel campo rappresenta, il tipo di valore del dato di quel campo e l’unità di misura del valore, e dovranno essere coerenti con i dati che verranno mandati dai device.

Dopo avere creato il modello va creato il o i device che rappresentano i dispositivi fisici (Digital TWIN) all’interno della piattaforma. Per crearli si accede alla lista completa dei devices tramite il menu laterale (IOT Directory and Devices -> IOT Device) e cliccando sul bottone in altro a destra “New Device” si può andare crearli.

Nella creazione del device verrano inserite: le informazioni generali come l’identificativo del device e il tipo di device, sotto la voce model si seleziona il modello che abbiamo creato e che vogliamo utilizzare con il dispositivo che si sta creando, la selezione del modello automaticamente aggiungerà gli attributi statici e i valori che sono stati specificati nel modello selezionato, sarà poi necessario cliccare sul bottone per la generazione delle chiavi in modo da ottenerne due che serviranno insieme al Device Identifier , ad identificare il device su Snap4city ed autenticarsi per poterlo gestire. Infine la selezione del punto geografico di dove sarà posizionato il dispositivo hardware.

 

La comunicazione tra i dispositivi hardware e la piattaforma Snap4city avviene tramite il Broker, il quale si interpone tra il dispositivo e la piattaforma cloud, fornendo a quest’ultima, l’informazione che riceve dal dispositivo in un formato standardizzato. I vantaggi derivanti dall’utilizzo di un Broker sono principalmente:

• Riduzione accoppiamento tra dispositivi e cloud con incremento sicurezza della trasmissione.
• Device shadowing, che fa si che eventuale indisponibilità del dispositivo non generi nessun’eccezione, in quanto è il Broker che comunica con il cloud.
• Gestione dell’intero ciclo vitale delle informazioni (aggiornamenti del contesto, query, registrazioni, sottoscrizioni).

In questo caso per entrambi i dispositivi, come è stato specificato nella creazione dei modelli e dei dispositivi su Snap4city, è stato scelto di utilizzare l’Orion Broker messo a disposizione dalla piattaforma Cloud.

Nello swagger su km4city ( https://www.km4city.org/swagger/external/index.html ) è possibile consultare l’API relative all’Orion Broker, selezionando in alto a destra “Orion Broker k1-k2 Authentication”.

HTTP invece di HTTPS

Dato che su entrambi i dispositivi i moduli GPRS/GSM e 4G non era supportato https, è stato necessario l’utilizzo di un Access Point diverso ( http://iot-app.snap4city.org:80 invece di https://broker1.snap4city.org:8080 ) basato su http in cui il dato è stato protetto tramite l’utilizzo di k1 e k2 invece che con il certificato.

Aggiornamento del contesto

In conclusione l’invio dei dati si riduce ad una chiamata post di aggiornamento del contesto del broker in cui nell’url si passa sia il deviceId che le chiavi k1 e k2 e il payload è un json formattato in maniera standardizzata secondo l’Orion Broker.

L’url sarà quindi della forma

http://iot-app.snap4city.org:80/orion-broker/v1/updateContext?elementid=ELEMENTID&k1=K1&k2=K2

Verranno mostrati poi, nelle sezioni relative ai due dispositivi, degli esempi del Json payoload delle chiamate per l’aggiornamento del contesto.

 

Aspetti generali e hardware

AirQino è una stazione di monitoraggio della qualità dell’aria sviluppata da CNR IBE. Essa è essenzialmente composta da 3 circuiti stampati: AirQino circuit board, GRPS Shield v3.0 e una scheda Arduino.

AirQino è una scheda sviluppata dal CNR compatibile con schede Arduino, integrata con sensori ad alta risoluzione e basso costo, dedicata al monitoraggio dei parametri ambientali e delle particelle inquinanti. Inoltre vi è integrata un’unità microprocessore che si occupa di acquisire i valori dei sensori, elaborarli, ed inviarli su una seriale alla scheda Arduino.

La GPRS Shield v3.0 di Seedstudio è una shield che consente all’Arduino di comunicare tramite la rete cellulare GSM/GPRS, dopo che è stata inserita una scheda SIM nella parte inferiore della scheda come è possibile vedere nella foto sottostante

 

L’ultima è la scheda Arduino è una scheda open-source con microcontrollore ATmega sviluppata da Arduino.cc, è programmabile tramite linguaggio C ed è utilizzata per sviluppare progetti di robotica, elettronica e automazione. Viene utilizzata in questo caso per acquisire tramite seriale i dati forniti dalla scheda AirQino e per inviarli tramite la Shield GPRS alla piattaforma Snap4city.

 

Per poter programmare la scheda Arduino viene utilizzato il cavetto di programmazione in dotazione, esso deve essere opportunamente collegato all’arduino e poi al pc tramite la porta USB. (IMPORTANTE: Collegare il cavetto di programmazione all’arduino in modo che il cavo nero sia collegato al pin GND)

 

 

Programmazione Arduino

Per poter programmare l’Arduino è necessario scaricare e installare dal sito ufficiale di Arduino il loro Ambiente di Sviluppo Integrato ( https://www.arduino.cc/en/Main/software ). Successivamente si collega il dispostivo alla porta USB del PC tramite il cavo di programmazione, e il dispositivo alla corrente per poter fornire sufficiente alimentazione che magari la porta USB da sola non è in grado di fornire.

Settaggi IDE per caricamento sketch: Nell’ambiente di sviluppo installato una volta aperto si deve selezionare la Scheda “Arduino Pro or Pro Mini”, il Processore “ATmega328P (3.3V, 8MHz)” e la porta seriale corretta.

 

Il codice

Il file principale è “AriaBus23_SWH_am_SENSE_pm_Dollars_SPAGNA.ino”, come in ogni sketch arduino troviamo la funzione setup() e la funzione loop().

La funzione setup() viene eseguita una sola volta all’avvio dell’arduino, in essa viene essenzialmente aggiustata la data e l’ora in base all’orario del PC nel momento della compilazione dello sketch, ed avviato il RealTimeClock.

 

 

Quando si va a caricare lo sketch sul dispositivo per avere l’orario sincronizzato con UTC è necessario sottrarre/aggiungere il numero di secondi corretto in base all’orario del PC.

 

La funzione loop() viene eseguita ciclicamente dall’arduino ed essa è composta essenzialmente da due fasi: lettura dei dati dalla scheda con i sensori tramite le funzioni definite nel file “Sensor_reading.ino”, invio dei dati alla piattaforma Snap4city tramite il modem GPRS/GSM, grazie alle funzioni definite nel file “GSM.ino”.

Lettura dei dati

La lettura dei dati inviati dalla scheda AirQino, avviene su una porta seriale tramite la lettura di una stringa che contiene le acquisizioni di CO2, AM2315-°C, AM2315-UR, Bar, PM10, PM2,5, DS18B20-°C, O3, MiCS2714 (NO2), TGS2600 (CO), MiCS5524 (VOC). Dalla stringa intera vengono poi estratti i valori di ciascuna misura.

 

 

Per quanto riguarda i valori di CO2, AM2315-°C, AM2315-UR, Bar, PM10, PM2,5, DS18B20-°C, MiCS5524 (VOC), sono interpretati come segue:

• CO2: I valori sono espressi in ppm di CO₂.
• AM2315-°C: il valore rappresenta l’ultima lettura della temperatura ambientale ed è espresso in °C/10
• AM2315-UR: il valore rappresenta l’ultima lettura dell’umidità relativa dell’ambiente ed è espresso in %RH/10
• Bar: Pressione barometrica. Il valore presentato è l’ultima misura fatta, espressa in mBar. Se il sensore non è presente viene presentato il valore fisso 0000.
• PM10 e PM2,5: sono i valori delle polveri pm10 e pm2,5, entrambi sono espressi in mg/m³ di aria ed hanno campo di misura tra 0 e 990 PM

• DS18B20-°C: Il valore presentato è l’ultima lettura della temperatura interna del dispositivo, ed è espressa in °C/100.

• MiCS5524 (VOC): I valori sono espressi in ppm di VOC.

 

Invece ai valori di O3, MiCS2714 (NO2), TGS2600 (CO), vengono applicate delle formule di conversione (Foglio Smart27 del file Excel), fornite da CNR-IBE nel contesto del progetto EU TRAFAIR (nella cartella di progetto sono presenti i file Excel che riassumono le formule), che al momento non sono precise e calibrate per questi sensori, ma che permettono di avere un dato coerente con l’unità di misura. In particolare:

• Al valore di O3 viene applicata la seguente formula  dove x è il  valore di O3,  ,, , .
• Al valore di MiCS2714 (NO2) viene applicata la seguente formula  dove x è il valore di NO2, , .
• Al valore di TGS2600 (CO) viene applicata la seguente formula  dove x è il valore di CO, ,   

Il valore dell’y è sempre espresso in ppm

Successivamente al ciascun valore y ottenuto tramite le formule, viene applicato un fattore di conversione che ci fornisce il dato finale in mg/m³ (Vedi Foglio Legenda file Excell).

Per ciascun valore finale i limiti min e max che può assumere sono   (anche questi da aggiustare dopo aver ottenuto numeri più precisi).

Invio dati

Dopo che sono stati letti i valori dei sensori, si può passare all’invio di tali dati, effettuando la chiamata POST per l’aggiornamento del contesto nel broker.

La fase di invio dei dati avviene tramite la shield GPRS/GSM equipaggiata di opportuna scheda SIM. La shield GPRS/GSM è dotata di un modulo Sim900 il quale utilizza i Comandi-AT (https://simcom.ee/documents/SIM900/SIM900_AT%20Command%20Manual_V1.11.pdf) per le operazioni di comunicazione che possono essere effettuate (chiamate http, chiamate ftp, invio sms, chiamate vocali, etc..). Mentre per comunicare i Comandi-AT, dalla scheda Arduino che stiamo programmando alla shield GPRS/GSM, viene utilizzato la comunicazione seriale tramite la libreria SoftwareSerial.

Visto che l’invio dei dati dei sensori si riconduce all’esecuzione di una chiamata POST con payload Json opportunamente costruito, sono stati utilizzati una sequenza di Comandi-AT per effettuare tale chiamata.

Nell’invio di questa sequenza di comandi c’è da porre attenzione principalmente a:

• Corretto utilizzo di print() e println() per la comunicazione dei comandi tramite seriale alla shield GPRS. Il new line indica alla shield GPRS il termine di un comando.
• Settare correttamente l’Access Point in base al service provider della scheda sim inserita, ed eventualmente anche l’username e la password.
• Verificare che l’inserimento del pin della sim sia disabilitato, o aggiungere i comandi per l’inserimento del pin della sim per sbloccarla.
• Corretto settaggio dei parametri della chiamata http (content-type e url con server, deviceId, k1 e k2 corretti)
• Al comando AT+HTTPDATA , il quale necessita di due parametri, la lunghezza esatta del payload che viene inviata e il tempo di attesa massimo per l’invio tramite seriale del payload.

 

Di seguito è possibili vedere un esempio di payload per la chiamata di aggiornamento del contesto del broker.

 

 

Infine all’interno della cartella di progetto troviamo i file Dollars.ino e GPS.ino i quali erano già presenti e non utilizzati ai fini del progetto in questione.

In Dollars.ino troviamo il codice che effettua il print di una stringa che inzia e termina con $$$ e la quale contiene il valore delle letture dei sensori che si inviano tramite la shield GPRS. Il print di questa stringa formattata in questa maniera viene utilizzato per permettere ad un altro arduino di operare da sniffer, catturare la stringa e salvare i dati su una sd, creando cosi un unità data logger.

Ai fini di questo progetto è stato interamente commentato per occupare minor memoria sull’arduino.

In GPS.ino invece troviamo il codice per l’acquisizione della posizione GPS con il calcolo del CKS.

 

 

 

La parte finale riguarda la creazione di due Dashboard che mostrasse gli andamenti dei valori dei sensori dei due dispositivi.

Per creare le Dashboard su Snap4city si accede alla piattaforma, si procede nella sezione relativa alle Dashboard, e si clicca sul bottone “New Dashboard”. A questo punto c’è solo da seguire la Three Stage Wizard:

1. Inserimento del titolo della dashboard e scelta di eventuale template.
2. Selezione Data and Widget che si vuole inserire nella Dashboard.
3. Conferma e istanziazione della Dashboard.

Le due Dashboard create possono essere visualizzate dopo aver fatto il login su Snap4city ai sequenti link: https://www.snap4city.org/dashboardSmartCity/view/index.php?iddasboard=Mjk3MA== e https://www.snap4city.org/dashboardSmartCity/view/index.php?iddasboard=Mjk2OQ==