MQTT

MQTT ist die übliche Wahl für Firmware, die Sie selbst schreiben: eine Verbindung, die offen bleibt, und eine Veröffentlichung, sobald ein Messwert vorliegt.

Bevor Sie beginnen, holen Sie sich die Device UUID, das MQTT-Topic und die MQTT-Anmeldedaten von Gerätedetails; siehe Was Sie zuerst von der Plattform brauchen.

Verbindungseinstellungen

Einstellung	Wert
Host	mqtt.sensocan.com
Port	8883 für TLS, 1883 für einfaches TCP
Client-ID	Genau die Device UUID
Benutzername	Der MQTT-Benutzername aus Gerätedetails (er hat die Form device- gefolgt von der Device UUID)
Passwort	Das MQTT-Passwort aus Gerätedetails
Clean Session	Ja
QoS	0 oder 1. Verwenden Sie 1 bei einer unzuverlässigen Verbindung
Keep-alive	Nach Ihrer Wahl; kürzere Keep-alive-Intervalle erkennen einen Abriss früher

Verwenden Sie im Produktivbetrieb den Port 8883. Der Port 1883 überträgt das Gerätepasswort im Klartext und ist für Arbeiten am Prüfplatz in einem Netz gedacht, das Sie selbst kontrollieren.

Eine Clean Session (es wird keine Sitzung fortgesetzt) genügt vollkommen: Geräte veröffentlichen nur. Abonnements werden abgelehnt, es gibt also keine Sitzungsdaten, deren Fortsetzung sich lohnen würde.

Der Dialog MQTT-Anmeldedaten, geöffnet auf Gerätedetails eines Standardgeräts (kein Gateway), mit den Feldern Benutzername und Passwort samt ihren Schaltflächen zum Kopieren und der Schaltfläche Beides kopieren.

Das Passwort wird verschlüsselt gespeichert. Beim erneuten Öffnen des Dialogs erscheint dasselbe Passwort: Über die Oberfläche lässt es sich nicht wechseln, und ein neues wird nur dann automatisch ausgestellt, wenn die gespeicherten Anmeldedaten verloren gehen oder sich nicht mehr entschlüsseln lassen.

Die Client-ID-Regel

Ihre Client-ID muss die Device UUID sein

Eine Verbindung mit einer anderen Client-ID wird abgelehnt, ganz gleich, wie Benutzername und Passwort lauten. Das ist der häufigste Fehler nach einer Firmware-Änderung, denn viele MQTT-Bibliotheken erfinden die Client-ID für Sie: PubSubClient verwendet das, was Sie an connect() übergeben, und andere Bibliotheken nehmen standardmäßig eine zufällige Zeichenfolge oder die MAC-Adresse. Setzen Sie die Client-ID ausdrücklich selbst.

Zwei Geräte dürfen sich niemals eine Client-ID teilen. Geschieht es doch, verdrängt jede Verbindung die andere: Die ältere Sitzung wird jedes Mal getrennt, wenn sich die andere neu verbindet, und beide Geräte pendeln endlos zwischen verbunden und nicht verbunden. Haben Sie die Firmware auf ein zweites Gerät kopiert, legen Sie dafür einen eigenen Geräteeintrag mit einer eigenen UUID an.

Topics

Es gibt drei Publish-Topics, also drei Kanäle, unter denen ein Gerät veröffentlichen kann. Welches davon Sie verwenden, entscheidet darüber, wie die Nutzdaten (payload) gelesen werden.

1. Ein Messwert für einen Sensor

tenant/{tenant_id}/device/{device_uuid}/sensor/{sensor_identifier}

{
  "data": {
    "value": 24.5,
    "timestamp": "2026-09-03T10:00:00Z"
  },
  "battery_voltage": 3.7
}

2. Mehrere Messwerte für einen Sensor

Beachten Sie den Plural sensors. Verwenden Sie dieses Topic, um den Puffer eines einzelnen Sensors zu leeren.

tenant/{tenant_id}/device/{device_uuid}/sensors/{sensor_identifier}

{
  "data": [
    { "value": 24.0, "timestamp": "2026-09-03T09:00:00Z" },
    { "value": 24.2, "timestamp": "2026-09-03T09:15:00Z" },
    { "value": 24.4, "timestamp": "2026-09-03T09:30:00Z" }
  ]
}

3. Messwerte für mehrere Sensoren

Das Topic auf Geräteebene: genau das, was auf Gerätedetails steht. Das ist die effizienteste Möglichkeit, wenn ein Gerät mehr als einen Sensor trägt.

tenant/{tenant_id}/device/{device_uuid}

{
  "data": [
    { "sensor_slug": "temp_01", "value": 24.5 },
    { "sensor_slug": "humidity_01", "value": 45.2 },
    { "sensor_uuid": "7a8b9c0d-1234-5678-90ab-cdef12345678", "value": 100 }
  ],
  "battery_voltage": 3.7
}

Jeder Eintrag benennt seinen Sensor entweder über sensor_slug oder über sensor_uuid. Ein Eintrag ohne beides wird verworfen.

{sensor_identifier} in den ersten beiden Topics ist ebenfalls entweder der Slug des Sensors oder seine UUID; beide stehen auf der Seite des Sensors, und der Abgleich erfolgt exakt, einschließlich Groß- und Kleinschreibung.

Sie können auch allein die Batteriespannung veröffentlichen, ganz ohne data-Schlüssel, auf jedem der drei Topics:

{ "battery_voltage": 3.7 }

Topics nicht von Hand zusammensetzen

Gerätedetails gibt das Topic auf Geräteebene vollständig aus, mit einer Schaltfläche zum Kopieren, und die Schaltfläche MQTT-Payload-Beispiele daneben öffnet alle drei Topics mit den passenden Nutzdaten, die bereits mit der Organisation, der UUID und dem ersten Sensor dieses Geräts gefüllt sind.

