DEVELOPMENT GUIDE

HOP Ubiquitous S.L.

www.hopu.eu

Luis Buñuel 6
30562
Ceutí, Murcia
Spain
Index
Homard API REST______________________________________ 2
Homard RESTFul API Examples_________________________ 6
URL Manager__________________________________________ 15
URL Manager RESTFul API____________________________ 16
URL Manager RESTFul API Examples__________________ 16
FIWARE Integration____________________________________ 19
Orion Context Broker NGSI RESTFul API_______________ 22
ANNEX 1: OMA LwM2M_______________________________ 52
 DEVELOPMENT GUIDE

Homard API REST

Homard offers in top of the OMA LwM2M1 server a internally. Therefore, non-external delays are
RESTFul services such as mechanism to communicate introduced and a very fast reply can be offered.
with the OMA LwM2M server. This HTTP/HTTPS API • Asynchronous API is required mainly for the data
RESTFul allows users to manage connected devices coming from the sensors (i.e. Smart Spot); since the
connected to the server. value will be available when the Smart Spot replies to
the request to Homard; delays can be introduced due
Homard shows connected devices, and manages each to issues such as communication latency (GPRS, WiFi
of them. Inherit from OMA, the devices expose a set etc. latency), sensors reading time (specially sensors
of objects/resources, which can contain one or more such as air quality which includes a processing time
instances, and each instance, contains the final resources. of few seconds), and finally due to duty cycle from
Some objects allow multiple instances (such as a Digital the Smart Spot in order to optimize energy (battery or
I/O Object, which represents the different digital inputs solar panels powered). For that reason, Asynchronous
and outputs from the Smart Spot, which can be used to API will requires a callback address to inform when
control relays, read external added digital sensors etc.) the value is available.
and others only one instance (such as Device Object).
Numbers are used to identify the tuple (Object ID / Information returned by the API is encapsulated
Instance ID / Resource ID). into a JSON data structure, since is the best way to
communicate with high level applications (commonly
There are two API types: Synchronous and Asynchronous: developed in Java, JavaScript and Android).
• Synchronous API provides the data as part of the
reply to a request in near-real time; it is used mainly More info in: https://homard.hopu.eu/indexPage/wiki.html
for data which is available in Homard platform

HTTP Path Method Description Result

[{client1},...
/api/rest GET Returns all OMA clients connected to HOMARD
{clientN}]
/api/rest/{endpoint_id} GET Returns the the client description for a {endpoint_id} {client}
/api/rest/{endpoint_id} /
Returns resource {resource} from client {endpoint_id} to [{resource1},...
{resource} ?proto={https|http} GET
destination callback URL {resourceN}]
&cburl={DESTINATION_URL}
/api/rest/{endpoint_id} / Changes value of the resource {resource} on client
{resource}?proto={http|https} PUT {endpoint_id}. Content type need to be application/JSON
&cburl={DESTINATION_URL} and in the request body {“id”: 2, “value”: new_value}
Sets observe on the resource {resource} and, when the
/api/rest/{endpoint_id} /
resource value is between ‘cbmin’ and ‘cbmax’, posts its
{resource}/co (Requires POST POST
value on ‘URL’. Note that if cbmin and cbmax are omitted
JSON payload)
then all values will be tracked.
/api/rest/{endpoint_id} /
DELETE Stops the monitoring on resource {resource}
{resource} /observe

1. OMA LwM2M protocol: Annex 1

2
 SMART SPOT

API-RESTFul
There are two API types synchronous and asynchronous, will send to a callback URL defined by the client. This API
on one hand it is synchronous API, that corresponds requires the HTTP basic authentication using a Homard
with Server request such as get the client list, get a client account.
specific data or list the observes set on a device. On the
other hand it is device request. The device requests are The following diagram shows the differences between
launched on background, this means that the response synchronous and asynchronous API.

User HTTP Client Homard

Synchronous request

Synchronous response

User Callback
User HTTP Client Homard
Client Server

Asynchronous request

Asynchronous response

This subsection will present the synchronous API and an example. The available synchronous API resources are as
follows:

HTTP Method Path Description

