Reconfigurar Clientes MQTT Depois do HiveMQ: Exemplos para ESP32, Python, Node.js e Node-RED

Tirar um cliente do HiveMQ Cloud Serverless muda quatro coisas: o hostname, as credenciais, o client ID e, às vezes, as configurações de confiança do TLS. Seus topics, payloads e a lógica da aplicação continuam os mesmos. Este artigo mostra exatamente o que alterar nos clientes mais comuns, com exemplos de antes e depois usando um broker privado da ConnectMQ como destino.

O processo completo está no guia de migração do HiveMQ Serverless.

O que muda e o que continua igual

Atenção à porta do WebSocket seguro: dashboards no navegador costumam ter a 8884 fixa no código, enquanto a ConnectMQ usa a 8084. Confira no console do HiveMQ os valores exatos que o seu cluster usava.

ESP32 com Arduino e PubSubClient

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

Depois (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), cole o PEM de 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 emitido + sufixo único
  while (!mqtt.connected()) {
    if (mqtt.connect(clientId.c_str(), MQTT_USER, MQTT_PASS)) {
      mqtt.publish("site1/esp32/status", "online", true);  // republica o estado retido
      mqtt.subscribe("site1/esp32/cmd");
    } else {
      delay(5000);
    }
  }
}

void setup() {
  // ... conecte o Wi-Fi primeiro ...
  net.setCACert(ROOT_CA);
  mqtt.setServer(MQTT_HOST, MQTT_PORT);
  mqtt.setBufferSize(1024);
  connectMqtt();
}

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

Se o seu firmware para o HiveMQ usava setInsecure(), aproveite a oportunidade para verificar os certificados corretamente. Mais detalhes em ESP32 MQTT com SSL. Lembre-se de que o ESP32 precisa da hora correta para algumas pilhas TLS; sincronize o NTP antes de conectar.

Python com paho-mqtt 2.x

Antes:

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

Depois:

# 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)   # o repositório de CAs do sistema confia no 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()

Assinar dentro do on_connect é importante: isso restaura as assinaturas a cada reconexão, então o cliente nunca depende de estado de sessão armazenado por um broker. Veja paho-mqtt em Python e reconexão no paho-mqtt.

Node.js com MQTT.js

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

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

Para um dashboard no navegador, use wss://broker.connectmq.com:8084/mqtt com as mesmas opções. Veja MQTT.js com Node.js e MQTT sobre WebSocket.

Node-RED

No Node-RED, todos os nós MQTT compartilham um único nó de configuração do broker, então a migração costuma ser uma única edição:

1. Abra qualquer nó mqtt in ou mqtt out e clique no lápis ao lado do servidor.
2. Aba Connection: defina Server como broker.connectmq.com, Port como 8883, marque Use TLS e selecione uma configuração TLS que verifique o certificado do servidor. Defina Protocol como MQTT V5 se você usa recursos do MQTT 5.
3. Client ID: informe o seu client ID emitido com um sufixo, por exemplo YOUR_CLIENT_ID_nodered.
4. Aba Security: informe o novo usuário e a nova senha.
5. Faça o deploy e confira se os nós mostram connected.

Se o nó continuar mostrando "connecting", veja Node-RED MQTT não conecta e Node-RED MQTT com TLS.

Clientes de linha de comando do mosquitto

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

No Windows ou no macOS, use --cafile com um bundle PEM que contenha a ISRG Root X1 em vez de --capath.

Solução de problemas de conexão

Facilite a próxima mudança

Já que você vai editar todos os clientes de qualquer forma, mova hostname, porta, credenciais e client ID para uma configuração que possa ser atualizada remotamente: um arquivo de configuração, variáveis de ambiente, um serviço de provisionamento ou um payload de configurações via OTA. Assim, rotacionar credenciais ou trocar de broker no futuro vira um envio de configuração, e não um projeto de firmware.

Você pode testar qualquer um destes exemplos agora mesmo com um broker gratuito em app.connectmq.com.

Perguntas frequentes

Preciso mudar os meus topics ao sair do HiveMQ Cloud?

Não. Topics, payloads e níveis de QoS continuam os mesmos. Só mudam as configurações de conexão.

Por que a ConnectMQ exige um client ID específico?

Vincular os client IDs às credenciais impede que outro tenant ou uma credencial vazada se passe pelos seus dispositivos. Mesmo assim, você pode rodar muitos clientes com um único conjunto de credenciais acrescentando um sufixo único.

A porta 8883 é a mesma nos dois brokers?

Sim, o MQTT sobre TLS usa a 8883 nos dois. A porta do WebSocket seguro é diferente: a ConnectMQ usa a 8084 com o caminho /mqtt.

Posso continuar usando setInsecure no ESP32?

Vai conectar, mas isso pula a verificação do servidor e expõe os dispositivos a falsificação de identidade. Use o certificado ISRG Root X1.