» IoT Agents & Robots » IoT Sensors

FIWARE IoT Agents Payload Ultralight

Background: This tutorial does not use the NGSI-v2 interface directly. it covers
background information about IoT devices and protocols, which is then used in
subsequent chapters.

Description: This tutorial is an introduction to IoT devices and the usage of the UltraLight 2.0
Protocol for constrained devices. The tutorial introduces a series of dummy IoT devices which
are displayed within the browser and allows a user to interact with them. A complete
understanding of all the terms and concepts defined in this tutorial is necessary before
proceeding to connect the IoT devices to the Orion Context Broker via a real IoT Agent.
The tutorial uses cUrl commands throughout, but is also available as Postman documentation

What Are IoT Devices?

"All our knowledge begins with the senses."

— Immanuel Kant (Critique of Pure Reason)

The Internet of Things (IoT) is a network of physical devices which are able to connect to a
network and exchange data. Each "thing" or "smart device" is a gadget with embedded
electronics and software which can act as a sensor or actuator. Sensors are able to report the
state of the real-world around them. Actuators are responsible for altering the state of the
system, by responding to a control signal.
Each device is uniquely identifiable through its embedded computing system but is able to
interoperate within the existing internet infrastructure.
FIWARE is a system for managing context information. For a smart solution based on the
internet of Things, the context is provided by the array of attached IoT devices. Since each IoT
device is a physical object which exists in the real world, it will eventually be represented as a
unique entity within the context.
IoT devices can range from simple to complex. Here are some examples of IoT devices which
will be used within this tutorial:
A Smart Door is an electronic door which can be sent commands to be locked or unlocked
remotely. It can also report on its current state (OPEN, CLOSED or LOCKED),
A Bell can be sent a command to activate and ring for a short period
A Motion Sensor will activate and send a count when someone is nearby
A Smart Lamp can be switched on or off remotely. It can also report on its current state (ON
or OFF). When switched on, a Motion Sensor within the device checks to see if light is
needed and will dim if no one is nearby. Furthermore the device can report the current
luminosity of the bulb.

As you can see, the Bell is an example of a pure actuator, as it only reacts to the given
commands. Meanwhile, the Motion Sensor is an example of a pure sensor, since it will only
report on the state of the world as it sees it. The other two devices are able to both respond to
the commands and report on state in a meaningful way.
The state information held within each device, as it will eventually be seen within the Context
Broker is defined in the diagram below:

What Is Ultralight 2.0?

UltraLight 2.0 is a lightweight text based protocol for constrained devices and communications
where bandwidth and device memory resources are limited. The payload for measurement
requests is a list of key-value pairs separated by the pipe | character.
e.g.

<key>|<value>|<key>|<value>|<key>|<value> etc..

For example a payload such as latest

 t|15|k|abc

contains two attributes, one named "t" with value "15" and another named "k" with value "abc".
Values in Ultralight 2.0 are not typed (everything is treated as a string).
Ultralight 2.0 defines a payload describing measurements and commands to share between
devices and servers but, does not specify a single transport protocol. Instead, different
transport protocol bindings (such as HTTP, MQTT and AMQP) can be used for different
scenarios. For this tutorial we will be using HTTP as a transport protocol.

Southbound Traffic (Commands)

HTTP requests generated by the Context Broker and passed downwards towards an IoT device
(via an IoT Agent) are known as southbound traffic. Southbound traffic consists of commands
made to actuator devices which alter the state of the real world by their actions. For example a
command to alter the state of a lamp to ON would switch on the lamp in real life. This in turn
could alter the readings of other sensors nearby.

Push Command Using HTTP POST

Setting up the southbound communication between an IoT Agent and IoT devices is known as
provisioning. This ensures that the IoT Agent holds sufficient information to be able to contact
each IoT device. In other words it knows where to send commands and which commands are
supported. In order to send a command to a device, the IoT Agent sends a POST request to the
endpoint supplied by the device. The body of the POST request holds the command.
The payload for Ultralight commands has the following format:

<device_name>@<command>|<param|<param>

Where <device_name> is the entity id as held in the context broker, <command> is one of the
supported commands and any additional required values are passed in subsequent
parameters, for example

urn:ngsi-ld:Robot:001@turn|left|30

will tell a device "I am known as id="urn:ngsi-ld:Robot:001" within the Context Broker. I
would like the device listening on this endpoint to perform the turn command. I have
supplied the parameters left and 30 (degrees) as required for the device to be able to
perform the maneuver".
The defined Northbound response to an IoT Agent is as follows:

urn:ngsi-ld:Robot:001@turn|Turn ok

which is saying "I have complied with a request from the entity known as id="urn:ngsi-
ld:Robot:001" within the Context Broker. The command I have performed was a turn
command. The result was Turn ok".
As you can see, because the Southbound command defines the id used within the interaction,
and the same data is also returned, every response can always be associated to the appropriate
entity held within the Context Broker.
Push commands can only be used if the device is able to supply a separate endpoint for
listening to southbound traffic, an alternative polling mechanism can be used when all
interactions are initiated from the device itself, but this is beyond the scope of this tutorial.

Northbound Traffic (Measurements)

Requests generated from an IoT device and passed back upwards towards the Context Broker
(via an IoT Agent) are known as northbound traffic. Northbound traffic consists of
measurements made by sensor devices and relays the state of the real world into the context
data of the system. For example a measurement from a humidity sensor could be relayed back
into the context broker to indicate that the moisture level of the entity has changed. A
subscription could be made to be informed of such changes and there provoke further actions
(such as turning on a sprinkler).

Measurement Using HTTP GET

A device can report new measures to an IoT Agent using an HTTP GET request to a "well-
known" endpoint (the path /iot/d) along with the following query parameters:
i (device ID): Device ID (unique for the API Key).

k (API Key): API Key for the service the device is registered on.

t (timestamp): Timestamp of the measure. Will override the automatic IoT Agent
timestamp (optional).
d (Data): Ultralight 2.0 payload.

The i and k parameters are mandatory.

For example the request:

<iot-agent>/iot/d?i=motion001&d=c|12

latest
would indicate that the device id=motion001 wishes to inform the IoT Agent that is has made
a real-world measurement c with the value 12. This would eventually be passed up into the
Context Broker.

Measurement Using HTTP POST

HTTP POST can also be used. Again the path will be /iot/d, but in this case, d (Data) is not
necessary - the key-value pairs of the measurement are passed as the body of the request. i
and k query parameters are still mandatory:
i (device ID): Device ID (unique for the API Key).

k (API Key): API Key for the service the device is registered on.

t (timestamp): Timestamp of the measure. Will override the automatic IoT Agent
timestamp (optional).

Once again the i and k parameters are mandatory.

Device Monitor
For the purpose of this tutorial, a series of dummy IoT devices have been created, which will
eventually be attached to the context broker. The state of each device can be seen on the
UltraLight device monitor web page found at http://localhost:3000/device/monitor.

Architecture
The demo application will only make use of a single custom component acting as a set of
dummy IoT devices. Every IoT device will be using the UltraLight 2.0 protocol running over
HTTP. Since all interactions are initiated by HTTP requests, the entities can be containerized
and run from exposed ports.

The necessary configuration information can be seen in the services section of the associated
docker-compose.yml file:

latest
 tutorial:
image: quay.io/fiware/tutorials.context-provider
hostname: iot-sensors
container_name: fiware-tutorial
networks:
- default
expose:
- '3000'
- '3001'
ports:
- '3000:3000'
- '3001:3001'
environment:
- 'DEBUG=tutorial:*'
- 'PORT=3000'
- 'IOTA_HTTP_HOST=iot-agent'
- 'IOTA_HTTP_PORT=7896'
- 'DUMMY_DEVICES_PORT=3001' # Port used by the dummy IOT devices to receive
commands
- 'DUMMY_DEVICES_API_KEY=4jggokgpepnvsb2uv4s40d59ov'

The tutorial container is listening on two ports:

Port 3000 is exposed, so we can see the web page displaying the Dummy IoT devices.
Port 3001 is exposed purely for tutorial access - so that cUrl or Postman can make UltraLight
commands without being part of the same network.

The tutorial container is driven by environment variables as shown:

Key Value Description

DEBUG tutorial:* Debug flag used for logging

WEB_APP_PORT 3000 Port used by web-app which displays the dummy

device data

IOTA_HTTP_HOST iot-agent The hostname of the missing IoT Agent - used in a later
tutorial

IOTA_HTTP_PORT 7896 The port that the missing IoT Agent will be listening on.
7896 is a common default for UltraLight over HTTP

DUMMY_DEVICES_PORT 3001 Port used by the dummy IoT devices to receive

commands

DUMMY_DEVICES_API_KEY 4jggokgpepnvsb2uv4s40d59ov Random security key used for UltraLight interactions -

