New Integration Guide

(Python & MQTT)

Basics

Every customer can access the data of the sensors assigned to him via MQTT. You need to let us know if you wanna access your data via MQTT!

The following data is valid for the MQTT broker:

• mqtts://data.sentinum.de:8883 for secured (recommended), mqtt://data.sentinum.de:1883 for unsecured traffic.
• Each client must authenticate itself using a username and password. These are issued by Sentinum upon request and are independent of the my.sentinum.de user accounts. If authentication by private key is desired, this can be requested.
• QoS = 0, up to QoS = 2 are allowed
• Username and password or key can be used for multiple clients. However, a unique ClientID should be used for each client.
• There are two ways to access your data (Python, Node Red)

Telemetry Data

Telemetry data is published according to the following topic schemes:

devices/<customerTransformedName>/<deviceBaseType>/<deviceType>/<deviceId>/up

• customerTransformedName: corresponds to MQTT user names.
• deviceBaseType: device base type. This type represents the product name, e.g. “apollon”, “febris”, or “neptun”
• deviceType: device type. This type includes specific sub variants of sensors. For most sensors, deviceType mirrors deviceBaseType. Generally, we recommend using ‘+’ placeholder in the topic here
• deviceId: Unique device id. Usually a combination of device type and EUI (e.g. IMEI for Cellular, Dev.-EUI for LoRaWAN/MIOTY).

Subscription for telemetry data of all Febris/Apollon sensors (deviceBaseType=febris/apollon).

devices/musterfirma/febris/+/+/up
devices/musterfirma/apollon/+/+/up

Subscription for all sensors (e.g. febris + apollon)

devices/musterfirma/+/+/+/up or devices/musterfirma/#

Python Script

The easiest access to you data is using a Python script.

In the example code we are using Paho MQTT, which you can install with

pip install paho-mqtt

In the following example code you have to set username and password, which you will get fom us.

Optionally: You can specify the topic.

import paho.mqtt.client as mqtt
import ssl

# MQTT broker address and port
broker_address = "data.sentinum.de"
broker_port = 8883

# MQTT credentials
username = ""       # we will provide you with the information
password = ""       # we will provide you with the information

# MQTT topic to subscribe to
topic = "devices/" + username + "/#"
# TOPIC EXAMPLES
# topic = devices/USERNAME/febris/+/+/up
# topic = devices/USERNAME/apollon/+/+/up

# MQTT topic to publish to (if required)
publish_topic = "my/publish/topic"

# QoS level to use when subscribing and publishing
# QoS 0 (at most once): The message will be delivered at most once, and the broker will not send any confirmation that the message has been received.
# QoS 1 (at least once): The message will be delivered at least once, and the broker will send a confirmation when the message has been received.
# QoS 2 (exactly once): The message will be delivered exactly once, and the broker will send a confirmation when the message has been received and processed.
# ONLY 0 AND 2 ARE ACCEPTABLE
qos_level = 0

#--------------------------------------------------------------------------------#
#-------------------------------- CHANGE AT YOUR --------------------------------#
#---------------------------------- OWN RISK! -----------------------------------#
#--------------------------------------------------------------------------------#

# Path to the client certificate and key files (if required)
cert_file = None
key_file = None

# Create an SSL context and load the client certificate and key files (if required)
ssl_context = ssl.create_default_context()
if cert_file is not None and key_file is not None:
    ssl_context.load_cert_chain(cert_file, key_file)

receivedMessage = ""

# Callback function that will be called when a new message is received
def on_message(client, userdata, message):
    receivedMessage = str(message.payload.decode())
    print("Received message: " + receivedMessage)

# Create a new MQTT client instance
client = mqtt.Client()

# Set the username and password (if required)
if username is not None and password is not None:
    client.username_pw_set(username, password)

# Set the callback function for new messages
client.on_message = on_message

# Set the SSL context for secure connection
client.tls_set_context(context=ssl_context)

# Connect to the MQTT broker
client.connect(broker_address, broker_port)

# Subscribe to the topic
client.subscribe(topic, qos=qos_level)

# Publish a message to the topic with QoS 1
client.publish(publish_topic, receivedMessage, qos=qos_level)

# Start the MQTT client loop to listen for new messages
client.loop_forever()

Node-RED

Select the “mqtt in” node and connect it to a “debug” node

MQTT IN Node Configuration

Server Configuration

Configuration for TLS with public certificate

You can see the incoming messages in the debug section on the right

The field “deviceId” tells you which sensor sent the message. An example: apollon_lora_FCA84A0123456789 or neptun_cellular_123123123123123

Notes

• Currently, only telemetry data is made accessible. If a downlink configuration of the sensors is necessary, this can be done by Sentinum.
• A comprehensive API including device management and configuration is currently under construction and will be made available to customers immediately upon completion.