[Framework] Homie for ESP8266

Tags: #<Tag:0x00007f616f39d348> #<Tag:0x00007f616f39d230> #<Tag:0x00007f616f39d168>

After I purchased some ESP8266-boards (NodeMCU v1.0 and WeMos D1 mini) I was looking for an easy way to connect them via wifi to an mqtt broker.

I found this framework called "Homie for ESP8266"

The “bare minimum sketch” (“Hello World”) is only 10 lines of code and provides everything to connect to your wifi, your mqtt broker and sending general information.

It startes as an access point on configuration mode after flashing.
With a simple app (Web, Android, iOS) you can configure Wifi and mqtt credentials.
That’s it.

As a beginner, I am happy I can control my first LED via wifi on an Arduino board. :slight_smile:
Without having to deal with error handling (reconnecting) for wifi and mqtt.

Have a look at this project.
It might be worth it.
Or let me now if this is a completely bad designed framework and you know a better one. :wink:


Hi, I am the creator of the Homie for ESP8266 framework.

I would also be glad to have feedback, positive or negative, as long as it is constructive.



Looks promising!

Trying to make a bit of sense of it…Would we need a “homie server” setup on our network for it to work?

Maybe if someone could explain how this would properly integrate into OpenHAB… I’m thinking it’ll be a case of using the MQTT Binding to subscribe and post message to each homie device?

The building block of the whole framework is the Homie MQTT convention. To be able to work with it, the only needed software is a classical MQTT broker. The homie-server you mentionned is just a Web UI and an OTA server for Homie devices, but you don’t need it, especially if you are using openHAB.

You’re right, to integrate with openHAB you will need the MQTT binding. Take the LightOnOff example. To interact with it, you need to:

  • Subscribe to devices/<the device ID>/light/on
  • Publish to devices/<the device ID>/light/on/set

I am not familiar with openHAB but I guess it would look something like this:

Switch light {mqtt="<[mybroker:devices/<the device ID>/light/on:state:ON:true],<[mybroker:devices/<the device ID>/light/on:state:OFF:false],>[mybroker:devices/<the device ID>/light/on/set:command:ON:true],>[mybroker:devices/<the device ID>/light/on/set:command:OFF:false]"}

Note I am not sure about the syntax.

It seems like a nice framework:)

So I did install everything got a solid blue light i.e in configuration mode. Serial port prints out :

Triggering Wi-Fi scan
✔ Wi-Fi scan completed

However when I go to http://marvinroger.github.io/homie-esp8266/ it says : Waiting for the device…

And never gets out of that… Any Idea why?

After flashing the device and openeing the Homie-website you need to connect to your device wich started an wifi access point…

I connected my android phone to the new wifi network and used the android app from homie to configure the wifi and mqtt credentials.

I successfully integrated an LED light and a push button via the mqtt binding to openhab so far.

Switch LED	{mqtt=">[openhab:devices/<the device ID>/light/on/set:command:ON:true],		>[openhab:devices/<the device ID>/light/on/set:command:OFF:false]"}
Switch Switch	{mqtt="<[openhab:devices/<the device ID>/button/pressed:command:ON:true],	<[openhab:devices/<the device ID>/button/pressed:command:OFF:false]"}

