ESPMetRED an Arduino IDE compatible library to communicate ESP8266 and Node-Red via MQTT

This library can be used to control ESP8266 nodes from Node-Red. Just burn Examples/ESPMetRED/ESPMetRED.ino to your ESP8266 using Arduino IDE and you are ready to go.



  • Arduino IDE compatible
  • Works with all ESP8266 SOICs such as ESP-12E, ESP-12F and boards such as NodeMCU, WeMos D1 Mini etc.
  • Back and forth communication between ESP8266 and Node-Red using MQTT protocol
  • Auto connect to WiFi or MQTT server in case of failure
  • Support Static IP address configurations
  • Deep sleep support (no connection problem on waking up, connects within 2 seconds)
  • Timer for Timely operations, update Sunrise or Sunset data and preserve it in flash memory
  • Save variables in Flash memory
  • Retrieve variables from Flash memory on booting ESP8266
  • Preserve and restore GPIO state i.e. HIGH or LOW
  • Over the Air (OTA) update
  • More are coming soon!!


Client API:

Save a variable to Flash memory:

  • Instance of ESPMetRED Library
  • Save a  variable in Flash memory
  • Where
    • Object: A String type of data
    • Value: Supports “int”, “long” data types
  • Return: true or false

Retrieve a variable value from Flash memory:

  • Instance of ESPMetRED Library
  • Get a variable value out of Flash memory
  • Where
    • Object: A String type of data
  • Return: “int” or “long” type of data

Switch a pin to LOW or HIGH:

  • Instance of ESPMetRED Library
  • Switch a pin to HIGH
  • Where
    • Pin: An “int” data type
    • Value: An “int” data type (0 or 1)
  • Return: true or false
  • New state of a pin will be automatically saved in flash memory
  • To retrieve state of a pin
  • Where
    • 12 is pin number in “String” data type


  • Don’t forget to set the pin as output

Fetch Time, Sunrise and Sunset:

  • Instance of ESPMetRED Library
  • Retrieve system time
  • Save time to Flash memory
  • Where
    • Time: JSON property used for recording time in Flash memory
  • Retrieve sunrise
  • Retrieve sunset

  • Retrieved time is in milliseconds
    • Applicable for “system time”, “sunrise” and “sunset”

Publish data to server:

  • Instance of ESPMetRED Library
  • Send data to MQTT_PUBLISH_TOPIC
  • Where
    • Payload: String data type


  • Sending JSON data to MQTT_PUBLISH_TOPIC
  • Where
    • Topic: String data type
    • Payload: String data type
  • JsonString(Topic, Payload) function will return a String data into the JSON format i.e. "Topic":"Payload"


  • Send data to a specific topic
  • Where
    • MQTT_Topic: const char data type
    • Payload: String data type


  • Sending JSON data to a specific topic
  • Where
    • Topic: String data type
    • Payload: String data type
    • MQTT_Topic: const char data type
  • JsonString(Topic, Payload) function will return a String data into the JSON format i.e. "Topic":"Payload"

Custom callback function in Arduino IDE sketch for MQTT message received:

If you want to get data received from MQTT subscribed topic right in your sketch, follow me;

  • Instance of ESPMetRED Library
  • Add callback in void setup()  function
  • Add callback function at the end after or before void loop()  function

  • Payload received is String data type and is not processed in JSON object
  • Used the following commands to convert Payload into JSON object
  • Suppose Payload contains the following information
  • To get data out of “TOPIC” and “PAYLOAD” i.e. “MyTopic” and “1”, respectively, use the following commands

Static IP Address:

  • To assign static IP address, add three variables to your sketch
  • Change XX with your desired IP address e.g. 192, 168, 50, 100
  • Rest of the values should resembles your WiFi network
  • Now instantiate ESPMetRED Library

Server API:

Pulling Node System Information:

  • Add “INJECT” node in Node-Red
  • Choose “{} JSON” option in “Payload”
  • Add the following code in “Payload” field

  • Hit done
  • Add “mqtt out” node in Node-Red
  • Add server settings according to this post
  • In “Topic” field add your subscribed topic (Arduino sketch) e.g. ESPMetRED/IN

  • Hit done
  • Join both nodes and click on “Deploy”

  • Now hit Inject node button and you will get node system information
  • Don’t forget to add “mqtt in” node with “debug” topic attached with debug node as all kind of system information will go on “debug” topic.

Push Time data to ESP8266 units:

  • Create a “MQTT in” node and enter ntp/IN  in Topic field
  • Add json node and link it to “MQTT in” node 
  • Add a “function” node and add following code in to it
  • Name the “function” node as “Time Push”
  • Add “MQTT out” node and leave it as it is
  • Link all of these nodes as shown below and hit “Deploy”

