ESP32 MQTT debugging: see exactly what your device publishes

Why use a desktop MQTT client to debug an ESP32?

Most ESP32 and ESP8266 MQTT bugs come down to a small set of questions: is the device actually connecting to the broker, is it publishing to the topic you think it is, and is the payload in the shape your backend expects? Serial logs only show you the device's side of the story. An MQTT client connected to the same broker shows you the broker's view — the ground truth of what was actually delivered.

MQTT Viewer is a native desktop app for macOS, Windows, and Linux. It keeps a live topic tree of everything on the broker, an interactive message timeline you can scrub through, and decoders for common payload formats. That makes it a practical way to verify a firmware change without reflashing or adding more print statements.

How to debug ESP32 MQTT messages with MQTT Viewer

Follow these steps to confirm your device's publish and subscribe paths end to end.

1. Download and install MQTT Viewer. Grab the build for your OS from the download page and install it. It's free, open-source under GPL-3.0, and needs no account or sign-up.
2. Connect to the same broker your ESP32 uses. Create a connection with the exact broker host or IP your firmware points at, the matching port (1883 for plain TCP, 8883 for TLS/SSL), and the same username and password if your broker requires auth. If your device uses WiFiClientSecure over 8883, connect MQTT Viewer over TLS too so the handshake matches.
3. Subscribe to the wildcard topic #. This shows every topic on the broker, so you can confirm the device is connected and publishing at all. Once you see traffic, narrow to a device prefix like devices/esp32-1/# to cut out the noise.
4. Watch the device publish. Trigger your firmware — power-cycle the board, press a button, or wait for its publish interval — and watch new topics appear in the live topic tree and the message timeline in real time. The timeline lets you scrub back through earlier messages to see what changed and when.
5. Decode payloads and filter. If your device sends JSON, read it directly; if it sends raw bytes, switch the decoder to Hex or Base64 to inspect the actual bytes on the wire. Use free-text or pattern-based filtering to isolate a specific device, message type, or value while the firehose keeps flowing.
6. Publish a test message back to the device. To verify the downlink, publish to the topic your ESP32 subscribes to (for example a command or config topic) with the payload your firmware expects, and confirm the device reacts. MQTT Viewer keeps a searchable publish history, so you can re-send the same command without retyping it.

Reading binary and structured payloads

Embedded firmware rarely sends tidy text. A sensor node might pack a reading into a couple of bytes, or your backend might expect a specific JSON shape that a typo in the sketch quietly broke. MQTT Viewer decodes Base64 and Hex so you can see the exact bytes your PubSubClient.publish() call put on the wire, and it decodes Sparkplug B (protobuf) if your industrial gateway speaks it. Seeing the decoded bytes side by side with what you intended to send usually pinpoints an encoding or endianness bug in seconds.

Because MQTT Viewer supports up to 10 simultaneous broker connections, you can also watch a development broker and a production broker at the same time — handy when a fleet of ESP32s behaves on the bench but not in the field. New to the terminology? The MQTT glossary explains retained messages, QoS, wildcards, and the other concepts that trip up first-time device debugging.

Common ESP32 and ESP8266 MQTT problems

• Nothing appears under #. The device isn't reaching the broker. Check the host/IP, port, and credentials in your sketch against the connection in MQTT Viewer, and confirm the board has WiFi.
• Messages appear, but on the wrong topic. A typo or a mismatched topic prefix between firmware and backend. The topic tree makes the actual published topic obvious at a glance.
• Payload looks like garbage. You're sending binary where the consumer expects text, or vice versa. Switch the MQTT Viewer decoder to Hex to see the real bytes.
• The device never receives commands. Its subscription topic doesn't match what's being published, or QoS expectations differ. Publish a test message from MQTT Viewer to confirm the exact topic the device listens on.

Frequently asked questions

Ready to see your device's traffic? Download MQTT Viewer for macOS, Windows, or Linux — it's free and installs in seconds.