Edge
ThingsBoard Documentation
Cloud Professional Edition Community Edition Edge IoT Gateway License Server Trendz Analytics
Try it now Pricing
Getting Started > Getting Started CE
Documentation Installation Architecture

On this page

Getting started with ThingsBoard Edge and ThingsBoard CE

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 Community Edition server (cloud);
  • Push data from devices to ThingsBoard Edge and propagate this data to ThingsBoard Community 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 start using ThingsBoard Edge you need to have ThingsBoard Community Edition server that supports edge functionality up and running.

The easiest way is to use Live Demo server.
The alternative option is to install ThingsBoard Community Edition server that supports edge functionality on-premise. Please visit Install CE to install 3.3 version or higher of server that supports edge functionality.

Provisioning edge on cloud and installation

Additionally, you will need to have ThingsBoard Edge up and running and connected to the ThingsBoard Community Edition server.

To provision ThingsBoard Edge on ThingsBoard Community Edition server please visit this guide Provision ThingsBoard Edge on ThingsBoard Community Edition server.

Once ThingsBoard Edge provisioned on ThingsBoard Community Edition server please follow Installation Guide - this guide will help you to install ThingsBoard Edge and connect it to ThingsBoard Community Edition server.

Server UI will be available using the URL: Live Demo. Please use your Live Demo 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 Live Demo 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.

If during installation process you have changed edge HTTP_BIND_PORT please use that port instead for Edge UI URL:

http://localhost:HTTP_BIND_PORT

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 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.

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 (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 Community Edition using the URL http://SERVER_URL.

  • Login to your ThingsBoard Community Edition instance and open Devices page.
  • Verify that "My New Device" device was created on the ThingsBoard Community 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.

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 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.

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:

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.


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.

Step 4. Push data from ThingsBoard Edge to ThingsBoard Community 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 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.

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 Dashboards page in the ThingsBoard Community Edition server. Click on the "+" icon in the top right corner. Select "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.

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.

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.

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. Apply changes.
  • 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 and 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 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.

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

  • Open Edge instances page in the ThingsBoard Community Edition server.
  • Click on the Dashboards button on the edge instance to open dashboards that are already assigned to this edge.
  • Click on the "+" plus icon and select "My New Dashboard" in the list. Now this dashboard is 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.

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.