Getting Started With ThingsBoard
Getting Started With ThingsBoard
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 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:
Copy to clipboard
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.
• 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;
• 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.
• 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
This command works for Windows, Ubuntu and macOS, assuming the cURL tool is
already installed.
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".
Step 3. Create Dashboard
We will create a dashboard and add the most popular widgets. See the instructions below.
• 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.
Step 3.3 Add Table Widget
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;
• 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.
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 t he
chart widget.
• Enter Edit mode;
• Click the "Add new widget" icon in the bottom right corner of the screen;
• 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.
• 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;
• 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;
• Select key type, input key name, select value type, and click "Add" filter;
• Click "Save";
• 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;
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.
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;
• Navigate to the "Customers" page. Click "Manage customer dashboards" icon for "My New Customer";
• 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;
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.