Hackathon Developers User Guide

Hackathon Developers User Guide Indice 1. Descrizione del Framework IoT...2 1.1 Informazioni fornite dalla filiera Alimentare...3 1.2 Interfaccia Applicativa...6 1.2.1 Richiesta di Sottoscrizione dati...7 1.2.2 Esempio di Cancellazione della sottoscrizione... 11 1

1. Descrizione del Framework IoT La fase finale dell Hackathon prevede una fase di implementazione sperimentale che contribuirà alla valutazione complessiva dell idea. Per recuperare sperimentalmente le informazioni provenienti dalle sorgenti di informazioni dislocate sul territorio, i partecipanti dovranno interfacciarsi con una piattaforma denominata IoT Service Enablement Framework, fornita da Ericsson. Questo framework industriale consente di recuperare in maniera sicura, controllata e centralizzata, le informazioni provenienti dalla sensoristica e dai dispositivi remoti. Le informazioni vengono storicizzate in un database centralizzato e sono rese disponibili mediante interfacce di semplice invocazione (REST). La struttura del Service Enablement Framework è visibile nella figura seguente, che ne illustra le principali funzionalità. Figura 1 - Descrizione architetturale Applicazioni: Sono le applicazioni IoT alla base dell evento Hackathon. L applicazione può essere sviluppata in qualsiasi linguaggio e su qualsiasi piattaforma. L applicazione esegue la logica di business necessaria all esecuzione del caso di uso ed interagisce con la piattaforma di Service Enablement per recuperare le informazioni provenienti dai devices IoT o dalle basi dati. 2

Accesso da Public Internet: le Applicazioni possono entrare in contatto con la piattaforma di Service Enablement sul canale Public Internet. La piattaforma è raggiungibile mediante una specifica URL ed utilizza un protocollo di comunicazione REST. Maggiori dettagli nel capitolo 1.2 Interfaccia Applicativa. Service Enablement Plaform: E la piattaforma che recupera le informazioni dai dispositivi interconnessi e le mette a disposizione delle Applicazioni in maniera sicura e strutturata, disaccoppiando l ambito applicativo da quello dei dispositivi. La piattaforma consente anche l invio di comandi ai dispositivi interconnessi (funzionalità non utilizzata nell Hackathon). Servizi di Connettività: Consentono ai dispositivi interconnessi di collegarsi con la piattaforma di Service Enablement e fornire dati e/o ricevere comandi. I dispositivi sono normalmente interconnessi mediante Mobile Broadband (GPRS,3G,LTE) per consentire la raggiungibilità sul territorio in mobilità. In caso di dispositivi stazionari, la connettività utilizzabile può essere di tipo ethernet o wifi. Questo livello è al di fuori dello scopo dell Hackathon e non è accessibile ai partecipanti. Sensoristica,Dati ed Attuatori: Sono i dispositivi che forniscono le informazioni alla piattaforma di Service Enablement. Le informazioni possono provenire da sensori, possono essere inserite manualmente o recuperate da una base dati esistente sul territorio. Nel caso dell Hackathon queste informazioni vengono fornite dinamicamente. I sistemi che generano i dati sono al di fuori dello scopo applicativo dell Hackathon. 1.1 Informazioni fornite dalla filiera Alimentare Ai fini della sperimentazione pratica, i partecipanti dovranno interagire esclusivamente, tra gli ambiti descritti, esclusivamente con quello Applicativo. I Dispositivi sono già interconnessi e forniscono informazioni relative alla filiera della distribuzione alimentare. Verranno fornite informazioni dinamiche relative all offerta, e alla domanda di generi alimentari ridondanti, mentre le informazioni di dettaglio sui generi alimentari e il relativo packaging saranno recuperabili da una sorgente statica. Lo scopo principale dell applicazione o del sistema proposto nell Hackathon dai partecipanti è di utilizzare i flussi dinamici di informazioni e le sorgenti statiche di dettaglio al fine di ottimizzare la filiera e ridurre gli sprechi alimentari. Per poter comprendere la struttura delle informazioni recuperabili a livello applicativo, è necessario comprendere in che modo tali informazioni vengono fornite dai dispositivi e memorizzate in piattaforma. 3

