Getting Started with ThingsBoard

Introduction
Prerequisites
Step 1. Provision Device
Step 2. Connect device
Step 3. Create Dashboard
Step 4. Configure Alarm Rules
Step 5. Create Alarm
Step 6. Alarm notifications
Step 7. Assign Device and Dashboard to Customer
Next steps
Your feedback

Introduction

The goal of this tutorial is to demonstrate the basic usage of the most popular ThingsBoard features. 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.

Prerequisites

You will need to have ThingsBoard server up and running. The easiest way is to use Live Demo server.

The alternative option is to install ThingsBoard using Installation Guide. Windows users should follow this guide. Linux users that have docker installed should execute the following commands:

mkdir -p ~/.mytb-data && sudo chown -R 799:799 ~/.mytb-data
mkdir -p ~/.mytb-logs && sudo chown -R 799:799 ~/.mytb-logs
docker run -it -p 8080:9090 -p 7070:7070 -p 1883:1883 -p 5683-5688:5683-5688/udp -v ~/.mytb-data:/data \
-v ~/.mytb-logs:/var/log/thingsboard --name mytb --restart always thingsboard/tb-postgres

These commands install ThingsBoard and load demo data and accounts.

ThingsBoard UI will be available using the URL: http://localhost:8080. You may use username [email protected] and password tenant. More info about demo accounts is available here.

Step 1. Provision Device

For simplicity, we will provision the device manually using the UI.

Login to your ThingsBoard instance and navigate to the "Entities". Then click 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;
The window to check the device's connection to ThingsBoard will open. This step is optional. Select the messaging protocol and your operating system. Install the necessary client tools and copy the command;
Execute previously copied command. The device state should be changed from "Inactive" to "Active" and you should see the published "temperature" readings. Then, close connectivity window;
Your first device has been added. As long as you have one device. But as new devices are added, they will be added to the top of the table, since the table sort devices using the time of the creation by default;
When adding a new device, you will receive a notification. You can view it by clicking on the "bell" icon in the top right corner.

Login to your ThingsBoard instance and navigate to the "Entities". Then click 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;

The window to check the device's connection to ThingsBoard will open. This step is optional. Select the messaging protocol and your operating system. Install the necessary client tools and copy the command;

Execute previously copied command. The device state should be changed from "Inactive" to "Active" and you should see the published "temperature" readings. Then, close connectivity window;

Your first device has been added. As long as you have one device. But as new devices are added, they will be added to the top of the table, since the table sort devices using the time of the creation by default;

When adding a new device, you will receive a notification. You can view it by clicking on the "bell" icon in the top right corner.

Learn more about notifications and how to configure them here.

You may also use:

Bulk provisioning to provision multiple devices from a CSV file using UI;
Device provisioning to allow device firmware to automatically provision the device, so you don’t need to configure each device manually;
REST API to provision devices and other entities programmatically;

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. Note that the device state is "Inactive";
Click "Copy access token". Token will be copied to your clipboard. Save it to a safe place.

Click on the device row in the table to open device details. Note that the device state is "Inactive";

Click "Copy access token". Token will be copied to your clipboard. Save it to a safe place.

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.

HTTPLinux, macOS or Windows

MQTTLinux or macOS

MQTTWindows

CoAPLinux or macOS

Other ProtocolsModbus, SNMP, LoRaWAN, etc

Install cURL for Ubuntu:

sudo apt-get install curl

Install cURL for macOS:

brew install curl

Install cURL for Windows:

Starting Windows 10 b17063, cURL is available by default. More info is available in this MSDB blog post. If you are using older version of Windows OS, you may find official installation guides here.

This command works for Windows, Ubuntu and macOS, assuming the cURL tool is already installed.

Replace $THINGSBOARD_HOST_NAME_AND_PORT and $ACCESS_TOKEN with corresponding values.

curl -v -X POST -d "{\"temperature\": 25}" $THINGSBOARD_HOST_NAME_AND_PORT/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

For example, $THINGSBOARD_HOST_NAME_AND_PORT reference live demo server, $ACCESS_TOKEN is ABC123:

curl -v -X POST -d "{\"temperature\": 25}" https://demo.thingsboard.io/api/v1/ABC123/telemetry --header "Content-Type:application/json"

For example, $THINGSBOARD_HOST_NAME_AND_PORT reference your local installation, port is 8080, $ACCESS_TOKEN is ABC123:

curl -v -X POST -d "{\"temperature\": 25}" http://localhost:8080/api/v1/ABC123/telemetry --header "Content-Type:application/json"

Install mqtt client for Ubuntu:

sudo apt-get install mosquitto-clients

Install cURL for macOS:

brew install mosquitto-clients

Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.

mosquitto_pub -d -q 1 -h "$THINGSBOARD_HOST_NAME" -p "1883" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -m {"temperature":25}

For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:

mosquitto_pub -d -q 1 -h "demo.thingsboard.io" -p "1883" -t "v1/devices/me/telemetry" -u "ABC123" -m {"temperature":25}

For example, $THINGSBOARD_HOST_NAME reference your local installation, $ACCESS_TOKEN is ABC123:

mosquitto_pub -d -q 1 -h "localhost" -p "1883" -t "v1/devices/me/telemetry" -u "ABC123" -m {"temperature":25}

Successful output should look similar to this one:

Client mosqpub|xxx sending CONNECT
Client mosqpub|xxx received CONNACK
Client mosqpub|xxx sending PUBLISH (d0, q1, r0, m1, 'v1/devices/me/telemetry', ... (16 bytes))
Client mosqpub|xxx received PUBACK (Mid: 1)
Client mosqpub|xxx sending DISCONNECT

Note: Since ThingsBoard 3.2, you are able to use basic MQTT credentials (combination of client id, user name and password ) and customize topic names and payload type using Device Profile. See more info here.

Use the instructions listed below to download, install, setup and run mosquitto_pub in Windows:

Download and Install Eclipse Mosquitto. Visit Mosquitto’s official download page and choose the appropriate Windows installer (32-bit or 64-bit depending on your system).
Once downloaded, run the installer and follow the instructions. This will install Mosquitto on your Windows machine. By default, Mosquitto is installed in ‘C:\Program Files\mosquitto’;
Update the System’s “Path” variable. The executables ‘mosquitto_pub.exe’ and ‘mosquitto_sub.exe’ are located in the directory where you installed the Mosquitto. You need to add this directory to your system’s “Path” environment variable so that Windows can find these executables regardless of the current directory.

To add the Mosquitto directory to the “Path” variable, follow these steps:

Press the Win + X, then select "System". Then click on the "System" page;
Navigate to the "About" section, then click "Advanced system settings";
In the "System Properties" pop-up window, click "Environment Variables" button on the "Advanced" tab;
In the "Environment Variables" pop-up window select the "Path", then click on the "Edit" button;
In the "Edit environment variable" pop-up window click on the "New" button and add the path to the directory containing 'mosquitto_pub.exe' and 'mosquitto_sub.exe' ('C:\Program Files\mosquitto' by default). Click "OK" button;
Click "OK" button to save changes in the environment variables;
Finally, click "OK" button to apply all changes in the system properties.

Press the Win + X, then select "System". Then click on the "System" page;

Navigate to the "About" section, then click "Advanced system settings";

In the "System Properties" pop-up window, click "Environment Variables" button on the "Advanced" tab;

In the "Environment Variables" pop-up window select the "Path", then click on the "Edit" button;

In the "Edit environment variable" pop-up window click on the "New" button and add the path to the directory containing 'mosquitto_pub.exe' and 'mosquitto_sub.exe' ('C:\Program Files\mosquitto' by default). Click "OK" button;

Click "OK" button to save changes in the environment variables;