GET /api/rest/ Lists all connected clients with their current data
GET /api/rest/{endpoint_id} Get specific connected client data
/api/rest /cached /{endpoint_id} /
GET Read the resource cached value (last value)
{resource}
GET /api/rest/{endpoint_id}/co List client observes
/api/rest /{endpoint_id} /
POST Observes the selected resource and updates the internal cache.
{resource} /observe
/api/rest/{endpoint_id} /
DELETE Removes selected client observer
{resource_path} /observe
/api/rest/{endpoint_id} /
DELETE Removes selected client composite observer
{resource_path} /co /{coID

3
 DEVELOPMENT GUIDE

Cached Synchronous RESTFul API

Synchronous APIs are for requests which are directly resolved by Homard Server. Thereby, we get the last values cached
on the server directly, without any delay. At this way, Homard can be seen as a data broker.

HTTP Method Path Parameters Description

/api/rest /cached /{endpoint_id}
GET None Read the resource cached value
/{resource}

The API is very useful in special for applications that can not setup a HTTP server in its architecture. This synchronous
API can be outdated, to solve it, the user can enable a simple observer, which constantly updates the resource. In order
to create an internal observer to maintain the value updated for a specific resource is as follows:

HTTP Method Path Parameters Description

/api/rest /{endpoint_id} / Observes the selected resource and
POST None
{resource} /observe updates the internal cache

Asynchronous RESTFul API

This subsection present the asynchronous API and an execution example. The available asynchronous API resources
are as follows:

HTTP Method Path Parameters Description

cburl: Destination
/api/rest /{endpoint_id} / callback url Read the value and returns it to the
GET
{resource} proto: Destination destination callback url
callback url protocol
cburl: Destination
/api/rest /{endpoint_id} / callback url Write the value on resource and
PUT
{resource} proto: Destination returns the status to callback url
callback url protocol

4
 SMART SPOT

Historical Data RESTFul API

Homard offers in top of the OMA LwM2M server a temperature and humidity. In addition, sensor status and
RESTFul services such as mechanism to communicate maintenance parameters can be queried in order to know
with the OMA LwM2M server. This HTTP/HTTPS RESTFul if there are any problem with network connectivity.
API allow users to query the stored information such as

HTTP Path Method Description Result

[ { “name”: “HOPf4b85eab98de”,
Returns historic of OMA clients
/api/hist GET “cn”: “HopCore2” }, { “name”:
connected to HOMARD
“HOPf4b85eab98d6”, “cn”: “HopCore9” } ]
/api/hist/{endpoint_id}
[?from={timestamp}} [ { “eid”: “HOPf4b85eab98de”,
[&to={timestamp}] Returns all historic values of “temperature”: 27.36767578125,
GET
[&limit={max_records}] {enpoint_id} device. “humidity”: 45.654815673828125,
[&page={limited_page_ “date”: “Jun 21, 2016 2:10:36 PM” }, ... ]
requested}]
/api/hist/{endpoint_id} /
temp [?from={timestamp}] { values: [ 27.36767578125,
[&to={timestamp}] Returns temperature historic 27.96767578125, ... ], dates:[ “Jun 21,
GET
[&limit={max_records}] values of {enpoint_id} device. 2016 2:10:36 PM”, “Jun 21, 2016 2:10:37
[&page={limited_page_ PM”, “Jun 21, 2016 2:10:48 PM”, .... ] }
requested}]
/api/hist/{endpoint_id} /
hum [?from={timestamp}] { values: [ 27.36767578125,
[&to={timestamp}] Returns humidity historic values 27.96767578125, ... ], dates:[ “Jun 21,
GET
[&limit={max_records}] of {enpoint_id} device. 2016 2:10:36 PM”, “Jun 21, 2016 2:10:37
[&page={limited_page_ PM”, “Jun 21, 2016 2:10:48 PM”, .... ] }
requested}]
/api/hist/events /{endpoint_ [ { “name”: “HOPf4b85eab98de”,
id}/ [?from={timestamp}] “event”: “REGISTRATION”, “ts”: “Jun
Returns device events such as
[&to={timestamp}] 21, 2016 2:08:09 PM” }, { “name”:
GET when {enpoint_id} was registered,
[&limit={max_records}] “HOPf4b85eab98de”, “event”:
updated or deregistered.
[&page={limited_page_ “UPDATED”, “ts”: “Jun 21, 2016 2:08:56
requested}] PM” }, ... ]
/api/hist/events/
[ { “count”: 2, “event”: “DEREGISTRATION”
recount /{endpoint_id}/ Returns a count of {enpoint_id}
GET }, { “count”: 4, “event”: “REGISTRATION” },
[?from={timestamp}] events.
{ “count”: 841, “event”: “UPDATED” } ]
[&to={timestamp}]

5
 DEVELOPMENT GUIDE

Homard RESTFul API Examples

Synchronous RESTFul API Examples
List connected clients: GET /api/rest/

Query
GET /api/rest

Result

[ },
{ “objectId”:4
“endpoint”:”HOP-Sensor-Debug”, },
“registrationId”:”MTKt5ejSeu”, {
“registrationDate”:”2015-02-16T01:06:27+01:00”, “url”:”/5”,
“address”:”/127.0.0.1:54604”, “attributes”:{
“lwM2MmVersion”:”1.0”,
“lifetime”:120, },
“bindingMode”:”UQ”, “objectId”:5
“rootPath”:”/”, },
“objectLinks”:[ {
{ “url”:”/3201/0”,
“url”:”/1/0”, “attributes”:{
“attributes”:{
},
}, “objectId”:3201,
“objectId”:1, “objectInstanceId”:0
“objectInstanceId”:0 },
}, {
{ “url”:”/3201/1”,
“url”:”/3”, “attributes”:{
“attributes”:{
},
}, “objectId”:3201,
“objectId”:3 “objectInstanceId”:1
}, }
{ ]
“url”:”/4”, }
“attributes”:{ ]

6
 SMART SPOT

Get specific client: GET /api/rest/{endpoint_id}

Query
GET /api/rest/HOP-Sensor-Debug

Result

{ “objectId”:4
“endpoint”:”HOP-Sensor-Debug”, },
“registrationId”:”MTKt5ejSeu”, {
“registrationDate”:”2015-02-16T01:06:27+01:00”, “url”:”/5”,
“address”:”/127.0.0.1:54604”, “attributes”:{
“lwM2MmVersion”:”1.0”,
“lifetime”:120, },
“bindingMode”:”UQ”, “objectId”:5
“rootPath”:”/”, },
“objectLinks”:[ {
{ “url”:”/3201/0”,
“url”:”/1/0”, “attributes”:{
“attributes”:{
},
}, “objectId”:3201,
“objectId”:1, “objectInstanceId”:0
“objectInstanceId”:0 },
}, {
{ “url”:”/3201/1”,
“url”:”/3”, “attributes”:{
“attributes”:{
},
}, “objectId”:3201,
“objectId”:3 “objectInstanceId”:1
}, }
{ ]
“url”:”/4”, }
“attributes”:{

},

7
 DEVELOPMENT GUIDE

Get client observes: GET /api/rest/{endpoint_id}/co

Query
GET /api/rest/UBI8086f2759cbb/observes

Result

[ {
{ “field”: “value”,
“client”: “HOPf4b85eab962b”, “value”: “$value”
“path”: },
{ {
“objectId”: 3303, “field”: “r”,
“objectInstanceId”: 0, “value”: “$resource”
“resourceId”: 5700 },
}, {
“ocos”: “field”: “threshold”,
[ “value”: “$threshold”
{ }
“url”: “homard.hopu.eu:8090/co”, ],
“protocol”: “https://”, “id”: 1,
“threshold”: 0, “type”: 0,
“condition”: “>=”, “endpoint”: “HOPf4b85eab962b”,
“method”: “POST”, “path”: “/3303/0/5700”
“oneShot”: false, }
“outputFormat”: ]
[ }
{ ]
“field”: “sensor”,
“value”: “$eID”
},

Remove client observe: DELETE /api/rest/{endpoint_id}/{resource_path}/observe

Query
DELETE /api/rest/HOPf4b85eab9b03/3303/0/5700/observe

Result
HTTP Response 200 OK

8
 SMART SPOT

Asynchronous RESTFul API Examples

Read device resource: GET /api/rest/{endpoint_id}/{resource}

GET parameters:
• proto (mandatory): Determines the protocol to use • cbauthusr (optional): Used if the destination server
(HTTP or HTTPS). requires Basic authentication.
• cburl (mandatory): Determines the response • cbauthpass (optional): Used if the destination server
destination url. requires Basic authentication.

Read Device Resource Query

GET /api/rest/HOPf4b85eab9b03/1/0/5?proto=https&cburl=homard.hopu.eu:8090/co

Post Result on Callback Url

{“eid”:”HOPf4b85eab98de”,”url”:”/1/0/5”,”oID”:1,”iID”:0,”rID”:5,”type”:”INTEGER”,”value”:1}

Post Error on Callback Url

{“eid”:”HOPf4b85eab98de”, “operation”:”read”, “resource”:”/1/0/5”, “status”:”ERROR”}

Write device resource: PUT /api/rest/{endpoint_id}/{resource}

PUT parameters: proto (mandatory), cburl (mandatory), cbauthusr (optative), cbauthpass (optative).

Write Device Resource Query

PUT /api/rest/HOPf4b85eab9b03/1/0/5?proto=https&cburl=homard.hopu.eu:8090/co

Required Payload (Data to write)

{
“id”: 5,
“value”: 2
}

Post Result on Callback Url Post Error on Callback Url

{“eid”:”HOPf4b85eab98de”,”url”:”/1/0/5”,”oID”:1,”iID”:0, {“eid”:”HOPf4b85eab98de”, “operation”:”write”,

”rID”:5,”type”:”INTEGER”,”value”:1} “resource”:”/1/0/5”, “status”:”ERROR”}

9
 DEVELOPMENT GUIDE

Asynchronous API: Observers

Observation creation requires a specific POST payload. ◊ method: The method of the request, usually POST
This is a JSON object that contains the necessary ◊ durl: Destination URL where the observer will send
parameters. The necessary data to create an observer is the notifications
as follows: ◊ proto: Protocol to use (“https://” or “http://”)
• Observe resource: POST /api/rest/{endpoint_id/ ◊ authUsr: Destination URL Basic authentication
{resource}/co user (Optional)
• Payload: ◊ authPass: Destination URL Basic authentication
◊ threshold: Threshold value password (Optional)
◊ op: Operation condition (<=, >=, ...)
◊ typeShot: Type shot could be “repeat” or “oneshot” Also the JSON schema for this object is:

{ “type”: “string”
“$schema”: “http://json-schema.org/draft-04/ },
schema#”, “authUsr”: {
“id”: “http://jsonschema.net”, “id”: “http://jsonschema.net/authUsr”,
“type”: “object”, “type”: “string”
“properties”: { },
“threshold”: { “authPass”: {
“id”: “http://jsonschema.net/threshold”, “id”: “http://jsonschema.net/authPass”,
“type”: “string” “type”: “string”
}, }
“op”: { },
“id”: “http://jsonschema.net/op”, “required”: [
“type”: “string” “threshold”,
}, “op”,
“typeShot”: { “typeShot”,
“id”: “http://jsonschema.net/typeShot”, “method”,
“type”: “string” “durl”,
}, “proto”
“method”: { ]
“id”: “http://jsonschema.net/method”, }
“type”: “string”
},
“durl”: {
“id”: “http://jsonschema.net/durl”,
“type”: “string”
},
“proto”: {
“id”: “http://jsonschema.net/proto”,

10
 SMART SPOT

Example of request:

Create Observation
POST /api/rest/HOPf4b85eab9b3a/3303/0/5700/co

Required Payload
{
“threshold”: “0”,
“op”: “>=”,
“typeShot”:”repeat”,
“method”: “POST”,
“durl”:”homard.hopu.eu:8090/co”,
“proto”:”https://”,
“authUsr”: “”,
“authPass”: “”
}

Response Received
HTTP response 200

Notification Received on Callback Url

{“eid”:”HOPf4b85eab9b3a”,”url”:”3303/0/5700”,”oID”:3303,”iID”:0,”rID”:5700,”value”:”17.028683”}

Error Notification Received on Callback Url

{“eid”:”HOPf4b85eab9b3a”, “operation”:”observe”, “resource”:”/1/0/5”, “status”:”ERROR”}

11
 DEVELOPMENT GUIDE

Asynchronous API: Customizing observer notification message (integrating with third

party platform that requires a specific format)
Observation notifications have a standard output that attribute, It can be constant or variable. The allowed
can be formatted according to user needs. To achieve variable are the following:
this we must add a JSON array called “outputPacket” that • $eID: The Endpoint ID of the observed device.
contains the format of the notification packet. • $resource: The OMA LwM2M resource observed.
• $value: The observation value received.
This array contains field/value JSON objects This • $threshold: The observation threshold.
array contains one or more objects of type field/value • $condition: The observation condition.
({“field”:”NameFile”, “value”:”Variable or Constant”}). The
field “field” contains the attribute name of the notification For example if we want to receive the following
final object. The field “value” represents the value of that notification:

{“sensor”: “HOPf4b85eab9b3a”, “value”:15.32, “uuid”: “067e6162-3b6f-4ae2-a171-2470b63dff00”}

We have to set the following “outputPacket”:

{
...,
“outputPacket”:[
{“field”:”name”, “value”:”$eID”},
{“field”: “value”, “value”:”$value”},
{“field”: “uuid”, “value”:”067e6162-3b6f-4ae2-a171-2470b63dff00”}
]
}

12
 SMART SPOT

The JSON schema of the complete object is:

{ {
“$schema”: “http://json-schema.org/draft-04/schema#”, “id”: “http://jsonschema.net/outputPacket/0”,
“id”: “http://jsonschema.net”, “type”: “object”,
“type”: “object”, “properties”: {
“properties”: { “field”: {
“threshold”: { “id”: “http://jsonschema.net/outputPacket/0/field”,
“id”: “http://jsonschema.net/threshold”, “type”: “string”
“type”: “string” },
}, “value”: {
“op”: { “id”: “http://jsonschema.net/outputPacket/0/value”,
“id”: “http://jsonschema.net/op”, “type”: “string”
“type”: “string” }
}, }
“typeShot”: { },
“id”: “http://jsonschema.net/typeShot”, {
“type”: “string” “id”: “http://jsonschema.net/outputPacket/1”,
}, “type”: “object”,
“method”: { “properties”: {
“id”: “http://jsonschema.net/method”, “field”: {
“type”: “string” “id”: “http://jsonschema.net/outputPacket/1/field”,
}, “type”: “string”
“durl”: { },
“id”: “http://jsonschema.net/durl”, “value”: {
“type”: “string” “id”: “http://jsonschema.net/outputPacket/1/value”,
}, “type”: “string”
“proto”: { }
“id”: “http://jsonschema.net/proto”, }
“type”: “string” }
}, ]
“authUsr”: { }
“id”: “http://jsonschema.net/authUsr”, },
“type”: “string” “required”: [
}, “threshold”,
“authPass”: { “op”,
“id”: “http://jsonschema.net/authPass”, “typeShot”,
“type”: “string” “method”,
}, “durl”,
“outputPacket”: { “proto”
“id”: “http://jsonschema.net/outputPacket”, ]
“type”: “array”, }
“items”: [

13
 DEVELOPMENT GUIDE

Example of request:

Create Observation
POST /api/rest/HOPf4b85eab9b3a/3303/0/5700/observe

Required Payload
{
“threshold”: “0”,
“op”: “>=”,
“typeShot”:”repeat”,
“method”: “POST”,
“durl”:”homard.hopu.eu:8090/co”,
“proto”:”https://”,
“authUsr”: “”,
“authPass”: “”,
“outputPacket”:[
{“field”:”name”, “value”:”$eID”},
{“field”: “value”, “value”:”$value”}
]
}

Response Received
HTTP response 200

Notification Received on Callback Url

{“name”:”HOPf4b85eab9b03”,”value”:17.028683}

14
 SMART SPOT

URL Manager (Physical Web configuration for advertising URLs)

Device URL Manager is the key component of the to people around the Smart Spot for use cases such
Industrial Physical Web solution offered to provide as tourism, infortainment, accesibility, marketing, make
accessible and intuitive user interfaces. In details, the visible content or Webs available linked to a Physical
Device URL manager is used to administer the URL place, etc
broadcasted / transmitted by the devices; this URL can be
issued by BLE or Wi-Fi direct and must be coded with the Device URL Manager provides an Open Source Core2 for
Eddystone URL protocol1 from Google. users to be able to develop their own solutions which is
accessible through an API REST, which is developed in
Nowadays, there is more than 3 million Apps hosted python using Open Source frameworks such as Django
on Google Play, most of them are used a few times and Django REST Framework that provides to the
for their temporal or location context and later they developers an ecosystem that allows an easy extension
are forgotten wasting resources on mobile devices or of the system for introducing layers of security or
at best cases uninstalled. Google wants to solve this registration of devices.
problem through Physical Web, this technology will
allows service providers to interact with users depending
on the location, temporality context or directly with the
objects surrounding the user without the need of install User interface
any application on any device, These applications will be
developed as progressive webs and they will allow user
to feel that they are interacting with the real world through Web Interface
native applications, these applications are capable of
interacting directly with mobile device hardware or even
receiving notifications.
API REST
HOP Ubiquitous is a partner from Google for physical Security
Web, and a service for the creation of secure and
validated URLs is available in HPOI.info. Contact HOP
Ubiquitous team for more details. Identity Management
Core
Physical Web creates a communication channel
that connects the physical and virtual worlds using HOP Security
the Bluetooth Low Energy connection to send “push” Device Register
Interface
notifications to nearby Smartphones that are in their
range of action. This connection does not need any
tracker native app, only with Google Chrome installed and Object Security Device URL
with bluetooth switched on every user can interact with Server Manager Core
digital content directly in this physical point.

Thanks to technologies such as physical web and the

Device URL Manager, Smart Spot is able to broadcast 1. Eddystone Protocol: https://developers.google.com/beacons/eddystone
a URL with temporal and spatial context that will send 2. URL Manager: https://github.com/HOP-Ubiquitous/DeviceUrlManager

15
 DEVELOPMENT GUIDE

URL Manager RESTFul API

This tool is used for manage the physical web URL of any Manager, then the Device URL Manager will redirect the
device by software. request to the real uRL.

Smart PhoneS detect the Eddystone URL advertisement More information in the repository: https://github.com/
with a fixed device url that point to the Device URL HOP-Ubiquitous/DeviceUrlManager

URL Manager RESTFul API Examples

• Fixed device url (Request): https://hpoi.info/ • MAC address: is a normal mac without the two
AA00BB11DD22 dots. E.g: mac: 00:11:22:33:44:55 > shortened mac:
• Device Url Manager external device url (Response): 001122334455
https://google.es

Create device

URL Method URL Params Data Params Description

Type: application/json
Method to add a device with its
/api/v1/devices POST None body: { “mac”: “001122334455”, MAC and a target URL
“external_url”: “https://google.es/” }

Success Response Error Response

Code: 201 (Created) Code: 400 (Bad Request)
Content: { “mac”: “001122334455”, “external_url”: Content: { “bad_field_name”: [error causes] }
“https://google.es/” }

Sample Call
$.ajax({
url: “/api/v1/devices”,
dataType: “json”,
data: { “mac”: “001122334455”, “external_url”: “https://google.es/” },
type : “POST”,
success : function(r) {
console.log(r);
}
});

16
 SMART SPOT

Show Device Data

URL Method URL Params Data Params Description

/api/v1/devices/ shortened_ Method to show the device
GET None
:shortened_mac mac=[String] information

Success Response
Code: 200 (Ok)
Content: { “mac”: “001122334455”, “external_url”: “https://google.es/” }

Error Response
Code: 404 (Not Found)
Content: { “detail”: “Device Not Found” }

Sample Call
$.ajax({
url: “/api/v1/devices/001122334455”,
dataType: “json”,
type : “GET”,
success : function(r) {
console.log(r);
}
});

17
 DEVELOPMENT GUIDE

Update Device Data

URL Method URL Params Data Params Description

Type: application/json
/api/v1/devices/ Method to update the device
PUT None body: { “mac”: “001122334455”,
:shortened_mac information
“external_url”: “https://google.es/” }

Success Response
Code: 200 (Ok)
Content: { “mac”: “001122334455”, “external_url”: “https://google.es/” }

Error Response
Code: 404 (Not Found)
Content: { “detail”: “Device Not Found” }

Sample Call
$.ajax({
url: “/api/v1/devices/001122334455”,
dataType: “json”,
data: { “external_url”: “https://google.es/” },
type : “PUT”,
success : function(r) {
console.log(r);
}
});

18
 SMART SPOT

FIWARE Integration
FIWARE (www.fiware.org) in an open platform promoted FIWARE and the solutions from HOP Ubiquitous are
by the European Commision and maintained by the contributing to the creation of adapted and standardized
FIWARE Foundation, where HOP Ubiquitous is Gold solutions to satisfy the described process from the co-
Member. creation and citizens engagement to the deployment of
solutions based on IoT to reach the digitalization and
FIWARE offers an Open Ecosystem that join different enhancement of different areas in the city.
technology enablers for scalable data mangement and
make feasible to integrate different services and Internet Thanks to the LwM2M Bootstrap Server deployed and
of Things devices into a common and interoperable integrated in the Homard platform, it is really easy to
framework based on Open Standards. In particular, setup the server configuration for a the device. In this
FIWARE is based on Open Standards such as OMA way, anyone can deploy its own LwM2M IOTAgent with a
NGSI for the Services Interface and ETSI ISG CIM for the public server IP and configure the device to integrate it in
data models. HOP Ubiquitous is an active member and FIWARE.
contributor in ETSI ISG CIM and also an active contributor
in OMA; being one of pioneer and main companies A tutorial about Orion Context Broker has been
working around OMA LwM2M protocol. developed by FIWARE and HOP Ubiquitous, which can be
downloaded in: http://goo.gl/o1KXcT
In details, FIWARE has a strong role in the Smart Cities
market, since the is key to the growth and functionality
of Smart Cities, for this reason we are committed to
initiatives such as Open and Agile Smart Cities (OASC)
association with over 100 cities enrolled and FIWARE
technology as the basis for making it feasible.

Smart Spot is a FIWARE-ready device, it means that

Smart Spot has been validated, passed a set of tests,
participated in plugfests and the most important is
supporting the APIs, FIWARE data models based on ETSI
ISG CIM and it is fully interoperable and integrated with
key components from FIWARE such as Orion Context
Broker.

In details, Orion Context Broker is the core of FIWARE

platform; since it enables the common integration of
heterogenous data sources into a common component,
which enables the capacity to carry out advanced queries,
cross data among heterogenous domains (e.g., noise
with crowd, weather and mobility, etc.), and finally it can
exports data to several data analytics components such
as Hadoop / COSMOS (Big Data), SHT (Time Series),
CKAN (Open Data), MongoDB (Non-structured data), etc.

19
 DEVELOPMENT GUIDE

OMA LwM2M IoT Agent

OMA LwM2M is a device management protocol created In some scenarios, routers are transparent for the end-
by the Open Mobile alliance (OMA) which allows the devices such as cellular technologies, examples are:
remote manipulation of Internet of Things constrained GSM, SigFox, NarrowBand IoT or Wi-Fi Hallow, since they
devices. This complete protocol defines the procedures are already deployed by Telco’s. Others, such as Wi-Fi,
for provisioning, commissioning and management of a Bluetooth, 6LoWPAN and Z-Wave are provided individually
device through the definition of the resources exposed by with the devices. In HOP Ubiquitous our technology is
the device. mainly based on GSM and Bluetooth 4.0.

The functionality of LwM2M protocol is carried out The FIWARE Foundation counts with its own set of
through a set of basic objects such as “Server”, “Security”, services for the IOT. One of this kind of services is called
“Device”, “Statistics”... but there are also more specific FIWARE IOT Agent, and we can find one that is fully
objects defined by the IPSO Alliance which aims to compatible with our device architecture and connection
cover the need common definitions for sensors such as protocols. HOP Ubiquitous in collaboration with ATOS and
temperature, humidity, presence, etc. Or actuators such as Telefonica are maintaining the integration of OMA LwM2M
power/light/load control, buzzers, etc. protocol with FIWARE via the Orion Context Broker. It is
fully Open Source (URL al IoT Agent de HOPU en GitHub),
CoAP (Constrained Application Protocol) defines the and it counts with a simple deployment over FIWARE and
message header, request/response codes, message Linux-based platforms.
options and retransmission mechanisms, this protocol
together with UDP is used by LwM2M as a transport In addition, HOP Ubiquitous offers containers and Cloud-
mechanism. enabled services with the integration of FIWARE and
Orion Context Broker (including OMA LwM2M IoT Agent).
There are a large variety of topologies on the IoT but they Contact HOP Ubiquitous support team for more details.
have three common parts; devices, routers and backends.

Orion Context Broker

In The architecture, a service for context and information storage, sharing and consumption is needed, in the FIWARE
Architecture this is the Orion Context Broker. This service is the one in charge to connect with the OMA LwM2M IOT
Agent in order to collect data coming from the IOT devices. One of the most important features of the Context Broker
is that it allows to model and gain access to context information in a way that is independent from the source of that
information. It uses a non-relational database (Mongodb) to store all the data, and counts with an easy to use REST API
with makes data accessible.

Cygnus FIWARE architecture

This is the FIWARE Service in charge of persisting data. It Taking the previous two components into account the
is based on Apache Flume, Cygnus offers as a data bus FIWARE IoT platform is composed, in the following lines
the interconnection with several data sources and data the deployment of every service and the integration with
platforms such as Hadoop, CKAN, STH Comet etc. the HOP Ubiquitous Smart Spot is described.

20
 SMART SPOT
Store Aggregated Data
STH Comet

Notify with data received

Store Raw Data

Cygnus

Sends event based on subscription

Store Subscriptions
Subscription Cygnus Orion Context Broker

NGSI Interface

Store Device Mapping

IoT Agent

OMA LwM2M

Deployment and integration with FIWARE

A previous setting up is needed before things can be • Prepare The orion context broker infrastructure:
switched on, taking into account the following steps. We 1. Launch a mongoDB instance for the IoTAgent
will assume that the user has a basic knowledge about with external port 1026.
DOCKER and LINUX CMD. 2. Launch a ORION Context Broker instance.

• Get and configure the Hopu modified FiWARE Docker makes really simple the previous steps.
IOTAgent:
1. git clone https://github.com/HOP-Ubiquitous/ • Make sure that the Smart Spot knows where is the
lightweightm2m-iotagent/tree/hopu IoTAgent to connect with:
2. change the file content for confi g.js, 1. Notify The Smart Spot about the IOTAgent IP with
omaRegistry.json and omaInverseRegistry. the bootstrap procedure.
json in order to set up our device configuration to
connect with. • Rock & Roll:
3. execute: npm install 1. Change directory (cd) to the IOTAgent one and
4. Launch a mongoDB instance for the IOTAgent execute ./bin/lwm2mAgent.js
with external port 7900. 2. Turn on the Smart Spot

21
 DEVELOPMENT GUIDE

Orion Context Broker NGSI RESTFul API

Orion is a C++ implementation of the NGSIv2 REST API availability. Using the Orion Context Broker, you are able
binding developed as a part of the FIWARE platform. to create context elements and manage them through
updates and queries. In addition, you can subscribe to
Orion Context Broker allows you to manage the entire context information so when some condition occurs
lifecycle of context information including updates, queries, (e.g. the context elements have changed) you receive a
registrations and subscriptions. It is an NGSIv2 server notification. These usage scenarios and the Orion Context
implementation to manage context information and its Broker features are described in this documentation.

Create entity v2

URL Method URL Params Definition

Url: Link to the service that will be
consulted. Method to put an entity in
http://{{url}}:{{port-orion}}/v2/entities POST
Port-orion: Port to connect with the a service.
service.

Body Example of Body

{ {
id:”Entity ID”, id:”Room7”,
type:”Entity type”, type:”Room”,
“attributeID0”: { “temperature”: {
value:”Attribute value”, value: 23,
type:”Attribute type” type: ”Float”
}, },
“attributeID1”: { “preassure”: {
value:”Attribute value”, value: 720,
type:”Attribute type” type: ”Integer”
},... },...
} }

Return
Returns an error message, if already exists an entity in the service with the same id.

22
 SMART SPOT

Retrieve entity v2

URL Method URL Params Definition

Url: Link to the service that will be consulted.
http://{{url}}:{{port-orion}}/v2/ Port-orion: port to connect with the service. Method to retrieve an
GET
entities/{{fiware-entity}} Fiware-entity: ID of the entity which will be entity of a service.
retrieved from the service.

Return
If the search has been successful then it returns the information else it returns an message error.

Retrieve entity as data model v2

URL Method URL Params Definition

Url: Link to the service that will be consulted.
http://{{url}}:{{port-orion}}/
Port-orion: Port to connect with the service. Method to obtain an entity
v2/entities/{{fiware- GET
Fiware-entity: ID of the entity which will be of a service.
entity}}?options=keyValues
retrieved from the service.

Return
If the search has been successful then it returns the information of compressed way else returns an error message.

Retrieve entities v2

URL Method URL Params Definition

http://{{url}}:{{port-orion}}/v2/ Url: Link to the service that will be consulted. Method to retrieve all
GET
entities?limit=50 Port-orion: Port to connect with the service. entities.

Return
All entities of the service and for each entity shows their information

23
 DEVELOPMENT GUIDE

Retrieve entities as data model v2

URL Method URL Params Definition

http://{{url}}:{{port-orion}}/ Url: Link to the service that will be consulted. Method to retrieve all
v2/ entities?options= GET
Port-orion: port to connect with the service. entities of a service.
keyValues&limit=50

Return
All entities of the service and for each entity shows their information of compressed way.

Update entity v2

URL Method URL Params Definition

Url: Link to the service that will be
consulted.
http://{{url}}:{{port-orion}}/v2/entities/ Port-orion: Port to connect with the Method to update some
PATCH
{{fiware-entity}}/attrs service. attributes of the entity.
Fiware-entity: id of the entity where
their attributes will be updated.

Body Example of Body

{ {
“attributeID”:{ “temperature”: {
value:”Attribute value”, “value”: 26.5,
type:”Attribute type” “type”: “Float”
} },
} “pressure”: {
“value”: 763,
“type”: “Float”
}
}

24
 SMART SPOT

Delete entity v2

URL Method URL Params Definition

Url: Link to the service that will be consulted.
http://{{url}}:{{port-orion}}/v2/ Port-orion: Port to connect with the service. Method to delete an entity
DELETE
entities/{{fiware-entity}} Fiware-entity: ID of the entity which will be of a service.
deleted.

Create attribute for entity v2

URL Method URL Params Definition

Url: Link to the service that will be consulted.
http://{{url}}:{{port-orion}}/
Port-orion: Port to connect with the service. Method to add a new
v2/entities/{{fiware-entity}}/ POST
Fiware-entity: ID of the entity which will attribute to the entity.
attrs/
have new attributes.

Body Example of Body

{ {
“attributeID”:{ “temperature”: {
value:”Attribute value”, “value”: 26.5,
type:”Attribute type” “type”: “Float”
} },
} }
Retrieve entity attribute v2

URL Method URL Params Definition

Url: Link to the service that will be consulted.
http://{{url}}:{{port-orion}}/ Port-orion: Port to connect with the service.
Method to retrieve an
v2/entities/{{fiware-entity}}/ GET Fiware-entity: ID of the entity where is the attribute of an entity.
attrs/{{fiware-attr}} attribute.
Fiware-attr: ID of the attribute.

Return
If the search has been successful then the attribute is retrieved and shows their information else an error message is
returned

25
 DEVELOPMENT GUIDE

Retrieve entity attribute as data model v2

URL Method URL Params Definition

Url: Link to the service that will be consulted.
http://{{url}}:{{port-orion}}/ Port-orion: Port to connect with the service.
Method to retrieve an
v2/entities/{{fiware- GET Fiware-entity: ID of the entity where is the attribute of an entity.
entity}}?options=keyValues attribute.
Fiware-attr: ID of the attribute.

Return
If the search has been successful then the attribute is retrieved and shows their information, else it returns a message
error.

Delete attribute for entity v2

URL Method URL Params Definition

Url: Link to the service that will be
consulted.
Port-orion: Port to connect with the
http://{{url}}:{{port-orion}}/v2/entities/ service. Method to delete an
DELETE
{{fiware-entity}}/attrs/{{fiware-attr}} Fiware-entity: ID of the entity which attribute of an entity.
will delete attributes.
Fiware-attr: ID of the attribute which
will delete.
Retrieve type v2

URL Method URL Params Definition

Url: Link to the service that will be consulted.
http://{{url}}:{{port-orion}}/v2/ Port-orion: Port to connect with the service. Method to retrieve an
GET
types/{{fiware-service}} Fiware-service: ID of type of the entity which entity type of the service.
will be searched in the service.

Return
If the search has been successful then type is retrieved and shows all their information, else an error message is
returned

26
 SMART SPOT

Retrieve types v2

URL Method URL Params Definition

http://{{url}}:{{port-orion}}/v2/ Url: Link to the service that will be consulted. The different entity types
GET in the service and their
types Port-orion: port to connect with the service. information.

Create subscription v2

URL Method URL Params Definition

http://{{url}}:{{port-orion}}/v2/ Url: Link to the service that will be consulted. Method to create a
POST subscription to one or
subscriptions Port-orion: Port to connect with the service. many entities

Body

{ }
“description”: “Definition of the subscription”, },
“subject”: { “notification”: {
“entinties”: [ “http”: {
{ “url”: “http://localhost:1028/accumulate”
“id”: “Room1” },
“type: “Room” “attrs”: [
} “temperature”
], ]
“condition”: { },
“attrs”: [ “expires”: “2040-01-01T14:00:00.00Z”,
“pressure” “throttling”: “5”
] }

• Condition: It defines the “trigger” for the subscription.

• Url: URL where to send notifications
• Throttling: It is used to specify a minimum inter-notification
arrival time.
• Notification.attr: Attributes which you will received in a
notification when “condition.attr” changes.

27
 DEVELOPMENT GUIDE

Retrieve subcriptions v2

URL Method URL Params Definition

http://{{url}}:{{port-orion}}/v2/ Url: Link to the service that will be consulted. Method to retrieve all
GET
subscriptions Port-orion: Port to connect with the service. subscriptions of a service.

Return
All existing subscriptions of the service and for each subscription show their information.

Remove subscription v2

URL Method URL Params Definition

Url: Link to the service that will be consulted
http://{{url}}:{{port-orion}}/
Port-orion: Port to connect with the service. Method to delete a
v2/subscriptions/{{fiware- DELETE
Fiware-subscription: ID of the subscription subscription of a service
subscription}}
will be deleted.

28
 SMART SPOT

Create context entity v1

URL Method URL Params Definition

http://{{url}}:{{port-orion}}/v1/ Url: Link to the service that will be consulted. Method to create a context
POST of entity, an entity without
registry/registerContext Port-orion: Port to connect with the service. values.

Body

{ “name”: “nombre_atributo”,
“contextRegistrations”: [ “type”: “attribute_type”,
{ “isDomain”: “false”
“entities”: [ }
{ ],
“type”: “entity_type”, “providingApplication”: “http://homard.hopu.
“isPattern”: “false”, eu:1026/v2/entities”
“id”: “entity_id” }
} ],
], “duration”: “P1M”
“attributes”: [ }
{

• isPattern: Nowadays, it is not being used. Threfore, value is

always “false”.
• isDomain: The attribute domains aren’t supported. Always
‘false’.
• providingApplication: The URL that represents the context
information of the registered entities and attributes.
• duration: The duration of the element. In ISO 8601 standard
format.

Return

Returns a confirmation that the item has been created correctly

{
“duration”: “P1M”,
“registrationId”: “5a79812d777fc523840b8446”
}

29
 DEVELOPMENT GUIDE

Retrieve context entity v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port- Method to retrieve a context of entity,
be consulted.
orion}}/v1/registry/ POST an entity without values, depends on
Port-orion: Port to connect with
discoverContextAvailability ID and type.
the service.

Body Return

{ In case of finding this element, it returns the information.

“entities”: [ In case of not finding this element, it returns a 404 error “No
{ context element found”.
“type”: “entity_type”,
“isPattern”: “false”,
“id”: “entity_id”
}
]
}

• isPattern: Nowadays, it is not being used. Threfore, value is

always “false”.

30
 SMART SPOT

Create/update entity v1

URL Method URL Params Definition

http://{{url}}:{{port-orion}}/v1/ Url: Link to the service that will be consulted. Method to create or update
POST an entity, depends on
updateContext Port-orion: Port to connect with the service. method’s body.

Body (creation) Body (updating)

{ {
“contextElements”: [ “contextElements”: [
{ {
“type”: “entity_type”, “type”: “entity_type”,
“isPattern”: “false”, “isPattern”: “false”,
“id”: “entity_id “, “id”: “entity_id “,
“attributes”: [ “attributes”: [
{ {
“name”:”attribute_id “, “name”:”attribute_id”,
“type”: “attribute_type”, “type”: “attribute_type”,
“value”: “attribute_value” “value”: “attribute_value”
} }
] ]
} }
], ],
“updateAction”: “APPEND” “updateAction”: “UPDATE”
} }

• isPattern: Nowadays, it is not being used. Threfore, value is always “false”.

• updateAction: Action to be carried out (“APPEND” or “UPDATE”). In case of “APPEND” creates the entity, if else “UPDATE”
updatdes the entity

Return

In case of performing the method correctly, it return 200 OK together with the information of the entity.
In UPDATE, in case of not find that entity, it return a 404 ERROR “No context element found”.

31
 DEVELOPMENT GUIDE

Create entity v1

URL Method URL Params Definition

Url: Link to the service that will
be consulted.
http://{{url}}:{{port-orion}}/
Port-orion: Port to connect with
v1/contextEntities/{{fiware- POST Method to create a new entity
the service.
entity}}
Fiware-entity: ID of the entity
that will be create of the service.

Body Return

{ In case of performing the method correctly, it return 200 OK

“type”: “entity_type”, together with the information of the new entity.
“attributes”: [
{
“name”: “attribute_id”,
“type”: “attribute_type”,
“value”: “attribute_value”
}
]
}

Retrieve entity standard v1

URL Method URL Params Definition

Url: Link to the service that will
be consulted.
http://{{url}}:{{port-orion}}/
Port-orion: Port to connect with Method that return a defined entity
v1/contextEntities/{{fiware- GET
the service. passed as parameter.
entity}}
Fiware-entity: ID of the entity
that will be create of the service.

Return

In case of performing the method correctly, it return 200 OK together with the information of the entity.
In case of not find that entity, it return a 404 ERROR “No context element found”.

32
 SMART SPOT

Retrieve entity as object standard v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port- be consulted.
orion}}/v1/registry/
Port-orion: Port to connect with Method that return a defined entity
contextEntities/{{fiware- GET
the service. with object JSON format.
type}}?attributeFormat
=object Fiware-entity: ID of the entity
that will be create of the service.

Return

In case of performing the method correctly, it returns 200 OK together with the information of the entity with object JSON format.
In case of not find that entity, it return a 404 ERROR “No context element found”.

Retrieve entity convenience v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/v1/ be consulted. Method that returns a defined entity
POST
queryContext Port-orion: Port to connect with passed in the body of the method.
the service.

Body Return

{ In case of performing the method correctly, it returns 200 OK

“entities”: [ together with the information of the entity.
{ In UPDATE, in case of not finding that entity, it returns a 404
“type”: “entity_type”, ERROR “No context element found”.
“isPattern”: “false”,
“id”: “entity_id”
}
]
}

33
 DEVELOPMENT GUIDE

Retrieve entity as object convenience v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port- Method that return a defined entity
be consulted.
orion}}/v1/queryContext? POST with object JSON format. The entity ID
Port-orion: Port to connect with
attributeFormat=object is passed in the body of method.
the service.

Body Return

{ In case of performing the method correctly, it returns 200 OK

“entities”: [ together with the information of the entity with object JSON
{ format.
“type”: “entity_type”, In UPDATE, in case of not finding that entity, it returns a 404
“isPattern”: “false”, ERROR “No context element found”.
“id”: “entity_id”
}
]
}

Retrieve entities v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/v1/ be consulted.
GET Method that return all entities.
contextEntities Port-orion: Port to connect with
the service.

Return

Show all existing entities.

34
 SMART SPOT

Retrieve entities as object v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/ be consulted. Method that return all entities with
v1/cont extEntities? GET
Port-orion: Port to connect with object JSON format.
attributeFormat=object
the service.

Return

Show all existing entities with object JSON format.

Retrieve entities for type v1

URL Method URL Params Definition

Url: Link to the service that will
be consulted.
http://{{url}}:{{port-orion}}/v1/
Port-orion: Port to connect with Method that returns all entities of a
registry/contextEntityTypes/ GET
the service. concrete type.
{{fiware-type}}
Fiware-type: Type of entities that
we want to receive.

Return

In case of performing the method correctly, it returns 200 OK together with the information of the all entities of this type.
In UPDATE, in case of not finding that entity, it returns a 404 ERROR “No context element found”.

35
 DEVELOPMENT GUIDE

Retrieve entities for type as object v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/v1/ be consulted.
Method that return all entities of
registry/contextEntityTypes/ Port-orion: Port to connect with
GET a concrete type with object JSON
{{fiware-type}} the service.
format.
?attributeFormat=object Fiware-type: Type of entities that
we want to receive.

Return

In case of performing the method correctly, it returns 200 OK together with the information of the all entities of this type with object
JSON format.
In UPDATE, in case of not finding that entity, it returns a 404 ERROR “No context element found”.

Delete entity v1

URL Method URL Params Definition

Url: Link to the service that will
be consulted.
http://{{url}}:{{port-orion}}/
Port-orion: Port to connect with
v1/contextEntities/{{fiware- DELETE Method to delete a defined entity.
the service.
entity}}
Fiware-entity: ID of the entity we
want to delete.

Return

In case of performing the method correctly and delete the entity defined, it returns 200 OK .
In case of not finding that entity, it returns a 404 ERROR “No context element found”.

36
 SMART SPOT

Create/update entity attribute v1

URL Method URL Params Definition

Url: Link to the service that will
be consulted.
Method to update the values of one
http://{{url}}:{{port-orion}}/ Port-orion: Port to connect with
or many attributes of an entity passed
v1/contextEntities/{{fiware- POST the service.
as parameter. In addition, this method
entity}}/attributes Fiware-entity: ID of the entity can create new attributes for an entity.
that will be created of the
service.

Body (creation) Body (updating)

Create a new attribute. We transmit a new attribute in the body: Update an attribute. We transmit an existing/available attribute
with a new value.
{
“attributes”: [ {
{ “attributes”: [
“name”: “attribute_id”, {
“type”: “attribute_type”, “name”: “attribute_id_nuevo”,
“value”: “attribute_value” “type”: “attribute_type_nuevo”,
} “value”: “attribute_value_nuevo”
] }
} ]
}

Return

In case of performing the method correctly, it returns 200 OK together with the information of the entity updating.
In case of not finding that entity, it returns a 404 ERROR “No context element found”.

37
 DEVELOPMENT GUIDE

Retrieve entity attribute v1

URL Method URL Params Definition

Url: Link to the service that will
be consulted.
Port-orion: Port to connect with
http://{{url}}:{{port-orion}}/ the service. Method that retrieves the defined
v1/contextEntities/{{fiware-
GET Fiware-entity: ID of the entity attribute depending on the ID of a
entity}}/attributes/{{fiware-
that will be retrieved of the specific entity.
attr}}
service.
Fiware-attr: Attribute ID we want
to receive.

Return

In case of performing the method correctly, it returns 200 OK together the attribute value defining by its ID for a specific entity.
In case of not finding that entity or attribute, it returns 404 ERROR “No context element found”.
In UPDATE, in case of not finding that entity, it returns a 404 ERROR “No context element found”.

Delete entity attribute as object v1

URL Method URL Params Definition

Url: Link to the service that will
be consulted.
Port-orion: Port to connect with
http://{{url}}:{{port-orion}}/ Method that retrieves the defined
the service.
v1/contextEntities/{{fiware- attribute depending on the ID of a
GET Fiware-entity: ID of the entity
entity}}/attributes/{{fiware- specific entity with object JSON
that will be retrieved of the
attr}}?attributeFormat=object format.
service.
Fiware-attr: Attribute ID we want
to receive.

Return

In case of performing the method correctly, it returns 200 OK together the attribute value defined by its ID for a specific entity with
object JSON format.
In case of not finding that entity or attribute, it returns 404 ERROR “No context element found”.

38
 SMART SPOT

Retrieve entities attribute for type v1

URL Method URL Params Definition

Url: Link to the service that will
be consulted.
http://{{url}}:{{port-orion}}/v1/ Port-orion: Port to connect with
Method that returns the defined
registry/contextEntityTypes/ the service.
GET attribute of all entities of a specific
{{fiware-type}}/attributes/ Fiware-type: Type of entities that type.
{{fiware-attr}} we want to receive.
Fiware-attr: Attribute of type of
entities that we want to receive.

Return

In case of performing the method correctly, it returns 200 OK together with the information of defined attributes of all entities of this
type.
In UPDATE, in case of not finding that entity, it returns a 404 ERROR “No context element found”.

Retrieve entities attribute for types as object v1

URL Method URL Params Definition

Url: Link to the service that will
be consulted.
http://{{url}}:{{port- Port-orion: Port to connect with
orion}}/v1/registry/ Method that returns the defined
the service.
contextEntityTypes/{{fiware- GET attribute of all entities of a specific
Fiware-type: Type of entities that type with object JSON format.
type}}/attributes/{{fiware-
we want to receive.
attr}}?attributeFormat=object
Fiware-attr: Attribute of type of
entities that we want to receive.

Return

In case of performing the method correctly, it returns 200 OK together with the information of defined attributes of all entities of this
type with object JSON format.
In UPDATE, in case of not finding that entity, it returns a 404 ERROR “No context element found”.

39
 DEVELOPMENT GUIDE

Delete entity attribute v1

URL Method URL Params Definition

Url: Link to the service that will
be consulted.
Port-orion: Port to connect with
http://{{url}}:{{port-orion}}/ the service. Method to delete the defined attribute
v1/contextEntities/{{fiware-
DELETE Fiware-entity: ID of the entity depending on the ID of a concrete
entity}}/attributes/{{fiware-
that will be retrieve of the entity.
attr}}
service.
Fiware-attr: Attribute ID we want
to receive.

Return

In case of performing the method correctly and delete the entity defined, it returns 200 OK.
In case of not finding that entity or attribute, it returns 404 ERROR “No context element found”.

Retrieve type v1

URL Method URL Params Definition

Url: Link to the service that will
be consulted.
http://{{url}}:{{port-orion}}/v1/ Port-orion: Port to connect with Method to receive an entity type
GET
contextTypes/{{fiware-type}} the service. concrete.
Fiware-type: Type of entities that
we want to receive.

Return

In case of performing the method correctly, it returns 200 OK together the information of this entities type.
In case of not finding that entities type, it returns 404 ERROR “No context element found”.

40
 SMART SPOT

Retrieve types v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/v1/ be consulted. Method to receive the existing entities
GET
contextTypes Port-orion: Port to connect with types.
the service.

Return

In case of performing the method correctly, it returns 200 OK together the information of all entities type.
In case of not finding that entities type, it returns 404 ERROR “No context element found”.

Create context subscription standard v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/v1/ be consulted. Method to create a subscription to one
POST
subscribeContextAvailability Port-orion: Port to connect with or many context entities.
the service.

Body

{ “reference”: “http://cygnus:5050/notify”,
“entities”: [ “duration”: “P1M”
{ }
“type”: “id_entity_type”,
“isPattern”: “false”, • isPattern: Nowadays, it is not being used. Threfore, value is
“id”: “.*” always “false”.
} • id: To which entity it wants to subscribe. In this case, to all
], entities of those type.
“attributes”: [ • reference: URL of client that it want to subscribe.
“id_attribute” • duration: The duration of the subscription. In ISO 8601
], standard format..

Return

{
“subscriptionId”: “subscription_id”,
“duration”: “P1M”
}
41
 DEVELOPMENT GUIDE

Create context subscription convenience v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port- be consulted. Method to create a subscription to one
orion}}/v1/context POST
Port-orion: Port to connect with or many context entities.
AvailabilitySubscriptions
the service.

Body

{ “reference”: “http://cygnus:5050/notify”,
“entities”: [ “duration”: “P1M”
{ }
“type”: “id_entity_type”,
“isPattern”: “false”,
“id”: “.*” • isPattern: Nowadays, it is not being used. Threfore, value is
} always “false”.
], • id: To which entity it wants to subscribe. In this case, to all
“attributes”: [ entities of those type.
“id_attribute” • reference: URL of client that it want to subscribe.
], • duration: The duration of the subscription. In ISO 8601
standard format..

Return

{
“subscriptionId”: “subscription_id”,
“duration”: “P1M”
}

42
 SMART SPOT

Update context subscription standard v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/ be consulted. Method to update a subscription of a
v1/updateContext POST
Port-orion: Port to connect with context entity.
AvailabilitySubscriptions
the service.

Body Return

{ {
“entities”: [ “subscribeResponse”: {
{ “subscriptionId”: “id_subscription”,
“type”: “id_entity_type”, “id_parameter”: “value_parameter”
“isPattern”: “false”, }
“id”: “.*” }
}
],
“duration”: “P1M”
“subscriptionId”: “subscription_id”
}

43
 DEVELOPMENT GUIDE

Update context subscription convenience v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/ be consulted.
v1/registry/context Port-orion: Port to connect with Method to update a subscription of a
PUT
AvailabilitySubscriptions/ the service. context entity.
{{fiware-subscription}} Fiware-subscription: ID de la
suscripción a actualizar.