this will be used in a later tutorial to ensure the integrity
of interactions between the devices and the missing IoT
Agent

The other tutorial container configuration values described in the YAML file are not used in
this tutorial.
When describing the messages being passed through a working smart solution we will refer to
two further components which are not used in this tutorial, but will be needed to complete the
system subsequently.
The Orion Context Broker is used for holding the context data of the smart solution. As you
know all interactions with the context broker must be made using NGSI-v2
An IoT Agent acts as a middleware component converting NGSI-v2 requests (from the
context broker) into a protocol (such as UltraLight 2.0) usable by the IoT devices themselves.

It is therefore necessary to understand a sample device protocol first, and comprehend how
messages are passed through the system to subsequently understand the purpose of the IoT
Agent middleware. In this tutorial you will be playing the role of an IoT Agent making
commands to devices and receiving measurements from them.

Start Up
All services can be initialized from the command-line by running the bash script provided
within the repository. Please clone the repository and create the necessary images by running
the commands as shown:

#!/bin/bash
git clone https://github.com/FIWARE/tutorials.IoT-Sensors.git
cd tutorials.IoT-Sensors
git checkout NGSI-v2

./services create; ./services start;

This command will also import seed data from the previous Stock Management example on
startup.

latest
 Note: If you want to clean up and start over again you can do so with the following
command:
./services stop

Communicating With IoT Devices

To follow the tutorial correctly please ensure you have the device monitor page available in
your browser and click on the page to enable audio before you enter any cUrl commands. The
device monitor displays the current state of an array of dummy devices using Ultralight 2.0
syntax

Device Monitor
The device monitor can be found at http://localhost:3000/device/monitor.
Within this tutorial you will be playing the role of the missing IoT Agent component, making
Southbound commands to the attached IoT devices and receiving Northbound measurements
as the environment changes within the store. All the commands are made as HTTP POST
requests using Ultralight syntax and therefore are very simple. It is worthwhile keeping an eye
on the device monitor page as it shows all the Northbound traffic generated by the devices
themselves.

Note: In addition to user interactions, all dummy devices will periodically register a
heartbeat message

Bell Commands
A Bell is an example of an actuator. It can respond to commands, but the device does not
supply any measurements from the real world.

Ring A Bell
This example shows how a real IoT Agent would send commands to an actuator. The Bell has
supplied an endpoint /iot/bell001 where it is listening for commands.

1 Request:

curl -iX POST \

--url 'http://localhost:3001/iot/bell001' \
--data urn:ngsi-ld:Bell:001@ring

Response:

urn:ngsi-ld:Bell:001@ring| ring OK

The body of the request is in Ultralight syntax and consists of the id of the device (urn:ngsi-
ld:Bell:001) as held in the Context Broker and the name of the command (ring) to invoke on
the device.
The response returns the command and the result of the action.
If you are viewing the device monitor page, you can see the state of the bell change.

Smart Lamp Commands

The Smart Lamp can be switched on and off remotely - it also registers luminosity. It contains a
Motion Sensor within and will slowly dim as time passes (provided no movement is detected)
Measurements will be sent to the IoT Agent as the state and/or luminosity changes.

Switch On A Smart Lamp

This example shows how a real IoT Agent would send an Ultralight command to a Smart Lamp
to switch it on. The Smart Lamp has already supplied an endpoint /iot/lamp001 where it is
listening for commands.

2 Request:

curl -iX POST \

--url 'http://localhost:3001/iot/lamp001' \
--data urn:ngsi-ld:Lamp:001@on

The body of the request consists of the id of the device (urn:ngsi-ld:Lamp:001) as held in the latest
Context Broker and the name of the command (on) to invoke on the device.
Response:
The response returns the command and the result of the action.

urn:ngsi-ld:Lamp:001@on| on OK

Once the lamp is switched on the luminosity level will alter dependent upon whether the
internal motion sensor detects movement. The measurement is actively reported and requests
to the IoT Broker can be seen on the device monitor page.

Switch Off A Smart Lamp

This example shows how a real IoT Agent would send an Ultralight command to a Smart Lamp
to switch it off. The Smart Lamp has already supplied an endpoint /iot/lamp001 where it is
listening for commands.

3 Request:

curl -iX POST \

--url 'http://localhost:3001/iot/lamp001' \
--data urn:ngsi-ld:Lamp:001@off

The body of the request consists of the id of the device (urn:ngsi-ld:Lamp:001) as held in the
Context Broker and the name of the command (off) to invoke on the device.

