homie-esp8266 is an MIT-licensed Arduino framework that implements the Homie MQTT convention on ESP8266 and ESP32 boards, for developers building self-hosted home-automation and IoT devices that report to an MQTT broker.

What it is

The project is an Arduino implementation of Homie, a lightweight MQTT convention for the IoT, running on Espressif ESP8266 and ESP32 microcontrollers. This branch implements Homie 3.0.1 and adds support for the ESP32. It is built for the PlatformIO ecosystem, an open source environment for IoT development with a cross-platform build system and library manager, and it is published in the PlatformIO registry under the library identifier Homie. The Git repository holds the development version, while stable releases live on the releases page, with the latest marked as v3.0.0.

The concrete problem it solves is per-device glue code. Without a shared convention, every ESP8266 sketch invents its own MQTT topic layout, its own boot sequence, and its own way of receiving settings, so devices from different projects cannot be described or managed the same way. Homie defines that shared description over MQTT; homie-esp8266 supplies the Arduino code that implements it, replacing hand-written Wi-Fi and MQTT connection loops, ad hoc topic strings, and manual configuration flashing. In their place the framework offers automatic connection and reconnection to Wi-Fi and MQTT, a JSON configuration file, and an HTTP JSON API with a Web UI and app for sending configuration to a device and reading information back from it.

Key capabilities

• Automatic connection and reconnection to Wi-Fi and MQTT.
• A JSON configuration file used to configure the device at runtime rather than at compile time.
• An HTTP JSON API, Web UI, and app to send configuration remotely and query device state.
• Over-the-air updates over MQTT, controlled through OTA configuration updates; the README notes that the PIO_FRAMEWORK_ARDUINO_LWIP2_LOW_MEMORY build flag is needed for reliable OTA.
• Custom settings for values that fall outside the convention.
• Magic bytes support.
• Distributed through PlatformIO via lib_deps; the stable library is added as lib_deps = Homie, and the development branch as lib_deps = https://github.com/homieiot/homie-esp8266.git#develop.

Who uses it and how

• Home-automation builders who run their own MQTT broker and want ESP8266 or ESP32 relays, lights, and sensors to appear under a consistent topic structure; the README's light example uses a node declared as HomieNode lightNode("light", "Light", "switch") with PIN_RELAY = 5.
• Developers working in PlatformIO across Mac OS X, Windows, Linux 32/64, and Linux ARM hosts such as Raspberry Pi, BeagleBone, and CubieBoard.
• Devices deployed in places where USB reflashing is impractical, configured instead by pushing the JSON configuration file through the HTTP API.
• Devices already in service that need firmware or configuration updates delivered remotely by OTA over MQTT.

Getting started

Install the PlatformIO IDE, create a new project, and add the library to the Project Configuration File platformio.ini through the lib_deps option, using lib_deps = Homie for the stable release. Development builds are pulled by pointing lib_deps at https://github.com/homieiot/homie-esp8266.git#develop, and sketches are supplied in ./examples.

How it compares

No list of paid products it replaces is provided in the facts. Within the tools named, homie-esp8266 is the Arduino-side implementation of the Homie convention rather than the convention itself, so it sits alongside the Homie 3.0.1 specification and depends on an MQTT broker and the PlatformIO toolchain to be useful.

When to use it — and when not to

Choose it when an MQTT broker is already running, PlatformIO is already the build path, and devices should follow the Homie convention rather than a bespoke topic scheme. Do not choose it if running and maintaining an MQTT broker is out of scope, or if the target hardware is not an ESP8266 or ESP32. Be aware that the example sketches carry a "TODO: adapt to V3" note, so the examples trail the 3.0.1 implementation, that the repository language is listed as HTML even though it ships Arduino sketches, and that 89 open issues are outstanding.

[env:myboard]
platform = espressif8266
board = ...
framework = arduino
build_flags = -D PIO_FRAMEWORK_ARDUINO_LWIP2_LOW_MEMORY
lib_deps = Homie

[env:myboard]
platform = ...
board = ...
framework = arduino
build_flags = -D PIO_FRAMEWORK_ARDUINO_LWIP2_LOW_MEMORY

; the latest development branch (convention V3.0.x)
lib_deps = https://github.com/homieiot/homie-esp8266.git#develop

#include <Homie.h>

const int PIN_RELAY = 5;

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

bool lightOnHandler(const HomieRange& range, const String& value) {
  if (value != "true" && value != "false") return false;

  bool on = (value == "true");
  digitalWrite(PIN_RELAY, on ? HIGH : LOW);
  lightNode.setProperty("on").send(value);
  Homie.getLogger() << "Light is " << (on ? "on" : "off") << endl;

  return true;
}

void setup() {
  Serial.begin(115200);
  Serial << endl << endl;
  pinMode(PIN_RELAY, OUTPUT);
  digitalWrite(PIN_RELAY, LOW);

  Homie_setFirmware("awesome-relay", "1.0.0");

  lightNode.advertise("on", "On", "boolean").settable(lightOnHandler);

  Homie.setup();
}

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