Esphomelib - library to greatly simplify Home Assistant integration with ESP32

Hi, the last few months I’ve been working on this project of mine called esphomelib. It’s a library designed to greatly simplify your firmware code for ESP32-based devices and has great integration with Home Assistant through MQTT. You can find it here: https://github.com/OttoWinter/esphomelib

With its powerful core, the aim is to make creating things such as lights - which can often be very complicated with effects, etc. - extremely easy to create in code, so that you can focus on making the hardware, not the software for your boards.

I think an example can really show off how easy this library is to use. The following code shows how you can create an RGB light that will automatically show up in Home Assistant through MQTT discovery. This would have taken huge amounts of code and time without esphomelib.

#include "esphomelib/application.h"
using namespace esphomelib;
Application app;

void setup() {
    app.set_name("livingroom");
    app.init_log();
    app.init_wifi("YOUR_SSID", "YOUR_PASSWORD");
    app.init_mqtt("MQTT_HOST", "USERNAME", "PASSWORD");

    auto *red = app.make_ledc_component(32); // on pin 32
    auto *green = app.make_ledc_component(33);
    auto *blue = app.make_ledc_component(34);
    app.make_rgb_light("Livingroom Light", red, green, blue);

    app.setup();
}
void loop() { app.loop(); }

esphomelib tries to be extremely easy to use by abstracting between the back-end (which provides sensor data, PWM, …) and the MQTT front-end and it comes with support for lots of devices and sensors out-of-the-box. In the above code, you could, for example, just switch out the RGB channels with a PCA9685 PWM board, and the light component would still work without a problem.

I’m writing this because I’d like to get some feedback before adding support for more devices. My questions are:

  • If you had to re-code all of your espressif microcontrollers, would you consider using this library?
  • Are there any features/devices you would really like to see support for?
  • Would you like to see ESP8266 support?
  • Any general feedback?

Thank you!

28 Likes

Will have a look some more when I get some ESP32’s, but it looks like a really simple way of implementing IoT devices. Thanks for putting this together :smiley:

Having only ESP8266s, I didn’t test it, but the API looks really nice to use! There’s only one thing I couldn’t find easily: what about creating a sensor, let’s say a binary sensor, with something else than the direct output of a GPIO? The concrete example I have: I have a distance sensor, but I’m not interested in its actual value, I only want to know if the distance is higher than a specified value. I’m also not using the direct output value, but the average distance during the last five minutes.

I guess it’s something that one would want to do if using some hardware not supported (yet? :-)) by your library, too.

Is there any way to do that kind of “template sensor” with your library?

1 Like

The way I envisioned this library to be was that it would mostly just send/receive values from/to Home Assistant - and advanced features such as automation or template sensors would be done by Home Assistant. That’s because it’s very difficult to create a library that does “everything” and if you try doing that, the result often ends up being difficult to use.

In your case, the idea of this library would be to let the sensor report the value every so often and to have Home Assistant do the template binary sensor stuff. An exception to this is automatic smoothing of sensor values, which is already implemented in esphomelib for Sensors (see Filters) - by default the Application class already sets up all DHT sensors to smooth their “front-end” (i.e. MQTT) value over the last 5 minutes.

I know I should probably set up some guides/tutorials on how to support a custom sensor/other stuff soon, as this is probably quite important especially right now as not so many devices are support (yet). Anyway, adding support for a custom sensor is really quite easy in esphomelib - just create a new class extending sensor::Sensor and implement unit_of_measurement() and report your new values every so often using push_new_value().

(Also: ESP8266 is coming soon (hopefully in a few days), as adding the support seems to be easier than expected - a mostly working version is already on the esp8266-support branch of the repo)

2 Likes

I didn’t see the filters, neat! That’s really great, thanks for the answers :slight_smile:

Yeah I think I really should work on a better documentation / actual guides - could probably really help in this early phase of the library.

2 Likes

Hello!

