Using MQTT to remotely control an ESP8266 board

This tutorial shows how to use the MQTT protocol to remotely control the LED on the ESP8266 board and to monitor the state of the on-board button.

MQTT is a protocol that allows exchanging short messages between different small devices. It is optimized to use as little traffic as possible and to run on small devices like ESP8266.

MQTT communication involves a central MQTT broker (e.g. Mosquitto running on Raspberry Pi) and one or more MQTT clients. A client can subscribe to one or more topics and then once any other client posts a message to that topic, the subscribed clients will receive the message. The routing of messages is done by the MQTT broker, so the clients don’t need to handle that. In our example the ESP8266 board will subscribe to a topic called led and will turn the on-board LED on when someone sends ‘1’ to that topic and off when ‘0’ is sent instead. On the PC side we will run a basic program that will send ones and zeroes to the led topic to control the LED:schemeThe advantage of the MQTT protocol over just sending ones and zeroes via TCP or UDP is automatic configuration. The PC does not need to know how many ESP8266 boards are listening to the led topic. All it needs to do is send a message to the MQTT broker and every node that subscribed for this topic will receive. Likewise, the ESP8266 does not need to know which PC is currently controlling the LED. As long as it is subscribed to the led topic, the MQTT broker will route the messages automatically.

Before you begin, install VisualGDB 5.2 or later and update your ESP8266 toolchain to the latest version. Then install the mosquitto broker on your Raspberry Pi (or any other Linux machine) and ensure it is running:mosquittoNow we can begin with the main part of the tutorial.

  2. Select “Create a new project -> MSBuild”:02-msb
  3. Select the ESP8266 toolchain and proceed with the regular ESP8266 device:03-device
  4. The MQTT is currently supported by the IoT SDK (a.k.a. NONOS SDK) only, so select the HTTP Server (IoT SDK) sample:04-httpserver
  5. On the Debug Method page select OpenOCD, connect your JTAG programmer to ESP8266, pick your programming interface and click “Test settings” to automatically check the connection:05-debug
  6. Once the JTAG connection is tested, press “Finish” to generate the project: 06-test
  7. Open VisualGDB Project Properties for the newly generated project and add a reference to the MQTT client. This will automatically add a reference to an open-source esp_mqtt library:07-mqttlib
  8. Replace the contents of your main source file with the following:

    Do not forget to substitute the IP address of your Raspberry Pi and your Wi-Fi network settings to the lines marked with #error.
  9. Add a function that will start the MQTT connection once the Wi-Fi connection is established:
  10. Add mqttConnectedCb() function that will subscribe to the “led” topic and a two other callbacks for other MQTT events:
  11. Now add a function that will turn the LED on and off when someone posts to the “led” topic:
  12. We will also add a small function that will periodically poll the GPIO inputs of the ESP8266 and send them to the “inputs” topic so that the PC can check whether the on-board button is pressed:
  13. Try building the code. You should get an error that the INFO() function is not found. This happens because the ESP8266 MQTT library expects your code to define it as a macro in user_config.h:08-info
  14. Add the macro so that it calls os_printf(). Now you will get the “region iram1_0_seg overflowed” message:09-overflow
  15. This happens because too much code got placed into RAM. Open VisualGDB Project Properties and configure the ICACHE_FLASH_ATTR macro to actually place code into FLASH:10-flash
  16. Now the build should succeed:11-build
  17. If you are using the Custom edition of VisualGDB or higher and your ESP8266 UART port is connected to a COM-to-USB adapter, you can configure the Raw Terminal in VisualGDB Project Properties to connect to it and display the ESP8266 debug output inside Visual Studio:terminal
  18. Press F5 to start debugging. VisualGDB will automatically program the SPI FLASH and start debugging:12-start
  19. Verify that the ESP8266 joins your Wi-Fi network and connects to the MQTT broker. The UART output should contain something similar to this:
  20. Now we will create a very basic Windows MQTT client in C#. Open another instance of Visual Studio and create a Windows Forms application:13-client
  21. Open View->Other Windows->Package Manager and type the following command there:

    This will automatically download the C# MQTT client package and reference it from your application:14-nuget
  22. Place a checkbox and a panel on your form. You can change the Appearance parameter of the checkbox to make it look like a button:15-controls
  23. Replace contents of Form1.cs with the following code:

    Do not forget to assign checkBox1_CheckedChanged() as a CheckedChanged handler for the checkbox so that the client can actually publish the messages to led when you click it.
  24. Start your C# program and try pressing the button on the ESP8266 board. The panel should change its color to green when the button is pressed:16-window
  25. You can see what is going on by placing a breakpoint inside the _Client_MqttMsgPublishReceived() method. The inputs variable will hold the GPIO inputs sampled by the ESP8266 board and reported via the inputs channel:17-inputs
  26. Try clicking at the checkbox and observe the ESP8266 LED. See how it turns on and off. You can set a breakpoint in the mqttDataCb() function to see how the message gets delivered:18-ledWarning: the LED and the UART TX signal share the same pin. Turning the LED on or off will disrupt the debug output via UART.

The esp_mqtt library shown in this tutorial only works with the ESP8266 IoT SDK and is not compatible with the FreeRTOS SDK. If you want to use MQTT in a FreeRTOS-based application, you can try porting the official MQTT client library for embedded devices that supports FreeRTOS, but does not yet have an ESP8266-specific port.