Stop the war

Stand with Ukraine flag

Support Ukraine
Try it now Pricing
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 Edge

Doc info icon

Interested in the Edge Professional Edition? Explore the ThingsBoard PE Edge documentation here.

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 Community Edition server;
  • Transmit data from sensors to ThingsBoard Edge and further propagate this data to the ThingsBoard Community Edition server;
  • Construct real-time end-user dashboards in the cloud and provision them to the Edge.

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

Prerequisites

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

The easiest way is to use Live Demo server.

Alternatively, you can install the ThingsBoard Community Edition server on-premise. For this, please refer to the ThingsBoard installation guide.

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.

Provisioning a new Edge instance on the ThingsBoard server

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

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

  • Enter a name for your Edge. For instance, “My New Edge”. Click “Add” to confirm adding of 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 instance and navigate to the "Edge Management" section -> "Instances" page. Click the "+" icon in the top right corner and select "Add new edge".

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

Enter a name for your Edge. For instance, "My New Edge". Click "Add" to confirm adding of your new Edge.

Enter a name for your Edge. For instance, “My New Edge”. Click “Add” to confirm adding of 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:

  • Click an Edge entity row to open it's details;

  • Click on the “Install & Connection Instructions” button;

  • Follow instructions to install Edge and connect to the server.

Click an Edge entity row to open it's details;

Click an Edge entity row to open it's details;

Click on the "Install & Connection Instructions" button;

Click on the “Install & Connection Instructions” button;

Follow instructions to install Edge and connect to the server.

Follow instructions to install Edge and connect to the 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

Live Demo
Connect Edge to https://demo.thingsboard.io
On-premise server
Connect Edge to on-premise instance

The Server UI can be accessed through the following URL: Live Demo. Please log in using your Live Demo 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 Live Demo 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 and Connect 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.

  • Login to your ThingsBoard Edge instance and navigate to the "Entities" section -> "Devices" page;
  • Click on the "+" icon in the top right corner of the table and select "Add new 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;
  • The device is created. A window will open where you can check the device's connection to ThingsBoard Edge. Select the messaging protocol and your operating system. Install the necessary client tools and copy the command;
  • Execute the 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;
  • Open the "Last Telemetry" tab in the device details to check the received telemetry.
Login to your <b>ThingsBoard Edge</b> instance and navigate to the "Entities" section -> "Devices" page;
Login to your ThingsBoard Edge instance and navigate to the "Entities" section -> "Devices" page;
Click on the "+" icon in the top right corner of the table and select "Add new 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;
Click on the "+" icon in the top right corner of the table and select "Add new 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;
The device is created. A window will open where you can check the device's connection to ThingsBoard Edge. Select the messaging protocol and your operating system. Install the necessary client tools and copy the command;
The device is created. A window will open where you can check the device's connection to ThingsBoard Edge. Select the messaging protocol and your operating system. Install the necessary client tools and copy the command;
Execute the 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;
Execute the 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;
Open the "Last Telemetry" tab in the device details to check the received telemetry.
Open the "Last Telemetry" tab in the device details to check the received telemetry.


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 Community 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 ThingsBoard server.

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

  • Log in to your ThingsBoard Community Edition instance and navigate to the "Devices" page. Confirm that the device "My New Device" has been created on the ThingsBoard Community Edition cloud;
  • Click om the "My New Device" to open "Device details" 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 Community Edition</b> instance and navigate to the "Devices" page. Confirm that the device "My New Device" has been created on the ThingsBoard Community Edition cloud;
Log in to your ThingsBoard Community Edition instance and navigate to the "Devices" page. Confirm that the device "My New Device" has been created on the ThingsBoard Community Edition cloud;
Click om the "My New Device" to open "Device details" and navigate to the "Relations" tab. Switch the direction from "From" to "To" to view the relation to the Edge that provisioned this device.
Click om the "My New Device" to open "Device details" and navigate to the "Relations" tab. 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 Community Edition Server

