MQTT for ESP32: How Device Messaging Fits Together

Publish and subscribe

MQTT separates publishers and subscribers through a broker. An ESP32 can publish telemetry while dashboards or automations subscribe; commands should use separate topics.

Documentation-based example contract

This reproducible example is based on documentation, not a hardware experiment performed by ITHutir. The example topic and payload are an application contract, not observed production telemetry or an MQTT-standard sensor schema. A second MQTT client can stand in for the ESP32; no sensor or actuator is required.

Use ithutir/example/esp32-node-01/telemetry: ithutir/example isolates the exercise, esp32-node-01 identifies the example node, and telemetry carries readings. Use this exact topic in both clients and Home Assistant. Choose an unused private test namespace; change it consistently if needed.

{
  "temperature_c": 23.5,
  "sampled_at": "2026-10-16T12:00:00Z",
  "quality": "example"
}

Retained state versus a transient sample

A retained publication lets the broker keep the latest message for later subscribers. It is a snapshot, not proof that a device is online or that data is fresh. This exercise uses QoS 0, retain disabled and a clean session on an unused topic.

Keep command topics separate from telemetry. Do not use a retained actuator command as an instruction to energize a load.

• OASIS MQTT 3.1.1: PUBLISH retain semantics, section 3.3.1

Reproduce the exchange with two clients

Prerequisites: a private broker you administer, two authorized MQTT clients with distinct client IDs, and the same broker endpoint and secure connection settings. Use a GUI client or equivalent publish/subscribe tool; configure credentials privately, never in the payload. This is a proposed procedure, not a reported test run.

• 1. Connect client A with a clean session and subscribe to ithutir/example/esp32-node-01/telemetry at QoS 0. Confirm the subscription is accepted before continuing.
• 2. Connect client B and publish the JSON above to the exact same topic at QoS 0 with retain disabled.
• 3. In A, inspect the topic and JSON: expect temperature_c = 23.5, quality = example and the fixed sampled_at timestamp. Publish again with temperature_c = 24.0; expect the next message to contain 24.0.
• 4. Disconnect A and reconnect with a clean session, then subscribe again. On this unused non-retained topic, expect no old sample; publish again from B and expect a new message.
• 5. Success means the observer receives both deliberate values on the correct topic. It verifies broker/client routing only, not ESP32 firmware, sensor accuracy or electrical safety.
• 6. No message: check broker reachability, connection errors, exact topic spelling, subscription acknowledgement and publish/read ACL permissions. Old data on reconnect suggests a retained message, another publisher or a reused session. Malformed JSON is a payload problem even if MQTT delivered its bytes.

• Map this same telemetry contract into Home Assistant sensors

Design topics around meaning

Use a predictable topic hierarchy and document payload fields and units. Stable naming makes later integrations easier to maintain.

Reliability and security still matter

Use broker authentication, per-topic ACLs and TLS certificate validation where supported. Keep credentials out of public files and define fail-safe local behavior when the broker is unavailable, input is stale or the device restarts.

• Eclipse Mosquitto: authentication, topic ACLs and TLS configuration

From messages to physical inputs

Only after the message contract works should a real sensor replace the synthetic publisher. Before wiring that sensor, check the exact board pins, logic voltage and interface requirements. The GPIO planning material covers that separate electrical boundary; messaging success cannot validate wiring.

• Plan the electrical interface with the ESP32 GPIO article
• Record pin and voltage checks in the GPIO wiring checklist