LECTURE NOTES

Internet Of Things (IOT)

D5512 – Abba Suganda Girsang

Session 10

Fundamental Thingsboard

Code_Course – Name_Course
1. Overview Thingsboard

ThingsBoard is an open-source IoT platform that enables rapid development, management and
scaling of IoT projects. Our goal is to provide the out-of-the-box IoT cloud or on-premises solution
that will enable server-side infrastructure for your IoT applications. With ThingsBoard, we are
able to:

 Provision devices, assets and customers and define relations between them.
 Collect and visualize data from devices and assets.
 Analyze incoming telemetry and trigger alarms with complex event processing.
 Control your devices using remote procedure calls (RPC).
 Build work-flows based on device life-cycle event, REST API event, RPC request, etc
 Design dynamic and responsive dashboards and present device or asset telemetry and
insights to your customers
 Enable use-case specific features using customizable rule chains.
 Push device data to other systems.

ThingsBoard is designed to be:

 scalable: horizontally scalable platform, build using leading open-source technologies.

 fault-tolerant: no single-point-of-failure, every node in the cluster is identical.
 robust and efficient: single server node can handle tens or even hundreds thousands of
devices depending on use-case. ThingsBoard cluster can handle millions of devices.
 customizable: adding new functionality is easy with customizable widgets and rule engine
nodes.
 durable: never lose your data.

Code_Course – Name_Course
 Figure 10.1 Architecture Thingsboard

2. Feature Thingsboard

ThingsBoard provides the user interface and REST APIs to provision and manage multiple entity
types and their relations in your IoT application. Supported entities are:

Tenants - you can treat tenant as a separate business-entity: individual or organization who owns
or produce devices and assets; Tenant may have multiple tenant administrator users and millions
of customers;

Customers - customer is also a separate business-entity: individual or organization who

purchase or uses tenant devices and/or assets; Customer may have multiple users and millions of
devices and/or assets;

Users - users are able to browse dashboards and manage entities;

Devices - basic IoT entities that may produce telemetry data and handle RPC commands. For
example sensors, actuators, switches;

Code_Course – Name_Course
Assets - abstract IoT entities that may be related to other devices and assets. For example
factory, field, vehicle;

Alarms - events that identify issues with your assets, devices or other entities;

Dashboards - visualization of your IoT data and ability to control particular devices through
user interface;

Rule Node - processing units for incoming messages, entity lifecycle events, etc;

Rule Chain - logic unit of related Rule Nodes;

Each entity supports:

Attributes - static and semi-static key-value pairs associated with entities. For example serial
number, model, firmware version;

Telemetry data - time-series data points available for storage, querying and visualization. For
example temperature, humidity, battery level;

Relations - directed connections to other entities. For example contains, manages, owns,
produces.

Additionally, devices and assets also have a type. This allows distinguising them and process
data from them in a different way.

This guide provides the overview of the features listed above, some useful links to get more
details and real-life examples of their usage.

The easiest way to understand the concepts of ThingsBoard is to implement your first
ThingsBoard application. Let’s assume we want to build an application that collects data from
soil moisture and temperature sensors, visualize this data on the dashboard, detect issues, raise
alarms and control the irrigation.

Code_Course – Name_Course
Let’s also assume we want to support multiple fields with hundreds of sensors. Fields may be
also grouped to the Geo regions.

We believe there should be following logical steps to build such an application.

Step 1 . Provision entities and relations

We are going to setup following hierarchy of assets and devices.

Please review the following screen cast to learn how to provision region and fields assets and
their relations using ThingsBoard Web UI ( https://www.youtube.com/watch?v=C-
JoOfTBeT0).