Body Return

{ {
“entities”: [ “subscribeResponse”: {
{ “subscriptionId”: “id_subscription”,
“type”: “id_entity_type”, “id_parameter”: “value_parameter”
“isPattern”: “false”, }
“id”: “.*” }
}
],
“duration”: “P1M”
“subscriptionId”: “subscription_id”
}

44
 SMART SPOT

Delete context subscription standard v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/v1/ be consulted. Method to delete a subscription of a
POST
unsuscribeContextAvailability Port-orion: Port to connect with context entity.
the service.

Body Return

{ In case of performing the method correctly and delete the

“subscriptionId”: “5a785788777fc523840b843e” entity defined, it returns 200 OK together with the removed
} subscription ID.
In case of not finding that subscription, it returns 404 ERROR
“No context element found”.

Delete context subscription convenience v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port- be consulted.
orion}}/v1/context Port-orion: Port to connect with Method to delete a subscription of a
POST
AvailabilitySubscriptions/ the service. context entity.
{{fiware-subscription}} Fiware-subscription: ID of
subscription to remove.

Return
In case of performing the method correctly and delete the entity defined, it returns 200 OK together with the removed subscription ID.
In case of not finding that subscription, it returns 404 ERROR “No context element found”.

45
 DEVELOPMENT GUIDE

