Installing ThingsBoard Edge on Ubuntu Server

• Prerequisites
  • Edge Hardware Requirements
  • Provisioning a new Edge instance on the ThingsBoard server
• Guided Installation Using ThingsBoard Server Pre-configured Instructions
• Manual Installation and Configuration
  • Step 1. Install Java 17 (OpenJDK)
  • Step 2. Configure PostgreSQL
  • Step 3. ThingsBoard Edge service installation
  • Step 4. Configure ThingsBoard Edge
  • Step 5. Run installation script
  • Step 6. Restart ThingsBoard Edge service
  • Step 7. Open ThingsBoard Edge UI
• Troubleshooting
• Next Steps

Rules of Compatibility Between ThingsBoard Edge and ThingsBoard Server Versions:

• A ThingsBoard Edge version X.Y.Z is compatible with the same ThingsBoard Server version X.Y.Z and any later versions.
• A ThingsBoard Edge version X.Y.Z is NOT compatible with ThingsBoard Server versions preceding X.Y.Z.

Example: ThingsBoard Edge version 3.3.4.1 is compatible with ThingsBoard Server version 3.3.4.1 and subsequent versions (3.4.0, 3.4.1, …). However, ThingsBoard Edge version 3.4.0 is NOT compatible with ThingsBoard Server version 3.3.4.1 or any prior versions (3.3.4, 3.3.3, …). In such scenarios, ThingsBoard Server 3.3.4.1 or a preceding version must first be upgraded to ThingsBoard Server 3.4.0 or a later version.

Please ensure that the ThingsBoard Server is updated to the latest version before proceeding.

This guide describes how to install ThingsBoard Edge on Ubuntu 18.04 LTS / Ubuntu 20.04 LTS.

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

Alternatively, you can install the ThingsBoard Professional Edition server on-premise. For this, please refer to the ThingsBoard Professional Edition 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 PE 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”. 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 confirm adding your new Edge.

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

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.

Manual Installation and Configuration

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

Step 1. Install Java 17 (OpenJDK)

ThingsBoard service is running on Java 17. Follow this instructions to install OpenJDK 17:

1
2
sudo apt update
sudo apt install openjdk-17-jdk

Please don’t forget to configure your operating system to use OpenJDK 17 by default. You can configure which version is the default using the following command:

1
sudo update-alternatives --config java

You can check the installation using the following command:

1
java -version

Expected command output is:

1
2
3
openjdk version "17.x.xx" 
OpenJDK Runtime Environment (...)
OpenJDK 64-Bit Server VM (...)

Step 2. Configure PostgreSQL

ThingsBoard Edge uses PostgreSQL database as a local storage.

Instructions listed below will help you to install PostgreSQL.

1
2
3
4
5
6
7
8
# Automated repository configuration:
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

# install and launch the postgresql service:
sudo apt update
sudo apt -y install postgresql-16
sudo service postgresql start

Once PostgreSQL is installed you may want to create a new user or set the password for the main user. The instructions below will help to set the password for main PostgreSQL user.

To switch your current user context to the postgres user, execute the following script:

1
sudo su - postgres

To be able to interact with the PostgreSQL database, enter:

1
psql

You will connect to the database as the main PostgreSQL user. To set the password, enter the following command after postgres=# :

1
\password

Enter and confirm the password. Then, press “Ctrl+D” to return to main user console.

Then, connect to the “postgres” database as the “postgres” user:

1
psql -U postgres -d postgres -h 127.0.0.1 -W

Create the ThingsBoard Edge database named “tb_edge” :

1
CREATE DATABASE tb_edge;

Press “Ctrl+D” twice to exit PostgreSQL.

Step 3. ThingsBoard Edge service installation

Download installation package.

1
wget https://dist.thingsboard.io/tb-edge-3.8pe.deb

Go to the download repository and install ThingsBoard Edge service

1
sudo dpkg -i tb-edge-3.8pe.deb

Step 4. Configure ThingsBoard Edge

Click on Copy Edge Key and Copy Edge Secret in the edge details section. This will copy your edge credentials to your clipboard. Be sure to store them in a secure location, as these values will be needed in the following steps.

Edit ThingsBoard Edge configuration file

1
sudo nano /etc/tb-edge/conf/tb-edge.conf

Please update the following lines in your configuration file. Make sure to replace:

• “PUT_YOUR_POSTGRESQL_PASSWORD_HERE” with your actual postgres user password.

• “PUT_YOUR_CLOUD_IP” with an IP address of the machine where ThingsBoard PE Server is running. Depending on your setup:

  • If you’re connecting the Edge to ThingsBoard Cloud, use thingsboard.cloud.

  NOTE: thingsboard.cloud employs the SSL protocol for Edge communication. You should also uncomment export CLOUD_RPC_SSL_ENABLED=true in this case.

  • Use localhost if the Edge is running on the same machine as the Server instance.
  • Use an X.X.X.X IP address if the Edge is connecting to the Server instance in the same network or in a Docker container.
