Scarica l`Hackaton 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$Food_Offer_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$ONLUS1
Ericsson$ONLUS2
Ericsson$Food_Request_LOT
Ericsson$Request_Food_ID
Ericsson$Request_Quantity
Ericsson$Delivery_Date_Request
Ericsson$Delivery_Location_Latitude
Ericsson$Delivery_Location_Longitude
Tabella 1 - Nomenclatura dati
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-RequesterId=Ericsson%24e670696b9d8d2767a0c2969766abeee0017c&hub.topicSensorSpec=e901673cee3b-4054-a4b77f7dba0b7a6&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-RequesterId=Ericsson%24e670696b9d8d2767a0c2969766abeee0017c&hub.topicSensorSpec=bc0bee66a25a-4aef-973981f4d3958fd&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-RequesterId=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-4aef973981f4d3958fd"},"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-RequesterId=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-4054a4b77f7dba0b7a6"},"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
2015","value":"Food_ID_1","gatewayId":"Supermarket"}]
16
14:18:00
CEST
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-4b4396fe-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