Reconfigurer ses clients MQTT après HiveMQ : exemples ESP32, Python, Node.js et Node-RED

Faire quitter HiveMQ Cloud Serverless à un client modifie quatre choses : le nom d'hôte, les identifiants, le client ID et parfois les paramètres de confiance TLS. Vos topics, vos payloads et la logique de votre application restent identiques. Cet article montre précisément ce qu'il faut modifier pour les clients les plus courants, avec des exemples avant/après qui utilisent un broker privé ConnectMQ comme destination.

Le processus global est décrit dans le guide de migration HiveMQ Serverless.

Ce qui change et ce qui reste

Attention au port du WebSocket sécurisé : les tableaux de bord dans le navigateur codent souvent 8884 en dur, alors que ConnectMQ utilise 8084. Vérifiez dans votre console HiveMQ les valeurs exactes utilisées par votre cluster.

ESP32 avec Arduino et PubSubClient

Avant (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();

Après (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) : collez le PEM depuis letsencrypt.org/certificates
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;   // ID délivré + suffixe unique
  while (!mqtt.connected()) {
    if (mqtt.connect(clientId.c_str(), MQTT_USER, MQTT_PASS)) {
      mqtt.publish("site1/esp32/status", "online", true);  // republier l'état retenu
      mqtt.subscribe("site1/esp32/cmd");
    } else {
      delay(5000);
    }
  }
}

void setup() {
  // ... connecter d'abord le Wi-Fi ...
  net.setCACert(ROOT_CA);
  mqtt.setServer(MQTT_HOST, MQTT_PORT);
  mqtt.setBufferSize(1024);
  connectMqtt();
}

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

Si votre firmware HiveMQ utilisait setInsecure(), profitez-en pour vérifier correctement les certificats. Plus de détails dans ESP32 MQTT sur SSL. N'oubliez pas que certaines piles TLS exigent que l'ESP32 soit à l'heure : synchronisez NTP avant de vous connecter.

Python avec paho-mqtt 2.x

Avant :

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

Après :

# 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("Connected:", 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)   # le magasin de CA système fait confiance à 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()

S'abonner dans on_connect est important : les abonnements sont rétablis après chaque reconnexion, si bien que le client ne dépend jamais d'un état de session stocké par un broker. Voir paho-mqtt en Python et reconnexion paho-mqtt.

Node.js avec MQTT.js

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

const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
  // avant : 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 error:", err.message));

Pour un tableau de bord dans le navigateur, utilisez wss://broker.connectmq.com:8084/mqtt avec les mêmes options. Voir MQTT.js avec Node.js et MQTT sur WebSocket.

Node-RED

Dans Node-RED, tous les nœuds MQTT partagent un même nœud de configuration du broker : une migration se résume donc généralement à une seule modification.

1. Ouvrez n'importe quel nœud mqtt in ou mqtt out et cliquez sur le crayon à côté du serveur.
2. Onglet Connection : réglez Server sur broker.connectmq.com et Port sur 8883, cochez Use TLS et sélectionnez une configuration TLS qui vérifie le certificat du serveur. Réglez Protocol sur MQTT V5 si vous utilisez des fonctionnalités de MQTT 5.
3. Client ID : saisissez votre client ID délivré suivi d'un suffixe, par exemple YOUR_CLIENT_ID_nodered.
4. Onglet Security : saisissez le nouveau nom d'utilisateur et le nouveau mot de passe.
5. Déployez et vérifiez que les nœuds affichent connected.

Si le nœud reste sur « connecting », consultez Node-RED MQTT ne se connecte pas et Node-RED MQTT TLS.

Clients mosquitto en ligne de commande

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

Sous Windows ou macOS, utilisez --cafile avec un bundle PEM contenant ISRG Root X1 à la place de --capath.

Dépanner les connexions qui échouent

Facilitez le prochain changement

Puisque vous modifiez de toute façon chaque client, déplacez le nom d'hôte, le port, les identifiants et le client ID dans une configuration modifiable à distance : un fichier de configuration, des variables d'environnement, un service de provisioning ou un payload de paramètres OTA. Faire tourner les identifiants ou changer de broker à l'avenir deviendra alors un simple déploiement de configuration, et non un projet firmware.

Vous pouvez tester chacun de ces exemples dès maintenant sur un broker gratuit via app.connectmq.com.

Questions fréquentes

Dois-je modifier mes topics en quittant HiveMQ Cloud ?

Non. Les topics, les payloads et les niveaux de QoS restent les mêmes. Seuls les paramètres de connexion changent.

Pourquoi ConnectMQ exige-t-il un client ID spécifique ?

Lier les client IDs aux identifiants empêche un autre tenant ou un identifiant divulgué d'usurper l'identité de vos appareils. Vous pouvez tout de même faire tourner de nombreux clients avec un même jeu d'identifiants en ajoutant un suffixe unique.

Le port 8883 est-il le même sur les deux brokers ?

Oui, MQTT sur TLS utilise le port 8883 sur les deux. Le port du WebSocket sécurisé diffère : ConnectMQ utilise 8084 avec le chemin /mqtt.

Puis-je continuer à utiliser setInsecure sur l'ESP32 ?

La connexion fonctionnera, mais elle saute la vérification du serveur et expose vos appareils à l'usurpation d'identité. Utilisez plutôt le certificat ISRG Root X1.