Stop the war

Stand with Ukraine flag

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 MQTT Broker
Documentation Installation Architecture API FAQ
On this page

Getting started with ThingsBoard PE Edge

Introduction

The aim of this tutorial is to guide you through the fundamental usage of the most widely-used features of ThingsBoard Edge. Throughout this tutorial, you will learn how to:

  • Connect local devices, such as sensors, to ThingsBoard Edge;
  • Provision sensors from ThingsBoard Edge to the ThingsBoard Professional Edition server;
  • Transmit data from sensors to ThingsBoard Edge and further propagate this data to the ThingsBoard Professional Edition server;
  • Construct real-time end-user dashboards in the cloud and provision them to the Edge.

To maintain simplicity, we will connect and visualize data from a temperature sensor.

Prerequisites

Edge Hardware Requirements

The hardware specifications needed for ThingsBoard Edge are determined by both the number of devices connected locally and the extent of GUI interaction:

  • Light Usage: If you intend to operate ThingsBoard Edge with minimal GUI interactions (such as local dashboards and device management) and anticipate connecting fewer than 100 devices to a single machine, a minimum of 1GB of RAM should suffice.

  • Heavy Usage: Conversely, for heavy GUI interactions and connections to 100+ devices on a single machine, we recommend allocating at least 4GB of RAM to ensure optimal performance.

Setting Up the Server Environment for ThingsBoard Edge

To start utilizing ThingsBoard Edge, it is essential to have an operational server that supports Edge functionality.

The easiest way is to use ThingsBoard Cloud server.

Alternatively, you can install the ThingsBoard Professional Edition server on-premise. For installation guidance, please refer to Install PE.

Provisioning a New Edge Instance on Server

Additionally, you will need to provision ThingsBoard Edge on a server.

  • Sign in to your ThingsBoard PE instance and navigate to the “Edge Management” -> “Instances” page. Click the “+” icon in the top right corner and select “Add Edge”.

  • Enter a name for your edge. For instance, “My New Edge”. If necessary, update the cloud endpoint. This URL should be accessible from the edge. If the edge is running in a Docker container, using “localhost” is incorrect. It must be the IP address of the machine where ThingsBoard PE is running and accessible by the edge container. If you are using the ThingsBoard Cloud server to evaluate the edge, leave this setting as it is. Click “Add” to create your new edge.

  • Your new edge should now appear at the top of the list, as entries are sorted by creation time by default.

Sign in to your ThingsBoard <b>PE</b> instance and navigate to the "Edge Management" -> "Instances" page. Click the "+" icon in the top right corner and select "Add Edge".

Sign in to your ThingsBoard PE instance and navigate to the “Edge Management” -> “Instances” page. Click the “+” icon in the top right corner and select “Add Edge”.

Enter a name for your edge. For instance, "My New Edge". If necessary, update the cloud endpoint. This URL should be accessible from the edge. If the edge is running in a Docker container, using "localhost" is <b>incorrect</b>. It must be the IP address of the machine where ThingsBoard <b>PE</b> is running and accessible by the edge container. If you are using the ThingsBoard <b>Cloud</b> server to evaluate the edge, leave this setting as it is. Click "Add" to create your new edge.

Enter a name for your edge. For instance, “My New Edge”. If necessary, update the cloud endpoint. This URL should be accessible from the edge. If the edge is running in a Docker container, using “localhost” is incorrect. It must be the IP address of the machine where ThingsBoard PE is running and accessible by the edge container. If you are using the ThingsBoard Cloud server to evaluate the edge, leave this setting as it is. Click “Add” to create your new edge.

Your new edge should now appear at the top of the list, as entries are sorted by creation time by default.

Your new edge should now appear at the top of the list, as entries are sorted by creation time by default.

Edge Installation and Configuration

Guided Installation Using ThingsBoard Server Pre-configured Instructions

The most straightforward method to install and connect Edge to the Server is by utilizing the prepared installation instructions provided by the ThingsBoard Server. For every Edge Entity, the Server has prepared instructions with already populated fields such as the Edge secret key, Edge routing key, Edge RPC host URI, etc. Please follow the steps below to use these prepared instructions:

  • Open the Edge Entity Details Page by Clicking on the Edge Row;

  • Click on Install & Connection instructions;

  • Follow instructions to install Edge and connect to Server.

Open the Edge Entity Details Page by Clicking on the Edge Row;

Open the Edge Entity Details Page by Clicking on the Edge Row;

Click on Install & Connection instructions;

Click on Install & Connection instructions;

Follow instructions to install Edge and connect to Server.

Follow instructions to install Edge and connect to Server.

Manual Installation and Configuration

If, for any reason, you are unable to use the prepared ThingsBoard Server Instructions above, please follow the generic installation steps. These steps will guide you through installing and configuring the Edge by yourself.

Accessing User Interfaces: URLs and Credentials

Cloud
Connect Edge to https://thingsboard.cloud
On-premise server
Connect Edge to on-premise instance

The Server UI can be accessed through the following URL: Cloud. Please log in using your Cloud tenant credentials. Throughout this tutorial, we will refer to this URL as SERVER_URL.

The ThingsBoard Edge UI is accessible at http://localhost:8080. You can log in using your Cloud tenant credentials. This URL will be referred to as EDGE_URL in the subsequent sections of the tutorial.

The Server UI can be accessed through the following URL: http://localhost:8080. Log in using the username [email protected] and password tenant. Throughout this tutorial, we will refer to this URL as SERVER_URL.

The ThingsBoard Edge UI is accessible at http://localhost:18080. Use the same credentials: username [email protected] and password tenant. This URL will be referred to as EDGE_URL in the subsequent sections of the tutorial.

doc warn icon

As of now, Edge does not support OAuth 2.0 for login purposes. If you wish to access Edge using your OAuth 2.0 user credentials, it is necessary to assign a password for this user on the ThingsBoard server.

Doc info icon

If you changed the Edge HTTP bind port to 18080 during Edge installation, use the following ThingsBoard Edge UI link: http://localhost:18080.

Step 1. Provision Device

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

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

  • Log in to your ThingsBoard Edge instance and click the "Add Device" button.
  • Enter a name for the device, for example, "My New Device". No other changes are required at this time. Click "Add" to create the device.
  • Open the "Check connectivity" window from the device details page, or skip this step if the pop-up window has already appeared.
  • Please keep this window open and execute the "curl" command in a new terminal window. This command will publish demo telemetry data to the newly created device.
  • Open a new terminal window and execute the "curl" command copied from the previous step.
  • Observe the successful result of the "curl" command.
  • Revisit the connectivity instructions window and verify the telemetry upload.
  • If you have already closed the connectivity window, you can check the "Latest telemetry" tab of the device for verification.
Log in to your <b>ThingsBoard Edge</b> instance and click the "Add Device" button.
Log in to your ThingsBoard Edge instance and click the "Add Device" button.
Enter a name for the device, for example, "My New Device". No other changes are required at this time. Click "Add" to create the device.
Enter a name for the device, for example, "My New Device". No other changes are required at this time. Click "Add" to create the device.
Open the "Check connectivity" window from the device details page, or skip this step if the pop-up window has already appeared.
Open the "Check connectivity" window from the device details page, or skip this step if the pop-up window has already appeared.
Please keep this window open and execute the "curl" command in a new terminal window. This command will publish demo telemetry data to the newly created device.
Please keep this window open and execute the "curl" command in a new terminal window. This command will publish demo telemetry data to the newly created device.
Open a new terminal window and execute the "curl" command copied from the previous step.
Open a new terminal window and execute the "curl" command copied from the previous step.
Observe the successful result of the "curl" command.
Observe the successful result of the "curl" command.
Revisit the connectivity instructions window and verify the telemetry upload.
Revisit the connectivity instructions window and verify the telemetry upload.
If you have already closed the connectivity window, you can check the "Latest telemetry" tab of the device for verification.
If you have already closed the connectivity window, you can check the "Latest telemetry" tab of the device for verification.

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 Edge to ThingsBoard Professional Edition Server

Device provisioning from the Edge to the Server is automatic, requiring no additional actions. Once a device is created on the Edge, it will be automatically published to the Server.

To view the provisioned device, please open ThingsBoard Professional Edition by visiting SERVER_URL.

  • Log in to your ThingsBoard Professional Edition instance and navigate to the Devices page.
  • Confirm that the device "My New Device" has been created on the ThingsBoard Professional Edition Server.
  • Select "My New Device" and navigate to the "Relations" tab.
  • Switch the direction from "From" to "To" to view the relation to the Edge that provisioned this device.
Log in to your <b>ThingsBoard Professional Edition</b> instance and navigate to the Devices page.
Log in to your ThingsBoard Professional Edition instance and navigate to the Devices page.
Confirm that the device "My New Device" has been created on the ThingsBoard Professional Edition Server.
Confirm that the device "My New Device" has been created on the ThingsBoard Professional Edition Server.
Select "My New Device" and navigate to the "Relations" tab.
Select "My New Device" and navigate to the "Relations" tab.
Switch the direction from "From" to "To" to view the relation to the Edge that provisioned this device.
Switch the direction from "From" to "To" to view the relation to the Edge that provisioned this device.

Step 3. Push data from ThingsBoard Edge to ThingsBoard Professional Edition Server

Timeseries data and attributes are pushed to the Server according to the Edge Rule Engine. We will review the default Edge Root Rule Chain to understand how the temperature data is pushed from the Edge to the Server.

  • Navigate to the "Rule Chains" page within your ThingsBoard Edge instance and open the "Edge Root Rule Chain".
  • The Push to Cloud rule node will transmit temperature timeseries data to the cloud once it has been stored in the local database.
Navigate to the "Rule Chains" page within your ThingsBoard <b>Edge</b> instance and open the "Edge Root Rule Chain".
Navigate to the "Rule Chains" page within your ThingsBoard Edge instance and open the "Edge Root Rule Chain".
The <b>Push to Cloud</b> rule node will transmit temperature timeseries data to the cloud once it has been stored in the local database.
The Push to Cloud rule node will transmit temperature timeseries data to the cloud once it has been stored in the local database.

Step 4. Create And Configure Dashboard

We will create a dashboard and add both a table and a chart widget to view temperature data on the Server and on the Edge. Please see the instructions below.

To add the table widget, select it from the widget library, where widgets are organized into bundles. Each widget is associated with a data source, which determines the data it displays.

  • Click the Add Dashboard button on the ThingsBoard Professional Edition server.
  • Input the dashboard name, for example, "My New Dashboard", and click "Add" to create the dashboard.
  • Click the "Add new widget" button to begin adding new widgets to this dashboard.
  • Locate "Entity widgets" in the list and select this menu item.
  • Locate and select the "Entities table" widget.
  • From the devices list, select "My New Device" and add the "temperature" column to the table configuration. Click "Add" button.
  • The "Entities table" has been added, and "My New Device" is displayed in the list. Click the "Add widget" button.
  • Find "Charts" in the list and click on this menu item.
  • Locate and click on the "Timeseries Line Chart" widget.
  • From the devices list, select "My New Device" and click "Add" button.
  • The "Timeseries Line Chart" widget has been added to the dashboard.
  • Move and resize the "Timeseries Line Chart" widget. Click the "Edit timewindow" icon.
  • Specify "1 day" and "None" as the Data aggregation function. Click "Update" button.
  • Click the "Save" button to save the Dashboard.
