Yes, this topic is old and answered, but it took me a long time to find and gather all this info together, and this looks like a good place to post it. Hopefully it will save others some time.
Using ESP-01s with Home Assistant with ESPhome
Serial
When flashing an ESP for the first time, you need to figure out a way to talk serial from your computer to the ESP. After flashing with an OTA-capable firmware, you don’t need to use the serial programmer anymore – update wirelessly.
USB-serial bridge board
The easy way
Buy this specialty ESP-01S Programmer from Amazon or AliExpress
- No wiring necessary. Just plug in the ESP01 directly to the serial board.
- No driver necessary. The USB->UART on this board is a CH340G chip, and its serial driver is included by Apple since OSX 10.14.
- No GPIO0 disconnection necessary. The board has a built-in switch to go from flash mode (PROG) to serial only (UART).
When flashing with ESPHome (see below): Install the image, unplug the serial board, flip the switch to UART, and plug it back in for power.
The DIY way
Wire it up yourself using a different USB-serial bridge board.
Before finding the above board, I used a FT232RL-based usb-serial FTDI board from AliExpress. Connect the board to USB, the red led should light. USB-C is weird, I had to use two adapters to go from USB-C to A, then A back to C to convince USB-C to power on my board.
Connect the ESP to the serial device
Wiring:
Set 3.3V (not 5v) with on-board jumper on the FTDI board (between the pins and the chip). Jumper should be between middle pin and the one labelled 3.3v.
Make sure you can disconnect GPIO0; you will need to do this to take the board out of programming mode.
Install USB serial driver
Regardless of which board you’re using, you need make sure your computer can now speak serial over the USB port - meaning you need a driver for your USB-to-serial board.
(Note I’m using Mac OSX, other OS’s may/may not need to install new drivers.)
For the FT232RL board, download the latest driver from FTDI. For a CP210x usb-serial board, get the drivers from SILabs. The drivers for the CH340G (“the easy way” above) are already included in OSX.
Flash with ESPHome from Home Assistant
Install the ESPHome Add-On to your Home Assistant instance.
Home Assistant → Settings → Add Ons → ESPHome → WebUI → New Device → Continue
This gets you to Create Configuration, give it a name.
Select esp8266 device
How do you want to install: plug into this computer
“Download project” after it’s finished preparing (will take a few minutes) to get the newly-compiled firmware onto your laptop.
Open ESPHome Web, Connect. If you have properly installed your driver above, you will see an option in the list for usbserial.
or
Make sure the switch is in Prog mode, see above. Installation will try and fail if it isn’t.
Don’t use “Prepare for first use”, instead Install Downloaded Project, selecting the firmware file you just downloaded. If you use “Prepare for first use”, the install succeeds, but then the next thing that happens is “An error occurred. Improv Wi-Fi Serial not detected.”
You’ll see the TX/RX LEDs on your serial board flash (if it has them).
Unplug the serial board from USB. Take the board out of flashing mode (just flip the switch if you’re using the ESP-01S programmer, or disconnect the GPIO0 pin if not.)
Plug the serial board back in to power the ESP01.
Close that install window, going back to ESPHome in Home Assistant, hopefully you’ll see your new project on the dashboard, with “online” now in the upper right corner of the tile. Go to “logs” to see what’s up, got an IP, connected to you wifi and all.
Future code updates will all be done wirelessly, no need to go through any of the above steps again!
Code up your project and install from the ESPHome web gui
Edit the new device’s config to something useful.
Here’s a starter device yaml for an ESP01-S that generates the sensors shown picture below.
substitutions:
name: esp02
friendly_name: "ESP02"
esphome:
name: "${name}"
friendly_name: "${friendly_name}"
esp8266:
board: esp01_1m
restore_from_flash: false
# Enable logging
logger:
# Enable Home Assistant API
api:
encryption:
key: "...ESPHome will generate..."
ota:
password: "...ESPHome will generate..."
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
# Enable fallback hotspot (captive portal) in case wifi connection fails
ap:
ssid: "Esp02 Fallback Hotspot"
password: "...ESPHome will generate..."
captive_portal:
# Minimal flash writes, once per day
preferences:
flash_write_interval: 1440min
# Sync time with Home Assistant
time:
- platform: homeassistant
id: homeassistant_time
switch:
# Switch to restart the ESP
- platform: restart
name: ${friendly_name} Restart
# Blink LED for status, and also expose to HA as switch
light:
- platform: status_led
name: "${friendly_name} status light"
id: blueled
pin:
number: GPIO2
inverted: yes
restore_mode: RESTORE_DEFAULT_OFF
script:
- id: heartbeat
mode: single
then:
- light.toggle: blueled
- delay: 20 ms
- light.toggle: blueled
# Heartbeat while connected to HA
interval:
- interval: 5s
then:
if:
condition:
api.connected:
then:
- script.execute: heartbeat
text_sensor:
# Expose WiFi information as sensors
- platform: wifi_info
ip_address:
name: ${friendly_name} IP
mac_address:
name: ${friendly_name} Mac Address
binary_sensor:
- platform: gpio
# Use your pins for something fun!
pin:
number: GPIO3
inverted: true
# HW: pull to ground with 10k, tie high through pump NC switch
id: pump_alarm
name: Drain Pump Alarm
device_class: problem
- platform: status
# Status platform provides a connectivity sensor
name: "${friendly_name} - Status"
device_class: connectivity
sensor:
# Report wifi signal strength every 5 min if changed
- platform: wifi_signal
name: ${friendly_name} WiFi Signal
update_interval: 300s
filters:
- delta: 10%
# Pin assignments for ESP-01
# https://randomnerdtutorials.com/esp8266-pinout-reference-gpios/
# 3v3 | | RX/GPIO3 - high at boot
# RST | | GPIO0 - pulled up, flash if low on boot
# EN | | GPIO2 - pulled up, blue led on if pulled down, must be high at boot
# TX | | GND
# ^ TX/GPIO1 - high at boot
Save.
On the “…” Menu, Validate. If all is ok, go ahead and Install, Wirelessly. (Note if you get linking errors (like “not found”) you need to “Clean Build Files” from the ‘…’ menu.)
You will not need the serial board from here on out (assuming you’ve powered your ESP somehow).
Home Assistant
Go to HA Settings → Integrations → ESPHome. The Home Assistant Integration ESPHome, not the ESPHome Add-on this time - we’re adding the new working ESP device to HA for your automations and dashboards. You should see your new board as Discovered, hit Configure.
It will ask if you want to add it to HA, hit Submit, and you should now see it in your devices list, with all its sensors as Entities.
and lead me to expand it too!