• Replace “PUT_YOUR_EDGE_KEY_HERE” and “PUT_YOUR_EDGE_SECRET_HERE” with the respective Edge key and secret:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# UNCOMMENT NEXT LINES AND PUT YOUR CLOUD CONNECTION SETTINGS:
# export CLOUD_ROUTING_KEY=PUT_YOUR_EDGE_KEY_HERE
# export CLOUD_ROUTING_SECRET=PUT_YOUR_EDGE_SECRET_HERE

# UNCOMMENT NEXT LINES IF EDGE CONNECTS TO PE 'THINGSBOARD.CLOUD' SERVER:
# export CLOUD_RPC_HOST=thingsboard.cloud
# export CLOUD_RPC_SSL_ENABLED=true

# UNCOMMENT NEXT LINES IF YOU CHANGED DEFAULT CLOUD RPC HOST/PORT SETTINGS:
# export CLOUD_RPC_HOST=PUT_YOUR_CLOUD_IP
# export CLOUD_RPC_PORT=7070

# UNCOMMENT NEXT LINES IF YOU ARE RUNNING EDGE ON THE SAME MACHINE WHERE THINGSBOARD SERVER IS RUNNING:
# export HTTP_BIND_PORT=18080
# export MQTT_BIND_PORT=11883
# export COAP_BIND_PORT=15683
# export LWM2M_ENABLED=false

# export INTEGRATIONS_RPC_PORT=19090

# UNCOMMENT NEXT LINES IF YOU HAVE CHANGED DEFAULT POSTGRESQL DATASOURCE SETTINGS:
# export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/tb_edge
# export SPRING_DATASOURCE_USERNAME=postgres
# export SPRING_DATASOURCE_PASSWORD=PUT_YOUR_POSTGRESQL_PASSWORD_HERE

If ThingsBoard Edge is going to be running on the same machine where ThingsBoard PE server is running, you’ll need to update configuration parameters to avoid port collision between ThingsBoard Server and ThingsBoard Edge.

Please execute the following command to update ThingsBoard Edge configuration file (/etc/tb-edge/conf/tb-edge.conf):

1
2
3
4
5
6
7
8
sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf
export HTTP_BIND_PORT=18080
export MQTT_BIND_PORT=11883
export COAP_BIND_PORT=15683
export LWM2M_ENABLED=false
export SNMP_ENABLED=false
export INTEGRATIONS_RPC_PORT=19090
EOL'

Make sure that ports above (18080, 11883, 15683) are not used by any other application.

Step 5. Run installation script

Once ThingsBoard Edge is installed and configured please execute the following install script:

1
sudo /usr/share/tb-edge/bin/install/install.sh

Step 6. Restart ThingsBoard Edge service

1
sudo service tb-edge restart

Step 7. Open ThingsBoard Edge UI

Once started, you will be able to open ThingsBoard Edge UI using the following link http://localhost:8080.

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

Please use your tenant credentials from local Server instance or ThingsBoard Cloud to log in to the ThingsBoard Edge.

Troubleshooting

ThingsBoard Edge logs stored in the following directory:

1
/var/log/tb-edge

You can issue the following command in order to check if there are any errors on the service side:

1
cat /var/log/tb-edge/tb-edge.log | grep ERROR

Start edge service:

1
sudo service tb-edge start

Stop edge service:

1
sudo service tb-edge stop

Restart edge service:

1
sudo service tb-edge restart

Check status of ThingsBoard Edge service:

1
sudo service tb-edge status

Next Steps

Congratulations! You have successfully provisioned, installed and connected ThingsBoard Edge to ThingsBoard server.

You can continue with Getting started guide to get the basic knowledge of ThingsBoard Edge or you can jump directly to more advanced topics:

• Getting started guide - Provide quick overview of main ThingsBoard Edge features. Designed to be completed in 15-30 minutes:

• Edge Rule Engine:

  • Rule Chain Templates - Learn how to use ThingsBoard Edge Rule Chain Templates.

  • Provision Rule Chains from cloud to edge - Learn how to provision edge rule chains from cloud to edge.

• Security:
  • gRPC over SSL/TLS - Learn how to configure gRPC over SSL/TLS for communication between edge and cloud.

• Features:

  • Edge Status - Learn about Edge Status page on ThingsBoard Edge.

  • Cloud Events - Learn about Cloud Events page on ThingsBoard Edge.

• Use cases:

  • Manage alarms and RPC requests on edge devices - This guide will show how to generate local alarms on the edge and send RPC requests to devices connected to edge:

  • Data filtering and traffic reduce - This guide will show how to send to cloud from edge only filterd amount of device data:

• Roadmap - ThingsBoard Edge roadmap.