Please review the following screen cast to learn how to provision devices and their relations with
assets using ThingsBoard Web UI (https://www.youtube.com/watch?v=BUFinxvzIo40

You can automate this actions using ThingsBoard REST API. You can provision new asset
using POST request to the following URL
http(s)://host:port/api/asset

Code_Course – Name_Course
 For example:
 create-asset.sh
 create-asset.json

resources/create-asset.sh

curl -v -X POST -d @create-asset.json

http://localhost:8080/api/asset \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"

Note: in order to execute this request, you will need to substitute $JWT_TOKEN with a valid
JWT token. This token should belong to a user with TENANT_ADMIN role. You can use
following guide to get the token.
Also, you can provision new relation using POST request to the following URL
http(s)://host:port/api/relation
For example
 create-relation.sh
 create-relation.json

resources/create-relation.sh

curl -v -X POST -d @create-relation.json

http://localhost:8080/api/relation \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"

Note: Don’t forget to replace $FROM_ASSET_ID and $TO_ASSET_ID with valid asset
ids. Note: One can relate any entities. For example, assets to devices or assets to users. You
can receive them as a result of previous REST API call or use Web UI.

Step 2: Assign attributes to the assets

ThingsBoard provides the ability to assign attributes to entities and manage them. This topic is
covered in separate guide https://thingsboard.io/docs/user-guide/attributes

Code_Course – Name_Course
Step 3: Upload telemetry data from devices

ThingsBoard provides the ability to work with telemetry data for devices and other entities.
This topic is covered in separate guide. https://thingsboard.io/docs/user-guide/telemetry

Step 4: Creating Rules for Alarms

ThingsBoard provides the ability to raise alarms using rule engine for devices and other
entities. This topic is covered in the separate guide. https://thingsboard.io/docs/user-
guide/alarms

Step 5: Design your dashboard

Please import (https://thingsboard.io/docs/user-guide/ui/dashboards/#dashboard-import) the

following dashboard (https://thingsboard.io/docs/user-
guide/resources/region_fields_dashboard.json) that demonstrates Map, Alarm, Entity Table
and Charts widgets.

3. Rule Engine

Rule Engine is an easy to use framework for building event-based workflows. There are 3 main
components:

Message - any incoming event. It can be an incoming data from devices, device life-cycle event,
REST API event, RPC request, etc.

Rule Node - a function that is executed on an incoming message. There are many different Node
types that can filter, transform or execute some action on incoming Message.

Rule Chain - nodes are connected with each other with relations, so the outbound message from
rule node is sent to next connected rule nodes.

Code_Course – Name_Course
Rule Engine Message is a serializable, immutable data structure that represent various messages
in the system. For example:

• Incoming telemetry, attribute update or RPC call from device;

• Entity life-cycle event: created, updated, deleted, assigned, unassigned, attributes
updated;
• Device status event: connected, disconnected, active, inactive, etc;
• Other system events.

Rule Engine Message contains the following information:

• Message ID: time based, universally unique identifier;

• Originator of the message: Device, Asset or other Entity identifier;
• Type of the message: “Post telemetry” or “Inactivity Event”, etc;
• Payload of the message: JSON body with actual message payload;
• Metadata: List of key-value pairs with additional data about the message.

Rule Node is a basic component of Rule Engine that process single incoming message at a time
and produce one or more outgoing messages. Rule Node is a main logical unit of the Rule Engine.
Rule Node can filter, enrich, transform incoming messages, perform action or communicate with
external systems.

Rule Nodes may be related to other rule nodes. Each relation has relation type, a label used to
identify logical meaning of the relation. When rule node produces the outgoing message it always
specifies the relation type which is used to route message to next nodes.

Typical rule node relations are “Success” and “Failure”. Rule nodes that represent logical
operations may use “True” or “False”. Some specific rule nodes may use completely different
relation types, for example: “Post Telemetry”, “Attributes Updated”, “Entity Created”, etc.

Rule Chain is a logical group of rule nodes and their relations. For example, the rule chain below
will:

Code_Course – Name_Course
  save all telemetry messages to the database;
 raise “High Temperature Alarm” if temperature field in the message will be higher then 50
degrees;
 raise “Low Temperature Alarm” if temperature field in the message will be lower then -40
degrees;
 log failure to execute the temperature check scripts to console in case of logical or syntax
error in the script.

Tenant administrator is able to define one Root Rule Chain and optionally multiple other rule
chains. Root rule chain handles all incoming messages and may forward them to other rule chains
for additional processing. Other rule chains may also forward messages to different rule chains.

For example, the rule chain below will:

raise “High Temperature Alarm” if temperature field in the message will be higher then 50 degrees;

clear “High Temperature Alarm” if temperature field in the message will be less then 50 degrees;

forward events about “Created” and “Cleared” alarms to external rule chain that handles
notifications to corresponding users.

There are three possible results of message processing: Success, Failure and Timeout. The message
processing attempt is marked as “Success” when the last rule node in the processing chain
successfully process the message. The message processing attempt is marked as “Failure” if one
of the rule nodes produce “Failure” of message processing, and there is no rule nodes to handle
that failure. The message processing attempt is marked as “Timeout” when overall time of
processing exceed configurable threshold.

See diagram below and let’s review the possible scenarios:

Code_Course – Name_Course
If the “Transformation” script fails, the message is not marked as “Failed”, because there is a “Save
to DB” node connected with “Failure” relation. If the “Transformation” script is successful, it will
be pushed to “External System” with the REST API call. If the external system is overloaded, the
REST API call may “hang” for some time. Let’s assume the overall timeout for message pack
processing is 20 seconds. Let’s ignore Transformation script execution time because it is < 1ms.
So, if the “External System” will reply within 20 seconds, the message will be successfully
processed. Similar, if “Save to DB” call will succeed, the message will be successfully processed.
However, if the external system will not reply within 20 seconds, the message processing attempt
will be marked as “timed-out”. Similar, if “Save to DB” call will fail, the message will be marked
Rule Engine subscribe to queues on startup and polls for new messages. There is always “Main”
topic that is used as a main entry point for new incoming messages. You may configure multiple
queues using thingsboard.yml or environment variables. Once configured, you may put message
to the other topic using “Checkpoint” node. This automatically acknowledges corresponding
message in the current topic.

The definition of the queue consists of the following parameters:

name - used for statistics and logging;

topic - used by Queue implementations to produce and consume messages;

poll-interval - duration in milliseconds between polling of the messages if no new messages arrive;

Code_Course – Name_Course
partitions - number of partitions to associate with this queue. Used for scaling the number of
messages that can be processed in parallel;

pack-processing-timeout - interval in milliseconds for processing of the particular pack of

messages returned by consumer;

submit-strategy - defines logic and order of submitting messages to rule engine. See separate
paragraph below.

processing-strategy - defines logic of acknowledgement of the messages. See separate paragraph

below.as failed.

Figure 10.2 Rule Engine Architecture

4. Integration

ThingsBoard Platform integrations feature was designed for two primary use cases /
deployment options.

 Connect existing NB IoT, LoRaWAN, SigFox and other devices with specific
payload formats directly to ThingsBoard platform.
 Stream data from devices connected to existing IoT Platforms to enable real-time
interactive dashboards and efficient data processing.

Code_Course – Name_Course
Both use cases have few things in common. There is a server-side component in the
deployment topology that prevents direct access to device and provides set of APIs to interact
with the device in the field instead. The payload format of the device is not well defined.
Often two devices that have similar sensors have different payload formats depending on a
vendor or even software version.

The job of ThingsBoard Integration is to provide secure and reliable API bridge between core
platform features (telemetry collection, attributes and RPC calls) and specific third-party
platform APIs.

At the moment ThingsBoard supports various integration protocols. Most popular are HTTP,
MQTT and OPC-UA. Platform also support integration with specific LoRaWAN Network
servers, Sigfox backend, various NB IoT devices using raw UDP and TCP integrations. AWS
IoT, IBM Watson and Azure Event Hub allows to subscribe to the data feed from devices via
MQTT or AMQP.

The list of platform integrations is constantly growing, however, the general integration
concepts are the same and explained below.

Once message arrives from External Platform to ThingsBoard it passes validation according
to platform specific payload format and security rules. Once message is validated
ThingsBoard Integration invokes assigned Uplink Data Converter to extract sub-set of
meaningful information out of the incoming message. The message is basically transformed
from device and platform specific payload to the format that ThingsBoard uses.

Since TB PE v2.0, Rule Engine is also able to push Downlink messages to the integrations.
The example of such message may be:

 notification about shared attribute (configuration) update;

 notification about oneway RPC call to trigger some action on the device;
 any custom message from the rule engine.

The most common use cases are:

Code_Course – Name_Course
  changing data upload frequency based on shared attribute value change
 triggering firmware update procedure based on shared attribute value change
 changing device state based on rpc call;

HTTP Integration allows to convert existing protocols and payload formats to ThingsBoard
message format and is useful in several deployment scenarios:

stream device and/or asset data from external system, IoT platform or connectivity provider
back-end.

stream device and/or asset data from your custom application running in the cloud.

connect the existing device with custom HTTP based protocol to ThingsBoard.

Code_Course – Name_Course