La piattaforma di Service Enablement ha una struttura dati gerarchica che rispecchia la configurazione dei dispositivi interconnessi come di seguito descritto: Figura 2 - Gerarchia della struttura dati Il Livello gerarchico massimo è rappresentato dal Device Gateway Group. Un Device Gateway Group conterrà al suo interno una serie di Device Gateways. Il Device Gateway è demandato al recupero delle informazioni dalla sensoristica e a comandare eventuali attuatori interconnessi. Focalizzandoci sulla sensoristica, un Device Gateway può gestire uno o più Sensori (Sensor). Il Sensore rappresenta il dispositivo che trasduce le grandezze fisiche in dati comprensibili al Device Gateway (esempio: Temperatura in Gradi Centigradi, Umidità in % di acqua per unità di volume d aria). Un Sensore può fornire varie grandezze fisiche. Ogni grandezza fisica recuperabile è definita Risorsa (Resource). Un esempio può essere quello di un modulo GPS (Sensor) che fornisce 3 grandezze fisiche (3 Resources): Latitudine, Longitudine, Altitudine. Figura 3 - Esempio di applicazione pratica Le informazioni relative alla filiera di distribuzione alimentari sono state organizzate secondo la medesima struttura gerarchica. Il flusso logico delle informazioni e la mappatura con il data model appena descritto è visibile in figura: 4

Figura 4 - Logica di funzionamento della Piattaforma IoT Di seguito vengono riportate in forma tabellare le informazioni presenti nei tre ambiti: Offerta, Richiesta, Dati statici. Per Gateway vengono riportati di seguito i valori delle variabili utilizzate nelle API che dovranno essere utilizzate dalle applicazioni. 5

Device Gateway ID sensorspec resourcespec Ericsson$Supermarket Ericsson$Canteen Ericsson$ONLUS1 Ericsson$ONLUS2 Tabella 1 - Nomenclatura dati Ericsson$Food_Offer_LOT Ericsson$Food_Request_LOT Ericsson$Offer_Food_ID Ericsson$Offer_Package_ID Ericsson$Offer_Quantity Ericsson$Available_from Ericsson$Available_to Ericsson$Expiry_Date Ericsson$LOCATION_Latitude Ericsson$LOCATION_Longitude Ericsson$Food_Description Ericsson$Calories Ericsson$Origin Ericsson$Seasonality Ericsson$Perishable Ericsson$Allergen Ericsson$Length Ericsson$Height Ericsson$Depth Ericsson$Weight Ericsson$Item_per_Package Ericsson$Request_Food_ID Ericsson$Request_Quantity Ericsson$Delivery_Date_Request Ericsson$Delivery_Location_Latitude Ericsson$Delivery_Location_Longitude 1.2 Interfaccia Applicativa L interfaccia esposta a livello applicativo prevede una fase di Autorizzazione ed una fase di sottoscrizione dati o richiesta dati. La fase di Autorizzazione viene effettuata mediante lo scambio di token secondo il protocollo OAUTH 2.0. Nell ottica di velocizzare l integrazione con le Applicazioni sviluppate per l Hackathon, l implementazione di questa logica non sarà necessaria, e verrà fornito direttamente un Token da utilizzare nelle API il primo giorno dell Hackathon. La URL pubblica da utilizzare per la fase di sottoscrizione dati o richiesta dati è la seguente: https://m2m-north.hsc.ericsson.net/rest/m2mdata/ 6

1.2.1 Richiesta di Sottoscrizione dati Questo tipo di richiesta va utilizzata per sottoscriversi ai topics e richiedere informazioni relative ai Gateways che forniscono dati dinamici di Offerta e Richiesta Alimentare. La procedura di sottoscrizione rispetta il segente scambio di dati tra Applicazione e IoT Platform: Figura 5 - Sottoscrizione Dopodichè, non appena l informazione viene pubblicata da uno dei devices che fornisce il tipo di informazione sottoscritta, la piattaforma SEP IoT la notifica all Applicativo: 7

