MQTT-Clients nach HiveMQ umstellen: Beispiele für ESP32, Python, Node.js und Node-RED

Wenn ein Client HiveMQ Cloud Serverless verlässt, ändern sich vier Dinge: der Hostname, die Zugangsdaten, die Client-ID und manchmal die TLS-Vertrauenseinstellungen. Ihre Topics, Payloads und Ihre Anwendungslogik bleiben gleich. Dieser Artikel zeigt genau, was Sie bei den gängigsten Clients ändern müssen, mit Vorher-nachher-Beispielen und einem privaten Broker von ConnectMQ als Ziel.

Das übergeordnete Vorgehen beschreibt der Migrationsleitfaden für HiveMQ Serverless.

Was sich ändert und was bleibt

Achten Sie auf den Port für Secure WebSocket: Browser-Dashboards haben oft 8884 fest eingetragen, ConnectMQ verwendet dagegen 8084. Prüfen Sie in Ihrer HiveMQ-Konsole die genauen Werte, die Ihr Cluster genutzt hat.

ESP32 mit Arduino und PubSubClient

Vorher (HiveMQ Cloud):

const char* MQTT_HOST = "abc123.s1.eu.hivemq.cloud";
const char* MQTT_USER = "hivemq-user";
const char* MQTT_PASS = "hivemq-pass";
String clientId = "sensor-" + WiFi.macAddress();

Nachher (ConnectMQ):

#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <PubSubClient.h>

const char* MQTT_HOST = "broker.connectmq.com";
const int   MQTT_PORT = 8883;
const char* MQTT_USER = "YOUR_USERNAME";
const char* MQTT_PASS = "YOUR_PASSWORD";
const char* CLIENT_ID_BASE = "YOUR_CLIENT_ID";

// ISRG Root X1 (Let's Encrypt), PEM von letsencrypt.org/certificates einfügen
static const char ROOT_CA[] PROGMEM = R"EOF(
-----BEGIN CERTIFICATE-----
...ISRG Root X1...
-----END CERTIFICATE-----
)EOF";

WiFiClientSecure net;
PubSubClient mqtt(net);

void connectMqtt() {
  String mac = WiFi.macAddress();
  mac.replace(":", "");
  String clientId = String(CLIENT_ID_BASE) + "_" + mac;   // ausgegebene ID + eindeutiges Suffix
  while (!mqtt.connected()) {
    if (mqtt.connect(clientId.c_str(), MQTT_USER, MQTT_PASS)) {
      mqtt.publish("site1/esp32/status", "online", true);  // Retained-Zustand erneut veröffentlichen
      mqtt.subscribe("site1/esp32/cmd");
    } else {
      delay(5000);
    }
  }
}

void setup() {
  // ... zuerst WLAN verbinden ...
  net.setCACert(ROOT_CA);
  mqtt.setServer(MQTT_HOST, MQTT_PORT);
  mqtt.setBufferSize(1024);
  connectMqtt();
}

void loop() {
  if (!mqtt.connected()) connectMqtt();
  mqtt.loop();
}

Wenn Ihre HiveMQ-Firmware setInsecure() verwendet hat, nutzen Sie die Gelegenheit, Zertifikate ab jetzt richtig zu prüfen. Mehr dazu unter ESP32 MQTT über SSL. Denken Sie daran, dass der ESP32 bei manchen TLS-Stacks die korrekte Uhrzeit braucht; synchronisieren Sie per NTP, bevor Sie sich verbinden.

Python mit paho-mqtt 2.x

Vorher:

client.username_pw_set("hivemq-user", "hivemq-pass")
client.connect("abc123.s1.eu.hivemq.cloud", 8883)

Nachher:

# pip install "paho-mqtt>=2.0"
import os, ssl
import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, reason_code, properties):
    print("Verbunden:", reason_code)
    client.subscribe("site1/#", qos=1)

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
                     client_id=os.environ["MQTT_CLIENT_ID"] + "_ingest",
                     protocol=mqtt.MQTTv5)
client.username_pw_set(os.environ["MQTT_USERNAME"], os.environ["MQTT_PASSWORD"])
client.tls_set(cert_reqs=ssl.CERT_REQUIRED)   # der System-CA-Store vertraut Let's Encrypt
client.on_connect = on_connect
client.on_message = lambda c, u, m: print(m.topic, m.payload.decode())
client.connect("broker.connectmq.com", 8883)
client.loop_forever()

