Updated Oct 20, 2026

HiveMQ migration for ESP32 and Node-RED

Replace HiveMQ connection settings with verified TLS, scoped RunMQTT credentials, and a real MQTT message round trip.

Start with the migration guide. These instructions describe configuration and acceptance checks, not a claim that every firmware or Node-RED version has been certified. Use a private test Broker and synthetic data.

ESP32 configuration

Keep the MQTT library already used by your firmware if it supports your required protocol and verified TLS. Replace the HiveMQ host with the secure RunMQTT hostname, use port 8883, and copy the full generated RunMQTT username and device password. Keep topic names and payload formats unchanged for the first test. Record the MQTT library, ESP32 framework and firmware versions used.

For ESP-IDF with ESP-MQTT, configure the target URI and generated credentials using your version's esp_mqtt_client_config_t. Configure server verification using the ESP certificate bundle or the correct trusted root CA. The maintained ESP-MQTT TLS example is the source for the exact API of your installed release.

For Arduino clients, use WiFiClientSecure, load the appropriate CA trust using the API supported by your ESP32 core, and initialize your existing MQTT client with that secure transport. Do not copy an old HiveMQ certificate pin and do not use setInsecure() as a migration fix. Synchronize the device clock before certificate validation. Leave passwords out of serial logs, screenshots and committed sketches.

Many Arduino MQTT libraries have different packet buffers, supported QoS levels, and MQTT versions. For example, do not assume a library that publishes only QoS 0 can run a QoS 2 acceptance test. Confirm client-specific limits separately from the Broker's features.

Node-RED configuration

The Node-RED MQTT cookbook explains the shared MQTT broker configuration used by MQTT input and output nodes.

  1. Back up the current flow and record the old broker configuration privately. Disable command publishers while preparing the replacement to avoid duplicate actions.
  2. Create a new MQTT broker configuration for the test. Set the server to the RunMQTT secure hostname and port 8883; enable TLS with server-certificate verification. Keep the hostname, not an IP address, so hostname validation works.
  3. Enter the generated device username and password in the broker configuration's Security fields. Use a distinct RunMQTT device identity for each role that needs different permissions. Use unique client IDs for simultaneous connections.
  4. Select the protocol version supported by the deployed Node-RED nodes. Leave existing production nodes on the old configuration while testing the new configuration with isolated test nodes.
  5. Create an MQTT input node for migration-check/nodered/state at QoS 1, connect it to a Debug node, and deploy it. Wait for the MQTT node to report connected.
  6. Connect an Inject node to an MQTT output node using the same new broker configuration. Set the topic to migration-check/nodered/state, QoS 1, retain false, and inject a unique synthetic string. Confirm that exact value appears in Debug. An output node reporting connected is not proof of delivery.
  7. Disconnect, redeploy, and repeat. Test a denied topic using an appropriately restricted test identity. Use the local verifier for an independent check of the same endpoint.

Use a policy granting publish and subscribe on migration-check/# for this test only. MQTT input/output nodes can share one broker configuration; its connection also counts toward the plan. Create separate production configurations and credentials where access roles differ.

Browser clients and WSS

Use wss://<broker>.tls-broker.runmqtt.com/mqtt as the full URL. Native TLS port 8883 is not the WSS URL. Check the path, credentials, origin/network access and proxy support instead of disabling TLS checks. See the verified MQTT.js examples.

Acceptance before fleet rollout

Test a real publish/subscription round trip, topic denials, restart and network loss, TLS trust after reboot, and burst traffic. Check packet size and subscriptions per client with your actual application. Verify current states and command routing after reconnecting. Keep the old configuration until the new workload passes the acceptance checklist, then update devices and backends in coordinated batches before the HiveMQ retirement date.

Retained messages and QoS 2 require Growth or Scale. Retained packet flags have a known compatibility limitation; read sessions and delivery and test before depending on retained behavior. Do not infer compatibility from an unchanged payload format or a single successful connection.