Deploying ThingsBoard

Overview

ThingsBoard is an open-source IoT platform designed for the rapid development, management, and scaling of IoT projects. In this guide the ALPON X5 AI or ALPON X4 runs a lightweight MQTT client container that publishes telemetry to an external MQTT broker; a ThingsBoard MQTT integration subscribes to that broker, decodes the payload with a TBEL converter, and maps it to the right device.

The steps below are identical on ALPON X4 and ALPON X5 AI. For other integration types, converters, and dashboards, see the official ThingsBoard documentation.

1. 1

   Create a device on ThingsBoard (optional)

   The integration can create the device automatically the first time data arrives, so you can skip this step if you prefer. To create it manually, log in to your ThingsBoard instance and navigate to Entities → Devices in the sidebar.

   

   Click the + icon in the top-right corner of the table and select Add new device.

   

   Enter the device name (for example ALPON_X4). No other changes are required at this time. Click Add and close the window — the device is created.

   

2. 2

   Add the MQTT integration and topic filter

   To transfer data from the ALPON to ThingsBoard via an external MQTT broker, you need an MQTT integration in ThingsBoard. The integration uses a topic filter to choose which MQTT topics to listen to and a data converter written in TBEL to process incoming data and map it to the appropriate device.

   In ThingsBoard, open the Integrations section in the left-side menu and click the + icon to add a new integration.

   

   Select MQTT as the integration type.

   

   In the Uplink data converter step, select TBEL, replace the default decoder with the code below, and click Next.

   

   TBEL · uplink decoder

   // Decode an uplink message from a buffer
   // payload - array of bytes
   // metadata - key/value object
   
   /** Decoder **/
   
   var payloadObj = decodeToJson(payload);
   
   var deviceName = 'ALPON X4';
   var deviceType = 'alpon';
   var groupName = 'alpon devices';
   var manufacturer = 'Sixfab';
   
   var result = {
      deviceName: deviceName,
      deviceType: deviceType,
   
      groupName: groupName,
      attributes: {
          model: 'X4',
          serialNumber: '111111111',
          manufacturer: manufacturer
      },
      telemetry: {
          temperature: payloadObj.temperature,
      }
   };
   
   /** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/
   
   return result;

   Configure the broker details, then click Add:

   Host broker.hivemq.com

   Port 1883

   Topic v1/devices/+/telemetry — this filter determines which topics the integration listens to.

   

   Understanding the topic filter

   The topic filter v1/devices/+/telemetry uses a single-level wildcard (+) that matches any single topic level in that position. It will match topics such as:

   • v1/devices/device1/telemetry
   • v1/devices/sensorA/telemetry
   • v1/devices/room23/telemetry

   It will not match topics such as:

   • v1/devices/device1/sensor/telemetry (because + matches only one level)
   • v1/devices/telemetry (because a level is missing)
   • v1/attributes/+/client (different topic structure)

   This structure lets the integration process data from multiple devices, each using a unique identifier (for example device1, sensorA, room23) in the topic. The ALPON can therefore send telemetry to ThingsBoard via the external broker, with the integration mapping the data to the correct device based on the topic structure.

3. 3

   Add the MQTT client container

   Next, build the MQTT client image on your local computer and push it to your Sixfab Container Registry so it is available to the device. Make sure Docker is installed on your machine — download it from docker.com if needed.

   Create a file named Dockerfile with the following content to set up the environment for the MQTT client:

   Dockerfile

   FROM alpine:latest
   
   RUN apk update && apk add \\
       mosquitto-clients \\
       mosquitto \\
       python3 \\
       py3-pip \\
       bash
   
   RUN pip3 install paho-mqtt --break-system-packages
   
   WORKDIR /app
   
   COPY mqtt_test.py /app/
   
   CMD ["python3", "/app/mqtt_test.py"]

   Create a file named mqtt_test.py in the same directory as the Dockerfile. This script makes the ALPON publish telemetry to ThingsBoard via MQTT — it connects to the broker, subscribes to the topic, and publishes a test temperature reading:

   python · mqtt_test.py

   import paho.mqtt.client as mqtt
   import json
   import ssl
   import time
   import os
   
   MQTT_SERVER = os.getenv("MQTT_SERVER")
   MQTT_PORT = os.getenv("MQTT_PORT")
   CLIENT_ID = os.getenv("CLIENT_ID")
   TOPIC = os.getenv("TOPIC")
   
   
   def on_connect(client, userdata, flags, rc):
       print(f"Connected with result code {rc}")
       client.subscribe(TOPIC, qos=0)
       print(f"Subscribed to topic: {TOPIC}")
   
       # Publish a test message after connecting
       test_message = {
           "temperature": 26
       }
       client.publish(TOPIC, json.dumps(test_message), qos=0)
       print("Test message published.")
   
   def on_message(client, userdata, msg):
       print(f"RECEIVED MESSAGE on {msg.topic}:")
       try:
           message = json.loads(msg.payload.decode())
           print(json.dumps(message, indent=4))
       except Exception as e:
           print(f"Error decoding JSON: {e}")
           print(msg.payload.decode())
   # Set up MQTT client
   client = mqtt.Client(client_id=CLIENT_ID, clean_session=True)
   
   # Set up callbacks
   client.on_connect = on_connect
   client.on_message = on_message
   
   # Enable SSL/TLS
   client.connect(MQTT_SERVER, int(MQTT_PORT), 60)
   
   # Start the loop
   client.loop_forever()

   Open a terminal in the directory containing the Dockerfile and mqtt_test.py, and build the arm64 image:

   bash · build the image

   docker build --platform=linux/arm64 -t thingsboard-mqtt-alpon-x4:latest .

   Then log in to Sixfab Registry, click + Add Container, and follow the prompts to push the image.

   

   Pushing images to the Sixfab Container Registry

   For the full walkthrough of tagging and pushing an image, see Update Containers from the Sixfab Container Registry and the Deploy Applications page.

4. 4

   Deploy the container on ALPON

   Open your device in ALPON Cloud, go to the Applications section, and click + Deploy. In the Deploy Container window, use these settings:

   Container Name thingsboard-mqtt-client

   Image The thingsboard-mqtt-alpon-x4 image and tag you pushed to the Sixfab Container Registry.

   Environment Click + Add More in the environment section and add the four variables in the table below.

   Key	Value
   TOPIC	v1/devices/alponx4/telemetry
   CLIENT_ID	alponx4
   MQTT_SERVER	broker.hivemq.com
   MQTT_PORT	1883

   

   Click + Deploy to launch the MQTT client on the device.

   

5. 5

   Check the data on ThingsBoard

   Once the container is running, verify that telemetry is received and displayed in ThingsBoard. Log in to your ThingsBoard instance, navigate to Entities → Devices, and select your ALPON X4 device. Open the Latest telemetry tab to view the temperature value sent by the container.

   

   If nothing appears, confirm the container is running in the Applications section and that the TOPIC value matches the integration's topic filter from step 2.

The Devices page under Entities in ThingsBoard.

Adding a new device from the Devices table.

The Add new device dialog with only the name filled in.

The Integrations page in ThingsBoard.

Choosing MQTT as the integration type.

The uplink data converter step with TBEL selected.

The MQTT connection settings with the HiveMQ broker and the topic filter.

The Sixfab Container Registry page on ALPON Cloud.

The Deploy Container window with the image selected and the four environment variables set.

Deploying the container from ALPON Cloud.

The test reading received by ThingsBoard under Latest telemetry.