Figura 6 - Notifica (Push Data) Vengono di seguito riportati degli esempi reali di chiamate e risposte secondo la sequenza logica appena descritta. CREAZIONE SOTTOSCRIZIONE: POST https://m2mnorth.hsc.ericsson.net/rest/m2mdata/subscription?protocol=http&hub.mode=subscribe&hub.call back=http%3a%2f%2f10.1.10.5:38080/notifications&daurn=ericsson%24dispatchersb&hub.topi csensorspec=ericsson%24food_offer_lot%2cericsson%24food_request_lot &responseformat=application%2fjson Authorization: Bearer UW02S0a5N7PGvPGbPEsv AccessKey: 8b1594f517a5d73f6749f503bd9779772554 Note: 1. Nella richiesta, il parametro hub.callback va popolato con il proprio IP address e porta in ascolto. 2. In questa richiesta, ci sono due argomenti sottoscritti: Ericsson$Food_Offer_LOT che appartiene al GW di offerta di Alimenti. Ericsson$Food_Request_LOT che appartiene GW di richiesta di Alimenti. In tal modo, con una singola richiesta di sottoscrizione è possibile sotoscriversi sia alle richieste che alle offerte, ottenendo tutti i dati necessari. 8

DI conseguenza, il Sistema IoT fornirà due differenti Challenge a cui si dovrà rispondere. 3. Il token OAUTH (nell esempio UW02S0a5N7PgvPGbPEsv ) e la Access Key (nell esempio 8b1594f517a5d73f6749f503bd9779772554 ) verranno forniti ad ogni team prima dell inizio dell Hackathon. CHALLENGE1 : GET /notifications?x-requester- Id=Ericsson%24e670696b9d8d2767a0c2969766abeee0017c&hub.topicSensorSpec=e901673c- ee3b-4054-a4b7-7f7dba0b7a6&hub.mode=subscribe&hub.topicgatewayspec=*&userid=*&ecid=*&hub.topicresou rcespec=*&daurn=%23dispatchersb9f3c&hub.lease_seconds=0&hub.challenge=51757551930 HTTP/1.1 Accept: text/plain Content-Type: application/x-www-form-urlencoded Host: 10.1.10.5:38080 CHALLENGE2: GET /notifications?x-requester- Id=Ericsson%24e670696b9d8d2767a0c2969766abeee0017c&hub.topicSensorSpec=bc0bee66- a25a-4aef-9739-81f4d3958fd&hub.mode=subscribe&hub.topicgatewayspec=*&userid=*&ecid=*&hub.topicresou rcespec=*&daurn=%23dispatchersb9f3c&hub.lease_seconds=0&hub.challenge=90576489603 HTTP/1.1 Accept: text/plain Content-Type: application/x-www-form-urlencoded Host: 10.1.10.5:38080 Note Importanti: 1. La piattaforma IoT invierà le challenges verso la callback URL indicata nella richiesta. 2. Il valore del parametro hub.challenge va memorizzato dall Applicazione e riutilizzato nell acknowledge verso la piattaforma IoT nel body della richiesta, come descritto nelle Challenge Acknowledge seguenti: 9

CHALLENGE ACK1: HTTP/1.1 200 OK Content-Type: text/plain;charset=utf-8 51757551930 CHALLENGE ACK2: HTTP/1.1 200 OK Content-Type: text/plain;charset=utf-8 90576489603 ACKNOWLEDGE SOTTOSCRIZIONE: HTTP/1.1 200 OK Content-Type: application/vnd.ericsson.m2m.subscription+json;version=1.2;charset=utf-8 [{"addressinginfo":{"protocol":"http","address":"http://10.1.10.4:27030/rest/m2m_data_exposur e_callback?endpoint=http%3a%2f%2f10.1.10.5%3a38080%2fnotifications&capabilityaccess=8b 1594f517a5d73f6749f503bd9779772554&X-Requester- Id=Ericsson%24e670696b9d8d2767a0c2969766abeee0017c","defaultAddressing":true,"m2mSupp ortedformats":{"idformat":"vnd.cybercom.m2m.output+json_1.0","externurn":"m2msupportedf ormaturntojson"},"validfrom":1442402712360,"datemodified":1442402712897,"externurn":"5a 93c152-5725-4634-b75aaa947c26cc1d"},"operator":{"externURN":"*"},"domainApplication":{"externURN":"#DispatcherSB 9f3c"},"customer":{"externURN":"*"},"user":{"externURN":"*"},"deviceGroupSpec":{"externURN":" *"},"devicegatewayspec":{"externurn":"*"},"sensorspec":{"externurn":"bc0bee66-a25a-4aef- 9739-81f4d3958fd"},"resourceSpec":{"externURN":"*"},"deviceGroup":{"externURN":"*"},"deviceGatew ay":{"externurn":"*"},"sensor":{"externurn":"*"},"resource":{"externurn":"*"},"createdbyaccou nt":{},"modifiedbyaccount":{},"validfrom":1442458952414,"datemodified":1442458952414,"exte rnurn":"a9dee612-4312-4f82-a3d2-53bd72"}, {"addressinginfo":{"protocol":"http","address":"http://10.1.10.4:27030/rest/m2m_data_exposur e_callback?endpoint=http%3a%2f%2f10.1.10.5%3a38080%2fnotifications&capabilityaccess=8b 1594f517a5d73f6749f503bd9779772554&X-Requester- Id=Ericsson%24e670696b9d8d2767a0c2969766abeee0017c","defaultAddressing":true,"m2mSupp ortedformats":{"idformat":"vnd.cybercom.m2m.output+json_1.0","externurn":"m2msupportedf ormaturntojson"},"validfrom":1442402712360,"datemodified":1442402712897,"externurn":"5a 93c152-5725-4634-b75aaa947c26cc1d"},"operator":{"externURN":"*"},"domainApplication":{"externURN":"#DispatcherSB 9f3c"},"customer":{"externURN":"*"},"user":{"externURN":"*"},"deviceGroupSpec":{"externURN":" *"},"devicegatewayspec":{"externurn":"*"},"sensorspec":{"externurn":"e901673c-ee3b-4054- a4b7-7f7dba0b7a6"},"resourcespec":{"externurn":"*"},"devicegroup":{"externurn":"*"},"devicegatew ay":{"externurn":"*"},"sensor":{"externurn":"*"},"resource":{"externurn":"*"},"createdbyaccou nt":{},"modifiedbyaccount":{},"validfrom":1442458952293,"datemodified":1442458952293,"exte rnurn":"940c9a61-bbea-4b43-96fe-478d8d"}] 10

Note Importanti: il parametro externurn dovrà essere memorizzato dall Applicazione per permettere poi la cancellazione eventuale della sottoscrizione, come descritto nel Paragrafo 1.2.2 PUSH DATA La piattaforma invierà spontaneamente i dati all applicazione sottoscritta non appena le informazioni di interesse saranno fornite dai devices IoT, nel seguente formato (esempio): POST /notifications HTTP/1.1 Accept-Charset: UTF-8 Content-Type: application/json Accept: text/xml Content-Length: 125 Host: 10.1.10.5:38080 Connection: Keep-Alive User-Agent: Apache-HttpClient/4.3.3 (java 1.5) Accept-Encoding: gzip,deflate [{"resourcespec":"offer_food_id","timestamp":"wed Sep 16 14:18:00 CEST 2015","value":"Food_ID_1","gatewayId":"Supermarket"}] PUSH DATA ACKNOWLEDGE L Applicazione dovrà rispondere al Push con un semplice HTTP 200 OK. 1.2.2 Esempio di Cancellazione della sottoscrizione Come descritto in precedenza, la richiesta va corredata della URN fornita dalla piataforma all atto della sottoscrizione (in rosso). DELETE https://m2m-north.hsc.ericsson.net/rest/m2mdata/subscription/940c9a61-bbea-4b43-96fe-478d8d Authorization: Bearer wojlslfawse4c3eatljj AccessKey: c43a488af3f474f741cc48a46567aac5c6ac RISPOSTA: -- response -- 200 OK 11

Date: Fri, 26 Jun 2015 08:03:57 GMT Server: Jetty(7.6.8.v20121106) Content-Type: text/plain; charset=utf-8 X-Powered-By: Servlet/2.5 JSP/2.1 Content-Length: 0 Keep-Alive: timeout=5, max=100 Connection: Keep-Alive 12