Getting Started with ThingsBoard Professional Edition

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. Share dashboard with customers
Next steps
Your feedback

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;
Set up push notifications about new alarms over email, SMS, or other systems.

In this guide, we will connect and visualize data from the temperature sensor to keep it simple.

Prerequisites

You will need to have access to ThingsBoard Professional Edition. The easiest way is to use ThingsBoard Cloud server. The alternative option is to install ThingsBoard using Installation Guide.

Step 1. Provision device

As an example, let’s add a device that will transmit the following data to ThingsBoard platform: the device’s name and temperature readings as telemetry.

To add a new device, follow these steps:

Login to your ThingsBoard instance and navigate to the "Entities" section. Then go to the "Devices" page;
By default, you navigate to the device group “All”. Click on the "+" icon in the top right corner of the table and then select "Add new device";
Enter the device name. For example, "My New Device". No other changes are required at this time. Click "Add";
Device is created. A window will open where you can check the device's connection to ThingsBoard. This step is optional. Let's close this window for now and return to checking the connection in the next step in more detail;
Your first device has been added. As new devices are added, they will be added to the top of the table, since the table sorts devices using the time of the creation by default.

Login to your ThingsBoard instance and navigate to the "Entities" section. Then go to the "Devices" page;

By default, you navigate to the device group “All”. Click on the "+" icon in the top right corner of the table and then select "Add new device";

Enter the device name. For example, "My New Device". No other changes are required at this time. Click "Add";

Device is created. A window will open where you can check the device's connection to ThingsBoard. This step is optional. Let's close this window for now and return to checking the connection in the next step in more detail;

Your first device has been added. As new devices are added, they will be added to the top of the table, since the table sorts 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.

You can view notification 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 provision the device automatically, so you don’t need to configure each device manually;
REST API to provision devices and other entities programmatically;

Step 2. Connect device

Now, let’s check the connection of our device to the ThingsBoard platform. To accomplish this, use the “Check connectivity” functionality to publish telemetry data (for example, temperature readings) on behalf of your device. You can do this both while adding the device and after.

Click on the your device, and click the "Check connectivity” button in the "Device details" window;
In the opened window select the messaging protocol and your operating system. Install the necessary client tools and copy the command;
Execute previously copied command. Once you have successfully published the “temperature” readings, the device state should be changed from "Inactive" to "Active" and you should see the published "temperature" readings. Now, close the connectivity window.

Click on the your device, and click the "Check connectivity” button in the "Device details" window;

In the opened window select the messaging protocol and your operating system. Install the necessary client tools and copy the command;

Execute previously copied command. Once you have successfully published the “temperature” readings, the device state should be changed from "Inactive" to "Active" and you should see the published "temperature" readings. Now, close the connectivity window.

You may also use ThingsBoard API reference. Here, you can find more detailed information about all supported protocols for device connectivity.

Step 3. Create dashboard

A dashboard in ThingsBoard allows users to visualize and monitor data collected from IoT devices.

Let’s create a dashboard and add three widgets to it in order to display a list of entities and their latest values, as well as show alarm signals related to the specified entity.

Step 3.1 Create an empty dashboard

To create a new dashboard, follow these steps:

Login to your ThingsBoard instance and navigate to the "Dashboards" page through the main menu on the left of the screen. By default, you navigate to the dashboard group "All";
Click the "+" sign in the upper right corner of the screen, and select "Create new dashboard" from the drop-down menu;
In the opened dialog, it is necessary to enter a dashboard title, description is optional. Click "Add";
After creating the dashboard, it will open automatically, and you can immediately start adding widgets to it. To save the dashboard, click "Save" button in the upper right corner;
Your first dashboard has been successfully created. As you continue to add new dashboards, they will appear at the top of the list. This default sorting is based on the creation timestamp.

Login to your ThingsBoard instance and navigate to the "Dashboards" page through the main menu on the left of the screen. By default, you navigate to the dashboard group "All";

Click the "+" sign in the upper right corner of the screen, and select "Create new dashboard" from the drop-down menu;

