Stop the war

Support Ukraine
Try it now Pricing
PE Edge
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application
Documentation Installation Architecture API FAQ

On this page

Getting started with ThingsBoard PE Edge

Introduction

The goal of this tutorial is to demonstrate the basic usage of the most popular ThingsBoard Edge features. You will learn how to:

  • Connect devices to ThingsBoard Edge;
  • Provision devices from ThingsBoard Edge to ThingsBoard Professional Edition server (cloud);
  • Push data from devices to ThingsBoard Edge and propagate this data to ThingsBoard Professional Edition server (cloud);
  • Build real-time end-user dashboards on cloud and provision them to edge;

We will connect and visualize data from the temperature sensor to keep it simple.

Prerequisites

ThingsBoard Cloud server

To begin using ThingsBoard Edge, you must have a ThingsBoard PE server supporting edge functionality up and running.

The easiest way is to use ThingsBoard Cloud server.

The alternative option is to install ThingsBoard Professional Edition server on-premise. Please visit Install PE to install server.

Edge provision on cloud

Additionally, you will need to provision ThingsBoard Edge on a cloud server. If you haven’t done so yet, please follow the Provision Edge on Cloud guide.

Once the ThingsBoard Edge is provisioned on the cloud server, please follow the installation steps provided below.

Edge installation

For further assistance, refer to the Edge Install Guide. This guide will aid in the installation of ThingsBoard Edge and its connection to the ThingsBoard server.

User Credentials and access URLs
Cloud
Connect edge to https://thingsboard.cloud
On-premise server
Connect edge to on-premise instance

Server UI will be available using the URL: Cloud. Please use your Cloud tenant credentials to log in.

At the moment Edge doesn’t support OAuth 2.0 login. To be able to login into Edge with your OAuth 2.0 user, you must set password for this user in the ThingsBoard server.

We are going to refer to this URL as http://SERVER_URL below in tutorial.

ThingsBoard Edge UI will be available using the URL: http://localhost:8080. You may use your Cloud tenant credentials to log in.

Server UI will be available using the URL: http://localhost:8080. You may use username [email protected] and password tenant.

We are going to refer to this URL as http://SERVER_URL below in tutorial.

ThingsBoard Edge UI will be available using the URL: http://localhost:18080. You can use the same username [email protected] and password tenant to login.

Use next ThingsBoard Edge UI link http://localhost:18080 if you updated HTTP 8080 bind port to 18080.

We are going to refer to this URL as http://EDGE_URL below in tutorial.

Step 1. Provision Device

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

We are going to provision device on the Edge. Please open ThingsBoard Edge UI using the URL http://EDGE_URL.

  • Login to your ThingsBoard PE Edge instance and open Device groups page.
  • Open "All" device group.
  • Click on the "Add Device"("+") icon in the top right corner of the table.
  • 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 table sort devices using created time by default.
image
Login to your ThingsBoard PE Edge instance and open Device groups page.
image
Open "All" device group.
image
Click on the "Add Device"("+") icon in the top right corner of the table.
image
Input device name. For example, "My New Device". No other changes required at this time. Click "Add" to add the device.
image
Now your device should be listed first, since table sort devices using created time by default.

You may also use:

  • Bulk provisioning to provision multiple devices from a CSV file using UI;
  • REST API to provision devices and other entities programmatically;

Step 2. Provision Device from ThingsBoard PE Edge to ThingsBoard Professional Edition server (cloud)

Provision device from the edge to the cloud done automatically, so no additional actions required. Once device has been created on the edge, it’s going to be automatically created on the cloud.

To see provisioned device please open ThingsBoard Professional Edition using the URL http://SERVER_URL.

  • Login to your ThingsBoard Professional Edition instance and open Device groups page.
  • Click on the "Open" icon of the "All" device group to see the list of devices.
  • Verify that "My New Device" device was created on the ThingsBoard Professional Edition cloud.
  • Click on the "My New Device" device and navigate to the "Relations" tab.
  • Change direction "From" to "To" and see relation to the edge that has provisioned this device.
image
Login to your ThingsBoard Professional Edition instance and open Device groups page.
image
Click on the "Open" icon of the "All" device group to see the list of devices.
image
Verify that "My New Device" device was created on the ThingsBoard Professional Edition cloud.
image
Click on the "My New Device" device and navigate to the "Relations" tab.
image
Change direction "From" to "To" and see relation to the edge that has provisioned this device.

Step 3. Connect device

To connect the device you need to get the device credentials first. ThingsBoard support different device credentials. We recommend to use default auto-generated credentials which is access token for this guide.

  • Open Device groups page in the ThingsBoard PE Edge instance.
  • Open "All" device group.
  • 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.
image
Open Device groups page in the ThingsBoard PE Edge instance.
image
Open "All" device group.
image
Click on the device row in the table to open device details.
image
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:

1

sudo apt-get install curl

Install cURL for macOS:

1

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.

1

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

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

1

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


Install mqtt client for Ubuntu:

1

sudo apt-get install mosquitto-clients

Install cURL for macOS:

1

brew install mosquitto-clients

Replace $HOST_NAME, $MQTT_PORT and $ACCESS_TOKEN with corresponding values.

1

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

For example, $HOST_NAME reference your local ThingsBoard Edge installation, MQTT port is 1883 and access token is ABC123:

1

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:

1
2
3
4
5

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.
image
Create new MQTT Client with the properties listed in screenshots below.
image
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:

1

npm install coap-cli -g

Replace $HOST_NAME, $COAP_PORT and $ACCESS_TOKEN with corresponding values. If $COAP_PORT is not specified, default 5683 used.

1

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

For example, $HOST_NAME reference your local ThingsBoard Edge installation, coap port is 5683 and access token is ABC123:

1

echo -n '{"temperature": 25}' | coap post coap://localhost:5683/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:

  • Click on the device row in the table to open device details.
  • Navigate to the "Latest telemetry" tab.
image
Click on the device row in the table to open device details.
image
Navigate to the "Latest telemetry" tab.

Step 4. Push data from ThingsBoard PE Edge to ThingsBoard Professional Edition server (cloud)

Timeseries data and attributes pushed to the cloud according to the Edge Rule Engine. We will go over default Edge Root Rule chain to see how temperature data is going to be pushed from edge to cloud.

  • Open Rule chains page in the ThingsBoard PE Edge instance.
  • Open Edge Root Rule Chain.
  • Push to cloud rule node pushes temperature timeseries data to the cloud once it is stored in local database.
image
Open Rule chains page in the ThingsBoard PE Edge instance.
image
Open Edge Root Rule Chain.
image
Push to cloud rule node pushes temperature timeseries data to the cloud once it is stored in local database.

Step 5. Create Dashboard

We will create a dashboard, add a table and a chart widget to see temperature data on cloud and edge. See instructions below.

Step 5.1 Create Empty Dashboard

  • Open Dashboard groups page in the ThingsBoard Professional Edition server. Click on the "+" icon in the top right corner "Add entity group".
  • Input dashboard group name. For example, "Edge dashboards". Click "Add" to add the dashboard group.
  • Click on the "+" icon to 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 table sort dashboards using created time by default. Click on the "Open dashboard" icon.
image
Open Dashboard groups page in the ThingsBoard Professional Edition server. Click on the "+" icon in the top right corner "Add entity group".
image
Input dashboard group name. For example, "Edge dashboards". Click "Add" to add the dashboard group.
image
Click on the "+" icon to create new dashboard.
image
Input dashboard name. For example, "My New Dashboard". Click "Add" to add the dashboard.
image
Now your dashboard should be listed first, since table sort dashboards using created time by default. Click on the "Open dashboard" icon.

Step 5.2 Add Entity Alias

Alias is a reference to single entity or group of entities that is used in the widgets. Alias may be static or dynamic. For simplicity, we will use “Single entity” alias reference one and only one entity (“My New Device” in our case). It is possible to configure an alias that reference multiple devices. For example, devices of a certain type or related to a certan asset. You may learn more about different aliases here.

  • Enter edit mode. Click on the pencil button in the bottom right corner.
  • Click "Entity Aliases" icon in the top right part of the screen. You will see empty list of Entity aliases.
  • Click "Add alias".
  • Input alias name, for example "MyDevice". Select "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 the device.
  • Click "Add" and then "Save".
  • Finally, Click "Apply changes" in the dashboard editor to save the changes. Then you should enter edit mode again.
