--- updatedAt: 2026-09-18T07:52:21.000Z agentTools: projectIndex: https://docs.sixfab.com/llms.txt --- # Deploying ThingsBoard Send telemetry from ALPON X5 AI or ALPON X4 to ThingsBoard through ALPON Cloud: create the ThingsBoard MQTT integration and topic filter, build a lightweight MQTT client container, push it to the Sixfab Container Registry, and verify the data in ThingsBoard. {`

Deploy ThingsBoard on ALPON

Connect your ALPON X5 AI or ALPON X4 to ThingsBoard and stream telemetry into its dashboards. This guide sets up an MQTT integration in ThingsBoard, builds a small MQTT client container that publishes a test reading through an external broker, and deploys it through ALPON Cloud.

ALPON X5 AI ALPON X4 ThingsBoard IoT platform
ALPON · Tutorial · Containers · IoT platforms
How do I deploy ThingsBoard on ALPON?

Create an MQTT integration in ThingsBoard that listens on v1/devices/+/telemetry at broker.hivemq.com:1883 with a TBEL uplink converter, build the thingsboard-mqtt-alpon-x4 MQTT client image and push it to your Sixfab Container Registry, then use the Applications → Deploy panel on ALPON Cloud to launch it on your ALPON X5 AI or ALPON X4 with the TOPIC, CLIENT_ID, MQTT_SERVER, and MQTT_PORT environment variables. The reading appears under the device's Latest telemetry tab in 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.

Before you start

You need an ALPON Cloud account, a ThingsBoard account, and an ALPON X5 AI or ALPON X4 registered and activated on ALPON Cloud with an active internet connection — see the ALPON X4 Getting Started page for setup instructions. Docker must be installed on your build machine to build and push the image. Familiarity with IoT concepts, containerized applications, and ThingsBoard dashboards helps. New to container deployment? Start with Containerize Apps for ALPON.

  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.

    ThingsBoard sidebar with Entities → Devices selected and the empty Devices table
    The Devices page under Entities in ThingsBoard.

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

    The + menu on the ThingsBoard Devices table with Add new device highlighted
    Adding a new device from the Devices table.

    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.

    ThingsBoard Add new device dialog with the device name filled in
    The Add new device dialog with only the name filled in.
  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.

    ThingsBoard Integrations page with the + button to add a new integration
    The Integrations page in ThingsBoard.

    Select MQTT as the integration type.

    ThingsBoard Add integration dialog with MQTT selected as the integration type
    Choosing MQTT as the integration type.

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

    ThingsBoard uplink data converter step with TBEL selected and the decoder editor open
    The uplink data converter step with TBEL selected.
    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.
    ThingsBoard MQTT integration connection step with host broker.hivemq.com, port 1883, and topic filter v1/devices/+/telemetry
    The MQTT connection settings with the HiveMQ broker and the topic filter.

    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.

    Sixfab Container Registry page on ALPON Cloud with the + Add Container button
    The Sixfab Container Registry page on ALPON Cloud.
    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.
    KeyValue
    TOPICv1/devices/alponx4/telemetry
    CLIENT_IDalponx4
    MQTT_SERVERbroker.hivemq.com
    MQTT_PORT1883
    ALPON Cloud Deploy Container window with the thingsboard-mqtt-alpon-x4 image and the TOPIC, CLIENT_ID, MQTT_SERVER, and MQTT_PORT environment variables
    The Deploy Container window with the image selected and the four environment variables set.

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

    The + Deploy button at the bottom of the ALPON Cloud Deploy Container window
    Deploying the container from ALPON Cloud.
  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.

    ThingsBoard device details for ALPON X4 showing the temperature key with value 26 in the Latest telemetry tab
    The test reading received by ThingsBoard under Latest telemetry.

    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.

Ready when…
  • The thingsboard-mqtt-client container shows as running in the Applications section.
  • The MQTT integration in ThingsBoard shows the connection as active.
  • The ALPON X4 device lists a temperature reading under Latest telemetry.

The ALPON is now integrated with ThingsBoard over MQTT for real-time data collection: you created a device in ThingsBoard, added an MQTT integration, and deployed an MQTT client through ALPON Cloud. For further assistance, refer to the ThingsBoard documentation or contact Sixfab support.

`} > **Production image policy:** Replace floating `:latest` references with a reviewed immutable tag or digest, then record the selected version for rollback. {`
Continue exploring

Related guides

Build on this workflow with deployment, fleet-management, and hardware guidance for the ALPON platform.

Workflow Deploy Applications on ALPON Push an ARM64 image, configure its runtime, and launch it from ALPON Cloud. Open guide Platform ALPON Cloud Manage devices, applications, connectivity, and remote operations from one workspace. Open guide Hardware Compare ALPON devices Compare ALPON X4 and ALPON X5 AI capabilities for your edge workload. Open guide Quickstart ALPON X4 Getting Started Bring an ALPON X4 online and complete the first device setup. Open guide
`}