IoT in the FIWARE Platform - 1
IoT Agents
Fernando López Aguilar
FIWARE Cloud and Platform Senior Expert
@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
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