Finally, click "OK" button to apply all changes in the system properties.

Open the Terminal and replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.

mosquitto_pub -d -q 1 -h "$THINGSBOARD_HOST_NAME" -p "1883" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -m {"temperature":25}

For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:

mosquitto_pub -d -q 1 -h "demo.thingsboard.io" -p "1883" -t "v1/devices/me/telemetry" -u "ABC123" -m {"temperature":25}

For example, $THINGSBOARD_HOST_NAME reference your local installation, $ACCESS_TOKEN is ABC123:

mosquitto_pub -d -q 1 -h "localhost" -p "1883" -t "v1/devices/me/telemetry" -u "ABC123" -m {"temperature":25}

Successful output should look similar to this one:

Client mosqpub|xxx sending CONNECT
Client mosqpub|xxx received CONNACK
Client mosqpub|xxx sending PUBLISH (d0, q1, r0, m1, 'v1/devices/me/telemetry', ... (16 bytes))
Client mosqpub|xxx received PUBACK (Mid: 1)
Client mosqpub|xxx sending DISCONNECT

Install coap-cli. Assuming you have Node.js and NPM installed on your Windows/Linux/MacOS machine, execute the following command:

npm install coap-cli -g

Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.

echo -n '{"temperature": 25}' | coap post coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry

For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:

echo -n '{"temperature": 25}' | coap post coap://demo.thingsboard.io/api/v1/ABC123/telemetry

For example, $THINGSBOARD_HOST_NAME reference your local installation, $ACCESS_TOKEN is ABC123:

echo -n '{"temperature": 25}' | coap post coap://localhost/api/v1/ABC123/telemetry

ThingsBoard supports many other protocols. Please explore Connectivity Diagram to find solution that matches your use case.

Note: We recommend to start exploring the platform capabilities with simulated devices that are connected over MQTT.

Once you have successfully published the “temperature” readings, you should immediately see them in the Device Telemetry Tab:

Navigate to the "Latest telemetry" tab. You should see the previously published "temperature" readings;
Close the device details tab and refresh the "Devices" table. The device state should be changed from "Inactive" to "Active".

Navigate to the "Latest telemetry" tab. You should see the previously published "temperature" readings;

Close the device details tab and refresh the "Devices" table. The device state should be changed from "Inactive" to "Active".

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;
Your first dashboard has been created. As long as you have one dashboard. But as new dashboards are added, they will be added to the top of the table, since the table sort dashboards using the time of the creation by default. Click on the row to open the 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;

Your first dashboard has been created. As long as you have one dashboard. But as new dashboards are added, they will be added to the top of the table, since the table sort dashboards using the time of the creation by default. Click on the row to open the dashboard.

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" button;
Input alias name, for example, "My Device". 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";
Click "Save";
Finally, click "Apply changes" in the dashboard editor to save the changes.

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" button;

Input alias name, for example, "My Device". 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";

Finally, click "Apply changes" in the dashboard editor to save the changes.

Entity Table widget displays the latest values with list of entities that matches selected alias and filter with ability of additional full text search and pagination options.

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 "Entities table" 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 "My Device" entity alias. Then click on the "Latest data key" 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. Apply changes.

Enter edit mode. Click on the "Add new widget" button;

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 "My Device" entity alias. Then click on the "Latest data key" 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. Apply changes.

Congratulations! You have added the first widget. Now you can send new telemetry reading and it will immediately appear in the table.

Chart widgets allow you to display time series data with customizable line charts and bar charts.

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" widget bundle;
Select the "Timeseries Line Chart" widget;
Click the "Add" datasource button;
Select "My Device" 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;
Now open time selection window. Change the interval and aggregation function. Update the time window and apply changes.

Click the "Add new widget" icon in the bottom right corner of the screen;

Select the "Timeseries Line Chart" widget;

Select "My Device" 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;

Now open time selection window. Change the interval and aggregation function. Update the time window and apply changes.