image
Enter edit mode. Click on the pencil button in the bottom right corner.
image
Click "Entity Aliases" icon in the top right part of the screen. You will see empty list of Entity aliases.
image
Click "Add alias".
image
Input alias name, for example "MyDevice". Select "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 the device.
image
Click "Add" and then "Save".
image
Finally, Click "Apply changes" in the dashboard editor to save the changes. Then you should enter edit mode again.

Step 5.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 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 "Cards" widget bundle. Select "Latest values" tab. Click on the header of the Entities widget. The "Add Widget" window will appear.
  • Click "Add" to add the data source. 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 to 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 edit the widget.
image
Enter edit mode. Click on the "Add new widget" button.
image
Select "Cards" widget bundle. Select "Latest values" tab. Click on the header of the Entities widget. The "Add Widget" window will appear.
image
Click "Add" to add the data source. Widget may have multiple data sources, but we will use only one in this case.
image
Select "MyDevice" entity alias. Then click on the input field to the right. The auto-complete with available data points will appear. Select "temperature" data point and click "Add".
image
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 edit the widget.

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

Step 5.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 "Add new widget" icon in the bottom right corner of the screen.
  • Click "Create new widget" icon.
  • Select "Charts" bundle. Scroll down and click on the "Timeseries - Flot" chart widget.
  • Click "Add datasource" button.
  • Select "MyDevice" Alias. Select "temperature" key. Click "Add".
  • Drag and Drop you widget to desired space. Resize the widget.
  • 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. Finally, apply changes.
image
Enter Edit mode.
image
Click "Add new widget" icon in the bottom right corner of the screen.
image
Click "Create new widget" icon.
image
Select "Charts" bundle. Scroll down and click on the "Timeseries - Flot" chart widget.
image
Click "Add datasource" button.
image
Select "MyDevice" Alias. Select "temperature" key. Click "Add".
image
Drag and Drop you widget to desired space. Resize the widget.
image
Publish different telemetry values multiple times Step 2. Note that the widget displays only one minute of data by default.
image
Enter Edit mode. Open time selection window. Change the interval and aggregation function. Update the time window. Finally, apply changes.

You have added chart widget. Now you can send new telemetry reading and it will immediately appear in the chart. Let’s provision this dashboard to the edge to see temperature data from the device on the edge as well.

Step 6. Provision Dashboard to ThingsBoard PE Edge

To provision dashboard to edge we need to open edge dashboards on ThingsBoard Professional Edition server and assign the newly created dashboard. Once this dashboard is assigned we are going to open ThingsBoard Edge UI to see the same dashboard on the edge.

Please open ThingsBoard Professional Edition using the URL http://SERVER_URL.

  • Open "Edge groups" page in the ThingsBoard Professional Edition server and open "All" group.
  • Click on the Dashboards button on the edge instance to open dashboard groups that are already assigned to this edge.
  • Click on the "+" icon to assign dashboard groups.
  • Select "Edge dashboards" group in the list. Now this group and all its dashboards are going to be provisioned to the edge.
image
Open "Edge groups" page in the ThingsBoard Professional Edition server and open "All" group.
image
Click on the Dashboards button on the edge instance to open dashboard groups that are already assigned to this edge.
image
Click on the "+" icon to assign dashboard groups.
image
Select "Edge dashboards" group in the list. Now this group and all its dashboards are going to be provisioned to the edge.

Let’s open ThingsBoard Edge UI using the URL http://EDGE_URL. to verify that dashboard was provisioned.

  • Open "Dashboard groups" page in the ThingsBoard Edge UI. Click on the "All" dashboard group to see "My New Dashboard" in the list. Open "My New Dashboard".
  • Verify that you see the same widgets that you have added on the cloud and temperature readings from the device.
image
Open "Dashboard groups" page in the ThingsBoard Edge UI. Click on the "All" dashboard group to see "My New Dashboard" in the list. Open "My New Dashboard".
image
Verify that you see the same widgets that you have added on the cloud and temperature readings from the device.

Congratulations! Dashboard has been provisioned to the edge. Now you can send new telemetry reading, and it will immediately appear in the chart on the edge.

Next steps


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.