Esphomelib - A comprehensive solution for using ESPs with Home Assistant

The ESP8266 and ESP32 are dirt cheap WiFi-enabled microcontrollers that have established themselves as the base for many DIY home automation projects. Even quite a few manufacturers like iTead with their Sonoff devices have chosen these controllers because of their competitive price.

Setting up these microcontrollers for some basic functionality has also gotten really easy over the years with popular projects like ESPEasy or Sonoff-Tasmota: You just download their firmware and flash it onto your chip. But if you’ve ever tried to go a bit beyond the basic set of functions of those frameworks and tried to do some customization, you will have probably noticed that it’s not that easy. Often times you’ll end up having to download some Arduino code project from the internet and customizing it to your needs.

This is where esphomlib comes in: The esphomelib suite is a set of tools that are designed with the goal of achieving the best possible user experience. esphomelib a) allows for lots of customization without touching a single line of code and b) has complete Home Assistant integration. Inside the esphomelib ecosystem, you essentially just have to write a simple YAML configuration file. The rest like compiling, flashing, uploading etc. will then be taken care of automatically.


An example probably illustrates this the best. To use esphomeyaml, there are two main ways: From a HassIO add-on, or from the command line. For the esphomeyaml add-on, you just have to add “” as an add-on repository (see Installing third party add-ons). Then select and install “esphomeyaml” and wait for the installation to complete. After that, you will be able to start the add-on and view the web interface.

From the command line you just need to install the Python 2 package using the pip command seen below. Then visit localhost:6052 to view the dashboard.

pip2 install esphomeyaml
esphomeyaml config/ dashboard
# Alternative for docker users:
docker run --rm -p 6052:6052 -p 6123:6123 -v "$PWD":/config ottowinter/esphomeyaml /config dashboard

Once in the dashboard interface, you will be greeted by a small setup wizard that will help you get started with esphomeyaml and create a basic configuration. You should end up with a configuration file like this.

  name: livingroom
  platform: ESP8266
  board: nodemcuv2
  ssid: 'MySSID'
  password: 'MyPassword'
  broker: ''
  username: ''
  password: ''

At this point, you can already flash the firmware. To do this, first plug in the USB cable of the ESP into a USB port of the device esphomeyaml is running on and wait until you see a “Discovered new serial port” message (in some cases you need to restart the add-on). Select the upload port in the top navigation bar and press the big “UPLOAD” button. If everything succeeds, you should now have a functioning esphomelib node and see the debug logs 🎉

Adding some basic functionality

Above configuration is, let’s face it, pretty dull. It really only connects to WiFi and MQTT and sits idle. So let’s add a basic GPIO switch! The GPIO switch component in esphomelib allows you to control the ON/OFF state of any of the pins on your ESP. For example, if you add this configuration to the bottom of your YAML file, you’re setting up the pin GPIO5 to be controlled as a switch with the name “Living Room Dehumidifer”.

  - platform: gpio
    name: "Living Room Dehumidifer"
    pin: GPIO5

If you now press upload again (this time the ESP doesn’t need to be connected via USB, as updates can be done over WiFi), you will see a switch show up in Home Assisstant automatically through MQTT discovery.