Click the <b>Add Dashboard</b> button on the <b>ThingsBoard Professional Edition</b> server.
Click the Add Dashboard button on the ThingsBoard Professional Edition server.
Input the dashboard name, for example, "My New Dashboard", and click "Add" to create the dashboard.
Input the dashboard name, for example, "My New Dashboard", and click "Add" to create the dashboard.
Click the "Add new widget" button to begin adding new widgets to this dashboard.
Click the "Add new widget" button to begin adding new widgets to this dashboard.
Locate "Entity widgets" in the list and select this menu item.
Locate "Entity widgets" in the list and select this menu item.
Locate and select the "Entities table" widget.
Locate and select the "Entities table" widget.
From the devices list, select "My New Device" and add the "temperature" column to the table configuration. Click "Add" button.
From the devices list, select "My New Device" and add the "temperature" column to the table configuration. Click "Add" button.
The "Entities table" has been added, and "My New Device" is displayed in the list. Click the "Add widget" button.
The "Entities table" has been added, and "My New Device" is displayed in the list. Click the "Add widget" button.
Find "Charts" in the list and click on this menu item.
Find "Charts" in the list and click on this menu item.
Locate and click on the "Timeseries Line Chart" widget.
Locate and click on the "Timeseries Line Chart" widget.
From the devices list, select "My New Device" and click "Add" button.
From the devices list, select "My New Device" and click "Add" button.
The "Timeseries Line Chart" widget has been added to the dashboard.
The "Timeseries Line Chart" widget has been added to the dashboard.
Move and resize the "Timeseries Line Chart" widget. Click the "Edit timewindow" icon.
Move and resize the "Timeseries Line Chart" widget. Click the "Edit timewindow" icon.
Specify "1 day" and "None" as the Data aggregation function. Click "Update" button.
Specify "1 day" and "None" as the Data aggregation function. Click "Update" button.
Click the "Save" button to save the Dashboard.
Click the "Save" button to save the Dashboard.

Congratulations! You have successfully configured the dashboard. Now, when you send a new telemetry reading, it will immediately appear in the table.

Step 5. Provision Dashboard to ThingsBoard 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 SERVER_URL.

  • Open Dashboards page on the ThingsBoard Professional Edition server. Click on the Edit icon of the "My New Dashboard" to view details.
  • Click "Manage owner and groups" button.
  • Type "Edge Dashboard Group" in the "Groups" fields and click "Create a new one!" blue link.
  • Click "Add" button to create new group.
  • Newly created "Edge Dashboard Group" appeared in the "Groups" field. Click "Update" button.
  • Verify that "Edge Dashboard Group" is available in the "Groups" field. Close edit window.
  • Open the Edge instances page. Click on the Manage edge dashboard groups icon of the edge instance to view dashboards that are already assigned to this edge.
  • Click on the "+" icon to assign dashboard groups to edge.
  • Select "Edge Dashboard Group" from the list and click "Assign" button.
  • This dashboard group will be provisioned to the edge.
Open Dashboards page on the <b>ThingsBoard Professional Edition</b> server. Click on the <b>Edit</b> icon of the "My New Dashboard" to view details.
Open Dashboards page on the ThingsBoard Professional Edition server. Click on the Edit icon of the "My New Dashboard" to view details.
Click "Manage owner and groups" button.
Click "Manage owner and groups" button.
Type "Edge Dashboard Group" in the "Groups" fields and click "Create a new one!" blue link.
Type "Edge Dashboard Group" in the "Groups" fields and click "Create a new one!" blue link.
Click "Add" button to create new group.
Click "Add" button to create new group.
Newly created "Edge Dashboard Group" appeared in the "Groups" field. Click "Update" button.
Newly created "Edge Dashboard Group" appeared in the "Groups" field. Click "Update" button.
Verify that "Edge Dashboard Group" is available in the "Groups" field. Close edit window.
Verify that "Edge Dashboard Group" is available in the "Groups" field. Close edit window.
Open the Edge instances page. Click on the <b>Manage edge dashboard groups</b> icon of the edge instance to view dashboards that are already assigned to this edge.
Open the Edge instances page. Click on the Manage edge dashboard groups icon of the edge instance to view dashboards that are already assigned to this edge.
Click on the "+" icon to assign dashboard groups to edge.
Click on the "+" icon to assign dashboard groups to edge.
Select "Edge Dashboard Group" from the list and click "Assign" button.
Select "Edge Dashboard Group" from the list and click "Assign" button.
This dashboard group will be provisioned to the edge.
This dashboard group will be provisioned to the edge.

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

  • Open the "Dashboards" page in the ThingsBoard Edge UI. Open "My New Dashboard".
  • Verify that you see the same widgets that you have added on the cloud and temperature readings from the device.
Open the "Dashboards" page in the <b>ThingsBoard Edge</b> UI. Open "My New Dashboard".
Open the "Dashboards" page in the ThingsBoard Edge UI. Open "My New Dashboard".
Verify that you see the same widgets that you have added on the cloud and temperature readings from the device.
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 Edge on github to help us spread the word. If you have some questions about this sample - post it on the forum.