{"id":2453,"date":"2016-12-01T15:27:53","date_gmt":"2016-12-01T23:27:53","guid":{"rendered":"http:\/\/visualgdb.com\/w\/?p=2453"},"modified":"2017-05-26T10:30:15","modified_gmt":"2017-05-26T17:30:15","slug":"using-mqtt-to-remotely-control-an-esp8266-board","status":"publish","type":"post","link":"https:\/\/visualgdb.com\/tutorials\/esp8266\/mqtt\/","title":{"rendered":"Using MQTT to remotely control an ESP8266 board"},"content":{"rendered":"

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.<\/p>\n

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.<\/p>\n

MQTT communication involves a central MQTT broker (e.g. Mosquitto <\/a>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<\/strong> 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<\/strong> topic to control the LED:\"scheme\"<\/a>The 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<\/strong> 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<\/strong> topic, the MQTT broker will route the messages automatically.<\/p>\n

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

    \n
  1. Start Visual Studio and open the VisualGDB Embedded Project Wizard:\"01-prjname\"<\/a><\/li>\n
  2. Select “Create a new project -> MSBuild”:\"02-msb\"<\/a><\/li>\n
  3. Select the ESP8266 toolchain and proceed with the regular ESP8266 device:\"03-device\"<\/a><\/li>\n
  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\"<\/a><\/li>\n
  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\"<\/a><\/li>\n
  6. Once the JTAG connection is tested, press “Finish” to generate the project: \"06-test\"<\/a><\/li>\n
  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<\/a>:\"07-mqttlib\"<\/a><\/li>\n
  8. Replace the contents of your main source file with the following:\n
    extern \"C\"\r\n{\r\n\u00a0\u00a0 \u00a0#include \"ets_sys.h\"\r\n\u00a0\u00a0 \u00a0#include \"osapi.h\"\r\n\u00a0\u00a0 \u00a0#include \"mqtt.h\"\r\n\u00a0\u00a0 \u00a0#include \"wifi.h\"\r\n\u00a0\u00a0 \u00a0#include \"debug.h\"\r\n\u00a0\u00a0 \u00a0#include \"gpio.h\"\r\n\u00a0\u00a0 \u00a0#include \"user_interface.h\"\r\n\u00a0\u00a0 \u00a0#include \"mem.h\"\r\n\u00a0\u00a0 \u00a0#include \"espmissingincludes.h\"\r\n\u00a0\u00a0 \u00a0#include \"gpio.h\"\r\n}\r\n\r\nstatic MQTT_Client s_MQTTClient;\r\n\r\nstatic os_timer_t s_Timer;\r\n\r\nextern \"C\" void ICACHE_FLASH_ATTR user_init(void)\r\n{\r\n\u00a0\u00a0 \u00a0#error TODO: enter Raspberry Pi address below\r\n\u00a0\u00a0\u00a0 MQTT_InitConnection(&s_MQTTClient, (uint8_t*)\"<YOUR RASPBERRY PI IP ADDRESS>\", 1883, 0);\r\n\u00a0\u00a0\u00a0 if (!MQTT_InitClient(&s_MQTTClient, (uint8_t*)\"client\", 0, 0, 100, 0))\r\n\u00a0\u00a0\u00a0 {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 os_printf(\"Failed to initialize properly. Check MQTT version.\\r\\n\");\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 return;\r\n\u00a0\u00a0\u00a0 }\r\n\u00a0\u00a0 \u00a0\r\n\u00a0\u00a0\u00a0 MQTT_InitLWT(&s_MQTTClient, (uint8_t*)\"\/lwt\", (uint8_t*)\"offline\", 0, 0);\r\n\u00a0\u00a0\u00a0 MQTT_OnConnected(&s_MQTTClient, mqttConnectedCb);\r\n\u00a0\u00a0\u00a0 MQTT_OnDisconnected(&s_MQTTClient, mqttDisconnectedCb);\r\n\u00a0\u00a0\u00a0 MQTT_OnPublished(&s_MQTTClient, mqttPublishedCb);\r\n\u00a0\u00a0\u00a0 MQTT_OnData(&s_MQTTClient, mqttDataCb);\r\n\r\n\u00a0\u00a0 \u00a0#error TODO: enter WiFi network settings below\r\n\u00a0\u00a0\u00a0 WIFI_Connect((uint8_t*)\"<YOUR WIFI NETWORK NAME>\", (uint8_t*)\"<YOUR WIFI NETWORK PASSWORD>\", wifiConnectCb);\r\n\u00a0\u00a0\u00a0 os_timer_setfn(&s_Timer, TimerFunction, NULL);\r\n\u00a0\u00a0\u00a0 os_timer_arm(&s_Timer, 100 , 1);\r\n}<\/pre>\n
    Do not forget to substitute the IP address of your Raspberry Pi and your Wi-Fi network settings to the lines marked with #error.<\/li>\n
  9. Add a function that will start the MQTT connection once the Wi-Fi connection is established:\n
    static void wifiConnectCb(uint8_t status)\r\n{\r\n\u00a0\u00a0\u00a0 if (status == STATION_GOT_IP) {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 MQTT_Connect(&s_MQTTClient);\r\n\u00a0\u00a0\u00a0 }\r\n\u00a0\u00a0\u00a0 else {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 MQTT_Disconnect(&s_MQTTClient);\r\n\u00a0\u00a0\u00a0 }\r\n}<\/pre>\n<\/li>\n
  10. Add mqttConnectedCb()<\/strong> function that will subscribe to the “led” topic and a two other callbacks for other MQTT events:\n
    static void mqttConnectedCb(uint32_t *args)\r\n{\r\n\u00a0\u00a0\u00a0 MQTT_Client* client = (MQTT_Client*)args;\r\n\u00a0\u00a0\u00a0 os_printf(\"MQTT: Connected\\r\\n\");\r\n\u00a0\u00a0\u00a0 MQTT_Subscribe(client, \"led\", 0);\r\n}\r\n\r\nstatic void ICACHE_FLASH_ATTR mqttDisconnectedCb(uint32_t *args)\r\n{\r\n\u00a0\u00a0\u00a0 MQTT_Client* client = (MQTT_Client*)args;\r\n\u00a0\u00a0\u00a0 os_printf(\"MQTT: Disconnected\\r\\n\");\r\n}\r\n\r\nstatic void ICACHE_FLASH_ATTR mqttPublishedCb(uint32_t *args)\r\n{\r\n\u00a0\u00a0\u00a0 MQTT_Client* client = (MQTT_Client*)args;\r\n\u00a0\u00a0\u00a0 os_printf(\"MQTT: Published\\r\\n\");\r\n}<\/pre>\n<\/li>\n
  11. Now add a function that will turn the LED on and off when someone posts to the “led” topic:\n
    static void mqttDataCb(uint32_t *args, const char* topic, uint32_t topic_len, const char *data, uint32_t data_len)\r\n{\r\n\u00a0\u00a0\u00a0 static bool initialized;\r\n\u00a0\u00a0 \u00a0\r\n\u00a0\u00a0\u00a0 if (!initialized)\r\n\u00a0\u00a0\u00a0 {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 initialized = true;\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 gpio_init();\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 PIN_FUNC_SELECT(PERIPHS_IO_MUX_U0TXD_U, FUNC_GPIO1);\r\n\u00a0\u00a0\u00a0 }\r\n\u00a0\u00a0 \u00a0\r\n\u00a0\u00a0\u00a0 if (topic_len == 3 && !memcmp(topic, \"led\", topic_len))\r\n\u00a0\u00a0\u00a0 {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 if (data_len >= 1 && data[0])\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 gpio_output_set(0, BIT1, BIT1, 0);\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 else\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 gpio_output_set(BIT1, 0, BIT1, 0);\r\n\u00a0\u00a0\u00a0 }\r\n}<\/pre>\n<\/li>\n
  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:\n
    void TimerFunction(void *arg)\r\n{\r\n\u00a0\u00a0\u00a0 unsigned gpioState = gpio_input_get();\r\n\u00a0\u00a0\u00a0 MQTT_Publish(&s_MQTTClient, \"inputs\", (char *)&gpioState, 4, 2, 0);\r\n}<\/pre>\n<\/li>\n
  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\"<\/a><\/li>\n
  14. Add the macro so that it calls os_printf(). Now you will get the “region iram1_0_seg overflowed” message:\"09-overflow\"<\/a><\/li>\n
  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\"<\/a><\/li>\n
  16. Now the build should succeed:\"11-build\"<\/a><\/li>\n
  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\"<\/a><\/li>\n
  18. Press F5 to start debugging. VisualGDB will automatically program the SPI FLASH and start debugging:\"12-start\"<\/a><\/li>\n
  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:\n
    rf cal sector: 120\r\nrf[112] : 03\r\nrf[113] : 00\r\nrf[114] : 01\r\n\r\nSDK ver: 2.0.0(656edbf) compiled @ Jul 19 2016 17:58:40\r\nphy ver: 1055, pp ver: 10.2\r\n\r\nWIFI_INIT\r\nmode : sta(18:fe:34:a2:06:eb)\r\nadd if0\r\nf r0, STATION_IDLE\r\nSTATION_IDLE\r\nSTATION_IDLE\r\nscandone\r\nstate: 0 -> 2 (b0)\r\nSTATION_IDLE\r\nstate: 2 -> 3 (0)\r\nstate: 3 -> 5 (10)\r\nadd 0\r\naid 4\r\ncnt \r\n\r\nconnected with <SSID>, channel 2\r\ndhcp client start...\r\nSTATION_IDLE\r\nSTATION_IDLE\r\nSTATION_IDLE\r\nSTATION_IDLE\r\nSTATION_IDLE\r\nSTATION_IDLE\r\nSTATION_IDLE\r\nip:192.168.0.223,mask:255.255.255.0,gw:192.168.0.1\r\nMQTT: Connected\r\nMQTT: Published\r\nMQTT: Published<\/pre>\n<\/li>\n
  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\"<\/a><\/li>\n
  21. Open View->Other Windows->Package Manager and type the following command there:\n
    Install-Package M2Mqtt<\/pre>\n
    This will automatically download the C# MQTT client package and reference it from your application:\"14-nuget\"<\/a><\/li>\n
  22. Place a checkbox and a panel on your form. You can change the Appearance<\/strong> parameter of the checkbox to make it look like a button:\"15-controls\"<\/a><\/li>\n
  23. Replace contents of Form1.cs with the following code:\n
    using System;\r\nusing System.Collections.Generic;\r\nusing System.ComponentModel;\r\nusing System.Data;\r\nusing System.Drawing;\r\nusing System.Linq;\r\nusing System.Text;\r\nusing System.Threading;\r\nusing System.Threading.Tasks;\r\nusing System.Windows.Forms;\r\nusing uPLibrary.Networking.M2Mqtt;\r\nusing uPLibrary.Networking.M2Mqtt.Messages;\r\n\r\nnamespace MQTTClient\r\n{\r\n\u00a0\u00a0\u00a0 public partial class Form1 : Form\r\n\u00a0\u00a0\u00a0 {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 private MqttClient _Client;\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 public Form1()\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 InitializeComponent();\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 _Client = new MqttClient(\"raspberrypi\");\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 _Client.Connect(\"C#Client\");\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 _Client.Subscribe(new[] { \"inputs\" }, new byte[] { MqttMsgBase.QOS_LEVEL_EXACTLY_ONCE });\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 _Client.MqttMsgPublishReceived += _Client_MqttMsgPublishReceived;\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 private void _Client_MqttMsgPublishReceived(object sender, MqttMsgPublishEventArgs e)\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 BeginInvoke(new Action(() =>\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 uint inputs = BitConverter.ToUInt32(e.Message, 0);\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 if ((inputs & 1) == 0)\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 panel1.BackColor = Color.Green;\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 else\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 panel1.BackColor = Color.Transparent;\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }));\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 private void checkBox1_CheckedChanged(object sender, EventArgs e)\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 _Client.Publish(\"led\", new [] { checkBox1.Checked ? (byte)1 : (byte)0 });\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }\r\n\u00a0\u00a0\u00a0 }\r\n}<\/pre>\n
    Do not forget to assign checkBox1_CheckedChanged()<\/strong> as a CheckedChanged handler for the checkbox so that the client can actually publish the messages to led<\/strong> when you click it.<\/li>\n
  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\"<\/a><\/li>\n
  25. You can see what is going on by placing a breakpoint inside the _Client_MqttMsgPublishReceived() method. The inputs<\/strong> variable will hold the GPIO inputs sampled by the ESP8266 board and reported via the inputs<\/strong> channel:\"17-inputs\"<\/a><\/li>\n
  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()<\/strong> function to see how the message gets delivered:\"18-led\"<\/a>Warning: the LED and the UART TX signal share the same pin. Turning the LED on or off will disrupt the debug output via UART.<\/li>\n<\/ol>\n
    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<\/a> that supports FreeRTOS, but does not yet have an ESP8266-specific port.<\/p>\n","protected":false},"excerpt":{"rendered":"
    This tutorial shows how to use the MQTT protocol to remotely control the LED on the ESP8266 board and to<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[142],"tags":[100,56,139],"_links":{"self":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/2453"}],"collection":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/comments?post=2453"}],"version-history":[{"count":1,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/2453\/revisions"}],"predecessor-version":[{"id":2475,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/2453\/revisions\/2475"}],"wp:attachment":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/media?parent=2453"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/categories?post=2453"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/tags?post=2453"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}