Star

Getting Started

Getting Started with ThingsBoard IoT Platform.

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:

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 1883:1883 -p 5683:5683/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.

You may also use:

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.

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.

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 $HOST_NAME and $ACCESS_TOKEN with corresponding values.

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

For example, $HOST_NAME reference live demo server, access token is ABC123:

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

For example, $HOST_NAME reference your local installation, access token is ABC123:

curl -v -X POST -d "{\"temperature\": 25}" http://localhost:8080/api/v1/$ACCESS_TOKEN/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 $HOST_NAME and $ACCESS_TOKEN with corresponding values.

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

For example, $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, $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.



Install MQTTBox plugin for Chrome. Use the instructions listed below:

  • Create new MQTT Client with the properties listed in screenshots below.
  • Populate the topic name and payload. Make sure the payload is a valid JSON document. Click "Publish" button.



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 $HOST_NAME and $ACCESS_TOKEN with corresponding values.

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

For example, $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, $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:

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

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.

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.

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.

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

Step 3.5 Add Alarm Widget

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.

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.

Step 6. Alarm notifications

It is quite easy to configure email or sms notifications for alarms. We recommend reviewing alarm rule examples and documentation about alarm notifications.

Note: At the moment ThingsBoard supports AWS SNS and Twilio to send SMS. Both services are non-free and require you to create an account. However, you may integrate with other SMS/EMAIL gateways using REST API call node.

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:

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.

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.

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.

Step 7.5 Activate customer user

Next steps


ThingsBoard Community Edition education course

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.