Create subscription standard v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/v1/ be consulted. Method to create a subscription to one
POST
suscribeContext Port-orion: Port to connect with or many entities.
the service.

Body

{ • isPattern: Currently is hasn’t use. Always ‘false’.

“entities”: [ • id: To which entity it wants to subscribe. In this case, to all
{ entities of those type.
“type”: “entity_type”, • reference: URL of client that it want to subscribe.
“isPattern”: “false”, • duration: The duration of the subscription. In ISO 8601
“id”: “.*” standard format.
} • notifyConditions: Define the launcher to notify the
], subscriptions. In this case, when change a value of
“attributes”: [ attributes transmitted via the “condValues” of an entity ,then
“attribute_id” it will trigger a notification.
], • throttling: Specify a minimum inter-notification arrival time.
“reference”: “http://cygnus:5050/notify”, In this case, 5 seconds.
“duration”: “P1M”
“notifyConditions”: [
{
“type”: “ONCHANGE”,
“condValues”: [
“attribute_id”
]
}
],
“throttling”: “PT5S”
}

Return

{
“subscribeResponse”: {
“subscriptionId”: “id_subscription”,
“duration”: “P1M”
}
}
46
 SMART SPOT

Create subscription convenience v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/v1/ be consulted. Method to create a subscription to one
POST
contextSubscriptions Port-orion: Port to connect with or many entities.
the service.

Body

{ • isPattern: Currently is hasn’t use. Always ‘false’.

“entities”: [ • id: To which entity it wants to subscribe. In this case, to all
{ entities of those type.
“type”: “entity_type”, • reference: URL of client that it want to subscribe.
“isPattern”: “false”, • duration: The duration of the subscription. In ISO 8601
“id”: “.*” standard format.
} • notifyConditions: Define the launcher to notify the
], subscriptions. In this case, when change a value of
“attributes”: [ attributes transmitted via the “condValues” of an entity ,then
“attribute_id” it will trigger a notification.
], • throttling: Specify a minimum inter-notification arrival time.
“reference”: “http://cygnus:5050/notify”, In this case, 5 seconds.
“duration”: “P1M” “notifyConditions”: [
{
“type”: “ONCHANGE”,
“condValues”: [
“attribute_id”
]
}
],
“throttling”: “PT5S”
}

Return

{
“subscribeResponse”: {
“subscriptionId”: “id_subscription”,
“duration”: “P1M”
}
}
47
 DEVELOPMENT GUIDE

Update subscription standard v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/v1/ be consulted. Method to update a subscription of an
POST
updateContextSubscription Port-orion: Port to connect with entity.
the service.

Body Return

{ {
“subscriptionId”: “id_subscription”, “subscribeResponse”: {
“id_parameter”: “value_parameter” “subscriptionId”: “id_subscription”,
} “id_parameter”: “value_parameter”
}
}

