FIWARE Context Broker

Pasquale VitaleEngineering Ingegneria Informatica

FIWARE Contex Broker

Introduction

Managing Context Information at large scale

FIWARE Context Broker GE (implementation: Orion)

Creating and pulling data

Pushing data and notifications

Convenience operations

Managing Context Information at large scale

Context Information is represented through values assigned to attributes

The Context Broker is able to:

handle context information at large scale

enable your application to query on context information

subscribe to changes in context information that will be received through notifications

enable your application or other applications to modify the context information

Context Management in FIWARE

Context Information: the value of attributes that characterize those entities relevant to your application

NGSI API

Bus• Location• No. passengers• Driver• License plate

Citizen• Name-Surname• Birthday• Preferences• Location• To Do list

Shop• Location• Business name• Franchise• Offerings

Applications/Services

Context Broker

A sensor in a pedestrian street

The Public Bus Transport Management system

A person from his smartphone

It’s too hot!

What’s the current temperature?

… but programmers should just care about entities and their attributes

Context Information independent from the source

Context information may come from many sources using different interfaces and protocols …


Get notified when an update on context information takes place

Bus = “X”, last_stop = “A”, arrived= “Yes”

push

Notify me when bus “X” arrives at the bus stop “A”

API


Acting on devices can be as easy as changing the value of attributes linked to its corresponding entity

Street lamp = “lamp1”, status= “on”

Street Lamp lamp1.status “on”

API

FIWARE Context Broker GE: Orion

Main functions:

Context availability management - OMA NGSI-9 specs

Context management - OMA NGSI-10 specs

HTTP and REST-based

XML payload support

JSON payload support


Functions Operations

NGSI-9• Register, • Search,• Subscribe for context sources

• registerContext• discoverContextAvailability• subscribeContextAvailability• updateContextAvailabilitySubscription• unsubscribeContextAvailability

NGSI-10• Query,• Update,• Subscribe to context elements

• updateContext• queryContext• subscribeContext• updateContextSubscription• unsubscribeContextSubscription


Context in NGSI is based in an entity-attribute model:

Attributes• Name• Type• Value

Entity

• EntityId• EntityType 1 n

“has”


Orion Architecture

11

Orion Context Broker

ContextProducers

ContextConsumers

subscriptions

update

query

notify

notify

update

update

DB

1026

1026

Context Broker operations: create and pull data

Context Producers publish data/context elements by invoking the updateContext operation on a Context Broker

Context Consumers can retrieve data/context elements by invoking the queryContext operation on a Context Broker

Context Consumer

queryContext

Context Producer

updateContext

Context Broker

speed

Entity creation example: car create

updateContext operation with APPEND action type

POST localhost:1026/v1/updateContext... {"contextElements": [{"type": "Car","isPattern": "false","id": "Car1","attributes": [{"name": "speed","type": "float","value": "98"

}]

}],"updateAction": "APPEND"

}

200 OK... {"contextResponses": [{"contextElement": {"attributes": [{"name": "speed","type": "float","value": ""

}],"id": "Car1","isPattern": "false","type": "Car"

},"statusCode": {"code": "200","reasonPhrase": "OK"

}}

]}

Update context elements example: car updateContext

updateContext operation with UPDATE action type

POST localhost:1026/v1/updateContext... {"contextElements": [{"type": "Car","isPattern": "false","id": "Car1","attributes": [{"name": "speed","type": "float","value": "110"

}]

}],"updateAction": "UPDATE"

}

200 OK... {"contextResponses": [{"contextElement": {"attributes": [{"name": "speed","type": "float","value": ""



}}

]}

Query context operation example: car queryContext

queryContext operation by Id

POST <cb_host>:1026/v1/queryContext... {"entities": [{"type": "Car","isPattern": "false","id": "Car1"

}]

}

200 OK... {"contextResponses": [{"contextElement": {"attributes": [{"name": "speed","type": "float","value": "110"

}],

"id": "Car1","isPattern": "false","type": "Car"


}}

]}

Entity creation example: room create

POST localhost:1026/v1/updateContext... {"contextElements": [{"type": "Room","isPattern": "false","id": "Room1","attributes": [{"name": "temperature","type": "float","value": "24"

},{"name": "pressure","type": "integer","value": "718"

}

]}

],"updateAction": "APPEND"

}

200 OK... {"contextResponses": [{"contextElement": {"attributes": [{"name": "temperature","type": "float","value": ""

},{"name": "pressure","type": "integer","value": ""

}],"id": "Room1","isPattern": "false","type": "Room"


}}

]}

Two attributes: temperature and pressure

Update context elements example: room updateContext

POST localhost:1026/v1/updateContext... {"contextElements": [{"type": "Room","isPattern": "false","id": "Room1","attributes": [{"name": "temperature","type": "float","value": "25"


}

]}

],"updateAction": "UPDATE"

}





}}

]}

Update: temperature and pressure

Query context operation example: room queryContext

queryContext operation by Id

POST <cb_host>:1026/v1/queryContext... {"entities": [{"type": “Room","isPattern": "false","id": “Room1"

}]

}

200 OK... {"contextResponses": [{"contextElement": {"attributes": [{"name": "temperature","type": "float","value": "25"




}}

]}


queryContext operation by Id and attribute

POST <cb_host>:1026/v1/queryContext... {"entities": [{"type": “Room","isPattern": "false","id": "Room1"

}] ,"attributes": [

"temperature"]

}

200 OK... {"contextResponses": [{"contextElement": {"attributes": [{"name": "temperature","type": "float","value": "25"

}],

"id": "Room1","isPattern": "false","type": "Room"


}}

]}

Entity creation example: room create

POST localhost:1026/v1/updateContext... {"contextElements": [{"type": "Room","isPattern": "false","id": "Room2","attributes": [{"name": "temperature","type": "float","value": “33"

},{"name": "pressure","type": "integer","value": “722"

}

]}

],"updateAction": "APPEND"

}





}}

]}

Append another room: Room2


queryContext operation by regex Room.*

POST <cb_host>:1026/v1/queryContext... {"entities": [{"type": “Room","isPattern": “true","id": "Room.*"

}] ,"attributes": [

"temperature"]

}