![](upload://jZSTq8iTXnv46cZpzCVIO15bcJb.png) How the newly configured switch will show up in Home Assistant if MQTT discovery is enabled and a default view is used.

Granted, this functionality would have been pretty simple with other projects too. But once you start adding lights, covers and other sensors, esphomelib’s modular design really starts to shine.

See Also

This is a companion discussion topic for the original entry at

platformio is apparently down (see - and that at worst possible time for me. so right now this guide pretty much doesn’t work :disappointed_relieved: I apologise for the inconvenience - nothing really I can do about it :frowning:

(Issue here:

Update: Up again :grinning:

This is looking really nice! This is something that you doesn’t even think it would be possible before someone just makes it!

Edit: I was about to ask for 443MHz sender/receiver support, but that’s planned in near future?

1 Like

Jep, working on that as we speak actually :wink:


I’ve been playing with this all evening and have managed to get 3 nodemcu’s (2x esp8266 and 1x esp32) setup with just the basic install so I can OTA over the config for what I decide to do with them Simply amazing! I can’t wait to play with this some more and really dig in to what it can do. Thanks @OttoWinter!!!

1 Like

Well done mate, will certainly make it easier for folks to use those cheap little devices for all sorts of things

1 Like

Wow. This sounds pretty cool!

I have been meaning to set up a couple of esp chips.

The functionality i wanted is.

A. Esp8266 with pir and temp sensor reporting back to HA.

B. Esp8266 in garage with reed sensor to detect for opening and closing of door, a relay for controlling the garage door, an ultrasonic distance sensor to report of car is in garage and pir for motion detection.

Wow this is realy cool.

I’m planning on using this on my home build weather station. Already have the parts, but i’m stuck on some pieces off code. esphomelib is a wonderfull solution whitout hardly any coding.

A question though: Is the FC-37 Rainsensor supported? i’m using two of them on a nodemcu, one digital and one analog. Or are there any plans to support them?

@kiwijunglist Yes that should be fully possible with esphomelib :slight_smile:

@XerOps The FC-37 should work out-of-the box. For the digital output, you can use a GPIO Binary Sensor and for the Analog (ADC) Sensor should work. Only thing that would be left to do is create a formula that converts the input voltage of the FC-37 analog output to a measure like mm^3/hour - see the TEMT600 Cookbook Entry for inspiration. And if you have a working formula, please do feel free to contribute it to the cookbook so that others don’t need to re-do the work :wink:

1 Like

@OttoWinter Thank you for a great addon

I’m having issues uploading to bruh’s sensornode. Tried both OTA and USB with luck.
Am I missing something?

INFO [esphomeyaml.config] Reading configuration…
INFO [esphomeyaml.main] Generating C++ source…
INFO [esphomeyaml.main] Compiling app…
INFO [esphomeyaml.main] Running: platformio run -d /config/esphomeyaml/sensornode1
[Wed Jun 6 19:48:13 2018] Processing sensornode1 (platform: espressif8266; board: nodemcu; framework: arduino)

Verbose mode can be enabled via -v, --verbose option
PLATFORM: Espressif 8266 > NodeMCU 0.9 (ESP-12 Module)
SYSTEM: ESP8266 80MHz 80KB RAM (4MB Flash)
Library Dependency Finder ->
Collected 32 compatible libraries
Scanning dependencies…
Dependency Graph
|-- v1.0
| |--
| | |-- v1.0
| |-- v1.0
|-- v1.0
| |-- v1.0
|-- v1.0
|-- v1.6.2 #053ee36
| |-- v0.8.2
| | |-- v1.1.3
| | | |-- v1.0
| |-- v5.13.3
| |-- v1.1.1
| | |-- v1.1.3
| | | |-- v1.0
| | |-- v1.0
| | |-- v1.0
| | |-- v5.13.3
| |-- v3.1.8 #d416194
| | |-- v3.3.1
| |-- v1.0
| |-- v1.0
| | |--
| | | |-- v1.0
| | |-- v1.0
| |--
| | |-- v1.0
| |-- v1.0
Calculating size .pioenvs/sensornode1/firmware.elf
text data bss dec hex filename
312608 11516 30528 354652 5695c .pioenvs/sensornode1/firmware.elf
========================= [SUCCESS] Took 20.64 seconds =========================
INFO [esphomeyaml.main] Successfully compiled program.
INFO [esphomeyaml.main] Uploading binary…
INFO [esphomeyaml.espota] Starting on
INFO [esphomeyaml.espota] Upload size: 328272
INFO [esphomeyaml.espota] Sending invitation to sensornode1.local
ERROR [esphomeyaml.espota] Failed
ERROR [esphomeyaml.espota] Host sensornode1.local Not Found

This is for the first flash using esphomelib? I don’t know if thr Bruh Multisensor is using the same OTA mechanism as esphomelib, do you might have to use the USB port.

For uploading through the USB port: You’re using esphomelib through the HassIO add-on, right? In that case you sometimes need to restart the HassIO add-on after you’ve plugged in a new USB device.

Could add-on restart itself?

Installed the add-on but it didn’t work, tried to re-install the add-on and now HA keeps rebooting…

The problem is that the add-on doesn’t even know when a new USB device is plugged in/out - so it can’t really know when it would need to restart itself. Also software that restarts itself and therefore becomes unresponsive for a short period of time is not really good UX…

@maxdaniel Huh, that’s weird. esphomeyaml is running inside a docker container, so it should actually be completely isolated from the rest of Home Assistant. (So, even if it wanted to, it shouldn’t be able to cause issues with the rest of Hass…)

weird, I think it has something to do with HASSio more than the add-on, im resetting everything now.

Such a clutch project! Pumped to see integrations like this lowering the to get into ESP projects. Looking forward to working more with this!


About time you got back. Hope you are well!

He’s alive !
Good to see you online Ben :smile:


This is so nice!
I’ve never touched or even tried to read up on esp programing, but after seeing this two days ago I just had to try. Two days later (including waiting time for my online order) I have 8 groups of roof led and two garage doors integrated with HASS and Siri - wow!

Just trying to figure out how to incorporate reed sensors for the garage doors to show current position in Hass.

1 Like

Where to execute esphomeyaml livingroom.yaml wizard I installed it trough the command window using hassbian.