Contextaware application development with FIWARE Orion Context Broker

Context-aware application development with FIWARE Orion Context Broker REST API February 3 rd, 2015 – Campus Party Brazil Contact twitter @fermingalan Contact email fermin. galanmarquez@telefonica. com

Introduction Orion Context Broker • • • Context Management in FIWARE Orion Context Broker Creating and pulling data Pushing data and notifications Convenience operations 2

Context Management in FIWARE Context Information The value of the attributes that characterize entities relevant to applications My Application API Person • Name-Surname • Birthday • Preferences • Location • To. Do list Bus • Location • No. passengers • Driver • Licence plate 3 Shop • Location • Business name • Franchise • offerings

Context Management in FIWARE Context information may come from many sources using different interfaces and protocols … but programmers should just care about entities and their attributes … It’s too hot! A sensor in a pedestrian street A person from his smartphone Context Information What’s the current temperature? 4 The Public Bus Transport Management system

Context Management in FIWARE Get notified when an update on context information takes place Notify me when bus “X” arrives at the bus stop “A” API Bus = “X”, last_stop = “A”, arrived= “Yes” push 5

Context Management in FIWARE Acting on devices can be as easy as changing the value of attributes linked to its corresponding entity Street Lamp lamp 1. status “on” API Street lamp = “lamp 1”, status= “on” 6

Orion Context Broker • Main functions: – Context availability management – Context management • HTTP and REST-based – XML payload support – JSON payload support • Context in NGSI is based in an entity-attribute model: Entity Attributes “has” • Entity. Id • Entity. Type 1 n 7 • Name • Type • Value

Orion Context Broker in a nutshell Orion Context Broker Context Consumers subscriptions Context Producers query 1026 update notify update 1026 notify update DB 8

Orion Context Broker – check health GET <cb_host>: 1026/version { } "orion" : { "version" : "0. 17. 0", "uptime" : "7 d, 21 h, 33 m, 39 s", "git_hash" : "238 c 3642 ad 67899 da 7 c 1 ff 08 aba 4 b 5 c 846 b 4901 a", "compile_time" : "Mon Dec 1 11: 27: 18 CET 2014", "compiled_by" : "fermin", "compiled_in" : "centollo" } 9

Orion Context Broker - Operations Functions NGSI 9 NGSI 10 • • • Operations Register, Search and Subscribe for context sources • • • register. Context discover. Context. Availability subscribe. Context. Availability update. Context. Availability. Subscription unsubscribe. Context. Availability Query, Update and Subscribe to context elements • • • update. Context query. Context subscribe. Context update. Context. Subscription unsubscribe. Context. Subscription 10

Context Broker operations: create & pull data • Context Producers publish data/context elements by invoking the update. Context operation on a Context Broker. • Context Consumers can retrieve data/context elements by invoking the query. Context operation on a Context Broker update. Context Producer query. Context Broker 11 Context Consumer

