Documentation for ESPHome?

ESPHome
1

First post… for the life of me, I can’t find documentation on the programming syntax besides ESPHome.io, which addresses how to interface with things. How do you write a program in ESPHome?

I have Arduino’s programmed that interface with I2C displays using Wire, and subscribe to MQTT do display temperatures, for example. They display on a Taylor Edge IN-12 Nixie tube. I’d like to see about doing this within the ESPHome system, but can’t seem to find out how I should approach it. I stumbled thru getting a ultrasonic sensor working because the ESPHome.io info was very basic.

Should I even try to convert? Can/should I run Arduino code under ESPHome? Or just keep doing it natively in Arduino?

Thanks!

2

Try these pages DIY Examples — ESPHome and this section ESPHome — ESPHome

1 Like
3

ESPHome is a great way of avoiding all of the boring boilerplate that makes ESP8266 and ESP32 devices work and integrate beautifully into Home Assistant. It’s also a great platform for managing multiple devices. But if you have working code now, it does everything you want, and you don’t plan to grow your ESP garden any further, there’s probably no point trying to migrate.

You are correct that documentation isn’t ideal for someone wanting to jump into Esphome directly into the deep end, which in your case is a custom I2C wire device. Esphome is best learned by starting with a MVP (minimum viable program) and then progressively adding to it. Here are the steps you could take:

  1. Set up the esphome environment, which is a web server with a dashboard. Ideally this should be running in a similar fashion to your existing Home Assistant and MQTT servers.
  2. Set up your wifi AP settings in secrets.
  3. Set up a minimum viable program that is compatible with your board. (See below)
  4. Compile and flash your device over cable.
  5. Confirm that the device connects to your wifi, appears as online on the Esphome dashboard, and can be added to Home Assistant as an integration. You can now change the config and compile/upload directly from the Esphome dashboard.

nixie-test.yaml

esphome:
  name: nixie-test

esp8266:
  board: nodemcuv2

logger:

api:
  password: !secret hass_password

ota:
  password: !secret ota_password

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

secrets.yaml

wifi_ssid: changeme
wifi_password: changeme
hass_password: changeme
ota_password: changeme

“hass_password” is what you’ll enter any time you add an Esphome device to integrations in Home Assistant. “ota_password” can be any old jumble of garbage, so long as it remains unchanged. It’s what allows the Esphome dashboard to talk to your devices.

———————

After you’ve gotten this far, your next task is to work out what parts you need to complete your device’s configuration and do everything you want. Add these components to your config one at a time. You can use the Esphome dashboard to open a live log view so you can see what’s happening on your device.

  • A Home Assistant sensor in order to bring in the temperature you want to display.

  • An I2C bus

  • If it uses a standard controller already known to Esphome, e.g. a PCF8574, then integration will be very simple. Otherwise you will need to build a custom I2C component or, if your code is simple enough, a trivial lambda (Esphome’s name for a block of raw C++) which can do the reading and writing based on whatever protocol your display uses. This uses the same Wire library as Arduino, so it’s going to be very familiar to you. Note that the i2c: block above initialises Wire, so you don’t need to run Wire.begin(); in your own code.

I’m not familiar with I2C but integration might be as simple as:

i2c:
  sda: D3
  scl: D4
  scan: true

sensor:
  - platform: homeassistant
    entity_id: sensor.temperature_sensor_1
    id: temp1
    on_value:
      then:
        - script.execute: update_nixie

script:
  - id: update_nixie
    mode: single
    then:
      - lambda: |-
          float t = id(temp1);
          // a bunch of C++ that converts t into whatever Wire wants          
          Wire.beginTransmission(0x21);
          Wire.write(0x78);
          Wire.write(0x42);
          Wire.endTransmission();
1 Like
4

Can:

Should?
Nah. ESPhome is mainly designed to bring sensors into HA and let HA do the grunt work, but using the Automations etc you can also do that work in the ESP itself.

2 Likes
5

Well, I have a project where I glued together the easiness of esphome with specific code (rhasspy micro/speaker). Works nicely and I get the best of both worlds in a single ESP32 :wink:

6

Can’t find a :deciduous_tree: in the forest? :wink:

and much more to be found on esphome.io which will help getting the show started :rocket:

7

I guess not! I need to spend some time learning more about yaml I guess, there’s an assumption that it’s understood, and I don’t understand it yet. If I want to port my C++ code to yaml, I’ll have to look on how to do that elsewhere I assume. I am new to both HA and ESPHome, and yaml is new to me as well. I’ll figure it out, but as a newbee to HA and ESPHome, this is a struggle right now, thinking of just sticking with the Arduino IDE and communicating to HA via MQTT. That’s where I am coming from.

Thanks for the links, I’ll read thru them!

1 Like
8

There are some good links here to read from everyone, I appreciate it.

9

You actually wouldn’t port your code but rather only look at the “functions” of your device and declare the needed components (all available in esphome.io) in your yaml. :mechanical_arm:

You can browse some yaml files to get an idea what things could look like :point_down:

But to get started it might be better to start with a small yaml and than just grow it :seedling:

1 Like
10

This would be correct for 95% of ESP-based projects where every sensor/output is natively supported within ESPHome. This might not be the case here.

He certainly won’t need to port any boilerplate code. But somewhere in his current project are a few lines of C++ which can take the temperature value and transforms it into the correct series of calls to the Wire library. These few lines of code can be pasted directly into a lambda block within the YAML file—see my earlier example.

The minimally viable YAML for his project could potentially be as simple as what I showed above. But it is hard to be sure because I don’t know anything about any of his hardware.

It was new to me as well, but I’m glad I made the switch. In part because I’m thankful to be rid of MQTT. In part because I have well over a dozen ESP devices throughout my house. But mostly because once you become comfortable with ESPHome, starting new projects and improving existing ones is so easy and enjoyable. Want to add a humidity or CO2 sensor to your nixie clock? Just wire it up, add a few extra lines to the YAML, and run an OTA update.

11

From the example YAML I posted earlier:

i2c:
  sda: D3
  scl: D4
  scan: true

▲ The i2c: block initialises Wire. I picked pins D3 and D4 at random to fill out the example; you would replace them with whichever pins are appropriate for you. Much like with Arduino code, if you’re using something like a NodeMCU or D1 Mini, you can specify pins by label. Or you can specify the GPIO number directly—just replace D4 with GPIO2, or whatever.

sensor:
  - platform: homeassistant
    entity_id: sensor.temperature_sensor_1
    id: temp1
    on_value:
      then:
        - script.execute: update_nixie

▲ The sensor: block contains one sensor of the type homeassistant. This reads the entity sensor.temperature_sensor_1 directly from your Home Assistant server. Whenever the value changes in HA, it’s sent to your ESP device and the script update_nixie is executed. (The indirection of the script isn’t actually necessary. The lambda block could have been placed here. But making it a script means you can trigger execution elsewhere. Plus you can guarantee no parallel execution.)

script:
  - id: update_nixie
    mode: single
    then:
      - lambda: |-
          float t = id(temp1);
          // a bunch of C++ that converts t into whatever Wire wants          
          Wire.beginTransmission(0x21);
          Wire.write(0x78);
          Wire.write(0x42);
          Wire.endTransmission();

▲ This script: block contains one script called update_nixie which is one lambda. A lambda is a block of C++ code. Any line which remain sufficiently indented is treated as C++ rather than YAML. The first line of the lambda calls id(temp1) to access the current sensor value.

1 Like
12

Yes, that in terms of the link I shared was meant to be what I was suggesting is the good way forward vs. straight Arduino IDE. I didn’t really explain myself well.

1 Like
13

I just would like to post an update to my experience thus far. The forum and help has been great - thank you! One of the things I decided to do was try to use one of the examples in the ESPHome Cookbook as a parallel to the work I was doing in Arduino - build a temperature display. So I bought some SSD1306 displays after reading this cookbook tutorial. It hasn’t’ gone so well, unfortunately.

In the Arduino world, I was able to get a MQTT client up and running, along with the WiFi libraries, and along with some Wire code, I was able to get the temperature display to work. I used examples from both the libraries to boot-strap my project.

In the ESPHome world, using this cookbook as the end product - not a small piece - I am still struggling to make it work. The concept seems to be this higher level language environment should be easier to get things going - my experience has been the opposite.

Using the cookbook tutorial as an example, I’ll go over the multiple issues I have run into.

“Getting Time”. Doesn’t work. Once I change the code to use sntp time, it works.

“Define the Fonts”. This section has no instructions on how this is done from a file level. This is my first use of a display in the ESPHome world, and I was left to find them - and the instruction on how to install them - via google. I still don’t have a working Arial font.

I2C display causes “Auth failed” with WiFi. Only after tinkering for several hours was I able to use the “frequency” definition (set to 200kHz now) and got the WiFi to work.

Still can’t get the temperature sensors to display, only time.

Spent a good chunk of yesterday troubleshooting/debugging an “example”.

I can chalk a lot of this up to me learning a new environment, and the promise appears to be great. But when the example code in the cookbook is lacking documentation (fonts), the code doesn’t work (time and i2c display) without major research and tinkering, the promise isn’t there.

Meanwhile, my Arduino display tells me the outside temp just fine.

Frustrated!

1 Like
14

Yes starting with ESPHome can have a steep learning curve. However when you get used to the structure it’s a very nice product (That’s my opinion of course).
Looking at your description, the first question which comes in my mind:
Did you add your device as an integration in HA?
Getting Started with ESPHome and Home Assistant — ESPHome

If it is not added, it has no connection with HA and the HA-time and the sensor information from HA won’t be available. It won’t help you, but I never had any problems with the HA-time.

And yes since the upgrade to the newer version of the Arduino framework, I also had some problems with wifi and ssd1306 displays (also with fastLED) and can imagine your frustration. As soon as you get more familiar with ESPHome you will recognise ‘weird’ behavior and in that cases you will ask earlier help from the community to avoid a lot of wasted time. If you post your yaml and logfiles we can help you to solve your current problems.

1 Like
15

Yes, ESPhome is an add-on with my HA install. I have a few other ESP8266’s running, reporting sensor data (well pump status, water tank level, temperature via 1wire, etc.). Yesterday I moved my HA install off of the Raspberry Pi I was running on to a VM install on my Synology NAS where I could give it 2 CPUs and 4G. Just compiling a ESPHome program on the Pi would kill it. most of the time. No warnings, no errors, just disappears. The HA console would be unresponsive. Sometimes, it would come back if you gave it a few hours (I guess the watchdog processes were still working). But when the keyboard can’t even respond, I call that dead.

I think HA and ESPHome has great potential - I am just sharing my experiences with getting it working so far. When the examples have multiple issues, it’s really hard for a newbie to see how this is “better”. I’ll be sticking to MQTT and Arduino for future sensor work - it just “works”.

16

You have something seriously wrong with your Pi. Possibly a slow or failing micro SD card. I have been using ESPHome for more than a year and I have never once heard of anyone on the forums with this complaint. In my case the ESPHome programs compile on my system faster than I can take a sip of coffee. (Though I am not running on an rPi).

I don’t think that Home Assistant or ESPHome are capable of running on more than one core.

And “4G” ??? Please explain.

Your linked example is literally my first (or second) ESPHome project that I made. Worked right out of the box. In fact, I like ESPHome so much that I am converting my Tasmota devices as often as I can get to them. I have one DIY device that runs Arduino code and I plan to try to replicate it in ESPHome, but that would involve learning to love Lambda code.

17

I’m trying to work out the difference between “update_interval” and “throttle”… Having some definition of all the supported options would be great?

18

Indeed, the bump was in the last esphome update and some limitations are mentioned in the changelog

Actually it will kill your sd card very fast if you have swap enabled. Most likely you running out of ram while compiling…

The docs will help you will that acutally:

throttle

Throttle the incoming values. When this filter gets an incoming value, it checks if the last incoming value is at least specified time period old. If it is not older than the configured value, the value is not passed forward.
Source: Sensor Component — ESPHome

While the update_interval is how often the value is pushed to ha :bulb:

The esphome website also features a search engine (which can be used free of charge!):

:mag: Search — ESPHome :mag_right:

19

One of the most important features why I ditched all my custom sensors made in arduino or platformio as well as all other systems like tasmote, espurna or espeasy in favor of esphome is the management and the painless updates. I’m probably run around 50 esp based devices and the only solution which doesn’t make them painful to manage is esphome.

I can update all esphome nodes with one click. I can easily share wifi configs and other basic (or advanced) stuff with the help of packages.

Getting a new esp up and running with esphome is a couple of minutes were it took me already 3 times more doing this with tasmota because I need to connect, ad wifi password, etc… The same thing with arduino is than just pita. Not thinking about running old and vulnerable arduino cores. Just this days I came across some one posting a arduino sketch and advises people to use the arduino core 2.7.1 because it will not work with something newer, bad because it includes the “WPA2 Authenticationmode downgrade” vulnerability which can be the beginning of the end for some ones private network.

Many people like the “fire and forget” stuff, but it’s actually a very bad idea for connected devices.

It’s not only a question “what’s the easiest way to get started” but actually more “what’s the easiest way to stay up to date” and that’s for sure esphome :rocket:

And mqtt? Seriously? :laughing: That’s a thing of the past for me. I turned my broker off when I migrated my last esp from tasmota to esphome. And what I can say? Best day in my smart home “career”. One can really see that this 20 year old was not designed for high performance networks we have nowadays (but quite for the opposite). When turning of mqtt (and switching to the esphome native api) you will somewhat be lost what to do with your time because there is simply no troubles/debugging/retained messages etc. anymore and things just work :tm:

20

The logs will tell you why it doesn’t work. It’s really easy like that.

If ha is your time source the esphome node needs to be “connected” to ha (not to confuse with the esphome hassio addon which will essentially is only the dashboard).

To use fonts you first have to define a font object in your ESPHome configuration file. Just grab a .ttf file from somewhere on the internet and place it, for example, inside a fonts folder next to your configuration file.

Next, create a font: section in your configuration:

font:
  - file: "fonts/Comic Sans MS.ttf"
    id: my_font
    size: 20

display:
  # ...

Source: Display Component — ESPHome

What exactly is missing in your opinion to get this started?

I see many people have problems navigating the docs or are simply not aware of the search function.

1 Like