Stand with Ukraine flag
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
Installation > On premise > Raspberry Pi
Getting Started Documentation Devices Library
Architecture API FAQ
On this page

Installing ThingsBoard Edge on Raspberry Pi

Before installing ThingsBoard Edge, ensure that ThingsBoard Server is installed and updated to the latest version.

Additionally, verify that the ThingsBoard Edge and ThingsBoard Server versions are compatible.

doc warn icon

Version Compatibility Rules:

  • ThingsBoard Edge version X.Y.Z works with the ThingsBoard Server version X.Y.Z and the next two versions.

ThingsBoard Edge 3.8.0 works with ThingsBoard Server 3.8.0 and two later versions (3.9.0 and 3.9.1). You can view the ThingsBoard Server Release Notes here.

  • ThingsBoard Edge version X.Y.Z does not work with older ThingsBoard Server versions.

ThingsBoard Edge 3.9.1 does not support ThingsBoard Server 3.8.0 or any earlier versions. In such cases, the ThingsBoard Server must be upgraded to the latest version first.

Doc info icon

If you run an older version of ThingsBoard Edge (e.g., version 3.6.0), the ThingsBoard team cannot guarantee the availability or proper functioning of all features.

This guide provides step-by-step instructions for installing ThingsBoard Edge on RaspberryPi.

Prerequisites

To start running ThingsBoard Professional Edition Edge, you will need an active ThingsBoard Professional Edition account that supports Edge functionality.

ThingsBoard Cloud
Local Server

Sign up for a ThingsBoard Cloud account, which is the easiest way to get started. Throughout the rest of this tutorial, this URL will be referred to as SERVER_URL

Log in using your ThingsBoard Cloud tenant credentials.

You can install the ThingsBoard Professional Edition local server. For this, please refer to the ThingsBoard installation guide.

The local server can be accessed via http://localhost:8080. Throughout this tutorial, we will refer to this URL as SERVER_URL. Log in with:

Edge Hardware Requirements

The hardware requirements for ThingsBoard Edge are determined by the number of connected devices and the intensity of interactions with the platform interface. To ensure optimal performance, we recommend the following:

  • At least 1GB of RAM (Light workload): It is suitable for minimal interactions with the platform interface, such as dashboards and device management, and fewer than 100 connected devices.
  • At least 4GB of RAM (Heavy workload): This configuration is suitable for intense platform interactions and 100+ devices connected to a single machine.

Deploying a New Edge Instance

To create a new Edge:

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

  • Enter a name for the Edge you are creating. For example, “My New Edge”. If needed, update the cloud endpoint.

    • If the Edge runs in a Docker container, do not use “localhost” as the endpoint. Instead, use the IP address of the machine where ThingsBoard PE is hosted and accessible by the Edge container. For example, http://10.7.2.143:8080.
    • If you are using the ThingsBoard Cloud, there’s no need to change this setting — keep it as is.
    • Click the “Add” button to confirm the addition of the Edge instance.

  • Your new Edge is created and will appear at the top of the list, as entries are sorted by creation time by default.

Sign in to your ThingsBoard PE instance and navigate to the Edge Management > Instances section. Click the "+" icon in the top right corner and select the "Add new edge" option.

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

