Flespi MQTT Connection

Overview

Flespi is a cloud-based platform for collecting and managing IoT device data. Its secure and flexible infrastructure suits device tracking, data analysis, and IoT projects, and it speaks the lightweight MQTT protocol for efficient communication. In this guide the ALPON runs a containerized MQTT client that connects to Flespi over TLS, subscribes to a topic, and publishes a JSON test message that you then confirm in the Flespi dashboard.

The steps below are identical on ALPON X4 and ALPON X5 AI. For more on Flespi’s features, see the Flespi documentation.

1. 1

   Create an MQTT channel in Flespi

   The channel is the hub that receives the ALPON’s MQTT messages. In your Flespi account:

   1. Log in at flespi.com.
   2. Go to Telematics Hub → Channels in the Flespi dashboard.
   3. Create a new channel (e.g. named ALPONX4-MQTT-CONNECTION) and configure it to listen for MQTT traffic. Make sure the channel is active, and note the Flespi token it provides — the ALPON authenticates with it in step 3.

   

2. 2

   Build the MQTT client container

   The client runs as a container on the ALPON and handles all communication with the Flespi broker. It uses these connection settings, all supplied at deploy time as environment variables:

   Broker mqtt.flespi.io (from MQTT_SERVER)

   Port 8883 — TLS, certificate verification required (from MQTT_PORT)

   Topic messages/alponx4 — subscribed and published with QoS 1 (from TOPIC)

   Client ID alponx4, clean session

   Username Your Flespi token (from TOKEN); the password is empty.

   Create the Dockerfile

   On your local machine, create a file named Dockerfile. It defines a minimal Alpine Linux environment with the Mosquitto clients and the paho-mqtt Python library:

   Dockerfile

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

   Create the MQTT client script

   In the same directory, create mqtt_test.py. On connect it subscribes to the topic and publishes a JSON test message; every message received on the topic is printed to the container log:

   python · mqtt_test.py

   import paho.mqtt.client as mqtt
   import json
   import ssl
   import time
   import os
   
   # Your flespi token (replace with your actual token)
   FLESPI_TOKEN = os.getenv("TOKEN")
   
   # Topic to subscribe and publish to
   TOPIC = os.getenv("TOPIC")
   
   # Define callback functions
   def on_connect(client, userdata, flags, rc):
       print(f"Connected with result code {rc}")
       client.subscribe(TOPIC, qos=1)
       print(f"Subscribed to topic: {TOPIC}")
   
       # Publish a test message after connecting
       test_message = {
           "ident": "alponx4",
           "device": {
               "id": 1,
               "name": "alponx4"
           },
           "message": "SAMPLE TEST MESSAGE",
           "timestamp": int(time.time())
       }
       client.publish(TOPIC, json.dumps(test_message), qos=1)
       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="alponx4", clean_session=True)
   client.username_pw_set(FLESPI_TOKEN, password="")  # Token as username, empty password
   
   # Set up callbacks
   client.on_connect = on_connect
   client.on_message = on_message
   
   # Enable SSL/TLS
   client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
   
   # Connect to flespi MQTT broker
   client.connect(os.getenv("MQTT_SERVER"), int(os.getenv("MQTT_PORT")), 60)
   
   # Start the loop
   client.loop_forever()

   Build the image

   Open a terminal in the directory containing the Dockerfile and mqtt_test.py, and build the image for the ALPON’s arm64 architecture:

   bash · build the image

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

   This creates an image tagged flespi-mqtt-alpon-x4:latest.

   Push the image to the Sixfab Container Registry

   Log in to ALPON Cloud, open the Sixfab Container Registry page, click + Add Container, and follow the prompts to push the image.

   Deploy Applications

   Visit the Deploy Applications page for all the details on pushing your container image to the Sixfab Container Registry.

3. 3

   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 flespi-mqtt-client

   Image The flespi-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	messages/alponx4
   TOKEN	YOUR_FLESPI_TOKEN — the token from step 1
   MQTT_SERVER	mqtt.flespi.io
   MQTT_PORT	8883

   Click + Deploy to start the Flespi client on the device.

4. 4

   Verify and monitor the messages

   Once deployed, the ALPON connects to the Flespi broker, subscribes to the topic, and publishes the test message. To confirm it arrived:

   1. Log in to Flespi and go to Telematics Hub → Channels.
   2. Select the channel you created (e.g. ALPONX4-MQTT-CONNECTION).
   3. Check the message log for the test message. Optionally click Add columns to show the messages column carrying the message field sent by the script.

   

   Troubleshooting

   • Environment variables: double-check that TOPIC, TOKEN, MQTT_SERVER, and MQTT_PORT are set correctly in ALPON Cloud.
   • Flespi token: make sure the token from your Flespi MQTT channel is valid and entered exactly.
   • Connection issues: if no messages appear, check the container status and logs in ALPON Cloud and confirm the MQTT channel is active in Flespi.

The MQTT channel created under Telematics Hub → Channels in Flespi.

The test message from the ALPON listed in the channel’s message log.