In the opened dialog, it is necessary to enter a dashboard title, description is optional. Click "Add";

After creating the dashboard, it will open automatically, and you can immediately start adding widgets to it. To save the dashboard, click "Save" button in the upper right corner;

Your first dashboard has been successfully created. As you continue to add new dashboards, they will appear at the top of the list. This default sorting is based on the creation timestamp.

The “Entities table” widget displays a list of entities and their latest values. The list of entities corresponds to selected devices or other entities, and filters with the 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.

Let’s add your first widget:

Enter dashboard edit mode. Simply open the dashboard and click the "Edit mode" button found in the upper right corner of the screen;
Click the "Add widget" button at the top of the screen or click the large "Add new widget" icon in the center of the screen (if this is your first widget on this dashboard);
Select the "Tables" widget bundle;
Select the "Entities table" widget;
The "Add Widget" window will appear. Specify the previously created device "My New Device" in the "Device" field. The “name” key has already been added to the “Columns” section, which is responsible for the column with the device name. You need to add another column that will display the value of the "temperature" key. To do this, click "Add column" to add a new field to enter the data key;
Click on the newly appeared data key input field. A list of available data keys will open. Select "temperature" data key;
Click the "Add" button in the bottom right corner of the widget to complete adding the widget.
Resize the widget to make it a little bigger. Just drag the bottom right corner of the widget. Click "Save" to apply changes.

Enter dashboard edit mode. Simply open the dashboard and click the "Edit mode" button found in the upper right corner of the screen;

Click the "Add widget" button at the top of the screen or click the large "Add new widget" icon in the center of the screen (if this is your first widget on this dashboard);

The "Add Widget" window will appear. Specify the previously created device "My New Device" in the "Device" field. The “name” key has already been added to the “Columns” section, which is responsible for the column with the device name. You need to add another column that will display the value of the "temperature" key. To do this, click "Add column" to add a new field to enter the data key;

Click on the newly appeared data key input field. A list of available data keys will open. Select "temperature" data key;

Click the "Add" button in the bottom right corner of the widget to complete adding the widget.

Resize the widget to make it a little bigger. Just drag the bottom right corner of the widget. Click "Save" to apply changes.

Congratulations! You’ve added your first widget.

In the “Entities table” widget, there are two columns. The first column displays the device’s name, and the second column displays the value of the “temperature” key (device telemetry). So, each column corresponds to an added key.

Now you are able to send a new telemetry reading (as in Step 1), 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 and click the "Add new widget" button at the top of the screen;
Select the "Charts" widget bundle;
Select the "Timeseries Line Chart" widget;
Specify the previously created device "My New Device" in the "Device" field and specify the "temperature" data key in the "Series" section. Click "Add";
Resize the widget and apply changes. Publish different telemetry values multiple times, as in Step 2. Note that the widget displays only one minute of data by default. Click "Save" to apply changes;
Now open the time selection window. Change the interval and aggregation function. Update the time window setting by clicking the "Update" button.

Enter edit mode and click the "Add new widget" button at the top of the screen;

Select the "Timeseries Line Chart" widget;

Specify the previously created device "My New Device" in the "Device" field and specify the "temperature" data key in the "Series" section. Click "Add";

Resize the widget and apply changes. Publish different telemetry values multiple times, as in Step 2. Note that the widget displays only one minute of data by default. Click "Save" to apply changes;

Now open the time selection window. Change the interval and aggregation function. Update the time window setting by clicking the "Update" button.

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

The alarms table widget displays alarms related to the specified entity in the certain time window. Alarm widget is configured by specifying an entity as the alarm source, and the corresponding alarm fields.

Enter edit mode and click the "Add new widget" button at the top of the screen;
Select "Alarm widgets" bundle;
Select "Alarms table" widget;
Specify the previously created device "My New Device" in the "Device" field and select the statuses and severities of alarms you want to display in the alarm widget;
Drag and Drop the "Timeseries Line Chart" widget to the top right corner of the dashboard to make room for the "Alarms" widget;
Scroll down and locate the new "Alarms" widget. Drag and Drop Alarm widget to the free space and resize it. Click "Save" to apply changes.

Specify the previously created device "My New Device" in the "Device" field and select the statuses and severities of alarms you want to display in the alarm widget;

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

Scroll down and locate the new "Alarms" widget. Drag and Drop Alarm widget to the free space and resize it. Click "Save" to apply changes.

Congratulations! You have added the alarm widget. Now it’s time to configure alarm rules and raise some alarms.

Note: in this documentation, we are using a single device as a data source for the widgets. To use dynamic entities (for example, devices of a certain type or related to a certain asset) as data source, you should use the alias. Alias is a reference to a single entity or a group of entities that are used in the widgets. You may learn more about different aliases here.

Step 4. Configure alarm rules

We will use the alarm rules feature to raise the 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.

Go to the "Profiles" section, and click on the "Device profiles" page. Then click on the default device profile row to open its details;
Navigate to 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 a key type, enter a key name, and select a value type. Then, click "Add" button in the "Filters" section;
Select an operation and enter a threshold value. Click "Add" button in the lower right corner;
Click "Save";
Finally, click "Apply changes".

Go to the "Profiles" section, and click on the "Device profiles" page. Then click on the default device profile row to open its details;

Navigate to 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 a key type, enter a key name, and select a value type. Then, click "Add" button in the "Filters" section;

Select an operation and enter a threshold value. Click "Add" button in the lower right corner;

Step 5. Create alarm

Now, our alarm rule is active (see Step 3), and we should send new telemetry on behalf of the device (see Step 1.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.

One of the most important ThingsBoard features is the ability to create end-user dashboards. Each Customer User should see his own devices and should not be able to see devices or any other data that belongs to a different customer.

We have already created a Device (see Step 1), and a Dashboard (see Step 3). Now it’s time to create a Customer and a Customer User and make sure they will have access to the device’s data and the dashboard. There are two options for how Tenant Administrator can give access to a certain Entity (Device, Dashboard, Asset, etc.) for a Customer:

A. Assign the Customer as the owner of the entity. This option is useful to ensure that only this customer can access the device and its data (see Step 7.2).
B. Share the entity with the Customer. This option is useful to share a single dashboard with multiple customers (see Step 7.3).

Step 7.1 Create a customer

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

Navigate to the "Customers" page. By default, you navigate to the customer group "All". Click the "+" sign to add a new customer;
Input the customer title. Additionally, you can input personal details for the customer and assign a home dashboard. To finalize the customer creation, you can click the "Add" button. In this case, the new customer will be created and located in the "All" customers folder. Let`s create a separate group for our customer. To do this, click on "Next: Owner and groups" button;
If desired, you can assign a different owner for this customer. We will leave this option unchanged. Enter a name for the new group and click "Create a new one!";
Click "Add" to create a new customers group;
Now, click "Add" to create a new customer;
The customer has been created and is located in the "My Customers" group. You can navigate to this group by clicking on its name.

Navigate to the "Customers" page. By default, you navigate to the customer group "All". Click the "+" sign to add a new customer;

Input the customer title. Additionally, you can input personal details for the customer and assign a home dashboard. To finalize the customer creation, you can click the "Add" button. In this case, the new customer will be created and located in the "All" customers folder. Let`s create a separate group for our customer. To do this, click on "Next: Owner and groups" button;

If desired, you can assign a different owner for this customer. We will leave this option unchanged. Enter a name for the new group and click "Create a new one!";

Click "Add" to create a new customers group;

Now, click "Add" to create a new customer;

The customer has been created and is located in the "My Customers" group. You can navigate to this group by clicking on its name.

Step 7.2 Change owner of the device

Let’s assign the Customer as the owner of the device. We will also create a group of devices and add our device to this group.

Open "Devices" page. Select your device to open its details;
Click "Manage owner and groups" button;
In the "Owner" line, start typing the customer name and then select the customer;
Now, create a device group. In the "Groups" line, input the desired device group name. Then, click "Create a new one";
In the next window, click "Add" button to create a device group;
Click "Update" to change the owner of your device. You can always change the owner back to the tenant;
By default, the general device list displays both tenant devices and devices of your customers. Disable "Include customer entities" to only see tenant devices in the device list;
Your device list should be empty now.

Open "Devices" page. Select your device to open its details;

In the "Owner" line, start typing the customer name and then select the customer;

Now, create a device group. In the "Groups" line, input the desired device group name. Then, click "Create a new one";

In the next window, click "Add" button to create a device group;

Click "Update" to change the owner of your device. You can always change the owner back to the tenant;

By default, the general device list displays both tenant devices and devices of your customers. Disable "Include customer entities" to only see tenant devices in the device list;

Make sure that the device is assigned to your customer.

Navigate to "Customers" page. Find your customer in the list of customers and then click on the "Manage customer devices" icon;
Your device is owned by the customer and is located in the customer's device group "My Devices".

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

Your device is owned by the customer and is located in the customer's device group "My Devices".

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 "Owner and groups" tab;
Select new owner and click "Add";
The device has been created, and it immediately belongs to your customer.

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

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

Let’s share our dashboard with the customer. Our dashboard is in the group “All”. Ideally, we should create another dashboard group, but to simplify the guide, we will use the group “All”.

Open "Dashboard" page, go to the "Groups" tab and click the "Share" icon for the "All" dashboard group;
Select the customer and specify permission - "Read". Click "Share".

Open "Dashboard" page, go to the "Groups" tab and click the "Share" icon for the "All" dashboard group;

Select the customer and specify permission - "Read". Click "Share".

You can also share the dashboard with your customer or user during its creation stage.

Click on the "+" icon in the top right corner of the table. Input dashboard name (for example, "Thermostats") and navigate to the "Owner and groups" tab;
Let`s create a separate group for them. Input a name (for example, "Thermostats group") for the new group and click "Create a new one!";
Click "Next: Share entity group" button;
Tick "Share entity group" checkbox, then select the customer with whom you want to share the dashboard and specify permission. Click "Add";
Click "Add" dashboard;
The dashboard has been created and is located in the "Thermostats group" group. You can navigate to this group by clicking on its name.

Click on the "+" icon in the top right corner of the table. Input dashboard name (for example, "Thermostats") and navigate to the "Owner and groups" tab;

Let`s create a separate group for them. Input a name (for example, "Thermostats group") for the new group and click "Create a new one!";

Click "Next: Share entity group" button;

Tick "Share entity group" checkbox, then select the customer with whom you want to share the dashboard and specify permission. Click "Add";

The dashboard has been created and is located in the "Thermostats group" group. You can navigate to this group by clicking on its name.

Step 7.4 Create a 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 itself. You may optionally configure the dashboard to appear just after the 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;
Navigate to the "Groups" tab and select "Customer Users" group;
Click "plus" icon in the top right corner to add a new user;
Specify email, first and last name. Click "Add";
Copy the activation link and save it to a safe place. Then click "OK";
Click on the created user to open details. Click "pencil" icon to enter edit mode;
Select the default dashboard and enable "Always fullscreen" mode. Apply changes.

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

Navigate to the "Groups" tab and select "Customer Users" group;

Click "plus" icon in the top right corner to add a new user;

Specify email, first and last name. Click "Add";

Copy the activation link and save it to a safe place. Then click "OK";

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

Select the default dashboard and enable "Always fullscreen" mode. Apply changes.

Step 7.5 Activate the 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 log in 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 log in as a customer user;

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

Next steps

Installation guides - Learn how to set up ThingsBoard on various available operating systems.
Connect your device - Learn how to connect devices based on your connectivity technology or solution.
Data visualization - These guides contain instructions on 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.

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.

Getting Started with ThingsBoard Professional Edition

Prerequisites

Step 1. Provision device

Step 2. Connect device