Timeseries data and attributes are pushed to the Server according to the Edge Rule Chain Template. 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 on the ThingsBoard Community Edition server, 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.

  • Navigate to the "Dashboards" page through the main menu on the left of the screen. Then, click the "+" sign in the upper right corner of the screen, and select "Create new dashboard" from the drop-down menu;
  • Input the dashboard name, for example, "New Dashboard", and click "Add" to create the dashboard;
  • 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);
  • Locate "Tables" in the list of widgets bundles and select this menu item;
  • Locate and 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;
  • The "Entities table" has been added, and "My New Device" is displayed in the list. Let's add another widget. Click the "Add widget" button;
  • Find "Charts" in the list of widgets bundles 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. Drag and Drop the "Timeseries Line Chart" widget to the top right corner of the dashboard;
  • Resize the "Timeseries Line Chart" widget. Just drag the bottom right corner of the widget;
  • Click the "Edit timewindow" icon. Specify "1 hour" as the time period and "None" as the "Data aggregation function". Click "Update" button. Apply all changes by clicking "Save" button in the upper right corner of the screen.
  • Congratulations! You have successfully configured the dashboard. Now, when you send a new telemetry reading, it will immediately appear in the table.
Navigate to the "Dashboards" page through the main menu on the left of the screen. Then, click the "+" sign in the upper right corner of the screen, and select "Create new dashboard" from the drop-down menu;
Navigate to the "Dashboards" page through the main menu on the left of the screen. Then, click the "+" sign in the upper right corner of the screen, and select "Create new dashboard" from the drop-down menu;
Input the dashboard name, for example, "New Dashboard", and click "Add" to create the dashboard;
Input the dashboard name, for example, "New Dashboard", and click "Add" to create the dashboard;
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);
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);
Locate "Tables" in the list of widgets bundles and select this menu item;
Locate "Tables" in the list of widgets bundles and select this menu item;
Locate and select the "Entities table" widget;
Locate and 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;
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 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;
Click the "Add" button in the bottom right corner of the widget to complete adding the widget;
The "Entities table" has been added, and "My New Device" is displayed in the list. Let's add another widget. Click the "Add widget" button;
The "Entities table" has been added, and "My New Device" is displayed in the list. Let's add another widget. Click the "Add widget" button;
Find "Charts" in the list of widgets bundles and click on this menu item;
Find "Charts" in the list of widgets bundles 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. Drag and Drop the "Timeseries Line Chart" widget to the top right corner of the dashboard;
The "Timeseries Line Chart" widget has been added to the dashboard. Drag and Drop the "Timeseries Line Chart" widget to the top right corner of the dashboard;
Resize the "Timeseries Line Chart" widget. Just drag the bottom right corner of the widget;
Resize the "Timeseries Line Chart" widget. Just drag the bottom right corner of the widget;
Click the "Edit timewindow" icon. Specify "1 hour" as the time period and "None" as the "Data aggregation function". Click "Update" button. Apply all changes by clicking "Save" button in the upper right corner of the screen.
Click the "Edit timewindow" icon. Specify "1 hour" as the time period and "None" as the "Data aggregation function". Click "Update" button. Apply all changes by clicking "Save" button in the upper right corner of the screen.
Congratulations! You have successfully configured the dashboard. Now, when you send a new telemetry reading, it will immediately appear in the table.
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 Community 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.

  • Open the "Edge management" section -> "Instances" page and click on the "Manage dashboards" button of the edge instance to view dashboards that are already assigned to this edge;
  • Click on the "+" icon and select "My New Dashboard" from the list, and click "Assign" button. This dashboard will be provisioned to the edge.
Open the "Edge management" section -> "Instances" page and click on the "Manage dashboards" button of the edge instance to view dashboards that are already assigned to this edge;
Open the "Edge management" section -> "Instances" page and click on the "Manage dashboards" button of the edge instance to view dashboards that are already assigned to this edge;
Click on the "+" icon and select "My New Dashboard" from the list, and click "Assign" button. This dashboard will be provisioned to the edge.
Click on the "+" icon and select "My New Dashboard" from the list, and click "Assign" button. This dashboard will be provisioned to the edge.

Now, open ThingsBoard Edge UI using the URL EDGE_URL to verify that dashboard is accessible.

  • 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 ThingsBoard <b>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.

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.

Next steps