Skip to content
💡 ESP8266 framework for Homie, a lightweight MQTT convention for the IoT
Branch: develop
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Add doc build for V3 Mar 10, 2019
data/homie Release 2.0.0 Jun 2, 2018
docs Update Mar 10, 2019
examples Add output for SENDING_STATISTICS to the example application (#567) Mar 9, 2019
scripts Add option for ota_updater script to connect to TLS-protected brokers… Jun 21, 2018
src Proposal to optionally run HomieNode::loop() also in disconnected sta… Mar 10, 2019
LICENSE Initial commit Dec 13, 2015
Makefile Add note about v3 to README.MD Mar 10, 2019
banner.png Release 2.0.0 Jun 2, 2018
homie-esp8266.cppcheck Release 2.0.0 Jun 2, 2018
library.json Update urls (#559) Jan 22, 2019
mkdocs.yml Added compiler-flag documentation to advanced usage Mar 10, 2019

homie-esp8266 banner

Homie for ESP8266

Build Status Latest Release Gitter PlatformIO

An Arduino for ESP8266 implementation of Homie, an MQTT convention for the IoT.

Currently Homie for ESP8266 implements Homie 2.0.1

Note about v3 features (Auto-discovery, ESP32, ...)

Version v3 is currently in development. It adds support for Homie-convention v3.0.1 and ESP32 controllers.

If you are interested in testing or helping development, please try the #develop-v3 branch.

Note for v1.x users

The old configurator is not available online anymore. You can download it here.


The Git repository contains the development version of Homie for ESP8266. Stable releases are available on the releases page.

Using with PlatformIO

PlatformIO is an open source ecosystem for IoT development with cross platform build system, library manager and full support for Espressif ESP8266 development. It works on the popular host OS: Mac OS X, Windows, Linux 32/64, Linux ARM (like Raspberry Pi, BeagleBone, CubieBoard).

  1. Install PlatformIO IDE
  2. Create new project using "PlatformIO Home > New Project"
  3. Open Project Configuration File platformio.ini

Stable version

  1. Add "Homie" to project using platformio.ini and lib_deps option:
platform = espressif8266
board = ...
framework = arduino
lib_deps = Homie

Add the PIO_FRAMEWORK_ARDUINO_LWIP2_LOW_MEMORY build flag to ensure reliable OTA updates.

Development version

  1. Update dev/platform to staging version:

  2. Before editing platformio.ini as shown below, you must install "git" if you don't already have it. For Windows, just go to and the download will start automatically. Note, this is only a requirement for the development versions.

  3. Add development version of "Homie" to project using platformio.ini and lib_deps option:

platform = ...
board = ...
framework = arduino

; the latest development branch (convention V2)
lib_deps =

; the latest development branch (convention V3.0.x) 
lib_deps =

; or tagged version
lib_deps =

Happy coding with PlatformIO!


#include <Homie.h>

const int PIN_RELAY = 5;

HomieNode lightNode("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);
  Homie.getLogger() << "Light is " << (on ? "on" : "off") << endl;

  return true;

void setup() {
  Serial << endl << endl;
  digitalWrite(PIN_RELAY, LOW);

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



void loop() {

Requirements, installation and usage

The project is documented on with a Getting started guide and every piece of information you will need.


I am a student and maintaining Homie for ESP8266 takes time. I am not in need and I will continue to maintain this project as much as I can even without donations. Consider this as a way to tip the project if you like it. 😉

Donate button

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.