Enter a name for the Edge you are creating. For example, "My New Edge". If needed, update the cloud endpoint. If the Edge runs in a [Docker container](https://docs.docker.com/get-started/docker-overview/){:target="_blank"}, do not use “localhost” as the endpoint. Instead, use the IP address of the machine where ThingsBoard PE is hosted and accessible by the Edge container. For example, http://10.7.2.143:8080. If you are using the ThingsBoard Cloud, there’s no need to change this setting — keep it as is. Click the "Add" button to confirm the addition of the Edge instance.

Enter a name for the Edge you are creating. For example, “My New Edge”. If needed, update the cloud endpoint.

  • If the Edge runs in a Docker container, do not use “localhost” as the endpoint. Instead, use the IP address of the machine where ThingsBoard PE is hosted and accessible by the Edge container. For example, http://10.7.2.143:8080.
  • If you are using the ThingsBoard Cloud, there’s no need to change this setting — keep it as is.
  • Click the “Add” button to confirm the addition of the Edge instance.
Your new Edge is created and will appear at the top of the list, as entries are sorted by creation time by default.

Your new Edge is created and will appear at the top of the list, as entries are sorted by creation time by default.

Step 1. Install Java 17 (OpenJDK)

ThingsBoard service is running on Java 17. To install OpenJDK 17, follow these instructions

1

sudo apt update && sudo apt install openjdk-17-jdk

Configure your operating system to use OpenJDK 17 by default. You can configure the default version by running the following command:

1

sudo update-alternatives --config java

To check the installed Java version on your system, use the following command:

1

java -version

The expected result is:

1
2
3

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

Step 2. ThingsBoard Edge Service Installation

Download the installation package.

1

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

Go to the download repository and install ThingsBoard Edge service:

1

sudo dpkg -i tb-edge-3.9pe.deb

Step 3. Configure ThingsBoard Edge Database

Doc info icon

The ThingsBoard team recommends using PostgreSQL for development and production environments with moderate load (less than 5000 msg/sec). Many cloud providers offer managed PostgreSQL services, making it a cost-effective solution for most ThingsBoard deployments.

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
9
10
11
12
13

# install **wget** if not already installed:
sudo apt install -y wget

# import the repository signing key:
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

# add repository contents to your system:
echo "deb https://apt.postgresql.org/pub/repos/apt/ $(lsb_release -cs)-pgdg main" | sudo tee  /etc/apt/sources.list.d/pgdg.list

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

Once PostgreSQL is installed, it is recommended to set the password for the PostgreSQL main user.

The following command will switch the current user to the PostgreSQL user and set the password directly in PostgreSQL.

1

sudo -u postgres psql -c "\password"

Then, enter and confirm the password.

Finally, create a new PostgreSQL database named tb_edge by running the following command:

1

echo "CREATE DATABASE tb_edge;" | psql -U postgres -d postgres -h 127.0.0.1 -W

ThingsBoard Configuration

Edit ThingsBoard Edge configuration file:

1
2
3
4
5

sudo bash -c 'echo "export DATABASE_TS_TYPE=sql
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/thingsboard
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=PUT_YOUR_POSTGRESQL_PASSWORD_HERE
export SQL_POSTGRES_TS_KV_PARTITIONING=MONTHS" >> /etc/tb-edge/conf/tb-edge.conf'
  • PUT_YOUR_POSTGRESQL_PASSWORD_HERE: Replace with your actual PostgreSQL password.
  • SQL_POSTGRES_TS_KV_PARTITIONING: Specify partitioning size for timestamp key-value storage. Allowed values: DAYS, MONTHS, YEARS, INDEFINITE.

Step 4. The Queue Service

By default, ThingsBoard Edge uses the built-in queue implementation, which requires no additional configuration.

It is useful for development or proof-of-concept (PoC) environments, but is not recommended for production or any type of clustered deployment due to limited scalability.

Step 5. [Optional] Memory Update for Slow Machines

Edit the ThingsBoard Edge configuration file by running this command:

1

echo 'export JAVA_OPTS="$JAVA_OPTS -Xms512M -Xmx1G"' | sudo tee -a /etc/tb-edge/conf/tb-edge.conf

This sets (or updates) the environment variable JAVA_OPTS by appending two options to its current value:

  • Xms512M: Sets the initial heap size of the Java Virtual Machine (JVM) to 512 Megabytes.
  • Xmx1G: Sets the maximum heap size that the JVM is allowed to use to 1 Gigabyte.

We recommend that you adjust these parameters according to your server resources. It should be set to at least 2G (gigabytes) and increased accordingly if additional RAM is available. Typically, you should set it to 1/2 of your total RAM if you are not running any other memory-intensive processes (e.g. Cassandra), or 1/3 otherwise.

Step 6. Run Installation Script

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

1

sudo /usr/share/tb-edge/bin/install/install.sh
Doc info icon

Make sure you run this script from the root. To change the current directory to the root directory, run the command cd /.

Step 7. Restart ThingsBoard Edge Service

1

sudo service tb-edge restart

Step 8. Open ThingsBoard Edge UI

Once the Edge service is started, open the Edge UI at http://localhost:8080.

Doc info icon

If the Edge HTTP bind port was changed to 18080 during Edge installation, access the ThingsBoard Edge instance at http://localhost:18080.

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

  • Or replace localhost with your actual Raspberry Pi’s local IP

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: