Getting start with the Homie library (MQTT) for connected objects based on ESP8266

The Homie library has become very popular for the rapid development of ESP8266-based connected objects that communicate through MQTT messages. This library (GitHub page) is developed and maintained by Marvin Roger (personal page). Homie is a library that supports Wi-Fi network connection, authentication to an MQTT server and even wireless update via MQTT (which I still have to discover). The documentation (official page) is a model of its kind. However, it is only available in English (at the moment?) And is aimed at an audience that already has a good command of the programming. We will approach Homie in this tutorial in a very practical way step by step.

Install the Homie library and its dependencies on the Arduino IDE

For this tutorial, I installed version 2 of the library (see the following paragraph for differences with v1.5). It is not available from the Arduino IDE bookseller. Download the version you are interested in

Do not decompress the archive. Go to Sketch menu / Include library / Add .ZIP library and select the ZIP file from the Homie library you just downloaded

homie v1 1 install library ide arduino

Four additional libraries must then be installed:

That’s all. You are ready to develop with the Homie bookstore

Differences between version 1.5 and version 2

Before going any further, here are the main differences between the two current versions. The stable version is v1.5. Version 2 is under development but is usable. The current differences are mainly at the level of the formalism of certain functions which has evolved (the complete list here):

  • Homie.setFirmware (name, version) becomes Homie_setFirmware (name, version)
  • Homie.setBrand (brand) becomes Homie_setBrand (brand)
  • Homie.registerNode () must be deleted. The Nodes are now automatically (automagically) saved
  • Serial.begin () must now be explicitly started
  • Homie.setNodeProperty () changes completely. The syntax Homie.setNodeProperty (node, “property”, “value”, true) is replaced by
  • Homie.setNodeProperty (node, “property”). SetRetained (true) .send (“value”).

First test

The Homie library incorporates several examples. Through the tutorial, we will test the DoorSensor example. Here I indicated the D1 pin on which I connected a micro switch. Compared to the initial code, the pinMode command uses the internal PULLUP resistor. Alternatively, you can add a resistor to your setup.

#include <Homie.h>

const int PIN_DOOR = D1;

Bounce debouncer = Bounce(); // Bounce is built into Homie, so you can use it without including it first
int lastDoorValue = -1;

HomieNode doorNode("door", "door");

void loopHandler() {
  int doorValue =;

  if (doorValue != lastDoorValue) {
     Homie.getLogger() << "Door is now " << (doorValue ? "open" : "close") << endl;

     doorNode.setProperty("open").send(doorValue ? "true" : "false");
     lastDoorValue = doorValue;

void setup() {
  Serial << endl << endl;
  //digitalWrite(PIN_DOOR, HIGH);

  Homie_setFirmware("awesome-door", "1.0.1");



void loop() {

As you can see, there are no parameters in the code. All is done via a configuration file in JSON format. There are several ways to configure Homie:

  • Create a data folder in the project directory and include a config.json file. It will then be necessary to upload the data folder in a second time in the SPIFFS memory area. To read more, you can read this article.
  • Use the Configuration Utility. It is available in the form of a website at this address or use the Android app. In both cases, it will be necessary to connect to the access point created by Homie automatically at the start
  • We can finally send a new configuration in HTTP using the following curl command for example
curl -X PUT --header "Content-Type: application/json" -d @config.json

It’s very practical, but it’s also a bit confusing when you start.

Configuring settings

Here I suggest you use the method similar to the ESP Easy framework and the WiFiManager library. We will connect to the access point created by Homie at startup. Homie creates an access point until such a connection to the Wi-Fi network exists.

Select your ESP8266 card, the port on which it is connected and then upload the sketch. Open the Terminal to retrieve the assigned ID and verify that everything works as expected.

homie library 3 serial monitor first startup

If you try to connect to the access point created by Homie, you will get this error page (UI bundle not loaded …) which tells you that no configuration file exists. Re-connect to your Wi-Fi network.

homie library 5 ui bundle not loaded message error

Open this page

homie 6 setup esp8266 parameters on line tool

Connect to the access point

homie library 4 connect ap access point wifi

Finally, reset the ESP8266. Once it is connected to the Wi-Fi network again, the page will automatically update. The first page displays the main information:

  • ID of module ESP8266
  • Version of the bookstore Homie
  • Firmware name: the name given to the Arduino program
  • Version: the version you gave to your Arduino program
  • The list of Nodes: here, there is only one: Door. It is a door opening detector. You can change its name and assign a type to be published in the $type message.

homie 7 setup step 1

Normally you have nothing to modify here since everything is contained in the program Arduino. Go to the next screen with Next. The following screen allows you to select the Wi-Fi network to connect to and specify the password.

homie 8 step2 stepup wifi parameters

The following screen is used to configure the server connection parameters (MQTT broker):

  • IP address or URL if you use an online broker (read this article for a selection)
  • Port: 1883 by default
  • Prefix of the topic. By default, all messages will start with /homie . Do not specify the device name here, it should be indicated on the next screen and it is automatically added by Homie in the Topic.
  • If you have set up a password authentication, specify the user and password

homie 9 step4 setup mqtt

On the last screen you can enter the name of the object. It is highly recommended to find the corresponding messages on a home automation server for example. This is the Device ID field that will be used by Homie to build the Topic.

homie 10 setp5 device name

The configuration is complete. The parameters are saved in the SPIFFS memory area in a file named config.json. Once the ESP8266 has rebooted, the access point is no longer accessible.

homie 11 setup finish restart device

Recover your first MQTT messages

Follow this tutorial to install a Mosquitto broker on your machine.

Open a Terminal and run the following command

mosquitto_sub -h localhost -t "homie/#" -v

If you have set up an authentication, execute this command after changing the username and password.

mosquitto_sub -h localhost -t "homie/#" -v -u "USER" -P "PASSWORD"

Meaning of the parameters:

  • -h: option to specify the MQTT server address. Here it is on the test machine.
  • -t: the topic on which the subscription is started. The jocker # indicates that you want to subscribe to the entire tree after it
  • -v (verbose): allows to indicate the path of the topic. Otherwise, only the messages will be displayed. Not always useful if you need to locate a particular topic to use it elsewhere
  • -u: option to specify the user
  • -P: and its Authentication Password

After a few moments, here are the first messages coming from the door opening detector. Here, the program uses the library Bounce2 which makes it possible to improve the detection of support on a switch. This library avoids the problem of “rebound” by detecting the rising / falling edge for a certain time (here 50ms) to determine when a switch has been pressed. You can test the switch (or micro switch). As soon as it is pressed or released, an MQTT message is sent by Homie.

homie 12 terminal mosquitto subscribe topic

As you can see, Homie is very talkative! It sends very many Topics very regularly (in addition to your own events). This page details all messages published by the library.

There are several other examples to find out how Homie works. In the next tutorial, we’ll see how to include Homie objects on the main home servers. If you need to develop objects that communicate using MQTT messages, Homie is actually a library to consider. It merely replaces the WiFiManager and PubSubClient libraries. It allows to get rid of all the Wi-Fi configuration work, re-connection … so less coding in perspective.

Subscribe to the weekly newsletter

No spam and no other use will be made of your email. You can unsubscribe anytime.

DIY Projects