SmartSantander Open Data access using FI-WARE G.E. [ORION]

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 page 1 and the FI-WARE catalogue 2. 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 POST Content-type Payload: "auth": cloud.lab.fi-ware.org:4730 /v2.0/tokens "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 GET PARAMS orion.lab.fi-ware.org:1026 /ngsi9/contextentities Entity ID Attributes HEADERS Accept X-Auth-Token ID of the Requested Node (returns all node attributes): http://orion.lab.fi-ware.org:1026/ngsi9/contextentities/urn:smartsantander:testbed:357 Only required if user is interested in a specific attribute: http://orion.lab.fiware.org:1026/ngsi9/contextentities/urn:smartsantander:testbed:357/attributes/sound 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 GET PARAMS orion.lab.fi-ware.org:1026 /ngsi10/contextentities Entity ID Attributes ID of the Requested Node (returns all node attributes): http://orion.lab.fi-ware.org:1026/ngsi10/contextentities/urn:smartsantander:testbed:357 Only required if user is interested in a specific attribute: http://orion.lab.fiware.org:1026/ngsi10/contextentities/urn:smartsantander:testbed:357/attributes/sound

HEADERS Accept 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 POST HEADERS orion.lab.fi-ware.org:1026 /ngsi9/discovercontextavailability Content-type Accept X-Auth-Token Payload: "entities":[ "type":"node", "ispattern":"true", "id":"sensor_id" "attributes":["temperature" 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg- VpfzNJWTcV7pMHF3iQRT Depending on the Payload, we can perform discovering processes like: Retrieving all Santander available nodes that provide sound attribute: "entities":[ "type":"", "ispattern":"true", "id":"urn:smartsantander:testbed.*" "attributes":["sound" Get all IDs and available context from the nodes deployed for the first Santander Hackathon "entities":[ "type":"", "ispattern":"true", "id":"hacksantander.*" Retrieving all available Santander nodes belonging to the luminous flux sensors (with all their available attributes): "entities":[ "type":"santander:lux","ispattern":"true", "id":".*" 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 POST HEADERS Payload: "entities":[ orion.lab.fi-ware.org:1026 /ngsi10/querycontext Content-type Accept X-Auth-Token 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg- VpfzNJWTcV7pMHF3iQRT

"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: "entities":[ "type":"santander:sound", "ispattern":"true", "id":".*" "attributes":["timeinstant", "sound", "Latitud", "Longitud" Get all IDs and available context from the nodes deployed for the first Santander Hackathon "entities":[ "type":"", "ispattern":"true", "id":"hacksantander.*" Retrieving the last Reactive Power and Active Power reported by the Santander Advanced Metering Systems (AMMS): "entities":[ "type":"", "ispattern":"true", "id":"amms.*" "attributes":["timeinstant", "ReactivePower", "ActivePower" 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 "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" Notification for Context availability subscriptions "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 POST HEADERS orion.lab.fi-ware.org:1026 /ngsi10/subscribecontext Content-type Accept X-Auth-Token Payload: [ONTIMEINTERVAL "entities": [ 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg- VpfzNJWTcV7pMHF3iQRT

"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 POST HEADERS orion.lab.fi-ware.org:1026 /ngsi10/updatecontextsubscription Content-type Accept X-Auth-Token Payload: [ONTIMEINTERVAL "subscriptionid": "54194e0c1860a30f3cf62c73", "notifyconditions": [ 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg- VpfzNJWTcV7pMHF3iQRT

"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 POST HEADERS orion.lab.fi-ware.org:1026 /ngsi10/unsubscribecontext Content-type Accept X-Auth-Token Payload: "subscriptionid": "54194e0c1860a30f3cf62c73" 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg- VpfzNJWTcV7pMHF3iQRT 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 POST HEADERS orion.lab.fi-ware.org:1026 /ngsi9/subscribecontextavailability Content-type Accept 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 POST HEADERS orion.lab.fi-ware.org:1026 /ngsi10/updatecontextavailabilitysubscription Content-type Accept X-Auth-Token Payload: "entities": [ "type": "santander:lux", "ispattern": "true", "id": ".*" "duration": "P2M", "subscriptionid": "5419a2391860a30f3cf62c82", 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg- VpfzNJWTcV7pMHF3iQRT 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 POST HEADERS orion.lab.fi-ware.org:1026 /ngsi9/unsubscribecontextavailability Content-type Accept X-Auth-Token Payload: "subscriptionid": "5419a2391860a30f3cf62c82" 6-ZGLIvuOF0NDjzzGVDWjQS82i24mydGfyIsbgYN_OLZVTyndvRlKnuaP6PsROdOg- VpfzNJWTcV7pMHF3iQRT

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