Response:
The response returns the command and the result of the action.

urn:ngsi-ld:Lamp:001@off| off OK

Once the lamp is switched off the luminosity level does not alter. The latest Ultralight
measurement (s|OFF|l|0) as sent to the IoT Broker can be seen on the device monitor page.
To turn the Smart Lamp back on again repeat the following command:

4 Request:

curl -iX POST \

--url 'http://localhost:3001/iot/lamp001' \
--data urn:ngsi-ld:Lamp:001@on

Response:

urn:ngsi-ld:Lamp:001@on| on OK

Smart Door Commands

A Smart Door is an electronic door which can be sent commands to be locked or unlocked
remotely. It can also report on its current state (OPEN, CLOSED or LOCKED),
Measurements will be sent to the IoT Agent as the state changes.

Unlock A Door
This example shows how a real IoT Agent would send an Ultralight command to a Smart Door
to unlock the door. The Smart Door has already supplied an endpoint /iot/door001 where it
is listening for commands.

5 Request:

curl -iX POST \

--url 'http://localhost:3001/iot/door001' \
--data urn:ngsi-ld:Door:001@unlock

The body of the request consists of the id of the device (urn:ngsi-ld:Door:001) as held in the
Context Broker and the name of the command (unlock) to invoke on the device.

Response:
The response returns the command and the result of the action.

urn:ngsi-ld:Door:001@unlock| unlock OK

Once the Smart Door is unlocked, it will automatically open and close as customers enter. The
changes of state are actively reported to the IoT Broker, and the state of the Smart Door can be
seen on the device monitor page.
The Motion Sensor within the store is not an actuator - it does not respond to the commands,
however it does actively measure the number of customers passing by. If the door is unlocked,
the Motion Sensor will detect movement and send Ultralight measurements back up to the
IoT Broker.
The Northbound HTTP requests generated by the Motion Sensor can be also viewed on the
device monitor page.
latest
Open A Door
This example shows how a real IoT Agent would send a command to a Smart Door to open the
door. The Smart Door has already supplied an endpoint /iot/door001 where it is listening for
commands.

6 Request:

curl -iX POST \

--url 'http://localhost:3001/iot/door001' \
--data urn:ngsi-ld:Door:001@open

The body of the request consists of the id of the device (urn:ngsi-ld:Door:001) as held in the
Context Broker and the name of the command (open) to invoke on the device.

Response:
The response returns the command and the result of the action.

urn:ngsi-ld:Door:001@open| open OK

The state of the Smart Door can be seen on the device monitor page. Customers may now
enter and the Motion Sensor may pick up movement and send measurements to the IoT
Broker.
The Northbound HTTP requests generated by the Smart Door and the Motion Sensor can also
be viewed on the device monitor page.

Close A Door
This example shows how a real IoT Agent would send a command to a Smart Door to close the
door. The Smart Door has already supplied an endpoint /iot/door001 where it is listening for
commands.

7 Request:

curl -iX POST \

--url 'http://localhost:3001/iot/door001' \
--data urn:ngsi-ld:Door:001@close

The body of the request consists of the id of the device (urn:ngsi-ld:Door:001) as held in the
Context Broker and the name of the command (close) to invoke on the device.

Response:
The response returns the command and the result of the action.

urn:ngsi-ld:Door:001@close| close OK

Since the door is currently unlocked, customers will continue to enter, and re-open the door
themselves. If motion is detected, the Motion Sensor will send measurements to the IoT
Broker.
The Northbound HTTP requests generated by the Motion Sensor can also be viewed on the
device monitor page.

Lock A Door
This example shows how a real IoT Agent would send an Ultralight command to a Smart Door
to lock the door. The Smart Door has already supplied an endpoint /iot/door001 where it is
listening for commands.

8 Request:

curl -iX POST \

--url 'http://localhost:3001/iot/door001' \
--data urn:ngsi-ld:Door:001@lock

The body of the request consists of the id of the device (urn:ngsi-ld:Door:001) as held in the latest
Context Broker and the name of the command (lock) to invoke on the device.
Response:
The response returns the command and the result of the action.

urn:ngsi-ld:Door:001@lock| lock OK

Once the door is locked, no further customers may enter. The Motion Sensor will report no
further movement detected, the Smart Door cannot be opened manually and the Smart
Lamp will slowly return to the ambient lighting level.
The Northbound HTTP requests generated by the Smart Lamp can be viewed on the device
monitor page.

latest