Test MQTT without Hardware: Mosquitto Clients and MQTT Explorer
Before debugging firmware, prove that the broker can accept a publication and route it to a subscriber. This test needs no ESP32, ESP8266 or sensor. It isolates broker, network, topic and authentication problems from board wiring and code.
You will open one subscriber and one publisher using Mosquitto command-line clients, then inspect messages with a graphical MQTT client such as MQTT Explorer. Use your own broker and a harmless test topic. Public test brokers are shared infrastructure: never send credentials, private sensor readings or device commands to them.
1. Install command-line clients
If Mosquitto runs on Raspberry Pi OS, install the broker and client tools if needed:
sudo apt update sudo apt install -y mosquitto mosquitto-clients
If the broker is already installed, you may only need the client package. On other systems, install the official Mosquitto client tools appropriate to your OS or use a graphical MQTT client.
2. Open a subscriber and publisher
In terminal A, start a subscriber on a test topic:
mosquitto_sub -h 127.0.0.1 -t 'solderhub/test' -v
In terminal B, publish a message:
mosquitto_pub -h 127.0.0.1 -t 'solderhub/test' -m 'hello from SolderHub'
The subscriber should display the topic and message. Try a string, a number-like payload and simple JSON. MQTT payloads are bytes; applications decide how to interpret them.
3. Understand localhost versus a remote broker
The host 127.0.0.1 means the computer where the command is running. It works when the broker is listening locally. If Mosquitto is on a Raspberry Pi and the client runs on a Windows PC, use the Pi's LAN address or hostname instead.
Mosquitto 2.0 and later use a local-only default when no listener is configured. A local test can therefore pass while a remote connection fails by design. Configure an explicit listener and suitable authentication before allowing other devices onto the broker; do not switch anonymous access on as a shortcut. See Install Mosquitto on Raspberry Pi 5.
4. Test topic matching and payloads
Use a simple topic hierarchy such as solderhub/lab/temperature, solderhub/lab/humidity and solderhub/lab/device01/status. Subscribe to the exact topic first, then try a wildcard filter such as solderhub/lab/+ to match one more level. Topic names are case-sensitive, and wildcards belong in subscription filters, not published topic names.
A successful broker delivery does not prove that a JSON payload is valid; downstream clients still need to parse it.
5. Test authentication and permissions
If the broker requires a username and password, use the options supported by your client version. Use a test account with minimum topic permissions. Avoid placing production passwords on command lines in shared terminals or recording them in screenshots; command-line arguments and shell history can expose secrets.
If the subscriber connects but a publication is rejected, inspect broker logs and topic ACLs. Authentication says who a client is; authorization determines which topics it can read or write. Use TLS or a suitable secure network when credentials cross an untrusted path.
6. Inspect messages with MQTT Explorer
MQTT Explorer provides a graphical way to connect to a broker and inspect topic trees, incoming messages and payloads. Configure host, port, authentication and TLS to match the broker. Subscribe to a test topic and publish a harmless test message from the GUI.
The tool helps find spelling/case errors and observe whether retained values are delivered to new subscribers. Be mindful that retaining a test message changes broker state for later clients; clear it when no longer needed and understand how your broker/client clears retained content for a topic.
Troubleshooting
Connection refused: check whether the broker service is active, the target host is correct, a listener exists and firewalls permit access.
Local publish works but remote does not: verify the listener is not loopback-only, then check routing and firewall settings.
Subscriber sees nothing: confirm topic spelling, subscription filter, broker identity and that the publisher sent after the subscriber connected.
Authentication fails: confirm credentials, broker logs and ACLs; do not enable anonymous public access just to make a test pass.
Node-RED or ESP32 still fails: once the CLI test works, compare application host, port, TLS/auth settings and topic against the successful configuration.