All of the code works fine but and  (global variables in Node-Red to store sunrise and sunset data) needs to be configured. There are variety of ways to get sunrise and sunset data for example, using http request  node to fetch data from


It requires getting your own api key from by registering yourself there. In http request node, send the following URL using get as method.

  • Don’t forget to change “your_api_key“, “latitude” and “longitude” according to your own information.
  • Change Return to “a parsed JSON object

Grab another “function” node and add follow code to it.

Now it will save sunrise and sunset to global and  variables. A “debug” node will show debug information when it will save data to these variables, however, it is not mandatory.


  • Sunrise or sunset values will be written to global variables daily at Noon i.e. 12:00 PM


Now every time an ESP8266 unit will boot up, It will get time data automatically. Moreover, to update sunrise and sunset data which changes by days, to ESP8266 units, We should do a little more work.

  • Add an “inject” node and select “interval” in “Repeat”
  • Add your desired time interval such as “12” and “hours” and hit done
  • Copy the “function” node as created above with the name of “Time Push” by Ctrl + C keys and paste it using Ctrl + V keys
  • Add “MQTT out” node and add ntp/OUT  in Topic field, hit done
  • Join all of three nodes as follows and “Deploy” changes

Now “Time”, “Sunrise” and “Sunset” data will be updated to all ESP8266 units every 12 hours automatically.

Drive a gpio right from Node-Red:

  • Publish the following code on MQTT_SUBSCRIBE_TOPIC in the same way you do in Pulling Node System Information
  • Change
    • “12”: Your desired gpio
    • “0”: Desired state either “0” or “1”


Leave a Reply

6 Comment threads
13 Thread replies
Most reacted comment
Hottest comment thread
10 Comment authors
hieunsMalikJMBMWaqas AhmedJames Recent comment authors
newest oldest most voted
Notify of

Do you have any OTA example using this library ? I am wondering how to send a binary file from node-red IBM cloud to ESP8266 via MQTT.


Can I use this library with Sonoff / Slampher?


I’m a beginner to IoT and found your library to be very useful and isolate me from some complexities. Thank you for your contribution.

I think I detected an error in file ESPMetRED/Examples/CallBack/CallBack.ino

In line 21 program calls “client.setCallback(callback);”, and it should be “client.setcallback(callback);” (no uppercase c)

This was driving me crazy with a compilation error!

Thanks again.


First a HUGE thank you for your work – this is my very first Arduino project and your code is working GREAT & I have my NodeMCU & RaspberryPi happily talking to each other over MQTT 🙂

Can I ask one request please – When my NodeMCU connects I would really like that a message is sent to Node-RED to say it has connected – I’ve tried adding the below line to end end of my void setup code, but nothing is sent 🙁


Any help much appreciated!



I am getting several error when try to compile the example. this is the log: Arduino:1.8.1 (Windows 10), Tarjeta:"NodeMCU 1.0 (ESP-12E Module), 80 MHz, 115200, 4M (3M SPIFFS)" C:\Users\xinux\Documents\Arduino\libraries\ESPMetRED-master\ESPMetRED.cpp:35:6: error: prototype for 'void ESPMetRED::joinWiFi()' does not match any in class 'ESPMetRED' void ESPMetRED::joinWiFi() In file included from C:\Users\xinux\Documents\Arduino\libraries\ESPMetRED-master\ESPMetRED.cpp:8:0: C:\Users\xinux\Documents\Arduino\libraries\ESPMetRED-master/ESPMetRED.h:57:10: error: candidate is: boolean ESPMetRED::joinWiFi() boolean joinWiFi(); C:\Users\xinux\Documents\Arduino\libraries\ESPMetRED-master\ESPMetRED.cpp:65:6: error: prototype for 'void ESPMetRED::joinMqTT()' does not match any in class 'ESPMetRED' void ESPMetRED::joinMqTT() In file included from C:\Users\xinux\Documents\Arduino\libraries\ESPMetRED-master\ESPMetRED.cpp:8:0: C:\Users\xinux\Documents\Arduino\libraries\ESPMetRED-master/ESPMetRED.h:59:10: error: candidate is: boolean ESPMetRED::joinMqTT() boolean joinMqTT(); C:\Users\xinux\Documents\Arduino\libraries\ESPMetRED-master\ESPMetRED.cpp:81:6: error: prototype for 'void ESPMetRED::keepalive()' does not match any in class 'ESPMetRED' void ESPMetRED::keepalive() ^… Read more »


Hi, can you tell me why you use JSON formatting to transmit data by MQTT between the ESP and the Node-Red application. As a beginner I would have though simple strings would be easier to use.
However, a really great library and blog from which I have learnt a great deal.

Thank you