IoT in the FIWARE Platform - 1

IoT Agents

Fernando López Aguilar

FIWARE Cloud and Platform Senior Expert

fernando.lopez@fiware.org

@flopezaguilar

Slides: http://bit.ly/IoTAgentsCairo

2

IoT Interoperability ? Still a $1,000,000 question

3

Even worse in 2017…

4

5

6

We need to find

We need to find the exit of this labyrinth

Tenemos un plan

We have a plan :

Smart* FIWARE most-used IoT Stack

8

IoT Agents in a nutshell

9

IoT Agents

▪ Device Protocol to NGSI Bridge:

• One entity per device.

• Constrained set of interactions.

▪ Design principles:

• Modular approach.

• Deployment flexibility.

• Simplify the creation of Custom IoT Agents.

▪ Provisioning of devices and groups of devices.

▪ IoT Manager.

▪ Additional services (e.g. security, device registration, stats).

10

Integration with sensor networks

▪ Smart solutions need to deal with the wide variety of IoT protocols today

▪ Rather than trying to solve the battle of standards at IoT level, it brings a

standard where no standard exists today: context information management

11

Context Broker

IoT

Agent-1

IoT

Agent-2

IoT

Agent-n

IoT Agent

Manager

create/monitor

IoT Framework

Standard API (northbound interface)

(southbound interfaces)

MQTTETSI M2M IETF CoAP

Transport & Payload

▪ Device protocol = transport protocol + payload format

▪ Transports protocols

• HTTP

• MQTT

• Others

▪ Payload format

• UL (ultralight)

• JSON

• Others

▪ Transport and payload format are orthogonal, e.g.

• HTTP transport using JSON payload

• MQTT transport using JSON payload

• HTTP transport using UL payload

• MQTT transport using UL payload

• Etc.

12

Physical

Link

TCP

MQTT

Physical

Link

TCP

HTTP

Payload formats examples

▪ JSON

▪ Ultralight (UL)

13

{

"h": "45%",

"t": "23",

"l": "1570"

}

h|45%|t|23|l|1570

Ultralight 2.0 (Measures)

▪ Simple HTTP-based protocol

▪ Measure reporting:

• Key/Value pairs separated by | and #

• POST request with plain/text content to the IoTA path:

POST http://{{host}}:{{iota_ul-port}}/iot/d?k=&i={{device-id}}&t=2016-03-01T10:00:00Z

▪ Payload example:

t|34#h|87#l|1900

▪ Required query params

• k: Service API Key

• i: Device ID

▪ Optional query params

• t: timestamp of the measure 14

API operations

15

Configuration API: Group provision

▪ Create service

• /iot/services

▪ Not exactly REST (check doc)

• POST

• GET

• DELETE

• PUT

▪ Static attributes

▪ Mandatory

• Resource

• Api key

• Entity Type

16

{

"services": [

{

"apikey": "4jggokgpepnvsb2uv4s40d59ov",

"cbroker": "http://0.0.0.0:1026",

"entity_type": "thing",

"resource": "/iot/d"

}

]

}

Configuration API: Device provision

▪ Create device

• /iot/devices

▪ Not exactly REST (check doc):

• POST

• GET

• DELETE

• PUT

▪ Mandatory

• Device_id

• Entity_type

• protocol

▪ Commands

• endpoint

17

{

"devices": [

{

"device_id": "my_device_01",

"entity_name": "my_entity_01",

"entity_type": "thing",

"protocol": "PDI-IoTA-UltraLight",

"timezone": "Europe/Madrid",

"attributes": [

{

"object_id": "t",

"name": "temperature",

"type": "int"

},

{

"object_id": "l",

"name": "luminosity",

"type": "number"

}

]

}

]

}

Sending Measurements: Ultralight 2.0 HTTP

18

Simple HTTP ProtocolAPI key (k)

Device Id (i)

Key Pair values

Push and Pull commands

POST /iot/d?k= k=4jggokgpepnvsb2uv4s40d59ov

&i=my_device_01 HTTP/1.1

Host: localhost:7896

Content-Type: text/plain

Cache-Control: no-cache

t|37#l|1200HTTP/1.1 200 OK

Content-Length: 88

Content-Type: text/html

Connection: Closed

my_device_01@t|2| my_device_01@l|200

Example: Group provision

19

API Key provision

Type definition

Common attributes and

commands

POST /iot/services HTTP/1.1

Host: localhost:4041

Fiware-Service: smartsville

