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.
More complicated
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
Download the latest driver from here (I’m using Mac OSX).
Alternatively, you can use a CP210x usb-serial board, get the drivers from SILabs.
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.
Flash with ESPHome
Install the ESPHome Add-On to your Home Assistant instance.
Home Assistant → Settings → Add Ons → ESPHome → WebUI → New Device → Continue
Select esp8266 device
How do you want to install: plug into this computer
Download the project image 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
Don’t use “Prepare for first use”, instead Install Downloaded Project, selecting the firmware file you just downloaded. You’ll see the TX/RX LEDs on your serial board flash (if it has them).
Unplug the serial board from USB. Disconnect the GPIO0 pin to take the board out of flashing mode (just flip the switch if you’re using the ESP-01S programmer).
Plug the serial board back in to power the ESP01.
Go back to ESPHome in Home Assistant, hopefully your new board is “online” now. Go to “logs” to see what’s up.
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: 2
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:
# Connectivity sensor
- platform: status
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
# GPIO0,2,6-11,15 internal flash interface, boot mode detection
# GPIO1,3 - TX,RX
# GPIO4,5 - GPIO
# GPIO12-14 - SPI controller
# GPIO16 Deep-Sleep wakeup pin, can be accessed from RTC
# GPIO17 (TOUT) ADC (0-1v)
# Analog pin
- platform: adc
pin: GPIO17
name: ${friendly_name} ADC
id: "${name}_adc"
# capture transient voltage spike over 0.5v
on_value_range:
- above: 0.5
then:
# Send a "button pressed" event to HA
- homeassistant.event:
event: esphome.button_pressed
data:
message: ${friendly_name} ADC high
filters:
# send the max value seen in this window
- max:
window_size: 40
# send to HA once every 40 * 0.05 = 2s
send_every: 40
# and only send if it changed by more than 20%
- delta: 20%
# check treshold every 50ms
update_interval: 0.05s
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.