Update subscription convenience v1

URL Method URL Params Definition

Url: Link to the service that will
http://{{url}}:{{port-orion}}/ be consulted. Method to update a subscription of an
v1/contextSubscriptions/ POST
Port-orion: Port to connect with entity.
{{fiware-subscription}}
the service.

Body Return

{ {
“subscriptionId”: “id_subscription”, “subscribeResponse”: {
“id_parameter”: “value_parameter” “subscriptionId”: “id_subscription”,
} “id_parameter”: “value_parameter”
}
}

48
 SMART SPOT

Delete subscription v1

URL Method URL Params Definition

Url: Link to the service that will
be consulted.
http://{{url}}:{{port-orion}}/
Port-orion: Port to connect with Method to delete the subscription to
v1/contextSubscriptions/ POST
the service. an entity.
{{fiware-subscription}}
Fiware-subscription: ID of
subscription to remove.

Return

{
“subscribeResponse”: {
“subscriptionId”: “id_subscription”,
“id_parameter”: “value_parameter”
}
}

49
ANNEXES
 DEVELOPMENT GUIDE

ANNEX 1: OMA LwM2M

OMA LightweightM2M is a device management protocol service enablement, features a modern architectural
designed for sensor networks and the demands of a design based on REST, defines an extensible resource and
machine-to-machine (M2M) environment. With LwM2M, data model and builds on an efficient secure data transfer
OMA has responded to demand in the market for a standard called the Constrained Application Protocol
common standard for managing lightweight and low (CoAP). LwM2M has been specified by a group of industry
power devices on a variety of networks necessary to experts at the Open Mobile Alliance’s Device Management
realize the potential of IoT. The LwM2M protocol, designed Working Group and is based on protocol and security
for remote management of M2M devices and related standards from the IETF.

Resource model
The LwM2M Enabler defines a simple resource model Write, Execute) which are individually supported by the
where each piece of information made available by the Resources belonging to that Object; this specification also
LwM2M Client is a Resource. Resources are organized defines the Mandatory or Optional characteristics of such
into Objects, and each Resource is given a unique Resources.
identifier within that Object.
Objects and Resources have the capability to have
Each Objec is assigned a unique OMA LwM2M Object multiple instances. Multiple-Instances Resources can be
identifier allocated and maintained by the OMA Naming instantiated by LwM2M Server operations in using JSON
Authority (OMNA). Further Objects may be added by OMA or TLV formats. The LwM2M Client also has the capability
or other organizations to enable additional M2M Services. to instantiate Single or Multiple-Instances Resources.

As an Object only specifies a grouping of Resources, an The LwM2M Enabler defines an access control
Object must be firstly instantiated so that the LwM2M mechanism per Object Instance. Object Instances should
Client can use the Resources of such an Object and the have an associated Access Control Object Instance. An
associated functionalities. Access Control Object Instances contains Access Control
Lists (ACLs) that define which operations on a given
When an Object is instantiated an Object Instance is Object Instance are allowed for which LwM2M Server(s).
created with a subset of the Resources defined in the
Object specification; a LwM2M Server can then access
that Object Instance and its set of instantiated Resources.

A Resource which is instantiated within an Object

Instance is a Resource which can either:
• contain a value (if the Resource is Readable and/or
Writeable)
• or can be addressed by a LwM2M Server to trigger
an action in the LwM2M Client (if the Resource is
Executable)

The Object specification defines the operations (Read,

52
 SMART SPOT

Objects
Each Object definition, which may be found in the LwM2M from 0 to many. If this field is “Single” then the number
specification, features the following information: of Object Instance can be from 0 to 1.
• Mandatory: if this field is “Mandatory”, then the
• Name: specifies the Object name. LwM2M Client MUST support this Object. If this field
• Object ID: specifies the Object ID. is “Optional”, then the LwM2M Client SHOULD support
• Instances: indicates whether this Object supports this Object.
multiple Object Instances or not. If this field is • Object URN
“Multiple” then the number of Object Instance can be • Resource definitions

Attributes
Attributes are metadata which can be attached to an Than”, “Less Than”, or “Step”) and the “Minimum
Object, an Object Instance or a Resource. The value of an Period” timing conditions are both fulfilled for that
Attribute is LwM2M Server specific. Resource.

