Home Assistant + DIY Microcontroller + ESP Home (Docker)
With ESPHome it is very easy to program your own microcontroller for use in HomeAssistant. My first use for a self-programmed microcontroller was to record the water flow and temperature values of my heater, see: www.script-example.com/topic/arduino. Although I was able to program the microcontroller relatively quickly, not least thanks to numerous examples in Arduino, the implementation with ESPHome is even easier. The program code with similar functionality in ESPHome has, compared to my Arduino version, about half the lines and is also much more understandable and stable than my Arduino version. One reason I reprogrammed my working microcontroller with ESPHome was that I had to restart the ESP every so often to get it to reconnect to the MQTT broker.
For changes to the program code or for debugging, I had to use Arduino to either plug in a laptop in the boiler room or, for cruder changes, remove the microcontroller and program it in a more comfortable place: Then more or less blindly without sensors, since they are installed in the boiler room. Reason enough to test ESPHome.
What is ESPHome?
ESPHome is a slim web interface with which microcontrollers like the ESP8266 or ESP32 can be programmed and easily integrated into Home Assistant. Unlike Arduino, ESPHome is not primarily programmed in C, but in YAML files. ESPHome converts the YAML code into C, compiles it and runs the finished program on the microcontroller. The finished example program takes care of the WLAN connection and the possibility to update itself. It also provides the basis for communication with Home Assistant.
OTA update
ESPHome can be used to program the devices via WLAN and display the console output: OTA update, i.e. over-the-air update. If the ESP has been programmed with the base code, the device can be installed and wired at its place of use and later supplied with the necessary software via WLAN from any browser.
ESPHome in Docker and https
I started Home Assistant in Docker, therefore the AddOn Store is not available. ESPHome can be started via an additional Docker container.
Docker Basics
Docker allows applications to be launched by command in a so-called container.A container is an isolated environment independent of the operating system (OS):
When a container is first launched, Docker independently loads all the necessary sources
from the internet.
Docker can be installed on Windows, macOS or an Linux Distribution
docker-compose.yml
To start ESPHome using docker compose, the official Docker ESPHome image can be used .The image can be downloaded, created and launched with a simple docker-compose.yml file. The file can be filled with any text editor as follows and then customized:
Filename: docker-compose.yml, Content:
version: "3"
services:
esphome:
container_name: esphome
image: esphome/esphome
privileged: true
environment:
- USERNAME=admin
- PASSWORD=???
- ESPHOME_DASHBOARD_USE_PING=true
#Für einen direkten Zugriff, ohne Internet. Aufruf: http://localhost:6052 oder http://ServerIP:6052
ports:
- 6052:6052
dns:
- 192.168.1.1
volumes:
- ./esphome:/config:rw
#Labels für ReverseProxy, siehe: https://www.libe.net/traefik
labels:
- "traefik.enable=true"
- "traefik.http.routers.esphome.rule=Host(`esphome.domain.tld`)"
- "traefik.http.routers.esphome.entrypoints=web"
- "traefik.http.routers.esphome.entrypoints=websecure"
- "traefik.http.routers.esphome.tls.certresolver=myresolver"
- "traefik.http.services.esphome.loadbalancer.server.port=6052"
restart: always
#Ohne dem Einsatz eines Reverse Proxy (https://www.libe.net/traefik) fehlt voraussichtlich das Netzwerk webproxy
#und die folgenden Zeilen können entfernt oder auskommentiert werden. Alternativ kann das Netzwerk mit "docker network create webproxy" erstellt werden
networks:
default:
external:
name: webproxy
For direct access via IP address or localhost - even without reverse proxy, DNS or public IP - the configuration includes "ports: - 6052:6052", which allows the call to be made via localhost:6052 as well. For use without a reverse proxy, the network: ... section can be removed.
For Internet access to work via the Traefik reverse proxy, the domain must be replaced in the labels with the previously created DNS records (in the example: esphome.domain.tld) .The example uses Docker bind mounts and no volumes for permanent data storage. See: Docker Data Storage: Docker Volumes vs Host Folders. For a working name resolution from ESPHome to the microcontrollers, I also added my router as a DNS server, see: offline.
Start container
The startup is done from the folder of the docker-compose.yml file with the command "docker-compose up":
docker-compose up -d
Startup / first call of the web interface
When calling the specified domain (https://wp.domain.tld) ESPHome logs in with a login mask. The username and password can be specified and changed in the docker-compose.yml file.
By clicking on "NEW DEVICE" new microcontrollers can be created:
The connection to the microcontroller must be done initially via a cable. In my case I have connected the microcontroller to a computer with USB, which allows me to connect via the browser using the UART Bridge Controller (Plug into this computer). Since the connection to the microcontroller is done via the browser, it does not matter if the ESPHome server is running on another device:
HA integration
In order for the microcontrollers to show up as devices in Home Assistant, we need ESPHome integration:
For the connection, I first used the IP address of my first microcontroller:
Back to ESPHome, an API key (Encryption key) can be read in it:
The Encryption key is needed for the connection in Home Assistant:
Here is a look at my included microcontroller and its provided sensors:
ESP-Home as menu item in the Home Assistant sidebar
In order for ESPHome to integrate into the Home Assistant gui, the web service can be created as a panel_iframe in the configuration.yaml file:
The following lines at the beginning of configuration.yaml add ESPHome as a new menu item:
panel_iframe:
esphome:
title: "ESPHome"
url: "https://esphome.domain.tld/"
icon: mdi:docker
The "url:" must of course be replaced here with the previously configured URL.
Troubleshooting
My first attempt ended with the following error: "Please upgrade to the PlatformIO Core 6".
I already tested ESPHome some time ago, starting a Docker container. When I tried to use ESPHome again, I could not program the ESP32 for the time being, because the container was obviously too old: A "docker-compose pull" could fix the problem by downloading a new version of ESPHome.
Configuration created but unable to detect the device on the network
Originally I wanted to connect the ESP to a hidden WLAN, but this did not work. The solution was to use a visible WLAN for the connection.
Offline
Although the controller was working fine, it was still showing as "OFFLINE":
The ESPHome Docker container is apparently trying to call the controller with the name heating.local. To make it able to do that, I put the DNS name of the ESP32 on the router and added the IP address of my router in the docker-compose.yml file (dns:...).
Conclusion
With ESPHome an inexpensive DIY hardware can be used for your own projects. The numerous examples on the ESPHome page facilitate programming and integration in Home Assistant. For the connection of an ultrasonicflow meter I have put an example on the following page: ESP32 Flowmeter - RS485 Modbus. How to read DS18B20 temperature sensors can be found on this page: DS18B20 - Temperature Sensors in ESP-Home.

{{percentage}} % positive

THANK YOU for your review!
Top articles in this section
To synchronize contacts, appointments, and photos of my NAS, I tested Nextcloud and thus turned my back on other cloud providers for my private data. Thanks to Docker, the installation is easier and more flexible than ever, allowing Nextcloud to run on almost any hardware.
The well-known Signal Messenger can besides the app also be used via command line or from other systems. The signal-cli-rest-api, which is available in the form of a Docker container, offers a simple option for this. For the API to work, it has to be coupled via the Signal app beforehand.
Bitwarden is a web-based password manager, similar to LastPass, but open source and the ability to run (host) it yourself. How Bitwarden compares to other password managers, I have considered on the following page: Password Managers Secure? KeePass vs LastPass vs Bitwarden. Bitwarden consists of several services, which can be provided via different containers. The relatively complex setup has been simplified with "Bitwarden Unified" especially for self-hosting by packing all services into one co...