Quick Usage Example: Car Create POST localhost: 1026/v 1/update. Context. . . { } "context. Elements": [ { "type": "Car", "is. Pattern": "false", "id": "Car 1", "attributes": [ { "name": "speed", "type": "float", "value": “ 98" } ], "update. Action": “APPEND" 200 OK. . . { "context. Responses": [ { "context. Element": { "attributes": [ { "name": "speed", "type": "float", "value": "" } ], "id": "Car 1", "is. Pattern": "false", "type": "Car" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } } ] } 12

Quick Usage Example: Car Update. Context (1) POST localhost: 1026/v 1/update. Context. . . { } "context. Elements": [ { "type": "Car", "is. Pattern": "false", "id": "Car 1", "attributes": [ { "name": "speed", "type": "float", "value": "110" } ], "update. Action": "UPDATE" 200 OK. . . { "context. Responses": [ { "context. Element": { "attributes": [ { "name": "speed", "type": "float", "value": "" } ], "id": "Car 1", "is. Pattern": "false", "type": "Car" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } } ] } 13

Quick Usage Example: Car Query. Context (1) POST <cb_host>: 1026/v 1/query. Context. . . { "entities": [ { "type": "Car", "is. Pattern": "false", "id": "Car 1" } ] } 200 OK. . . { "context. Responses": [ { "context. Element": { "attributes": [ { "name": "speed", "type": "float", "value": "110" } ], "id": "Car 1", "is. Pattern": "false", "type": "Car" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } } ] } 14

Quick Usage Example: Car Update. Context (2) POST localhost: 1026/v 1/update. Context. . . { "context. Elements": [ { "type": "Car", "is. Pattern": "false", "id": "Car 1", "attributes": [ { "name": "speed", "type": "float", "value": "115" } ], "update. Action": "UPDATE" } 200 OK. . . { "context. Responses": [ { "context. Element": { "attributes": [ { "name": "speed", "type": "float", "value": "" } ], "id": "Car 1", "is. Pattern": "false", "type": "Car" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } } ] } 15

Quick Usage Example: Car Query. Context (2) POST <cb_host>: 1026/v 1/query. Context. . . { "entities": [ { "type": "Car", "is. Pattern": "false", "id": "Car 1" } ] } 200 OK. . . { "context. Responses": [ { "context. Element": { "attributes": [ { "name": "speed", "type": "float", "value": "115" } ], "id": "Car 1", "is. Pattern": "false", "type": "Car" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } } ] } 16

Quick Usage Example: Room Create (1) POST localhost: 1026/v 1/update. Context. . . { "context. Elements": [ { "type": "Room", "is. Pattern": "false", "id": "Room 1", "attributes": [ { "name": "temperature", "type": "float", "value": "24" }, { "name": "pressure", "type": "integer", "value": "718" } } } 200 OK. . . { ] ], "update. Action": "APPEND" } "context. Responses": [ { "context. Element": { "attributes": [ { "name": "temperature", "type": "float", "value": "" }, { "name": "pressure", "type": "integer", "value": "" } ], "id": "Room 1", "is. Pattern": "false", "type": "Room" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } } ] 17

Quick Usage Example: Room Update. Context (2) POST localhost: 1026/v 1/update. Context. . . { "context. Elements": [ { "type": "Room", "is. Pattern": "false", "id": "Room 1", "attributes": [ { "name": "temperature", "type": "float", "value": "25" }, { "name": "pressure", "type": "integer", "value": "720" } } } 200 OK. . . { ] ], "update. Action": "UPDATE" } "context. Responses": [ { "context. Element": { "attributes": [ { "name": "temperature", "type": "float", "value": "" }, { "name": "pressure", "type": "integer", "value": "" } ], "id": "Room 1", "is. Pattern": "false", "type": "Room" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } } ] 18

Quick Usage Example: Room Query. Context (1) POST <cb_host>: 1026/v 1/query. Context. . . { "entities": [ { "type": "Room", "is. Pattern": "false", "id": "Room 1" }, "attributes": [ "temperature" ] ] } 200 OK. . . { "context. Responses": [ { "context. Element": { "attributes": [ { "name": "temperature", "type": "float", "value": "25" } ], "id": "Room 1", "is. Pattern": "false", "type": "Room" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } } ] } 19

Quick Usage Example: Room Query. Context (2) 200 OK. . . { POST <cb_host>: 1026/v 1/query. Context. . . { "entities": [ { "type": "Room", "is. Pattern": "false", "id": "Room 1" } ] } } "context. Responses": [ { "context. Element": { "attributes": [ { "name": "temperature", "type": "float", "value": "25" }, { "name": "pressure", "type": "integer", "value": "720" } ], "id": "Room 1", "is. Pattern": "false", "type": "Room" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } } ] 20

Quick Usage Example: Room Create (2) POST localhost: 1026/v 1/update. Context. . . { "context. Elements": [ { "type": "Room", "is. Pattern": "false", "id": "Room 2", "attributes": [ { "name": "temperature", "type": "float", "value": "33" }, { "name": "pressure", "type": "integer", "value": "722" } } } 200 OK. . . { ] ], "update. Action": "APPEND" } "context. Responses": [ { "context. Element": { "attributes": [ { "name": "temperature", "type": "float", "value": "" }, { "name": "pressure", "type": "integer", "value": "" } ], "id": "Room 1", "is. Pattern": "false", "type": "Room" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } } ] 21

Quick Usage Example: Room Update. Context (2) POST localhost: 1026/v 1/update. Context. . . { "context. Elements": [ { "type": "Room", "is. Pattern": "false", "id": "Room 2", "attributes": [ { "name": "temperature", "type": "float", "value": "29" }, { "name": "pressure", "type": "integer", "value": "730" } } } 200 OK. . . { ] ], "update. Action": "UPDATE" } "context. Responses": [ { "context. Element": { "attributes": [ { "name": "temperature", "type": "float", "value": "" }, { "name": "pressure", "type": "integer", "value": "" } ], "id": "Room 1", "is. Pattern": "false", "type": "Room" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } } ] 22

Quick Usage Example: Room Query. Context (3) POST <cb_host>: 1026/v 1/query. Context. . . { "entities": [ { "type": "Room", "is. Pattern": "true", "id": "Room. *" }, "attributes": [ "temperature" ] ] } 200 OK. . . { "context. Responses": [ { "context. Element": { "attributes": [ { "name": "temperature", "type": "float", "value": "25" } ], "id": "Room 1", "is. Pattern": "false", "type": "Room" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } }, { "context. Element": { "attributes": [ { "name": "temperature", "type": "float", "value": "29" } ], "id": "Room 2", "is. Pattern": "false", "type": "Room" }, "status. Code": { "code": "200", "reason. Phrase": "OK" } } ] } 23

Context Broker operations: push data • Context Consumers can subscribe to receive context information that satisfy certain conditions using the subscribe. Context. Such subscriptions may have a duration. • The Context Broker notifies updates on context information to subscribed Context Consumers by invoking the notify. Context operation they export Application subscription_id = subscribe. Context (consumer, expr, duration) notify. Context (subscription_id, data/context) Context Consumer Context Broker 24

Quick Usage Example: Subscription POST <cb_host>: 1026/v 1/subscribe. Context … { } "entities": [ { "type": "Room", "is. Pattern": "false", "id": "Room 1" } ], "attributes": [ "temperature" ], "reference": "http: //<host>: <port>/publish", "duration": "P 1 M", "notify. Conditions": [ 200 OK {. . . "type": "ONCHANGE", { "cond. Values": [ "subscribe. Response": { "temperature" "duration": "P 1 M", ] "subscription. Id": "51 c 0 ac 9 ed 714 fb 3 b 37 d 7 d 5 a 8", } "throttling": "PT 5 S" ], } "throttling": "PT 5 S" } 25

Quick Usage Example: Notification 25 19 26

Quick Usage Example: Notification POST http: //<host>: <port>/publish … { } "subscription. Id" : "51 c 0 ac 9 ed 714 fb 3 b 37 d 7 d 5 a 8", "originator" : "localhost", "context. Responses" : [ { "context. Element" : { "attributes" : [ { "name" : "temperature", "type" : "float", "value" : "19" } ], "type" : "Room", "is. Pattern" : "false", "id" : "Room 1" }, "status. Code" : { "code" : "200", "reason. Phrase" : "OK" } } ] 27

Convenience Operations • They are equivalent to previous standard operations in functionality • Avoid the need for POST-ing payloads in many cases or simplifying them considerably • Simple to write, more REST-like • They are not a substitute but a complement to standard NGSI operations • Four examples (there are many others): – Entities – Attributes – Subscriptions – Types 28

Convenience Operations – Example 1 Entities • GET /v 1/context. Entities/{entity. ID} • Retrieves an entity • POST /v 1/context. Entities/{entity. ID} • Creates an entity • PUT /v 1/context. Entities/{entity. ID} • Updates an entity • DELETE /v 1/context. Entities/{entity. ID} • Deletes an entity

Convenience Operations – Example 2 Attributes • GET /v 1/context. Entities/{entity. ID}/attributes/{attr. ID} • Retrieves an attribute’s value • POST /v 1/context. Entities/{entity. ID}/attributes/{attr. ID} • Creates a new attribute for an entity • PUT /v 1/context. Entities/{entity. ID}/attributes/{attr. ID} • Updates an attribute’s value • DELETE /v 1/context. Entities/{entity. ID}/attributes/{attr. ID} • Deletes an attribute

Convenience Operations – Example 3 Subscriptions • POST /v 1/context. Subscriptions • Creates a subscription • PUT /v 1/context. Subscriptions/{sub. ID} • Updates a subscription • DELETE /v 1/context. Subscriptions/{sub. ID} • Cancel a subscription

Convenience Operations – Example 4 Entity Types • GET /v 1/context. Types • Retrieve a list of all entity types currently in Orion, including their corresponding attributes • GET /v 1/context. Types/{type. ID} • Retrieve attributes associated to an entity type PRO TIP GET /v 1/context. Types? collapse=true Retrieves a list of all entity types without attribute info

Usage Examples Contact wwitter @fermingalan Contact email fermin. galanmarquez@telefonica. com

Usage Examples Orion Context Broker • • Freeboard Weather Bot Orion Context Explorer Hackathon setup 34

Usage Examples Orion Context Broker • • Freeboard Weather Bot Orion Context Explorer Hackathon setup 35

Freeboard • Playing the context consumer role 36

Freeboard • Orion freeboard connector – https: //github. com/telefonicaid/fiware-dataviz/tree/develop/Free. Board -Orion-Plugin • Very easy to use! (even in your local machine) • The fiware-dataviz repository includes connector for other visualization tools, along with documentation on how to use them – orion 2 duckboard connector – orion 2 cartodb connector 37

Weather Bot • Running at FIWARE Campus stand REST client … REST client Internet @FIWAREOrion. Live Orion orion 2 twitter Io. TA UDP 60001 orionlive. fiware. org Internet Campus Party Net 38 Internet FIWARE Lab Cloud TCP 80

Hackathon Setup Contex-aware application … FIWARE Lab Cloud Internet hackfest. testbed. fiware. org TCP 1026 eidas 4. testbed. fiware. org TCP 1026 Orion Io. TA-TT Commands Io. TA-LW UDP 9500 TCP 8002 Io. TA-UL 2. 0 API TCP 5371 Internet Campus Party Net TT TT TT … User Device 39 User Device …

Orion Context Explorer • Publicly available browser-based front-end for Orion Context Broker – Open source development by VM 9 • Authentication integrated with FIWARE Lab account • Have a look! – http: //orionexplorer. com/ 40

Advanced Topics Contact wwitter @fermingalan Contact email fermin. galanmarquez@telefonica. com

Pagination • Pagination helps clients organize query and discovery requests with a large number of responses. • Three URI parameters: – limit • Number of elements per page (default: 20, max: 1000) – offset • Number of elements to skip (default: 0) – details • Returns total elements (default: "off") 42

Pagination • Example, querying the first 100 entries: POST <orion_host>: 1026/v 1/query. Context? limit=100&details=on • The first 100 elements are returned, along with the following error. Code in the response: "error. Code": { "code": "200", "details": "Count: 322", "reason. Phrase": "OK" } • Now we now there are 322 entities, we can keep querying the broker for them: – – – POST <orion_host>: 1026/v 1/query. Context? offset=100&limit=100 POST <orion_host>: 1026/v 1/query. Context? offset=200&limit=100 POST <orion_host>: 1026/v 1/query. Context? offset=300&limit=100 43

Compound Attribute Values • An attribute can have a structured value. Vectors and key-value maps are supported. • It maps directly to JSON's objects and arrays. 44

Compound Attribute Values { • Example: we have a car whose four wheels' pressure we want to represent as a compound attribute for a car entity. We would create the car entity like this: } "context. Elements": [ { "type": "Car", "is. Pattern": "false", "id": "Car 1", "attributes": [ { "name": "tire. Pressure", "type": "k. Pa", "value": { "front. Right": "120", "front. Left": "110", "back. Right": "115", "back. Left": "130" } } ], "update. Action": "APPEND" 45

Metadata • Users may attach metadata to attributes • Reserved metadatas: ID, Location, cre. Date and mod. Date • Examples: … "attributes": [ { "name": "temperature", "type": "float", "value": "26. 5", "metadatas": [ { "name": "accuracy", "type": "float", "value": "0. 9" } ] … … "attributes": [ { "name": "temperature", "type": "float", "value": "26. 5", "metadatas": [ { "name": "average", "type": "float", "value": "22. 4" } ] … 46

Geo-location • Entities can have an attribute that specifies its location – • Using a "location" metadata Example: create an entity called Madrid …and create a couple more towns: • Leganés • Alcobendas 47 POST <cb_host>: 1026/v 1/update. Context { "context. Elements": [ { "type": "City", "is. Pattern": "false", "id": "Madrid", "attributes": [ { "name": "position", "type": "coords", "value": "40. 418889, -3. 691944", "metadatas": [ { "name": "location", "type": "string", "value": "WSG 84" } ] } ], "update. Action": "APPEND" }

Geo-location – Circle 48

Geo-location – Circle km 5. 3 iu d a r s POST <cb_host>: 1026/v 1/query. Context … { 1 } 49 "entities": [ { "type": "City", "is. Pattern": "true", "id": ". *" } ], "restriction": { "scopes": [ { "type" : "FIWARE: : Location", "value" : { "circle": { "center. Latitude": "40. 418889", "center. Longitude": "-3. 691944", "radius": "13500" } } } ] }

Geo-location – Inverse Circle km 5. 3 iu rad s POST <cb_host>: 1026/v 1/query. Context … { 1 } 50 "entities": [ { "type": "City", "is. Pattern": "true", "id": ". *" } ], "restriction": { "scopes": [ { "type" : "FIWARE: : Location", "value" : { "circle": { "center. Latitude": "40. 418889", "center. Longitude": "-3. 691944", "radius": "13500", "inverted": "true" } } } ] }

Registration & Context Providers • Uncached queries and updates Application 1. register. Context(provider= ) 5. data Context Consumer 2. query. Context(id) 4. data Context. Broker 3. query. Context(id) Context. Provider db 51

Registration & Context Providers POST <cb_host>: 1026/v 1/registry/register. Context … { } "context. Registrations": [ { "entities": [ { "type": "Car", "is. Pattern": "false", "id": "Car 1" 200 OK }, . . . "attributes": [ { { "duration" : "P 1 M", "name": "speed", "type": "float", "registration. Id" : "52 a 744 b 011 f 5816465943 d 58" "is. Domain": "false" } } ], "providing. Application": "http: //contextprovider. com/Cars" } ], "duration": "P 1 M" 52

Registration & Context Providers POST <cb_host>: 1026/v 1/query. Context. . . { "entities": [ { "type": "Car", "is. Pattern": "false", "id": "Car 1" } ] } data Context. Broker query. Context(id) 200 OK. . . { "context. Responses": [ { "context. Element": { "attributes": [ { "name": "speed", "type": "float", "value": "100" } ], "id": "Car 1", "is. Pattern": "false", "type": "Car" }, "status. Code": { "code": "200", "details": "Redirected to context provider http: //contextprovider. com/Cars", "reason. Phrase": "OK" } Context. Provider } ] db } 53

Multitenancy • Simple multitenant model based on logical database separation. • It eases tenant-based authorization provided by other components. • Just use an additional HTTP header called "Fiware-Service", whose value is the tenant name. Example: Fiware-Service: Tenant 1 Context Broker Tenant 1 Tenant 2 … 54

Entity Service Paths • A service path is a hierarchical scope assigned to an entity at creation time (with update. Context). 55

Entity Service Paths • In order to use a service path we put in a new HTTP header called “Fiware-Service. Path". For example: Fiware-Service. Path: Madrid/Gardens/Parque. Norte/Parterre 1 • Properties: – – A query on a service path will look only into the specified node Use "Parent. Node/#" to include all child nodes Queries without Fiware-Service. Path resolve to "/#" Entities will fall in the "/" node by default Parque. Sur Parque. Norte Parterre 1 Parque. Oeste Parterre 2 56

Entity Service Paths • Properties (continued): A – You can OR a query using a comma (, ) operator in the header • For example, to query all street lights that are either in Parque. Sur or in Parque. Oeste you would use: Service. Path: Madrid/Gardens/Parque. Sur, Madrid/Gardens/Parque. Oeste • You can OR up to 10 different scopes. B A or B – Maximum scope levels: 10 • Scope 1/Scope 2/. . . /Scope 10 – You can have the same element IDs in different scopes (be careful with this!) – You can't change scope once the element is created – One entity can belong to only one scope – It works not only with queries, but also with subscriptions/notifications 57 Parque. Norte light 1 Parterre 1 light 1

Thanks!

Backup slides BACKUP SLIDES 59

Integration with existing systems • Context adapters will be developed to interface with existing systems (e. g. , municipal services management systems in a smart city) acting as Context Providers, Context Producers, or both • Some attributes from a given entity may be linked to a Context Provider while other attributes may be linked to Context Producers Application query. Context (e 1, attr 2) query. Context (e 1, attr 1) System A update. Context (e 1, attr 2) Context Broker Context Provider System B Context Consumer 60

Integration with sensor networks • The backend Io. T Device Management GE enables creation and configuration of NGSI Io. T Agents that connect to sensor networks • Each NGSI Io. T Agent can behave as Context Consumers or Context Providers, or both OMA NGSI API (northbound interface) FIWARE Context Broker create/monitor Io. T Agent-1 Io. T Agent-2 Io. T Agent-n Io. T Agent Manager FIWARE Backend Io. T Device Management (southbound interfaces) ETSI M 2 M MQTT IETF Co. AP 61

Context Management in FIWARE Cloud • Federation of infrastructures (private/public regions) • Automated GE deployment Data • Complete Context Management Platform • Integration of Data and Media Content Io. T • Easy plug&play of devices using multiple protocols • Automated Measurements/Action Context updates Apps • Visualization of data (operation dashboards) • Publication of data sets/services Web UI • Easy support of UIs with advanced web-based 3 D and AR capabilities • Visual representation of context information. I 2 ND • Advanced networking capabilities (SDN) and Middleware • Interface to robots Security • Security Monitoring • Built-in Identity/Access/Privacy Management 62

FI-WARE Context/Data Management Platform Applications Processing/Analysis Algorithms OMA NGSI-9/10 Gathered data is injected for processing/analysis Data generated either by CEP or Big. Data is published Gathered data injected for CEP-like processing Distributed Context Sources Programming of rules Big. Data (COSMOS) Complex Event Processing (PROTON) Context/Data Management Platform 63 Processed data is injected for processing/analysi s Direct bigdata injection