Der Dialog MQTT-Payload-Beispiele auf Gerätedetails, der Tab Einzeln ist ausgewählt, mit dem erzeugten Topic und den JSON-Nutzdaten für ein Gerät mit mindestens einem Sensor.

Sie dürfen nur unter dem Topic Ihres eigenen Geräts veröffentlichen. Eine Veröffentlichung, deren Topic die UUID eines anderen Geräts trägt oder Ihre UUID unter der falschen Organisation, wird von der Verbindung abgelehnt und nicht stillschweigend übergangen.

Der data-Umschlag

Nutzdaten ohne data werden angenommen und dann ignoriert

Messwerte stehen unter einem data-Schlüssel auf oberster Ebene. Veröffentlichen Sie {"value": 24.5}, wird die Nachricht zugestellt, Ihr Gerät gilt als online, und es entsteht kein einziger Messwert. Nichts meldet Ihnen das zurück, denn eine MQTT-Veröffentlichung hat keine Antwort.

Wenn Ihre Nachrichten offensichtlich ankommen, das Gerät also online angezeigt wird und Zuletzt verbunden weiterläuft, aber keine Werte erscheinen, prüfen Sie zuerst den Umschlag.

Beispiel: ESP32 / Arduino

#include <PubSubClient.h>

const char* mqtt_server = "mqtt.sensocan.com";
const int   mqtt_port   = 8883;  // TLS — pass a WiFiClientSecure to PubSubClient
                                 // for this port; 1883 takes a plain WiFiClient

// All three come from Device Details. The client ID must be the Device UUID;
// the username and password are the MQTT credentials shown on that page.
const char* device_uuid   = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const char* mqtt_user     = "device-a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const char* mqtt_password = "your-device-mqtt-password";

// Copy the topic from Device Details rather than assembling it here.
const char* topic = "tenant/123/device/a1b2c3d4-e5f6-7890-abcd-ef1234567890/sensor/temp_01";

void setup() {
  client.setServer(mqtt_server, mqtt_port);
  client.setBufferSize(512);            // the default is too small for batches
  client.connect(device_uuid, mqtt_user, mqtt_password);
}

void loop() {
  if (!client.connected()) {
    client.connect(device_uuid, mqtt_user, mqtt_password);
  }
  client.loop();

  // The data envelope is required.
  const char* payload = "{\"data\":{\"value\":25.3}}";
  client.publish(topic, payload);
  delay(60000);                         // once a minute
}

PubSubClient verwirft eine Veröffentlichung stillschweigend, wenn sie den Puffer überschreitet, der standardmäßig 256 Bytes groß ist: genug für die Nutzdaten mit einem einzelnen Messwert oben, zu wenig für einen Stapel. Rufen Sie setBufferSize() auf, bevor Sie Stapel senden.

Fehlersuche

Die Verbindung wird abgelehnt

Arbeiten Sie diese Liste der Reihe nach ab:

1. Client-ID: Sie muss genau die Device UUID sein. Geben Sie aus, was Ihre Bibliothek tatsächlich gesendet hat.
2. Benutzername und Passwort: Kopieren Sie beides erneut aus dem Dialog MQTT-Anmeldedaten; der Dialog zeigt immer dasselbe, unveränderliche Passwort.
3. Gerätestatus: Ein Gerät, das auf Gerätedetails Fehler anzeigt, darf sich nicht verbinden. Ändern Sie seinen Status auf der Geräteseite zurück.
4. Kontostatus: Geräte eines gesperrten oder inaktiven Kontos werden abgelehnt. Wenden Sie sich an einen Administrator.

Das Gerät verbindet sich und wird getrennt, sobald sich ein anderes Gerät verbindet

Zwei Geräte teilen sich eine Client-ID. Siehe Die Client-ID-Regel.

Das Gerät ist online, aber es erscheinen keine Werte

Prüfen können Sie das auf Gerätedetails: Zuletzt verbunden und das Status-Badge zeigen Ihnen, dass Nachrichten ankommen, und die Tabelle Sensoren führt für jeden Sensor Aktueller Wert und Zuletzt aktualisiert auf.

• Zuletzt verbunden läuft weiter, die Sensoren zeigen keine Daten: Die Nachricht kommt an, es entsteht aber kein Messwert. Prüfen Sie den data-Umschlag und danach, ob in jedem Messwertobjekt value enthalten ist.
• Einige Sensoren aktualisieren sich, andere nicht: Die Kennung der leer bleibenden Sensoren passt zu keinem Sensor dieses Geräts. Vergleichen Sie sie Zeichen für Zeichen mit dem Slug und der UUID auf der Seite des Sensors.
• Alles sieht richtig aus und trotzdem passiert nichts: Die Messwerte werden angenommen und an die Regelkette übergeben, und die Kette verwirft sie. Eine Kette muss einen Speicherschritt enthalten, damit Werte erscheinen. Siehe Verwaltung → Regelketten.
• Zuletzt verbunden läuft nicht weiter: Die Nachricht kommt überhaupt nicht an. Vergleichen Sie das Topic mit dem, das auf Gerätedetails steht, und prüfen Sie, ob Ihre Nutzdaten gültiges JSON sind.

Ein Wert kommt einmal an und aktualisiert sich dann nicht mehr

Sendet Ihr Gerät denselben Wert wiederholt, werden Wiederholungen innerhalb weniger Sekunden bei einigen Sensortypen unterdrückt. Ändern Sie den Wert oder warten Sie das Intervall ab, um sich zu vergewissern, dass die Verbindung in Ordnung ist.