Congratulations, I had a quick read thought the github and it looks very nice already!
Documentation and guides would definitely help…

I use esp easy (esp8266 only) a lot because it’s “coding friendly”, supports plenty of components with very few configurations and works great with MQTT / Home Assistant.

Currently I’m working again on my automatic curtains so I’d love to see a decent servo support. :stuck_out_tongue:

Hmmm, I haven’t thought of servo motors yet, but it would definitely be a nice addition to the library and quite easy to implement too, as it’s just a simple modulated PWM signal. But before implementing it, I would like to know how people want to use servo motors. Do you wish to switch between two positions and for what/how are servo motors used in your project(s)? Is more fine-grained control like setting an exact percentage position with Home Assistant MQTT covers required/wished?

3 Likes

Hello @OttoWinter I use them to open / close our curtains, so it need a starting and end point to know where to stop and if emulated as a light we can use the brightness to controll how much "open / close’ they are.
I have seen people also using them for pressing buttons like in the dumb coffeemachines etc

It would be nice if the servo are exposed as a dimmer to HA, so automations can switch between positions and’ore be controlled with a slider, but the firmware take care of managing power.

E.g. when receiving a position change: turn on PWM with last duty cycle, turn on power, change PWM to desidered duty cycle, wait positioning, turn off power, turn off PWM.

2 Likes

Yes that’s more or less the way I would have done it too, with one exception: instead of using a dimmer (i.e. a light) I would opt to use the MQTT Cover component, because that would make more sense semantically but also supports the position stuff.

The difficult part is to support all configurations of covers/motorized components. The simplest case that needs to work is a simple servo motor that switches between two absolute positions. The next case that should be supported is motors that are either on/off, i.e. can’t simply go to an absolute position. For this case there are several possible hardware configurations to detect when the motor should stop - most notably end stops or a simple time delay or a combination of the two.

Concerning the power: esphomelib already has a powerful component that can handle switching a power supply on/off. See ATXComponent for more info.

1 Like

Yes, definitely the Cover component makes more sense :grin:

If we are referring to “servo” motors like the one used in cars and planes models, they move between absolute positions following the PWM duty cycle, you don’t have to care about end stops. A nice touch would be a way to set the movement speed.

When I sait “power on/power off” i was simply referring to the power wire of the servo. You can keep them powered, but it will only be a waste of energy. If a servo is used to change the orientation of a blind two times a day it’s useless to keep it powered.

Most servo motors do indeed move between absolute positions, but there do also exist continuous motion servos that change their relative speed according to the duty cycle. And I agree speed limiting and motion ease in/out would probably also be good.

Hello @OttoWinter

Do you have any plans to make a UI interface for configuration?

1 Like

No, I’m not planning on adding that - esphomelib is and will always be a C++ API/Framework to enable simplify creating Home Assistant nodes. However, I have thought about adding an interface on top of esphomelib that would create programs for you with a YAML-file similar to Home Assistant. I suppose something similar could also be done using a web interface, but both of these things would only be added after esphomelib is more or less feature-complete and bug-free.

1 Like

Hey Otto, do you plan to add any support for the bluetooth radio on the ESP32?

1 Like

This looks pretty cool. I have NodeMCU’s (ESP8266) so support for those would be awesome. As others have mentioned, having switches and sensors would be perfect if possible.

I am just starting out with MQTT, C and ESP’s so know its not completely simple, so much appreciated.

I have NodeMCU’s (ESP8266) so support for those would be awesome.

Working on that and it’s almost finished. I’m currently in the last phase of testing and fixing now, but I hope to get that feature released in a week or two.

As others have mentioned, having switches and sensors would be perfect if possible.

Switches and sensors are already supported :grinning:

I am just starting out with MQTT, C and ESP’s so know its not completely simple, so much appreciated.

Glad to hear that

ESP8266 support is now out guys :tada::tada::tada:

5 Likes

Just a thumbs up!!!
It’s really easy to use it.

1 Like