Skip to content

Getting started

This Getting Started guide assumes you have a board with a user-configurable LED and a user-programmable button, like a NodeMCU DevKit 1.0 or a typical ESP32 dev board. These restrictions can be lifted (see next pages).

This page intentionally stays close to the original upstream guide, so several examples remain ESP8266-centric. This fork is maintained primarily against current ESP32 Arduino cores while keeping the Homie 3.0.1 API and flow as close as possible to the original library.

The maintained installation path for this fork is PlatformIO with the labodj/homie-v5 Registry package. The Arduino IDE / ZIP flow below is legacy upstream documentation and is not the recommended path for this fork. See PlatformIO / PioArduino for the maintained ESP32 and ESP8266 project configuration examples.

To use this fork, you will typically need:

  • An ESP32 or ESP8266 board
  • PlatformIO for the maintained path, or the Arduino IDE for legacy upstream-style setups
  • Basic knowledge of the Arduino environment (upload a sketch, import libraries, ...)
  • To understand the Homie convention

Installing Homie for ESP8266

There are two ways to install Homie for ESP8266.

1a. With PlatformIO

Add this to your platformio.ini:

Maintained path for this fork

This fork is consumed through the labodj/homie-v5 PlatformIO Registry package. The primary maintained target today is ESP32 on pioarduino/platform-espressif32:

```
platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip
framework = arduino
board = esp32dev
lib_compat_mode = strict

lib_deps = labodj/homie-v5 @ ^3.4.0 ```

ESP8266 can still work on a best-effort basis, but it is not the main validation target
of this fork. If you use ESP8266, keep the ESP8266 platform and add
`PIO_FRAMEWORK_ARDUINO_LWIP2_LOW_MEMORY` when needed for reliable OTA behavior.

If you need unreleased changes from develop, use the git dependency and pin a commit SHA instead of the branch name.

Dependencies are installed automatically.

1b. For the Arduino IDE

This section is kept only as upstream legacy guidance. It is not the recommended installation path for this fork and its dependency list may not match the maintained PlatformIO path.

There is a YouTube video with instructions:

YouTube logo How to install Homie libraries on Arduino IDE

  1. Download an upstream release archive compatible with your target environment

  2. Load the .zip with Sketch → Include Library → Add .ZIP Library

Upstream Homie for ESP8266 has 5 dependencies:

Some of them are available through the Arduino IDE, with Sketch → Include Library → Manage Libraries. For the others, install it by downloading the .zip on GitHub.

Bare minimum sketch

#include <Homie.h>

void setup() {
  Serial.begin(115200);
  Serial << endl << endl;

  Homie_setFirmware("bare-minimum", "1.0.0"); // The underscore is not a typo! See Magic bytes
  Homie.setup();
}

void loop() {
  Homie.loop();
}

This is the bare minimum needed for Homie for ESP8266 to work correctly.

LED

Solid LED If you upload this sketch, you will notice the LED on the board will light on. This is because you are in configuration mode.

Homie for ESP8266 has 3 modes of operation:

  1. By default, the configuration mode is the initial one. It spawns an AP and an HTTP webserver exposing a JSON API. To interact with it, you have to connect to the AP. Then, an HTTP client can get the list of available Wi-Fi networks and send the configuration (like the Wi-Fi SSID, the Wi-Fi password, some settings...). Once the device receives the credentials, it boots into normal mode.

  2. The normal mode is the mode the device will be in most of the time. It connects to Wi-Fi and MQTT, sends initial information to the Homie server (like the local IP and the version of the firmware currently running), and subscribes to the needed MQTT topics. It automatically reconnects to Wi-Fi and MQTT when the connection is lost. It also handles OTA. The device can return to configuration mode in different ways (button press or custom function, see Resetting).

  3. The standalone mode. See Standalone mode.

Warning

As a rule of thumb, never block the device with blocking code for more than 50ms or so. Otherwise, you may very probably experience unexpected behaviors.

Connecting to the AP and configuring the device

Homie for ESP8266 has spawned a secure AP named Homie-xxxxxxxxxxxx, like Homie-c631f278df44. Connect to it.

Hardware device ID

This c631f278df44 ID is unique to each device, and you cannot change it (this is actually the MAC address of the station mode). If you flash a new sketch, this ID won't change.

Once connected, the webserver is available at http://192.168.123.1. Every domain name is resolved by the built-in DNS server to this address. You can then configure the device using the HTTP JSON API. When the device receives its configuration, it will reboot into normal mode.

Understanding what happens in normal mode

Visual codes

When the device boots in normal mode, it will start blinking:

LED

Slowly blinking LED Slowly when connecting to the Wi-Fi

LED

Fast blinking LED Faster when connecting to the MQTT broker

This way, you can have a quick feedback on what's going on. If both connections are established, the LED will stay off. Note the device will also blink during the automatic reconnection, if the connection to the Wi-Fi or the MQTT broker is lost.

Under the hood

Although the sketch looks like it does not do anything, it actually does quite a lot:

  • It automatically connects to the Wi-Fi and MQTT broker. No more network boilerplate code
  • It exposes the Homie device on MQTT (as <base topic>/<device ID>, e.g. homie/c631f278df44)
  • It subscribes to the special OTA and configuration topics, automatically flashing a sketch if available or updating the configuration
  • It checks for the configured reset trigger on the board to return to configuration mode

Creating an useful sketch

Now that we understand how Homie for ESP8266 works, let's create an useful sketch. We want to create a smart light.

GitHub logo LightOnOff.ino

Alright, step by step:

  1. We create a node with an ID of light, and name Light and a type of switch with HomieNode lightNode("light", "Light", "switch")
  2. We set the name and the version of the firmware with Homie_setFirmware("awesome-light" ,"1.0.0");
  3. We want our light node to advertise an on property, which is settable. We do that with lightNode.advertise("on").settable(lightOnHandler);. The lightOnHandler function will be called when the value of this property is changed
  4. In the lightOnHandler function, we want to update the state of the light node. We do this with lightNode.setProperty("on").send("true");

In about thirty SLOC, we have achieved to create a smart light, without any hard-coded credentials, with automatic reconnection in case of network failure, and with OTA support. Not bad, right?

Creating a sensor node

In the previous example sketch, we were reacting to property changes. But what if we want, for example, to send a temperature every 5 minutes? We could do this in the Arduino loop() function. But then, we would have to check if we are in normal mode, and we would have to ensure the network connection is up before being able to send anything. Boring.

Fortunately, Homie for ESP8266 provides an easy way to do that.

GitHub logo TemperatureSensor.ino

The only new things here are the Homie.setSetupFunction(setupHandler); and Homie.setLoopFunction(loopHandler); calls. The setup function will be called once, when the device is in normal mode and the network connection is up. The loop function will be called everytime, when the device is in normal mode and the network connection is up. This provides a nice level of abstraction.

Now that you understand the basic usage of Homie for ESP8266, you can head on to the next pages to learn about more powerful features like input handlers, the event system and custom settings.