Installing ThingsBoard Edge on Raspberry Pi

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

To run ThingsBoard Edge, you need an active ThingsBoard account that supports Edge functionality.

You can use ThingsBoard Cloud or install a local ThingsBoard server.

The hardware requirements for ThingsBoard Edge depend on the number of connected devices and platform interaction intensity.

To create a new Edge instance on your ThingsBoard Server:

1. Log in to your ThingsBoard server and go to Edge management > Edges. Click Add edge and select Add new edge.

2. Enter a name for the Edge, like My New Edge.

   If needed, update the Cloud endpoint (the field is shown only for Edges with legacy v1 licensing). If Edge runs in a Docker container, do not use localhost — use the IP address of the machine where ThingsBoard is hosted (e.g., http://10.7.2.143:8080). If you use ThingsBoard Cloud, keep the default. Click Add.
3. Your new Edge instance appears at the top of the list, and the Edge created dialog opens with ready-to-use installation instructions (unless Do not show again was turned on earlier).

Go to Edge management > Edges, click Add edge and select Add new edge Enter the Edge name and click Add The new Edge instance appears at the top of the list

The instructions generated by the server already contain the credentials of this Edge (Edge key and Edge secret), so this is the fastest way to install it. If you closed the dialog, open the instructions again:

1. Click the Edge to open its details.
2. On the Details tab, click Install & Connect Instructions.
3. Select the Docker, Ubuntu, or CentOS/RHEL tab and follow the instructions to install Edge and connect it to the server. The dialog opens on the Agent tab, which is for remote installation with a Remote Agent.

Click the Edge to open its details Click Install & Connect Instructions Follow the instructions to install and connect Edge to the server

If you are unable to use the guided instructions above, follow the steps below to install and configure Edge manually.

ThingsBoard Edge requires Java 25. To install OpenJDK 25:

OpenJDK 25 is available on Raspberry Pi OS based on Debian 13 (Trixie) and later.

sudo apt update && sudo apt install openjdk-25-jdk-headless

Configure your operating system to use OpenJDK 25 by default:

sudo update-alternatives --config java

Verify the installation:

java -version

The expected output:

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

wget https://github.com/thingsboard/thingsboard-edge/releases/download/v4.4.0.2/tb-edge-4.4.0.2.deb
sudo dpkg -i tb-edge-4.4.0.2.deb

ThingsBoard Edge uses PostgreSQL as its local database.

Install PostgreSQL:

# Automated repository configuration:
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

# Install and start PostgreSQL:
sudo apt update
sudo apt -y install postgresql
sudo service postgresql start

Set the password for the main PostgreSQL user:

sudo -u postgres psql -c "\password"

Enter and confirm the password when prompted.

Create a new PostgreSQL database named tb_edge:

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

Add the database connection settings to the ThingsBoard Edge configuration file:

sudo bash -c 'cat >> /etc/tb-edge/conf/tb-edge.conf <<EOL
export DATABASE_TS_TYPE=sql
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/tb_edge
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=PUT_YOUR_POSTGRESQL_PASSWORD_HERE
export SQL_POSTGRES_TS_KV_PARTITIONING=MONTHS
EOL'

Replace PUT_YOUR_POSTGRESQL_PASSWORD_HERE with your actual PostgreSQL password.

SQL_POSTGRES_TS_KV_PARTITIONING sets the partitioning interval for time-series storage. Allowed values: DAYS, MONTHS, YEARS, INDEFINITE.

On the server, open the Edge and click Copy Edge key and Copy Edge secret on its Details tab. Store these values securely. You need them below.

Edit the ThingsBoard Edge configuration file to set your Edge credentials and cloud connection parameters.

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf
export CLOUD_ROUTING_KEY=PUT_YOUR_EDGE_KEY_HERE
export CLOUD_ROUTING_SECRET=PUT_YOUR_EDGE_SECRET_HERE
export CLOUD_RPC_HOST=thingsboard.cloud
export CLOUD_RPC_PORT=7070
export CLOUD_RPC_SSL_ENABLED=true
EOL'

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf
export CLOUD_ROUTING_KEY=PUT_YOUR_EDGE_KEY_HERE
export CLOUD_ROUTING_SECRET=PUT_YOUR_EDGE_SECRET_HERE
export CLOUD_RPC_HOST=eu.thingsboard.cloud
export CLOUD_RPC_PORT=7070
export CLOUD_RPC_SSL_ENABLED=true
EOL'

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf
export CLOUD_ROUTING_KEY=PUT_YOUR_EDGE_KEY_HERE
export CLOUD_ROUTING_SECRET=PUT_YOUR_EDGE_SECRET_HERE
export CLOUD_RPC_HOST=PUT_YOUR_RPC_HOST
export CLOUD_RPC_PORT=7070
export CLOUD_RPC_SSL_ENABLED=false
EOL'

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'

Configuration parameters:

On devices with limited RAM, you can constrain the JVM heap size to prevent out-of-memory issues:

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

Adjust these values based on available RAM. A good rule of thumb: set -Xmx to half the total RAM if ThingsBoard Edge is the only memory-intensive process, or one-third if other services are also running.

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

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

Start the ThingsBoard Edge service:

sudo service tb-edge start

Once the service is running, open the Edge UI at http://localhost:8080 (port 18080 if you moved the Edge ports), or replace localhost with your Raspberry Pi’s local IP address if accessing from another device on the network.

Log in using your tenant credentials from ThingsBoard Server or ThingsBoard Cloud. To check the connection, go to Edge > Status in the Edge UI. The status is Connected.

ThingsBoard Edge logs are stored in:

/var/log/tb-edge

To check for errors:

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

To stop the ThingsBoard Edge service:

sudo service tb-edge stop

To restart the ThingsBoard Edge service:

sudo service tb-edge restart

To check the status of the ThingsBoard Edge service:

sudo service tb-edge status