{"contextResponses": [{"contextElement": {"attributes": [{"name": "temperature","type": "float","value": "25"



}},{"contextElement": {"attributes": [{"name": "temperature","type": "float","value": “33"



}}

]}

Context Broker operations: push data

Context Consumers can subscribe to receive context information that satisfy certain conditions using the subscribeContext. Such subscriptions may have a duration.

The Context Broker notifies updates on context information to subscribed Context Consumers by invoking the notifyContext operation they export

subscription_id = subscribeContext (consumer, expr, duration)

Context Consumer

notifyContext (subscription_id, data/context)

Context Broker

Application

Context subscriptions example: ONTIMEINTERVAL

POST <cb_host>:1026/v1/subscribeContext…{"entities": [{"type": "Room","isPattern": "false","id": "Room1"

}],"attributes": ["temperature"

],"reference": "http://<host>:<port>/publish","duration": "P1M","notifyConditions": [{"type": "ONTIMEINTERVAL","condValues": [“PT10S"

]}

]}

200 OK... {"subscribeResponse": {"duration": "P1M","subscriptionId": "54dcb87fa85d63b107245ff1"

}}

25

19

Context subscriptions example: ONCHANGE

POST <cb_host>:1026/v1/subscribeContext…{"entities": [{"type": "Room","isPattern": "false","id": "Room1"

}],"attributes": ["temperature"

],"reference": "http://<host>:<port>/publish","duration": "P1M","notifyConditions": [{"type": "ONCHANGE","condValues": ["temperature"

]}

],"throttling": "PT5S"

}

200 OK... {"subscribeResponse": {"duration": "P1M","subscriptionId": "51c0ac9ed714fb3b37d7d5a8","throttling": "PT5S"

}}

25

19

NotificationPOST http://<host>:<port>/publish…{"subscriptionId" : "51c0ac9ed714fb3b37d7d5a8","originator" : "localhost","contextResponses" : [{"contextElement" : {"attributes" : [{"name" : "temperature","type" : "float","value" : "19"}],"type" : "Room","isPattern" : "false","id" : "Room1"},"statusCode" : {"code" : "200","reasonPhrase" : "OK"}}]}

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


Entities

GET /v1/contextEntities/{entityID} Query Context Retrieves an entity

POST /v1/contextEntities/{entityID} Entity Creation Creates an entity

PUT /v1/contextEntities/{entityID} Update Context Updates an entity

DELETE /v1/contextEntities/{entityID} Delete Context Deletes an entity

GET all entities

GET /v1/contextEntities


Attributes

GET /v1/contextEntities/{entityID}/attributes/{attrID} Retrieves an attribute’s value

POST /v1/contextEntities/{entityID}/attributes/{attrID} Creates a new attribute for an entity

PUT /v1/contextEntities/{entityID}/attributes/{attrID} Updates an attribute’s value

DELETE /v1/contextEntities/{entityID}/attributes/{attrID} Deletes an attribute


Subscriptions

POST /v1/contextSubscriptions Creates a subscription

PUT / v1/contextSubscriptions/{subID} Updates a subscription

DELETE / v1/contextSubscriptions/{subID} Deletes a subscription


Entity types

GET /v1/contextTypes

Retrieve a list of all entity types currently in Orion, including their corresponding attributes

GET / v1/contextTypes/{typeID}

Retrieve attributes associated to an entity type

PRO TIP

GET /v1/contextTypes?collapse=trueRetrieves a list of all entity types without attribute info

Advanced features

Pagination

Compound attribute values

Metadata

Geo-location

Registrations & context providers

Entity service paths

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")

Pagination

Example, querying the first 100 entries:

POST <orion_host>:1026/v1/queryContext?limit=100&details=on

The first 100 elements are returned, along with the following errorCode in the response: "errorCode": {

"code": "200", "details": "Count: 322", "reasonPhrase": "OK"

}

Now there are 322 entities, we can keep querying the broker for them:POST <orion_host>:1026/v1/queryContext?offset=100&limit=100POST <orion_host>:1026/v1/queryContext?offset=200&limit=100POST <orion_host>:1026/v1/queryContext?offset=300&limit=100

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

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:

{"contextElements": [{"type": "Car","isPattern": "false","id": "Car1","attributes": [{"name": "tirePressure","type": "kPa","value": {"frontRight": "120","frontLeft": "110","backRight": "115","backLeft": "130"

}}]

}],"updateAction": "APPEND"

}

Metadata

Users may attach metadata to attributes

Reserved metadatas: ID, Location, creDate and modDate

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"}]}]

…

Context Element attributes

• Name• Type• Value

Context Element

• EntityId• EntityType

n

“has”

1

Metadata

• Name• Type• Valuen

“has”

1

Geo-location

Entities can have an attribute that specifies its location

- Using a "location" metadata

Example:

create an entity called Madrid (of type "City")

with attribute "position" defined as location

POST <cb_host>:1026/v1/updateContext{"contextElements": [{"type": "City","isPattern": "false","id": "Madrid","attributes": [{"name": "position","type": "coords","value": "40.418889, ‐3.691944","metadatas": [{"name": "location","type": "string","value": "WGS84"}

]}]}],"updateAction": "APPEND"}

Coordinates for Madrid are:

• latitude 40.418889

• longitude 3.691944

Geo-located queries

Entities location can be used in queryContex using:

- FIWARE::Location as scopeType

- and an area specification as scopeValue

The area specification are:

- area internal to a circle, given its centre and radius

- area external to a circle, given its centre and radius

- area internal to a polygon, given its vertices

- area external to a polygon, given its vertices

{"entities": [{"type": "Point","isPattern": "true","id": ".*"}],"restriction": {"scopes": [{"type" : "FIWARE::Location","value" : {"polygon": {"vertices": [{"latitude": "0","longitude": "0"},{"latitude": "0","longitude": "6"},{"latitude": "6","longitude": "6"},{"latitude": "6","longitude": "0"}]}}}]}}

Geo-location - circle

Distances between:

- Madrid / Alcobendas 13.65 km

- Madrid / Leganes 12.38 km

Consider a radius of 13.5 km

POST <cb_host>:1026/v1/queryContext…{"entities": [{"type": "City","isPattern": "true","id": ".*"}],"restriction": {"scopes": [{"type" : "FIWARE::Location","value" : {"circle": {"centerLatitude": "40.418889","centerLongitude": "‐3.691944","radius": "13500"}}}]}}

The query is Madrid and Leganes

Geo-location - inverse circle

Distances between:

- Madrid / Alcobendas 13.65 km

- Madrid / Leganes 12.38 km

Consider a radius of 13.5 km

POST <cb_host>:1026/v1/queryContext{"entities": [{"type": "City","isPattern": "true","id": ".*"}],"restriction": {"scopes": [{"type" : "FIWARE::Location","value" : {"circle": {"centerLatitude": "40.418889","centerLongitude": "‐3.691944","radius": "13500","inverted": "true"}}}]}}

The query is Alcobendas

Registration & Context Providers

Context Broker doesn't cache the result of the query internallyApplication

Context Broker Context Provider

1. registerContext(provider= )

2. queryContext(id) 3. queryContext(id)

4. data5. data

Context Consumer

db


POST <cb_host>:1026/v1/registry/registerContext…{"contextRegistrations": [{"entities": [{"type": "Car","isPattern": "false","id": "Car1"

},"attributes": [{"name": "speed","type": "float","isDomain": "false"

}],"providingApplication": "http://contextprovider.com/Cars"

}],"duration": "P1M"

}

200 OK... {"duration" : "P1M","registrationId" : "52a744b011f5816465943d58"}

The application registers the Context Provider for the Car1 speed using providingApplication attributeApplication

registerContext

http://contextprovider.com/Cars

{"contextResponses": [{"contextElement": {"attributes": [{"name": "speed","type": "float","value": "100"


},"statusCode": {"code": "200","details": "Redirected to context provider http://contextprovider.com/Cars","reasonPhrase": "OK"

}}

]}


It includes details in the response

POST <cb_host>:1026/v1/queryContext... {"entities": [{"type": "Car","isPattern": "false","id": "Car1"

}]

}

queryContext(id)

data

Multitenancy

Context Broker implements a simple multitenant/multiservice model based and logical database separation

Make easer service/tenant based authorization policies provided by other FI-WARE components or third party software

Orion uses the "Fiware-Service" HTTP header in the request to identify the service/tenant

Example:Fiware-Service: Tenant1

Context BrokerContext Broker

Tenant1

Tenant2

…

entities1/attributes1/subscripitions1

entities2/attributes2/subscripitions2

Entity Service Paths

Orion Context Broker supports hierarchical scopes

Entities can be assigned to a scope at creation time with updateContext

queryContext can be also scoped to locate entities in the corresponding scopes

For example, consider the following scopes in the figure:

- Madrid, as first level scope

- Gardens and Districts, as second-level scope (children of Madrid)

- ParqueNorte, ParqueOeste and ParqueSur (children of Gardens)

and Fuencarral and Latina (children of Districts)

- Parterre1 and Parterre2 (children of ParqueNorte)


In order to use a service path we put in a new HTTP header called “Fiware-ServicePath". For example:Fiware-ServicePath: Madrid/Gardens/ParqueNorte/Parterre1

ParqueNorte

Parterre2Parterre1


Properties:1. A query on a service path will look only into the specified node2. Use ParentNode/# to include all child nodes3. Queries without Fiware-ServicePath resolve to /#4. Entities will fall in the "/" node by default5. You can OR a query using a comma (,) operator in the header

For example, to query all street lights that are either in ParqueSur or in ParqueOeste you would use:

ServicePath: Madrid/Gardens/ParqueSur, Madrid/Gardens/ParqueOesteYou can OR up to 10 different scopes

- Maximum scope levels: 10Scope1/Scope2/.../Scope10

1. You can have the same element IDs in different scopes (be careful with this!)2. You can't change scope once the element is created3. One entity can belong to only one scope

A B

A or B

ParqueNorte

Parterre1light1

light1

Thanks!Thanks!

FIWARE Context Broker

Software

Transcript of FIWARE Context Broker