SmartSantander Open Data access using FI-WARE G.E.

[ORION]

What to find in this doc

FI-WARE is an open cloud-based infrastructure for Future Internet applications and services, composed by

different building blocks, known as General Enablers (GE). The FI-WARE consortium intends to deliver a

reference implementation for each of the Generic Enablers defined in its Architecture. Currently, FI-WARE

provides FI-LAB, a working instance of FI-WARE available for experimentation. ORION Context Broker is the

FI-LAB implementation of the Configuration Management GE and provides a way to manage context

information and context information availability of the nodes belonging to SmartSantander. This document

intends to describe how to use the ORION’s REST API to get context information from Santander nodes. It

is structured as follows:

1 Introduction ................................................................................................................................. 3

1.1 What is FI-WARE .................................................................................................................... 3

1.2 What is Orion ......................................................................................................................... 3

1.3 OMA – NGSI Context Management ....................................................................................... 3

1.3.1 FI-WARE NGSI-9 Open RESTful API Specification ........................................................... 5

1.3.2 FI-WARE NGSI-10 Open RESTful API Specification ......................................................... 6

2 Security & Trust ............................................................................................................................ 7

2.1 Registration ............................................................................................................................ 7

2.2 Getting Auth-Token ............................................................................................................... 7

3 ORION Functionalities .................................................................................................................. 9

3.1 Context Queries ..................................................................................................................... 9

3.1.1 GET Entity Context ......................................................................................................... 9

3.1.2 Discovering Context ..................................................................................................... 12

3.2 Subscriptions ....................................................................................................................... 15

3.2.1 Subscriptions payload .................................................................................................. 15

3.2.2 ORION notifications ..................................................................................................... 16

3.2.3 Context information subscriptions ............................................................................... 17

3.2.4 Context availability subscriptions ................................................................................ 20

4 Santander Open Data ................................................................................................................. 23

1 Introduction

1.1 What is FI-WARE

FI-WARE is a new infrastructure for the creation and development of services and applications on the Future

Internet. Cloud-based it aims at being a new open alternative for entrepreneurs and users of the services on the

Future Internet. The main objective of FI- WARE is to provide the basic elements with which to build new

services and applications in such diverse areas as smart cities, the Internet of things, e- health, e- education,

advanced manufacturing, multimedia applications, etc.

FI -WARE is based on a set of elements called “Generic Enablers” (GE) (which are, essentially, reusable software

systems)

Most of the FI- WARE’s GEs belong to one of the following chapters:

Cloud Hosting elements that provide the basic resources of computing, network and storage.

Data management modules, which provide tools for data analysis such as “Big Data”.

Modules to allow application integration that provides elements to integrate applications, publication,

mash up, etc. This includes also business aspects.

Elements for managing sensors and the Internet of Things, to easily use resources of sensors and

actuators.

Network access control and communications modules including terminals control.

Elements to support security and privacy for the applications.

1.2 What is Orion

Orion Context Broker is an implementation of a context information broker with persistent storage that can play

the role of two GEs within the FI-WARE platform.

Pub/Sub Context Broker GE.

Configuration Management GE (it implements registration forwarding).

It implements OMA NGSI9/10 specification.

NGSI-9 deals with context information availability (registerContext, discoverContextAvailability,

subscribeContextAvailability…).

NGSI-10 deals with context information itself (updateContext, queryContext…).

Using these interfaces, clients can do several operations:

Register context producers, e.g. a temperature sensor within a room

Update context information, e.g. send updates of temperature

Being notified when changes on context information take place (e.g. the temperature has changed) or

with a given frequency (e.g. get the temperature each minute)

Query context information. The Orion Context Broker stores context information updated from registerd

context producers, so queries are resolved based on that information.

1.3 OMA – NGSI Context Management

FI-WARE Context Broker G.E. specifications are based on Open Mobile Alliance (OMA) Next Generation

Services Interfaces (NGSI) for Context Management. This basically implies the provision of APIs that

provides functionalities to

Manage the Context Information about Context Entities, for example the lifetime and quality of

information.

Access (query, subscribe/notify) to the available Context Information about Context Entities.

OMA divides these APIs into two different interfaces, NGSI-9 and NGSI-10, with the following functions:

Register and retrieve the availability of Context Entities and/or Context Information.

Update Context Information in accordance to a specified Context Information Model.

Query for and subscribe to Context Information about Context Entities.

Both interfaces use the Basic NGSI Context Management Information Model that describes the context

information based on:

Entities: are the virtual representation of all kinds of physical objects (“things”) in the real world.

Virtual entities have an identifier and a type. For example, a virtual entity representing a person

named “John” could have the identifier “John” and the type “person”.

Attributes: any available information about entities is expressed in the form of attributes of virtual

entities. Attributes have a name and a type as well. For example, the body temperature of John

would be represented as an attribute having the name “body_temperature” and the type

“temperature”. Values of such attributes are contained by value containers. This kind of container

does not only consist of the actual attribute value, but also contains a set of metadata. Metadata is

data about data; in our body temperature example this metadata could represent the time of

measurement, the measurement unit, or any other information about the attribute value.

Attribute Domains: An attribute domain logically groups together a set of attributes. For example,

the attribute domain "health_status" could be comprised of the attributes "body_temperature"

and "blood_pressure".

Context Elements: the data structure used for exchanging information about entities is a context

element. A context element contains information about multiple attributes of one entity. The

domain of these attributes can also be specified inside the context element; in this case all

provided attribute values have to belong to that domain.

Formally, a context element contains the following information:

an entity id and type

a list of triplets <attribute name, attribute type, attribute value> holding information about

attributes of the entity

(optionally) the name of an attribute domain

(optionally) a list of triplets <metadata name, metadata type, metadata value> that apply to all

attribute values of the given domain

Using these OMA’s interfaces and its information model reference, FI-WARE Context Broker GE and its

implementation, ORION, provides the specifications described in following sections.

1.3.1 FI-WARE NGSI-9 Open RESTful API Specification

The FI-WARE version of the OMA NGSI-9 interface is a RESTful API via HTTP. It provides information about

the availability of context information. The three main interaction types are:

one-time queries for discovering hosts (also called 'agents' here) where certain context information

is available

subscriptions for context availability information updates (and the corresponding notifications)

registration of context information, i.e. announcements that certain context information is

available (invoked by context providers)

Figure 1below presents the mapping of NGSI-9 functionality within FI-WARE Context Broker specification to

a resource tree following the REST approach. Further, in this document we will explain how ORION

implements this functionality, from the point of view of SmartSantander Open Data Set access.

Figure 1. NGSI-9 reference model

1.3.2 FI-WARE NGSI-10 Open RESTful API Specification

The FI-WARE version of the OMA NGSI 10 interface is a RESTful API via HTTP. It provides context

information itself. The three main interaction types are:

one-time queries for context information

subscriptions for context information updates (and the corresponding notifications)

unsolicited updates (invoked by context providers)

Figure 2below presents the mapping of NGSI-10 functionality within FI-WARE Context Broker specification

to a resource tree following the REST approach. Further, in this document we will explain how ORION

implements this functionality, from the point of view of SmartSantander Open Data Set access.

Figure 2. NGSI-10 reference model

2 Security & Trust Security & Trust mechanisms and enablers are currently evolving within FI-WARE. You can check the status

of FI-WARE Security architecture at its web page1 and the FI-WARE catalogue2.

Access to the current FI-LAB ORION Context Broker instance is authenticated using OAuth2 FI-WARE

framework. To get a valid X-Auth-Token that grants access, identifying and authenticating the user it is

necessary to have a FI-WARE account. It is fairly simple to create such an account.

2.1 Registration

In order to gain access to the different assets and services provided in FI-LAB (not only ORION), it’s

necessary to get a FI-WARE account. Fi-Lab is a working instance of Fi-Ware, oriented to create, develop,

deploy and run new IoT applications. New users may get a FI-WARE account by signing up through this link:

[https://account.lab.fi-ware.org/]

Just by clicking “Sign Up” link and follow the registration process, the user will get a FI-WARE account,

including a valid user name and password to be used in the different ORION requests.

2.2 Getting an Authentication Token

Once you’ve completed the previous step, you can get an OAuth2 valid token by requesting it to the FI-LAB

Identity Management GEi KeyRock, using the available RESTful service and your FI-WARE user/password:

IdM Instance cloud.lab.fi-ware.org:4730

POST /v2.0/tokens

Content-type application/json

Payload:

{"auth": {"passwordCredentials": {"username":"Your_FIWARE_USER", "password":"Your_FIWARE_PASSWD" } } }

Advanced Rest example:

1 https://forge.fi-ware.org/plugins/mediawiki/wiki/fiware/index.php/Security_Architecture

2 http://catalogue.fi-ware.org/enablers?chapter_tid=6

It will return (if your user is allowed) a json structure including your user name, the X-AUTH-TOKEN (the id

attribute in the JSON response body) to be used in ORION queries and its expiring time:

{"access": {"token": {"expires":"2015-07-09T15:16:07Z", "id":"6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg-VpfzNJWTcV7pMHF3iQRT" }, "user": {"username":"your-user", "roles_links":[], "id":"your-user ", "name":"Your User " } } }

3 ORION Functionalities Although the FI-WARE Context Broker supports a wide range of functionalities, from the point of view of

Smart Santander deployments and its Open Data Set, we will focus on two main operations: Current

Context Information provider and Publish/Subscribe Broker, both of them provided through their

corresponding RESTful API. Once we have our OAuth2 Token, we will able to perform the operations

described in the following sub-sections.

3.1 Context Queries

This section describes the REST API for getting up to date context status of every Smart Santander deployed

node

3.1.1 GET Entity Context

3.1.1.1 Get entity context availability (NGSI9)

Through this operation, the consumer can get the set of attributes of a given entity. It allows to find which

context information a SmartSantander node can provide, in order to perform further subscriptions.

ORION Instance orion.lab.fi-ware.org:1026

GET /ngsi9/contextEntities

PARAMS

Entity ID ID of the Requested Node (returns all node attributes): http://orion.lab.fi-ware.org:1026/ngsi9/contextEntities/urn:smartsantander:testbed:357

Attributes Only required if user is interested in a specific attribute: http://orion.lab.fi-ware.org:1026/ngsi9/contextEntities/urn:smartsantander:testbed:357/attributes/sound

HEADERS

Accept application/json

X-Auth-Token 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg-VpfzNJWTcV7pMHF3iQRT

Advanced Rest example:

This will return a JSON with the registered set of available attributes of a given entity (or the description of

the selected attribute). The general context response structure contains:

Context Registration [Entity + {Attributes}]

o Entity: including its Type and ID. The “isPattern” here is unused.

o Attributes: A list of the attributes caught by the sensor, made up of two parts, name +

identifier.

{ "contextRegistrationResponses" : [ { "contextRegistration" : { "entities" : [ { "type" : "santander:soundacc", "isPattern" : "false", "id" : "urn:smartsantander:testbed:357" } ], "attributes" : [ { "name" : "TimeInstant", "type" : "urn:x-ogc:def:trs:IDAS:1.0:ISO8601", "isDomain" : "false" }, { "name" : "sound", "type" : "urn:x-ogc:def:phenomenon:IDAS:1.0:sound", "isDomain" : "false" }, { "name" : "batteryCharge", "type" : "urn:x-ogc:def:phenomenon:IDAS:1.0:batteryCharge", "isDomain" : "false" }, { "name" : "Latitud", "type" : "urn:x-ogc:def:phenomenon:IDAS:1.0:latitude", "isDomain" : "false" }, { "name" : "Longitud", "type" : "urn:x-ogc:def:phenomenon:IDAS:1.0:longitude", "isDomain" : "false" } ], "providingApplication" : "http://0.0.0.0:1029" } }, ] }

3.1.1.2 Get entity context information (NGSI10)

This REST resource retrieves the available context information related to a given entity. It can retrieve all

current available attribute values or just the last value of a specified attribute. It’s useful to obtain all the

current attribute values measured by a SmartSantander node.

ORION Instance orion.lab.fi-ware.org:1026

GET /ngsi10/contextEntities

PARAMS

Entity ID ID of the Requested Node (returns all node attributes): http://orion.lab.fi-ware.org:1026/ngsi10/contextEntities/urn:smartsantander:testbed:357

Attributes Only required if user is interested in a specific attribute: http://orion.lab.fi-ware.org:1026/ngsi10/contextEntities/urn:smartsantander:testbed:357/attributes/sound

HEADERS

Accept application/json

X-Auth-Token 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg-VpfzNJWTcV7pMHF3iQRT

Advanced Rest example:

This will return a JSON with the last measured value for every attribute of the node identified (if we specify

only one attribute, we will retrieve only the last value of its specified attribute). The general context

response structure contains:

Context Element [ Type + isPattern + ID + {Attributes}]

o Type: normally there is a blank here. It will be useful in next section.

o isPattern: false if you asked for a specific element. It will be useful in next section.

o ID: identifier of the element you are asking for.

o Attributes: A list of the attributes caught by the sensor, made up of two parts, identifier

and metadata.

Identifier: consists of the attribute’s name, its identifier (code) and its value.

Metadata: unit of the attribute.

{ "contextElement" : { "type" : "", "isPattern" : "false", "id" : "urn:smartsantander:testbed:357", "attributes" : [ { "name" : "TimeInstant", "type" : "urn:x-ogc:def:trs:IDAS:1.0:ISO8601", "value" : "2014-09-09T17:11:55.000000Z" }, { "name" : "sound", "type" : "urn:x-ogc:def:phenomenon:IDAS:1.0:sound", "value" : "56.4", "metadatas" : [ { "name" : "code", "type" : "", "value" : "dB"

} ] }, { "name" : "batteryCharge", "type" : "urn:x-ogc:def:phenomenon:IDAS:1.0:batteryCharge", "value" : "68", "metadatas" : [ { "name" : "code", "type" : "", "value" : "%" } ] }, { "name" : "Latitud", "type" : "urn:x-ogc:def:phenomenon:IDAS:1.0:latitude", "value" : "43.46323" }, { "name" : "Longitud", "type" : "urn:x-ogc:def:phenomenon:IDAS:1.0:longitude", "value" : "-3.80882" } ] }, "statusCode" : { "code" : "200", "reasonPhrase" : "OK" } }

3.1.2 Discovering Context

Using NGSI9 “discoverContextAvailability” and NGSI10 “queryContext” ORION REST commands, we will be

able to retrieve the current available context attributes and their associated last reported values. Both

queries will use a JSON payload (XML also available) through which we can perform our different context

searches and discovering processes. This payload allows specifying the entity types, the entity IDs and/or

the attributes availability and values we are interested in:

{"entities":[ {"type":"Node", "isPattern":"true", "id":"Sensor_ID" } ], "attributes":["temperature"] }

Entities o Type: specifies the type of the nodes to discover. o isPattern: “true” if we’re performing a search; “false” to query

for a specific value (entity type and/or id)

Attributes o List here the attributes to discover

A powerful feature of ORION Context Broker is that a regular expression for the entity ID can be used to

find all entities providing a specified attribute. For example, all entities whose ID starts with "Room" can be

discovered using the regex "Room.*". In this case, you have to set isPattern to "true".

ORION FI-LAB instance is configured to show only the first 20 hits of every query. In order to get more

results, the param “limit=X”, added to the REST call, will return X (maximum) hits. The param “details=0n”

will add to the response, the total hits the query returns. (“http://orion.lab.fi-

ware.org:1026/ngsi10/queryContext?limit=100&details=on” will return up to first 100 hits and the current

total available counts).

3.1.2.1 Discovering context availability

The ORION NGSI9 “discoverContextAvailability” implementation will provide a way to find context

attributes available within the current instance.

ORION Instance orion.lab.fi-ware.org:1026

POST /ngsi9/discoverContextAvailability

HEADERS

Content-type application/json

Accept application/json

X-Auth-Token 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg-VpfzNJWTcV7pMHF3iQRT

Payload:

{"entities":[ {"type":"Node", "isPattern":"true", "id":"Sensor_ID" } ], "attributes":["temperature"] }

Depending on the Payload, we can perform discovering processes like:

Retrieving all Santander available nodes that provide sound attribute:

Retrieving all available Santander nodes belonging to the luminous flux sensors (with all their available attributes):

{"entities":[ {"type":"", "isPattern":"true", "id":"urn:smartsantander:testbed.*"} ], "attributes":["sound"] }

{"entities":[ {"type":"santander:lux","isPattern":"true", "id":".*"} ] }

Get all IDs and available context from the nodes deployed for the first Santander Hackathon

{"entities":[ {"type":"", "isPattern":"true", "id":"HACKSANTANDER.*"} ] }

3.1.2.2 Requesting discovered context values

The ORION NGSI10 “queryContext” implementation provides a way to find current context status available,

retrieving the values of the selected attributes.

ORION Instance orion.lab.fi-ware.org:1026

POST /ngsi10/queryContext

HEADERS

Content-type application/json

Accept application/json

X-Auth-Token 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg-VpfzNJWTcV7pMHF3iQRT

Payload:

{"entities":[

{"type":"Node", "isPattern":"true", "id":"Sensor_ID" } ], "attributes":["temperature"] }

Following the same way described in “discoverContextAvailability” method, using the payload, we can

retrieve different context sets like:

Retrieving all sound context in Santander, including the sound value, the time when the measurement was taken and the location of the sensor:

Retrieving the last Reactive Power and Active Power reported by the Santander Advanced Metering Systems (AMMS):

{"entities":[ {"type":"santander:sound", "isPattern":"true", "id":".*"} ], "attributes":["TimeInstant", "sound", "Latitud", "Longitud"] }

{"entities":[ {"type":"", "isPattern":"true", "id":"AMMS.*" } ], "attributes":["TimeInstant", "ReactivePower", "ActivePower"] }

Get all IDs and available context from the nodes deployed for the first Santander Hackathon

{"entities":[ {"type":"", "isPattern":"true", "id":"HACKSANTANDER.*"} ] }

The requestor of this operation [queryContext] MAY specify restrictions on the returned Context

Information. Restrictions are based on the values of attributes and meta-data of the Context Information

and could be quite useful when a discover process is triggered. This restrictions are given within the

payload structure (more info about restrictions in the ORION users & programmers manual and in the OMA

NGSI9 documentation). Currently, ORION implements pre-defined restrictions scopes. The following

payload example (used with the “queryContext” resource) provides the context info of the entities within

100 meters (radius) of the given location, performing a discovering process and context retrieving of all

entities around “me”.

{"entities":[ {"type":"", "isPattern":"true", "id":".*" } all types and all entities ], "attributes":["position"], retrieving only position attribute value –remove to get all context info- "restriction": { "scopes": [ { "type" : "FIWARE_Location", type of restriction applied "value" : { "circle": { location circle definition "centerLatitude": "39.478056", "centerLongitude": "-0.407028", "radius": "100" in meters } } } ] } }

NOTE: When performing a request, you will get a “json” document retrieving its result. If there are no

matches, you will receive an error message "reasonPhrase": "No context element registrations found".

3.2 Subscriptions

Orion Context Broker provides the ability to subscribe to context information so when an event

(understanding an event as any change in available context information) happens, the subscribed

application will get an asynchronous notification. In that way, there is no need to continuously repeat

context requests (i.e. polling); Orion Context Broker will automatically report when new information comes.

Within NGSI and ORION environment, subscriptions are provided in two ways: notification will be sent

when any subscribed attribute value of a subscribed entity changes (context information subscription) or

when a new entity of a subscribed type (or with desired attributes) is created or modified (context

availability subscription).

3.2.1 Subscriptions payload

Subscription requests are implemented using HTTP POST methods, with a structured payload that contains

all data needed for ORION to create the kind of subscription requested. For all subscription types, ORION

uses the same payload structure:

{ "entities": [ { "type": " santander:sound", "isPattern": "false", "id": " urn:smartsantander:testbed:237" } ], "attributes": [ "sound" ], "reference": "http://localhost:1028/callback", "duration": "P1M", "notifyConditions": [ { "type": "ONTIMEINTERVAL", "condValues": [ "PT10S" ] } ] }

Entities and attributes define which context elements will be included in the notification message. They

work the same way as the elements with the same name in queryContext request. You can even include

lists or patterns to specify entities. In this example, we are specifying that the notification has to include the

“sound” attribute for entity “urn:smartsantander:testbed:237”.

The callback URL to send notifications is defined with the reference element. ORION will POST this URL with

the corresponding notification message. Only one reference can be included per subscribeContext request.

However, you can have several subscriptions on the same context elements.

Subscriptions have a duration, specified using the ISO 8601 standard format. Once that duration is expired,

the subscription is simply ignored (however, it is still stored in the broker database and needs to be

purged). You can extend the duration of a subscription by updating it. The example uses "P1M" which

means "one month".

The notifyCondition element defines the "trigger" for the subscription. There is a type element (which value

in this case is ONTIMERINTERVAL) and a condValueList element. The condValueList element structure

depends on the type. In the case of ONTIMEINTERVAL, it includes exactly one condValue child element

whose value is a time interval (using again, as usual in NGSI, the ISO 8601 format). A notification is sent

with a frequency equal to that interval. In the example above we are using 10 seconds as interval.

The response corresponding to that request contains a subscription ID (a 24 hexadecimal number used for

updating and cancelling the subscription) and a duration acknowledgement:

{ "subscribeResponse": { "duration": "P1M", "subscriptionId": "32a04c21d714fb3b38e9d5a7" } }

3.2.2 ORION notifications

Before describing the different subscription options currently available, just remark that, for all of them,

ORION will send a notification to the subscribed application: this is, ORION will POST the registered URL

(callback function) in the subscription payload a JSON (or xml) structure with the corresponding notification

info:

Notification for Context Info subscriptions Notification for Context availability subscriptions { "subscriptionId" : "51c0ac9ed714fb3b37d7d5a8", "originator" : "localhost", "contextResponses" : [ { "contextElement" : { "attributes" : [ { "name" : "TimeInstant", "type" : "urn:x-ogc:def:trs:IDAS:1.0:ISO8601", "value" : "2014-01-16T16:20:28.000000Z" }, { "name" : "sound", "type" : "urn:x-ogc:def:phenomenon:IDAS:1.0:sound", "value" : "69" }, { "name" : "Latitud", "type" : "urn:x-ogc:def:phenomenon:IDAS:1.0:latitude", "value" : "43.46433" }, { "name" : "Longitud", "type" : "urn:x-ogc:def:phenomenon:IDAS:1.0:longitude", "value" : "-3.79943" } ]

{ "subscriptionId" : "52a745e011f5816465943d59", "contextRegistrationResponses" : [{ "contextRegistration" : { "entities" : [ { "type" : "Sensor", "isPattern" : "false", "id" : "urn:smartsantander:testbed:237" } ], "attributes" : [ { "name" : "sound", "type" : "urn:x-ogc:def:phenomenon:IDAS:1.0:sound", "isDomain" : "false" } ], "providingApplication" : "http://0.0.0.0:1029" } } ]

"type" : " santander:sound ", "isPattern" : "false", "id" : " urn:smartsantander:testbed:471 " }, "statusCode" : { "code" : "200", "reasonPhrase" : "OK" } } ] } In both notifications, the subscriptionId element matches the one in the response to subscribeContext

request (explained below) and identifies the subscription sending the notification.

Notifications from Context information subscriptions includes the originator element (currently, is always

"localhost"), and the contextResponses element, which is the same than the one used in the queryContext

responses and contains all the attributes with their last values (or only those required in the corresponding

subscription request) belonging to the given entity id.

Notifications from Context availability subscriptions is mainly conformed by the

contextRegistrationResponses element, which is the same than the one used in the

discoverContextAvailability responses. This element provides all the entity info and attributes descriptions

(as given in the entity registration process), according to the subscription request performed. The

providingApplication element comes from an NGSI concept and represents the actual context information

provider (not relevant in Smart Santander open data set)

3.2.3 Context information subscriptions

Context Information deals with the current available attribute values of registered entities. In this line,

ORION implements the NGSI10 method subscribeContext that performs the following options on

subscriptions:

Periodical Subscription to an entity (element). You regularly receive an update about it as a whole

or about the attributes you specify. You can also indicate the duration and the interval of these

notifications. [ONTIMEINTERVAL].

Event-based Subscription to an entity. In this case, you only get a notification when the entity

changes any of the specified attributes value. You receive an update about it as a whole or about

the attributes you specify. You can only specify the duration of the subscription. [ONCHANGE].

There is also the possibility to subscribe to certain attributes without specifying the entities. You

will get an update when they change. This option is not currently supported in Orion 0.9.0.

Its name is subscribeContext – ONVALUE.

ORION Instance orion.lab.fi-ware.org:1026

POST /ngsi10/subscribeContext

HEADERS

Content-type application/json

Accept application/json

X-Auth-Token 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg-VpfzNJWTcV7pMHF3iQRT

Payload: [ONTIMEINTERVAL]

{"entities": [ {

"type": " santander:sound", we identify here the entity to subscribe to (patterns or lists can be added here if we "isPattern": "false", want to be subscribed to a set of entities "id": " urn:smartsantander:testbed:237" } ], "attributes": [ attribute (or list of attributes) value to be included in the notification "sound" ], "reference": "http://localhost:1028/callback", endpoint to be notified (HTTP POST will be used by ORION) "duration": "P1M", subscription lasts for… (in this example, 1 Month) "notifyConditions": [ { "type": "ONTIMEINTERVAL", Identifies the kind of subscription (ONTIMEINTERVAL, ONCHANGE, [ONVALUE]) "condValues": [ "PT10S" subs. Parameter (in the example, a notification will be sent every 10 seconds) ] } ] }

Payload: [ONCHANGE]

{"entities": [ { "type": " santander:sound", we identify here the entity to subscribe to (patterns or lists can be added here if we "isPattern": "false", want to be subscribed to a set of entities "id": " urn:smartsantander:testbed:237" } ], "attributes": [ attribute (or list of attributes) value to be included in the notification "sound", "TimeInstant" ], "reference": "http://localhost:1028/callback", endpoint to be notified (HTTP POST will be used by ORION) "duration": "P1M", subscription lasts for… (in this example, 1 Month) "notifyConditions": [ { "type": "ONCHANGE", Identifies the kind of subscription (ONTIMEINTERVAL, ONCHANGE, [ONVALUE]) "condValues": [ "sound" subs. Parameter (in the example, a notification will be sent when sound value changes) ] } ] }

The first payload example performs a subscription to entity “urn:smartsantander:testbed:237” in order to

get every 10 seconds (and during 1 month) its sound value . Using the second payload makes ORION to

produce a notification when the attribute sound changes, with sound and time values. If we use:

{"entities": [ { "type": " santander:sound", "isPattern": "true", "id": " urn:smartsantander:.*" } ] }

We will get notifications from all Santander deployed sound nodes.

This returns:

That includes the subscriptionId needed to identify the coming notifications, as well as to update or delete

the subscription.

3.2.3.1 Update Subscription

Subscriptions can be updated using the NGSI10 updateContextSubcription. The request includes the

subscriptionId that identifies the subscription to modify and the actual update payload. For example, if we

want to change the notification interval to 15 seconds we will use the following:

ORION Instance orion.lab.fi-ware.org:1026

POST /ngsi10/updateContextSubscription

HEADERS

Content-type application/json

Accept application/json

X-Auth-Token 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg-VpfzNJWTcV7pMHF3iQRT

Payload: [ONTIMEINTERVAL]

{ "subscriptionId": "54194e0c1860a30f3cf62c73", "notifyConditions": [ {

"type": "ONTIMEINTERVAL", "condValues": [ "PT15S" ] } ] }

3.2.3.2 Delete Subscription

A context information subscription can be cancelled using the ORION implemented NGSI10

unsubscribeContext method. It uses a payload including only the subscriptionId of the subscription to be

cancelled:

ORION Instance orion.lab.fi-ware.org:1026

POST /ngsi10/unsubscribeContext

HEADERS

Content-type application/json

Accept application/json

X-Auth-Token 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg-VpfzNJWTcV7pMHF3iQRT

Payload:

{ "subscriptionId": "54194e0c1860a30f3cf62c73" }

3.2.4 Context availability subscriptions

Context availability subscriptions are used when we want to be notified not about context information (i.e.

the values of attributes of some entities) but about the availability of the context sources themselves, this

is, when a new entity with desired attributes or from a selected type is created in ORION or an existing one

with the pointed characteristics is modified or deleted. The notification will inform about the new context

availability.

To perform this sort of subscriptions, ORION provides an implementation of NGSI9

subscribeContextAvailability method:

ORION Instance orion.lab.fi-ware.org:1026

POST /ngsi9/subscribeContextAvailability

HEADERS

Content-type application/json

Accept application/json

X-Auth-Token 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg-VpfzNJWTcV7pMHF3iQRT

Payload:

{"entities": [ { "type": "Sensor", we describe here the entities to subscribe to "isPattern": "true", "id": " urn:smartsantander:.*" } ], "attributes": [ attribute (or list of attributes) to be included in the notification "sound" ], "reference": "http://localhost:1028/callback", endpoint to be notified (HTTP POST will be used by ORION) "duration": "P1M" subscription lasts for… (in this example, 1 Month) }

The example payload performs a subscription to every entity from type “Sensor” deployed within

SmartSantander having “sound” attribute. The first notification will give the complete current set of entities

belonging to this group and, every time a new entity with these characteristics is created in ORION or a

previous one is modified, a new notification will be received by the “reference” function. According to the

payload structure, only “sound” attribute is of our interest.

This returns:

That includes the subscriptionId needed to identify the coming notifications, as well as to update or delete

the subscription.

3.2.4.1 Update context availability subscription

As with context subscriptions, context availability subscriptions can be updated using the ORION

implemented NGSI9 updateContextAvailabilitySubscription method. The request includes the

subscriptionId that identifies the subscription to modify, and the actual update payload.

ORION Instance orion.lab.fi-ware.org:1026

POST /ngsi10/updateContextAvailabilitySubscription

HEADERS

Content-type application/json

Accept application/json

X-Auth-Token 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg-VpfzNJWTcV7pMHF3iQRT

Payload:

{"entities": [ { "type": "santander:lux", "isPattern": "true", "id": ".*" } ], "duration": "P2M", "subscriptionId": "5419a2391860a30f3cf62c82", }

Example above changes the existing subscription to SmartSantander sound nodes to Luminous flux sensors,

also deployed within SmartSantander and including all attributes in the notification. It also sets its duration

to 2 months.

3.2.4.2 Delete Context availability subscription

A context information subscription can be cancelled using the ORION implemented NGSI9

unsubscribeContextAvailability method. It uses a payload including only the subscriptionId of the

subscription to be cancelled:

ORION Instance orion.lab.fi-ware.org:1026

POST /ngsi9/unsubscribeContextAvailability

HEADERS

Content-type application/json

Accept application/json

X-Auth-Token 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg-VpfzNJWTcV7pMHF3iQRT

Payload:

{ "subscriptionId": "5419a2391860a30f3cf62c82" }

4 Santander Open Data ORION provides the current context information (among other deployments) from the set of nodes

deployed in SmartSantander. Each one of these nodes, representing a context information source, is

presented as an entity, including an entity type (“type”) and an entity ID (“id”), used to classify the entities,

and a set of associated attributes that conform their context. According to this, the available

SmartSantander context information can be summarized as follows:

1º Entity name “ID”. A string always starting with "OUTSMART". It refers to the sensors located in

Parque de las Llamas.

Entity type. Possible values: Node, AMMS or Regulator.

Attribute name. It depends on the entity type:

Node: Entity ID: “OUTSMART.NODE_ID”

TimeInstant, Latitud, Longitud, Presence, batteryCharge, Illuminance.

AMMS: Entity ID: “OUTSMART.AMMS_ID”

TimeInstant, Latitud, Longitud, ActivePower, ReactivePower.

Regulator: Entity ID: “OUTSMART.RG_LAS_LLAMAS_ID”

TimeInstant, Latitud, Longitud, ActivePower, ReactivePower, electricPotential, elect

ricCurrent.

2º Entity name “ID”. A string always starting with "urn:smartsantander:testbed:ID". It refers to the

sensors located in the city of Santander. You can check them in this map.

Entity type. Possible values: santander:traffic, santander:sound and santander:lux.

Attribute name:

Traffic. Entity type: “santander:traffic”

TimeInstant

trafficIntensity. Number of vehicles traversing per minute the measurement point.

occupancy. The same than trafficIntensity, number of vehicles traversing per

minute the measurement point.

median_speed

average_speed

Latitud

Longitud

Sound. Entity type: “santander:sound”

TimeInstant

sound

batteryCharge

acceleration

Model

Latitud

Longitud

Lighting. Entity type: “santander:lux”:

TimeInstant

temperature

luminousFlux

batteryCharge

acceleration

Model

Latitud

Longitud