Week 7

Ts. Dr. Ezmin Binti Abdullah

Lab tutorial using ThingsBoard

Apparatus
1. ThingsBoard
https://www.thingsboard.io/
2. Google Colab
https://colab.research.google.com/

1.1 ThingsBoard

A. What is ThingsBoard?
Procedures
In this part, you are expected to read information about ThingsBoard.

1. What is ThingsBoard?
https://thingsboard.io/docs/getting-started-guides/what-is-thingsboard/

2. Use Cases.
a. https://thingsboard.io/smart-energy/
b. https://thingsboard.io/smart-farming/
c. https://thingsboard.io/fleet-tracking/
d. https://thingsboard.io/smart-metering/
e. https://thingsboard.io/use-cases/environment-monitoring/
f. https://thingsboard.io/use-cases/smart-office/
g. https://thingsboard.io/use-cases/water-metering/

B. How To Register Your Account

Procedures
In this part, you are expected to register your account.
1. ThingsBoard is an open-source IoT platform. Therefore, you can install the platform on
premise. The installation procedure is stated in the following URL:
https://thingsboard.io/docs/user-guide/install/installation-options/
The fastest installation is to use docker. However, we need a high spec computer if we want to
install Docker Desktop (https://docs.docker.com/desktop/). Therefore, we are going to use the
“Live demo” option.
2. Click “Live demo” option and click “Signup”
https://demo.thingsboard.io/signup
3. Choose an account - use your gmail account.

C. How To Use ThingsBoard

Procedures
In this part, you are expected to learn the basic usage of the most popular ThingsBoard
features.
https://thingsboard.io/docs/getting-started-guides/helloworld/
You will learn how to:
● Connect devices to ThingsBoard;
● Push data from devices to ThingsBoard;
● Build real-time end-user dashboards;
● Define thresholds and trigger alarms;
● Push notifications about new alarms over email, sms or other systems.
We will connect and visualize data from the temperature sensor to keep it simple.

Step 1. Provision Device

For simplicity, we will provision the device manually using the UI.
● Login to your ThingsBoard instance and open the Devices page.
● Click on the "+" icon in the top right corner of the table and then select "Add new device".
● Input device name. For example, "My New Device". No other changes required at this
time. Click "Add" to add the device.
● Now your device should be listed first, since the table sorts devices using the time of the
creation by default.

Step 2. Connect device

To connect the device you need to get the device credentials first. ThingsBoard supports
various device credentials. We recommend using default auto-generated credentials which is
“access token” for this guide.
● Click on the device row in the table to open device details
● Click "Copy access token". Token will be copied to your clipboard. Save it to a safe
place.

This is my “access token” for my device. Your “access token” must be different from mine.
eYo1rV9jKU2N4BB7W5XJ

Now you are ready to publish telemetry data on behalf of your device. We will use simple
commands to publish data over HTTP or MQTT in this example.

=== Using Google Colab ===

!sudo apt-get install curl

Using HTTP - https://thingsboard.io/docs/reference/http-api/

#!curl -v -X POST -d "{\"temperature\": 25}"
$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-
Type:application/json"
!curl -v -X POST -d "{\"temperature\": 25}"
https://demo.thingsboard.io/api/v1/eYo1rV9jKU2N4BB7W5XJ/telemetry --header
"Content-Type:application/json"

Once you have successfully published the “temperature” readings, you should immediately see
them in the Device Telemetry Tab:
● Click on the device row in the table to open device details
● Navigate to the telemetry tab.

Step 3. Create Dashboard

We will create a dashboard and add the most popular widgets. See the instructions below.

Step 3.1 Create Empty Dashboard

● Open the Dashboards page. Click on the "+" icon in the top right corner. Select "Create
new dashboard".
● Input dashboard name. For example, "My New Dashboard". Click "Add" to add the
dashboard.
● Now your dashboard should be listed first, since the table sorts dashboards using the
time of the creation by default. Click on the "Open dashboard" icon.
Step 3.2 Add Entity Alias
Alias is a reference to a single entity or group of entities that are used in the widgets. Alias may
be static or dynamic. For simplicity, we will use “Single entity” alias references the one and only
entity (“My New Device” in our case). It is possible to configure an alias that references multiple
devices. For example, devices of a certain type or related to a certain asset. You may learn
more about different aliases here.
● Enter edit mode. Click on the pencil button in the bottom right corner.
● Click the "Entity Aliases" icon in the top right part of the screen. You will see an empty
list of Entity aliases.
● Click "Add alias".
● Input alias name, for example, "MyDevice". Select the "Single entity" Filter type. Select
"Device" as Type and type "My New" to enable autocomplete. Choose your device from
the auto-complete and click on it.
● Click "Add" and then "Save".
● Finally, click "Apply changes" in the dashboard editor to save the changes. Then you
should enter edit mode again.

Step 3.3 Add Table Widget

To add the table widget we need to select it from the widget library. Widgets are grouped into
widget bundles. Each widget has a data source. This is how the widget “knows” what data to
display. To see the latest value of our “temperature” data that we sent during step 2, we should
configure the data source.
● Enter edit mode. Click on the "Add new widget" button.
● Select the "Cards" widget bundle. Select the "Latest values" tab. Click on the header of
the Entities widget. The "Add Widget" window will appear.
● Click "Add" to add the data source. A widget may have multiple data sources, but we will
use only one in this case.
● Select "MyDevice" entity alias. Then click on the input field on the right. The auto-
complete with available data points will appear. Select "temperature" data point and click
"Add".
● Resize the widget to make it a little bigger. Just drag the bottom right corner of the
widget. You can also play with the advanced settings if you would like to edit the widget.

Congratulations! You have added the first widget. Now you can send new telemetry reading and
it will immediately appear in the table.
Step 3.4 Add Chart Widget
To add the chart widget we need to select it from the widget library. Chart widget displays
multiple historical values of the same data key (“temperature” in our case). We should also
configure the time window to use the chart widget.
● Enter Edit mode.
● Click the "Add new widget" icon in the bottom right corner of the screen.
● Click the "Create new widget" icon.
● Select the "Charts" bundle. Scroll down and click on the "Timeseries - Flot" chart widget.
● Click the "Add Datasource" button.
● Select "MyDevice" Alias. Select the "temperature" key. Click "Add".
● Drag and Drop your widget to the desired space. Resize the widget. Apply changes.
● Publish different telemetry values multiple times Step 2. Note that the widget displays
only one minute of data by default.
● Enter Edit mode. Open time selection window. Change the interval and aggregation
function. Update the time window and apply changes.

Step 3.5 Add Alarm Widget

● Enter Edit mode.
● Click the "Add new widget" icon in the bottom right corner of the screen.
● Click the "Create new widget" icon.
● Select the "Alarm widgets" bundle. Click on the "Alarms" widget header.
● Select the "Entity" alarm source and "MyDevice" alias. Click "Add"
● Scroll down and locate the new "Alarms" widget. Drag and Drop widget to the top right
corner of the dashboard.
● Resize the widget and apply changes.

Congratulations! You have added an alarm widget. Now it’s time to configure alarm rules and
raise some alarms.
Step 4. Configure Alarm Rules
We will use the alarm rules feature to raise alarm when the temperature reading is greater than
25 degrees. For this purpose, we should edit the device profile and add a new alarm rule. The
“My New Device” is using the “Default” device profile. We recommend creating dedicated device
profiles for each corresponding device type but will skip this step for simplicity.
● Navigate to the device profiles page.
● Click the default profile row. This will open device profile details.
● Select the "Alarm Rules" tab and toggle edit mode.
● Click "Add alarm rule".
● Specify alarm type and click the "+" icon to add alarm rule condition.
High Temperature
● Click the "Add key filter" button to specify a condition.
● Select key type, input key name, select value type, and click "Add".
Timeseries, temperature, 123 Numeric
● Select operation and input threshold value. Click "Add".
Greater than 25

● Click "Save".
● Finally, click "Apply changes".

Step 5. Create Alarm

Now our alarm rule is active (see Step 4), and we should send new telemetry on behalf of the
device (see Step 2) to trigger the alarm. Note that the temperature value should be 26 or higher
to raise the alarm. Once we send a new temperature reading, we should immediately see a new
alarm on our dashboard.
● Notice that the new temperature telemetry causes a new active alarm.
● User may acknowledge and clear the alarms.
Step 6. Test your Alarm

=== Using Google Colab ===

import time
print(time.ctime())
time.sleep(10)
!curl -v -X POST -d "{\"temperature\": 21}"
https://demo.thingsboard.io/api/v1/eYo1rV9jKU2N4BB7W5XJ/telemetry --header
"Content-Type:application/json" &> /dev/null

print (time.ctime())
time.sleep(10)
!curl -v -X POST -d "{\"temperature\": 22}"
https://demo.thingsboard.io/api/v1/eYo1rV9jKU2N4BB7W5XJ/telemetry --header
"Content-Type:application/json" &> /dev/null

print (time.ctime())
time.sleep(10)
!curl -v -X POST -d "{\"temperature\": 23}"
https://demo.thingsboard.io/api/v1/eYo1rV9jKU2N4BB7W5XJ/telemetry --header
"Content-Type:application/json" &> /dev/null

print (time.ctime())
time.sleep(10)
!curl -v -X POST -d "{\"temperature\": 24}"
https://demo.thingsboard.io/api/v1/eYo1rV9jKU2N4BB7W5XJ/telemetry --header
"Content-Type:application/json" &> /dev/null

print (time.ctime())
time.sleep(10)
!curl -v -X POST -d "{\"temperature\": 25}"
https://demo.thingsboard.io/api/v1/eYo1rV9jKU2N4BB7W5XJ/telemetry --header
"Content-Type:application/json" &> /dev/null

print (time.ctime())
time.sleep(10)
!curl -v -X POST -d "{\"temperature\": 26}"
https://demo.thingsboard.io/api/v1/eYo1rV9jKU2N4BB7W5XJ/telemetry --header
"Content-Type:application/json" &> /dev/null

print (time.ctime())
time.sleep(10)
!curl -v -X POST -d "{\"temperature\": 30}"
 https://demo.thingsboard.io/api/v1/gwT6obBhTkoDKx8gbnpz/telemetry --header
"Content-Type:application/json" &> /dev/null

Reference
1. https://thingsboard.io/docs/getting-started-guides/what-is-thingsboard/
2. https://thingsboard.io/docs/getting-started-guides/helloworld/
3. https://thingsboard.io/docs/user-guide/dashboards/
4. https://thingsboard.io/docs/user-guide/rule-engine-2-0/re-getting-started/
5. https://thingsboard.io/docs/reference/http-api/

THE END