Congratulations! You have added a chart widget. Now you can send new telemetry reading and it will immediately appear in the chart.

Alarms table widget displays alarms related to the specified entity in the certain time window (for example, “Alarms table”). Alarm widget is configured by specifying an entity as the alarm source, and the corresponding alarm fields.

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;
Select the "Alarms table" widget;
Select the "Entity" alarm source and "My Device" alias. Click "Add";
Drag and Drop the Timeseries Line Chart widget to the top right corner of the dashboard to make room for the Alarm widget;
Scroll down and locate the new "Alarms" widget. Drag and Drop Alarm widget to the free space and resize it. Apply changes.

Select the "Entity" alarm source and "My Device" alias. Click "Add";

Drag and Drop the Timeseries Line Chart widget to the top right corner of the dashboard to make room for the Alarm widget;

Scroll down and locate the new "Alarms" widget. Drag and Drop Alarm widget to the free space and resize it. 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 "Profiles". Then click on the "Device profiles" page;
Click on the default device profile row to open its details;
Select the "Alarm rules" tab and click "pencil" button to enter edit mode;
Click "Add alarm rule" button;
Specify alarm type and click the "+" icon to add alarm rule condition;
Click the "Add key filter" button to specify a condition;
Select key type, input key name, select value type, and click "Add" filter;
Select operation and input threshold value. Click "Add";
Click "Save";
Finally, click "Apply changes".

Navigate to the "Profiles". Then click on the "Device profiles" page;

Click on the default device profile row to open its details;

Select the "Alarm rules" tab and click "pencil" button to enter edit mode;

Specify alarm type and click the "+" icon to add alarm rule condition;

Click the "Add key filter" button to specify a condition;

Select key type, input key name, select value type, and click "Add" filter;

Select operation and input threshold value. Click "Add";

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;
You may acknowledge and clear the alarms;
When you receive a new alarm, you will receive a message in the notification center. You can view the message by clicking on the bell icon in the upper right corner.

Notice that the new temperature telemetry causes a new active alarm;

You may acknowledge and clear the alarms;

When you receive a new alarm, you will receive a message in the notification center. You can view the message by clicking on the bell icon in the upper right corner.

Step 6. Alarm notifications

It’s quite easy to set up notifications using the Notification center. ThingsBoard Notification center allows you to send notifications to the end-users. Learn more about notifications and how to configure them here.

We also recommend reviewing alarm rule examples and documentation about alarm notifications.

Step 7. Assign Device and Dashboard to Customer

One of the most important ThingsBoard features is the ability to assign Dashboards to Customers. You may assign different devices to different customers. Then, you may create a Dashboard(s) and assign it to multiple customers. Each customer user will see his own devices and will not be able to see devices or any other data that belongs to a different customer.

Step 7.1 Create customer

Let’s create a customer with title “My New Customer”. Please see instruction below:

Navigate to the Customers page;
Click the "+" sign to add a customer;
Input customer title and click "Add".

Step 7.2 Assign device to Customer

Let’s assign device to the customer. The customer users will have ability to read and write telemetry and send commands to devices.

Open "Devices" page, then select your device to open its details;
Click "Assign to customer" button;
Select the customer to whom you want to assign the device, and then click "Assign";
You have changed the owner of the device. In the "Customer" column, you can see the owners name of the device;

Open "Devices" page, then select your device to open its details;

Select the customer to whom you want to assign the device, and then click "Assign";

You have changed the owner of the device. In the "Customer" column, you can see the owners name of the device;

Make sure that the device is assigned to your customer.

Navigate to "Customers" page to make sure that the device is assigned to your customer. Find your customer in the list of customers and then click on the "Manage customer devices" icon;
The device is with your client.

You can make the customer the owner of the device during its creation stage.

Click on the "+" icon in the top right corner of the table. Input device name (for example, "Thermostat") and navigate to the "Customer" tab;
Select the customer to whom you want to assign the new device. Then click "Add";
The device has been created, and it immediately belongs to the selected customer.

Click on the "+" icon in the top right corner of the table. Input device name (for example, "Thermostat") and navigate to the "Customer" tab;

Select the customer to whom you want to assign the new device. Then click "Add";

The device has been created, and it immediately belongs to the selected customer.

Step 7.3 Assign dashboard to Customer

Let’s share our dashboard with the customer. The customer users will have read-only access to the dashboard.

Open "Dashboards" page. Mark your dashboard and click the "Assign dashboards" icon;
Mark "My New Customer" and click "Assign";
Navigate to the "Customers" page. Click "Manage customer dashboards" icon for "My New Customer";
"My New Dashboard" is assigned to your customer.

Open "Dashboards" page. Mark your dashboard and click the "Assign dashboards" icon;

Mark "My New Customer" and click "Assign";

Navigate to the "Customers" page. Click "Manage customer dashboards" icon for "My New Customer";

"My New Dashboard" is assigned to your customer.

Step 7.4 Create customer user

Finally, let’s create a user that will belong to the customer and will have read-only access to the dashboard and the device. You may optionally configure the dashboard to appear just after user login to the platform web UI.

Navigate to "Customers" page. Find your customer in the list of customers and then click on the "Manage customer users" icon;
Click the "Add user" icon in the top right corner of the table;
Specify email that you will use to login as a customer user and click "Add";
Copy the activation link and save it to a safe place. You will use it later to set the password. Click "OK";
Click on the created user to open details. Click "pencil" icon to enter edit mode;
Select default dashboard and check "Always fullscreen". Apply changes.

Navigate to "Customers" page. Find your customer in the list of customers and then click on the "Manage customer users" icon;

Click the "Add user" icon in the top right corner of the table;

Specify email that you will use to login as a customer user and click "Add";

Copy the activation link and save it to a safe place. You will use it later to set the password. Click "OK";

Click on the created user to open details. Click "pencil" icon to enter edit mode;

Select default dashboard and check "Always fullscreen". Apply changes.

Step 7.5 Activate customer user

Paste the previously copied link into a new browser tab and press Enter. Come up with and enter a password twice, then press "Create Password". You will automatically login as a customer user;
You have logged in as a Customer User. You may browse the data and acknowledge/clear alarms.

Paste the previously copied link into a new browser tab and press Enter. Come up with and enter a password twice, then press "Create Password". You will automatically login as a customer user;

You have logged in as a Customer User. You may browse the data and acknowledge/clear alarms.

Next steps

Connect your device - Learn how to connect devices based on your connectivity technology or solution.
Data visualization - These guides contain instructions how to configure complex ThingsBoard dashboards.
Data processing & actions - Learn how to use ThingsBoard Rule Engine.
IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.
Hardware samples - Learn how to connect various hardware platforms to ThingsBoard.
Advanced features - Learn about advanced ThingsBoard features.
Contribution and Development - Learn about contribution and development in ThingsBoard.

Your feedback

Don’t hesitate to star ThingsBoard on github to help us spread the word. If you have some questions about this sample - post it on the forum.

On this page

Getting Started with ThingsBoard

Introduction

Prerequisites

Step 1. Provision Device

Step 2. Connect device

Step 3. Create Dashboard

Step 3.1 Create Empty Dashboard

Step 3.2 Add Entity Alias

Step 3.3 Add Table Widget

Step 3.4 Add Chart Widget

Step 3.5 Add Alarm Widget

Step 4. Configure Alarm Rules

Step 5. Create Alarm

Step 6. Alarm notifications

Step 7. Assign Device and Dashboard to Customer

Step 7.1 Create customer

Step 7.2 Assign device to Customer

Step 7.3 Assign dashboard to Customer

Step 7.4 Create customer user

Step 7.5 Activate customer user

Next steps

Your feedback