Fiware-ServicePath: /management

Content-Type: application/json

{

"services": [

{

"apikey": "1234567890",

"resource": "/iot/d",

"type": "smartcity",

"protocol": "PDI-IoTA-UltraLight"

}

]

}

Example: Device provision

20

Device ID definition

Defines per-device

attributes and commands

POST /iot/devices HTTP/1.1

Host: localhost:4041

Fiware-Service: smartsville

Fiware-ServicePath: /management

Content-Type: application/json

{

"devices": [{

"device_id": "smartsville",

"entity_type": "smartcity",

"protocol": "PDI-IoTA-UltraLight",

"attributes": [

{

"object_id": "lum",

"name": "Luminance",

"type": "lumens"

}

]}]}

Example: Ultralight 2.0 HTTP

21

Simple HTTP Protocol

Key Pair values

Push and Pull commands

POST /iot/d?k=1234567890&i=smartsville HTTP/1.1

Host: localhost:7896

Content-Type: text/plain

Cache-Control: no-cache

park1|true|park2|false|lum|300HTTP/1.1 200 OK

Content-Length: 88

Content-Type: text/html

Connection: Closed

smartsville@semaphoreFreq|2|smartsville@luminosityLi

mit|200

Attributes and Commands

22

Attribute types

▪ Active attributes

• Actively updated to CB

▪ Lazy attributes

• Kept at the device, obtained using the CPr-forwarding mechanism

▪ Static attributes

• As active attributes, but with a “fixed” value

▪ Commands

• For actuation capabilities

• Managed in a similar way to lazy attributes, but involving also an

info and a status CB attributes

23

Interaction models: Active & Static

Attributes

24

IOT Agent

DB

Device

ProtocolNGSI

Entity information

Interaction

begins

Active attributes

25

…

"attributes": [

{ "object_id": "t", "name": "temperature", "type": "float" },

{ "object_id": "h", "name": "humidity", "type": "float" }

],

…

Static attributes

▪ Similar to active attributes but…

• They don’t correspond to actual measures sent by the physical device

• They have a fixed value

• They are attached to every IOTA-to-CB update operation

▪ Q: Why using static attributes?

26

…

"static_attributes": [

{ "name": "serialID", "type": "02598347", "value": "02598347" }

]

…

Interaction models: Lazy Attributes &

Commands

27

IOT Agent

Device

ProtocolNGSI

Command

Execution

Interaction

begins

Result Information

Requires the IOT Agent to be

registered as a Context

Provider

Lazy attributes

▪ Q: Why all this complication? Why don’t use only active attributes?

28

…

"lazy":[

{ "object_id": "l", "name": "luminosity", "type": "percentage" }

],

…

Commands

▪ Three supporting attributes at CB (per command)

• <cmd> (write), the one used by the application (through update context at

CB) in order to execute command

• <cmd>_status (read only), the one in which IOTA published status

□ UNKNOWN: transient status, just after device provisioning and before any

execution is done

□ PENDING: command execution is in progress

□ ERROR: command execution finished in error status

□ FINISHED: command execution finished in ok status

• <cmd>_info (read only): upon completion, the result of the command

execution (if any) is published by IOTA in this attribute

▪ Example:

• turn

• turn_info

• turn_status

29

…

"commands": [

{ "object_id": "u", "name": "turn", "type": "string" }

],

…

Commands

30

…

"commands": [

{ "object_id": "u", "name": "turn", "type": "string" }

],

…

turn_statusturn_status

turn_info

31

Question & Answer

fiware-tech-help@lists.fiware.org

fiware-lab-help@lists.fiware.org

32

Further reading

▪ IoT Agent Library

• https://github.com/telefonicaid/iotagent-node-lib

▪ IoT Agent-Ultralight 2.0

• Base doc: https://github.com/fiware/iotagent-ul

▪ Orion Context Broker

• Base doc: https://github.com/fiware/orion

• ReadTheDocs: https://fiware-orion.readthedocs.io

▪ STH-Comet

• Github repository: https://github.com/fiware/fiware-sth-comet

• ReadTheDocs: https://fiware-sth-comet.readthedocs.io/en/latest

▪ The FIWARE Catalogue

• https://catalogue.fiware.org/

33

34

http://fiware.org

Follow @FIWARE on Twitter

Thank you!

http://fiware.org

Follow @FIWARE on Twitter

35

Thank you!

http://fiware.org

Follow @FIWARE on Twitter

Backup slides