Das Abonnieren in on_connect ist wichtig: So werden Abonnements nach jedem Reconnect wiederhergestellt, und der Client hängt nie von Session-Zustand ab, den ein Broker speichert. Siehe paho-mqtt mit Python und paho-mqtt Reconnect.

Node.js mit MQTT.js

// npm install mqtt
const mqtt = require("mqtt");

const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
  // vorher: mqtts://abc123.s1.eu.hivemq.cloud:8883
  username: process.env.MQTT_USERNAME,
  password: process.env.MQTT_PASSWORD,
  clientId: `${process.env.MQTT_CLIENT_ID}_api`,
  protocolVersion: 5,
  reconnectPeriod: 2000,
});

client.on("connect", () => client.subscribe("site1/+/telemetry", { qos: 1 }));
client.on("message", (topic, payload) => console.log(topic, payload.toString()));
client.on("error", (err) => console.error("MQTT-Fehler:", err.message));

Für ein Browser-Dashboard verwenden Sie wss://broker.connectmq.com:8084/mqtt mit denselben Optionen. Siehe MQTT.js mit Node.js und MQTT über WebSocket.

Node-RED

In Node-RED teilen sich alle MQTT-Nodes einen Broker-Konfigurationsknoten, sodass eine Migration meist aus einer einzigen Änderung besteht. Das gilt auch für Edge-Gateways in der Fertigung, die mit Node-RED SPS-Daten in einen Unified Namespace (UNS) nach ISA-95 veröffentlichen:

1. Öffnen Sie einen beliebigen mqtt in- oder mqtt out-Node und klicken Sie auf den Stift neben dem Server.
2. Reiter Connection: Setzen Sie Server auf broker.connectmq.com, Port auf 8883, aktivieren Sie Use TLS und wählen Sie eine TLS-Konfiguration, die das Serverzertifikat prüft. Setzen Sie Protocol auf MQTT V5, wenn Sie MQTT-5-Funktionen nutzen.
3. Client ID: Tragen Sie Ihre ausgegebene Client-ID mit Suffix ein, zum Beispiel YOUR_CLIENT_ID_nodered.
4. Reiter Security: Tragen Sie den neuen Benutzernamen und das neue Passwort ein.
5. Deployen Sie und prüfen Sie, ob die Nodes connected anzeigen.

Wenn der Node dauerhaft „connecting" anzeigt, siehe Node-RED MQTT verbindet nicht und Node-RED MQTT mit TLS.

mosquitto-Kommandozeilen-Clients

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID_cli \
  -t 'site1/#' -v

Unter Windows oder macOS verwenden Sie statt --capath die Option --cafile mit einem PEM-Bundle, das ISRG Root X1 enthält.

Fehlersuche bei gescheiterten Verbindungen

Den nächsten Wechsel einfacher machen

Da Sie ohnehin jeden Client anfassen, verlagern Sie Hostname, Port, Zugangsdaten und Client-ID in eine Konfiguration, die sich aus der Ferne aktualisieren lässt: eine Konfigurationsdatei, Umgebungsvariablen, einen Provisionierungsdienst oder eine OTA-Einstellungs-Payload. Dann ist das Rotieren von Zugangsdaten oder ein künftiger Broker-Wechsel ein Konfigurations-Push und kein Firmware-Projekt.

Sie können jedes dieser Beispiele sofort gegen einen kostenlosen Broker unter app.connectmq.com testen.

Häufig gestellte Fragen

Muss ich meine Topics ändern, wenn ich HiveMQ Cloud verlasse?

Nein. Topics, Payloads und QoS-Stufen bleiben gleich. Nur die Verbindungseinstellungen ändern sich.

Warum verlangt ConnectMQ eine bestimmte Client-ID?

Die Bindung der Client-IDs an Zugangsdaten verhindert, dass ein anderer Mandant oder geleakte Zugangsdaten sich als Ihre Geräte ausgeben. Sie können trotzdem viele Clients mit einem Satz Zugangsdaten betreiben, indem Sie ein eindeutiges Suffix anhängen.

Ist Port 8883 bei beiden Brokern gleich?

Ja, MQTT über TLS nutzt bei beiden 8883. Der Port für Secure WebSocket unterscheidet sich: ConnectMQ verwendet 8084 mit dem Pfad /mqtt.

Kann ich setInsecure auf dem ESP32 weiter verwenden?

Die Verbindung kommt zustande, aber die Serverprüfung wird übersprungen, und Ihre Geräte sind Identitätsdiebstahl ausgesetzt. Verwenden Sie stattdessen das Zertifikat ISRG Root X1.