Getting started

This Getting Started guide assumes you have an ESP8266 board with an user-configurable LED, and an user programmable button, like a NodeMCU DevKit 1.0, for example. These restrictions can be lifted. (see Advanced usage)

To use Homie for ESP8266, you will need:

  • An ESP8266
  • The Arduino IDE for ESP8266 (version 2.2.0 minimum)
  • 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. For the Arduino IDE

  1. Download the latest release
  2. Load the .zip with Sketch → Include Library → Add .ZIP Library

Homie for ESP8266 has 3 dependencies: ArduinoJson, Bounce2 and PubSubClient. You can install them through the Arduino IDE, with Sketch → Include Library → Manage Libraries. Be sure the installed version is >= 5.0.8 for ArduinoJson, >= 2.0 for Bounce2, >= 2.5 for PubSubClient.

1b. With PlatformIO

In a terminal, run platformio lib install 555.

Dependencies are installed automatically.

Bare minimum sketch

#include <Homie.h>

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

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

This is the bare minimum needed for Homie for ESP8266 to work correctly. If you upload this sketch, you will notice the LED of the ESP8266 will light on LED solid. This is because you are in configuration mode.

Homie for ESP8266 has 3 modes of operation:

  1. 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 credentials (like the Wi-Fi SSID, the Wi-Fi password, ...). Once the device receives the credentials, it boots into normal mode.

  2. The normal mode is the mode the device will be most of the time. It connects to the Wi-Fi, to the MQTT, it sends initial informations to the Homie server (like the local IP, the version of the firmware currently running, ...) and it subscribes from the MQTT to properties change. The device can return to configuration mode in different ways (press of a button or custom function, see 3. Advanced usage).

  3. The OTA mode is triggered from the normal mode when the MQTT server sends a version different from the current firmware version. It will reach the OTA HTTP server and flash the latest firmware available. When it ends (either a success or a failure), it returns to normal mode.

Very important: 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-xxxxxxxx. For example, if the AP is named Homie-c631f278, the AP password is c631f278. Connect to it.

Note: This c631f278 ID is unique to each device, and you cannot change it. If you reflash a new sketch, this ID won't change.

Once connected, the webserver is available at http://homie.config. To bypass the built-in DNS server, you can reach directly 192.168.1.1. You can then configure the device using the Configuration API. When the device receives its configuration, it will reboot to normal mode.

Understanding what happens in normal mode

Visual codes

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

  • Wi-Fi LED blinking Slowly when connecting to the Wi-Fi
  • MQTT LED blinking 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 devices / device ID, e.g. devices/c631f278).
  • It subscribes to the special device property $ota, automatically rebooting in OTA mode if OTA is available
  • It checks for a button press on the ESP8266, 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.

#include <Homie.h>

const int PIN_RELAY = 5;

HomieNode lightNode("light", "switch");

bool lightOnHandler(String value) {
  if (value == "true") {
    digitalWrite(PIN_RELAY, HIGH);
    Homie.setNodeProperty(lightNode, "on", "true"); // Update the state of the light
    Serial.println("Light is on");
  } else if (value == "false") {
    digitalWrite(PIN_RELAY, LOW);
    Homie.setNodeProperty(lightNode, "on", "false");
    Serial.println("Light is off");
  } else {
    return false;
  }

  return true;
}

void setup() {
  pinMode(PIN_RELAY, OUTPUT);
  digitalWrite(PIN_RELAY, LOW);

  Homie.setFirmware("awesome-relay", "1.0.0");
  lightNode.subscribe("on", lightOnHandler);
  Homie.registerNode(lightNode);
  Homie.setup();
}

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

Alright, step by step:

  1. We create a node with an ID of light and a type of switch with HomieNode lightNode("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 subscribe to the on property. We do that with lightNode.subscribe("on", lightOnHandler);. The lightOnHandler function will be called when the value of this property is changed
  4. We tell Homie for ESP8266 to expose our light node by registering it. We do this with Homie.registerNode(lightNode);
  5. In the lightOnHandler function, we want to update the state of the light node. We do this with Homie.setNodeProperty(lightNode, "on", "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 on property changes. But what if we want, for example, to send a temperature every 5 minute? 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 sending any property. Boring.

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

#include <Homie.h>

const int TEMPERATURE_INTERVAL = 300;

unsigned long lastTemperatureSent = 0;

HomieNode temperatureNode("temperature", "temperature");

void setupHandler() {
  // Do what you want to prepare your sensor
}

void loopHandler() {
  if (millis() - lastTemperatureSent >= TEMPERATURE_INTERVAL * 1000UL || lastTemperatureSent == 0) {
    float temperature = 22; // Fake temperature here, for the example
    Serial.print("Temperature: ");
    Serial.print(temperature);
    Serial.println(" °C");
    if (Homie.setNodeProperty(temperatureNode, "temperature", String(temperature), true)) {
      lastTemperatureSent = millis();
    } else {
      Serial.println("Sending failed");
    }
  }
}

void setup() {
  Homie.setFirmware("awesome-temperature", "1.0.0");
  Homie.registerNode(temperatureNode);
  Homie.setSetupFunction(setupHandler);
  Homie.setLoopFunction(loopHandler);
  Homie.setup();
}

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

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 Advanced usage page to learn about more powerful features like input handlers and the event system.