As @christoph_wempe suggested, you need to connect to the device Wi-Fi AP. It should be named Homie-xxxxxxxx, unless you used setBrand() to customize the name. Moreover, be sure to access the configurator through http (http://marvinroger.github.io/homie-esp8266/), not https. If you’ve followed these instructions and it still doesn’t work, just tell me!

I can connect to the AP from my PC, but the server says: Not found: /

I did this:
Once connected, the webserver is available at http://homie.config. To bypass the built-in DNS server, you can reach directly

works with the APP.

So which programs do you guys use as a broker on windows?


The / route does not exist. You can see the routes of the API on the Configuration API wiki page. I’ll add a / route with some explanation text to avoid the miscomprehension.

On Windows like on Linux, you can use mosquitto.

I am new to mqtt, but has been using arduino for a while. I really impressed by your work.

I came across adafruit and they have a cloud based broker. Maybe thats a good way to go?

What do you think?

The cloud based broker might be a good start for testing.

But keep in mind you might not want your home automation data started an accessible in the web.

I followed this guide to install mosquitto on my raspberry pi.

1 Like

I have a LoLin Node Mcu 1.0 (ESP 12-E) module and have been trying to load Homie onto it…

The LED doesn’t seem to flash etc as mentioned in the Wiki. But it does actually present itself as an AP which I connected to with the Home android app. I typed in my WiFi and MQTT credentials and it said it would reboot the device…

Still no LED flashing of any kind though…

And no matter how many times I restart the ESP8266 it doesn’t seem to connect to my wifi, it keeps presenting itself as an AP…

UPDATE : Okay I think I have it working, the thing that threw me is that the LED doesn’t blink at all so it’s hard to tell what “mode” it is in…

My Mosquitto server is showing the Homie device connecting to it and sending a PINGREQ every few seconds.

So now to try and make it do something… :slight_smile:

I’ll hack away at it but some more working examples with real sensors on your wiki would be great.
The first sensor I’m going to try is just a simple open/close sensor for my garage door…

Some of my posts were flagged as spam. Great. So I am sorry I unable to post links until a mod resolves the situation…

That’s weird… If you load a simple sketch with:

digitalWrite(BUILTIN_LED, HIGH);

Then another with

digitalWrite(BUILTIN_LED, LOW);

Is you led lighting on / off?

I take note for the lack of examples. :wink:

Thanks will try those…

In the meantime this is how far I have got with my gate open/close sensor… My Arduino knowledge is limited to copying and pasting examples together… At the moment this appears to work but once I close/open the contacts once then it seems to hang, I suspect there is an issue in a loop somewhere?

#include <Homie.h>

const int InputPin1 = 16;

HomieNode GateSensorNode("gatesensor01", "sensor");
Bounce debouncer = Bounce(); 
int oldValue=-1;

void setupHandler() {
  // Do what you want to prepare your sensor
  digitalWrite(InputPin1, HIGH);

  // After setting up the button, setup debouncer

void loopHandler() {
  // Get the update value
  int value = debouncer.read();
  if (value != oldValue) {
     // Send in the new value
     Serial.print("InputPin1: ");
     oldValue = value;

     Homie.setNodeProperty(GateSensorNode, "status", String(value));

void setup() {
  Homie.setFirmware("GateIoT", "1.0.0");

void loop() {

Yeah the LED doesn’t respond to these… I seem to recall the inbuilt LED is on pin 2 and in one other sketch I tested I had to specify pin 2 to make it work.

Yeah, I can confirm that the code below switches the LED on… Funny that “low” turns it on :slight_smile:

int LEDPin = 2;

void setup() {
// put your setup code here, to run once:
pinMode(LEDPin, OUTPUT);
digitalWrite(LEDPin, LOW);`

Your code seems to be fine. There is one thing, however: you set the debouncing interval to 5ms. You need to understand that Homie is doing some tasks in the background that might take more than 5ms. Try to increase this to 20 to 50ms. The latency still won’t be noticeable and might fix the issue.

You said you were using LoLin, these are non-standard boards. As defined in the NodeMCU variant of the Arduino for ESP8266, you have:

static const uint8_t BUILTIN_LED = 16;

Maybe fill an issue on the Arduino for ESP8266 repo with a request to add LoLin boards?

Thanks changing the debounce to 50ms hasn’t helped… I’ll have to keep tinkering.

In terms of the LED, maybe an option to override the LED pin?

I’ll also try with a push button, I never did but @christoph_wempe had some success with it if I recall correctly.

The LED pin option will land in 1.2.0. :wink: