NodeMCU ESP8266 MQTT LED Control with Mosquitto

This project lets a NodeMCU ESP8266 change an external LED when it receives an MQTT command. The board subscribes to a command topic, validates ON or OFF, updates the GPIO and publishes a separate state message. That last step matters: the command expresses what a controller requested, while the state topic reports what the firmware applied.

Use this low-voltage example to test the complete path—broker, Wi-Fi, topic, callback and GPIO—before adding relays or other actuators. This is a plain MQTT demonstration for a trusted lab network; use authentication and an appropriately secured transport for untrusted links.

Hardware and topics

Use a NodeMCU ESP8266, LED, series resistor, breadboard, jumper wires and USB cable. This example uses D5/GPIO14 for the LED; verify the pin mapping on your board. Connect GPIO to the LED through a resistor and connect the LED's cathode to GND.

Use:

• solderhub/lab/nodemcu01/command/led — controller publishes ON or OFF;
• solderhub/lab/nodemcu01/state/led — firmware reports applied state.

Do not retain one-shot command messages. A reconnecting client should not unexpectedly replay an old ON command unless that is explicitly intended.

1. Configure the broker first

Before uploading firmware, confirm Mosquitto is reachable from the NodeMCU's network. A local-only default listener will not accept a remote board via the Pi's LAN address until remote listening is configured. Create an authenticated broker account and give it only the topics needed for this project.

This article's firmware uses username/password authentication. Keep these credentials local; never commit them to a public repository. Start with Install Mosquitto on Raspberry Pi 5 and test the broker with Test MQTT without Hardware.

2. Upload the NodeMCU sketch

Install ESP8266 board support and the PubSubClient library in Arduino IDE. Replace credentials and broker address locally. The code resubscribes after a successful connection, rejects payloads other than ON/OFF, and publishes the GPIO state. It uses a simple retry interval; see the non-blocking reconnect guide for broader Wi-Fi recovery and backoff patterns.

3. Test with command-line clients

Subscribe to the reported state from a machine that can reach the broker:

mosquitto_sub -h BROKER_LAN_IP -t 'solderhub/lab/nodemcu01/state/led' -u TEST_USER -P 'TEST_PASSWORD' -v

Publish a command:

mosquitto_pub -h BROKER_LAN_IP -t 'solderhub/lab/nodemcu01/command/led' -u TEST_USER -P 'TEST_PASSWORD' -m 'ON'

Use your real local host and test credentials; never paste production passwords into screenshots or publish them in shell history. The state subscriber should show ON after a valid command. Then publish OFF and verify both physical LED and reported state.

State, retained messages and safety

The firmware publishes reported state as retained so a new subscriber can learn the latest output state. This is appropriate for current state in this simple example; it is not a full event history. Command messages are not retained. The board's retained report represents firmware-applied GPIO state, not independent proof that an external load physically changed.

Before adapting this to a relay, determine input polarity, driver rating, boot behavior and safe offline state. Do not connect mains loads on a breadboard or use a dashboard/MQTT message as the only safety interlock.

Troubleshooting

No connection: confirm Wi-Fi, broker LAN address, port, credentials and listener configuration.

Command arrives but LED stays off: verify the exact topic, D5/GPIO14 mapping, LED polarity and serial output.

State topic never changes: verify subscription callback and broker ACL for publishing the state topic.

Board disconnects repeatedly: check unique client ID, signal strength and broker logs. For a resilient loop, use Non-Blocking MQTT Auto-Reconnect on ESP32 as a pattern and adapt it to ESP8266 networking APIs.

Next steps

• MQTT Explained: Broker, Topics, QoS, Retained Messages and Last Will
• MQTT Topic Naming Best Practices
• ESP32 and ESP8266 Communicating Through an MQTT Broker

Official references: Mosquitto documentation and the PubSubClient documentation matching the library version installed.