Regardless to the LwM2M entity a given Attribute is This behaviour can be modified using the following
attached to, the value of such an Attribute can be set at available attributes:
various levels: Object, Object Instance, Resource levels. ◊ Minimum Period (pmin): The Minimum Period
Attribute indicates the minimum time in seconds
• <PROPERTIES> Class Attributes: The role of these the LwM2M Client must wait between two
Attributes is to provide metadata which may notifications.
communicate helpful information to LwM2M Server ◊ Maximum Period (pmax): The Maximum Period
for example easing data management. These include: Attribute indicates the maximum time in seconds
◊ Dimension (dim): Number of Instantiations for a the LwM2M Client MAY wait between two
Multiple Resource. notifications.
◊ Object Version (ver): Provide the version of the ◊ Greater Than (gt) and Less Than (lt): This
associated Object. Attributes defines a threshold high value and
• <NOTIFICATION> Class Attributes: The role of low value. When these Attributes is present, the
these R-Attributes is to provide parameters to the LwM2M Client must notify the Server each time
“Notify” operation; any readable Resource can have the Observed Resource value crosses these
such Rattributes. In the message sent by a LwM2M thresholds with respect to pmin parameter and to
Client in response to an “Observe” operation, the pmax parameter.
current Resource value is reported; this event can be ◊ Step (st): This Attribute defines a minimum
considered as the initial notification. change value between two notifications. When
this Attribute is present, the change value
Each time a Resource notification is sent, the condition will occur when the value variation since
“Minimum Period” and “Maximum Period” timers the last notification of the Observed Resource, is
associated to this Resource are restarted. greater or equal to the “Step” Attribute value.

The notification of a Resource value will be sent when

the combination of a change value condition (“Greater

53
 DEVELOPMENT GUIDE

Clients and servers

This enabler defines the application layer communication Client and the M2M service, platform or application acts
protocol between a LwM2M Server and a LwM2M as the LwM2M Server. The LwM2M Enabler has two
Client, which is located in a LwM2M Device. The OMA components, LwM2M Server and LwM2M Client. Four
Lightweight M2M enabler includes device management interfaces are designed between these two components:
and service enablement for LwM2M Devices. The target
LwM2M Devices for this enabler are mainly resource • Bootstrap
constrained devices. Therefore, this enabler makes use • Client Registration
of a light and compact protocol as well as an efficient • Device management and service enablement
resource data model. • Information Reporting

A Client-Server architecture is introduced for the LwM2M

Enabler, where the LwM2M Device acts as a LwM2M

Bootstrap Interface
The Bootstrap Interface is used to provision essential
information into the LwM2M Client to enable the LwM2M
Client to perform the operation “Register” with one or
more LwM2M Servers.

During the Bootstrap Phase, the Client may ignore

requests and flush all pending responses not related to
the Bootstrap sequence. There are four bootstrap modes
supported by the LwM2M Enabler:

• Factory Bootstrap
• Bootstrap from Smartcard
• Client Initiated Bootstrap
• Server Initiated Bootstrap

The last two Bootstrap modes require the help of a

LwM2M Bootstrap-Server to achieve the ultimate goal to
connect a LwM2M Client to their LwM2M Server(s).

The LwM2M Client must support at least one bootstrap

mode specified in the Bootstrap Interface.

The LwM2M Bootstrap-Server must support Client

Initiated Bootstrap and Server Initiated Bootstrap modes
specified in the Bootstrap Interface.

54
 SMART SPOT

Client Registration Interface

The LwM2M Server must support all the operations in this Server Object Instance. Finally, when shutting down or
interface and the LwM2M Client must support “Register” discontinuing use of a LwM2M Server, the LwM2M Client
and “Update” and should support “De-register” operation. performs a “De-register” operation.

The Client Registration Interface is used by a LwM2M The Binding Resource of the LwM2M Server Object
Client to register with one or more LwM2M Servers, informs the LwM2M Client of the transport protocol
maintain each registration and de-register from a LwM2M preferences of the LwM2M Server for the communication
Server. The registration is based on the Resource Model session between the LwM2M Client and LwM2M Server.
and Identifiers defined in Section 6 Identifiers and
Resources. When registering, the LwM2M Client performs The LwM2M Client should perform the operations with the
the “Register” operation and provides the properties the modes indicated by the Binding Resource of the LwM2M
LwM2M Server requires to contact the LwM2M Client Server Object Instance.
(e.g., End Point Name); maintain the registration and
session (e.g., Lifetime, Queue Mode) between the LwM2M
Client and LwM2M Server as well as knowledge of the
Objects the LwM2M Client supports and existing Object
Instances in the LwM2M Client. The registration is soft
state, with a lifetime indicated by the Lifetime Resource
of that LwM2M Server Object Instance. The LwM2M
Client periodically performs an update of its registration
information to the registered LwM2M Server(s) by
performing the “Update” operation– possibly without any
parameters. If the lifetime of a registration expires without
receiving an update from the LwM2M Client:

• The LwM2M Server must remove the registration of

that Client.

• The LwM2M Client must re-register (“Update” is

not sufficient) to the LwM2M Server in order to
be connected again, before initiating any further
communication.

If the LwM2M Server or the LwM2M Client set a value

to the Lifetime Resource of the Server Object Instance,
this value becomes the new lifetime of the Registration
session.

During “Register” or “Update” Operations, the parameter

Lifetime – if present – must match the current value
of the Mandatory Lifetime Resource of the LwM2M

55
 DEVELOPMENT GUIDE

Device Management and Service Enablement Interface

The LwM2M Server and the LwM2M Client must support • Create operation is used by the LwM2M Server to
all the operations in this interface. create Object Instance(s) within the LwM2M Client.
The “Create” operation must target an Object. If any
The Device Management and Service Enable Interface error occurs, nothing must be created
is used by the LwM2M Server to access Object Instances
and Resources available from a registered LwM2M • Finally, the Delete operation is used for LwM2M
Client. The interface provides this access through the Server to delete an Object Instance within the LwM2M
use of “Create”, “Read”, “Write”, “Delete”, “Execute”, “Write- Client.
Attributes”, or “Discover” operations.
The Object Instance that is deleted in the LwM2M
The Device Management and Service Enablement Client by the LwM2M Server must be an Object
interface defines the following commands: Instance that is announced by the LwM2M Client to
the LwM2M Server using the “Register” and “Update”
• Read operation is used to access the value of a operations of the Client Registration Interface.
Resource, an array of Resource Instances, an Object
Instance or all the Object Instances of an Object.

• Discover operation is used to discover LwM2M

Attributes attached to an Object, Object Instances,
and Resources. This operation can be used to
discover which Resources are instantiated in a given
Object Instance

• Write operation is used to change the value of

a Resource, the values of an array of Resources
Instances or the values of multiple Resources from an
Object Instance.

• Write-Attributes: In LwM2M 1.0, only Attributes from

the <NOTIFICATION> class may be changed in using
the “Write-Attributes” operation. The operation permits
multiple Attributes to be modified within the same
operation.

• Execute operation is used by the LwM2M Server to

initiate some action, and can only be performed on
individual Resources. A LwM2M Client must return an
error when the “Execute” operation is received for an
Object Instance(s) or Resource Instance(s).

56
 SMART SPOT

Information Reporting Interface

The LwM2M Server and the LwM2M Client must support
all the operations in this interface.

The Information Reporting Interface is used by a LwM2M

Server to observe any changes in a Resource on a
registered LwM2M Client, receiving notifications when
new values are available. This observation relationship is
initiated by sending an “Observe” operation to the LwM2M
Client for an Object, an Object Instance or a Resource. An
observation ends when a “Cancel Observation” operation
is performed.

• Observe: The LwM2M Server initiates an observation

request for changes of a specific Resource,
Resources within an Object Instance or for all the
Object Instances of an Object within the LwM2M
Client.

• Notify: The “Notify” operation is sent from the LwM2M

Client to the LwM2M Server during a valid observation
on an Object Instance or Resource. This operation
includes the new value of the Object Instance or
Resource. The “Notify” operation should be sent when
all the conditions (i.e., Minimum Period, Maximum
Period, Greater Than, Less Than, Step) configured by
“Write-Attributes” operation for “Observe” operation
are met

• Cancel Observation: The “Cancel Observation”

operation is sent from the LwM2M Server to the
LwM2M Client to end an observation relationship for
Object Instance or Resource.

More information about OMA LwM2M Protocol:

http://www.openmobilealliance.org/release/LightweightM2M/V1_0_1-20170704-A/OMA-TS-LightweightM2M-V1_0_1-
20170704-A.pdf

57
hopu.eu