What you will need:

I was recently trying to upload esphome firmware to my ESP-01 Modules. I was using this cheap programmer from aliexpress and nothing was working.

↑ this did not work (for me)

It turns out I needed some extra components to get this to work. Apparently your programmer usually handles all the pin pulling. But mine doesn't for whatever reason.  So these instructions are very general purpose.

Wiring

Pieter's Pages has some amazing resources on this and ESP8266 in general.

Andreas Jacob's Guide also helped me a lot, go check it out!

This was somehow the most difficult part to find out. To enter flash mode, some pins need to be pulled low and some others high on startup. More precisely the GPIO-0 pin needs to be pulled low on chip startup. This can be easily facilitated with a push button.

If your TTL Programmer does not have a capacitor, you should probably add one to your circuit, sudden power surges from Wi-Fi activity might play tricks on you otherwise. Smaller capacitors are probably fine as well.

This is also the wiring you'll need later on to run the ESP-01 on its own!

You could also combine all of this into a cozy board for your ESP-01 to sit in. I would at least recommend making a small break out board for your ESP to fit onto a breadboard, like so:

Installing ESPHome

My python installation is based on anaconda, but you can probably just use whatever python for windows you already have and get esphome with pip or pip3 respectively.

First I made a new anaconda environment for ESPHome

#make new env
conda create --name ESPHome
# activate env
conda activate ESPHome
#get esphome
pip install esphome

When using anaconda, you will have to re-activate the ESPHome environment every time you restart anaconda prompt.

Making a flashable firmware

If you're new to esphome it's not a bad idea to run the wizard!

mkdir ESPHome
cd ESPHome
esphome livingroom.yaml wizard

This will create a file called livingroom.yaml which contains all the information to make the firmware. It will ask you about the node name (how it will appear on the Wi-Fi), if you are using ESP32 or ESP8266 and about your board type. Here you should choose esp01_1m. If you choose esp01 OTA will not work, even if your board has 1 MB of flash.

Great you now have a recipe for a firmware file.

I recommend adding this code snippet to your .yaml to get debug messages:

logger:
  level: debug

Optional: to just build the firmware you could run

esphome livingroom.yaml compile

Flashing the ESP-01

Make sure your ESP-01 is in programming mode. Either hold the prog button (pulling it low) when connecting power to your ESP-01/plugging your programmer into the USB socket. Or hold the prog button and press reset. Release the prog button.

Now all that's left to do is run

esphome livingroom.yaml run


This will also compile any changes you made to your .yaml file.

If the esphome prompts you to use either your COM port or OTA, choose the COM port for now.

After flashing is complete, reset your ESP-01 with the reset button. You will now see the serial debug, if you have debug enabled.

Exiting logging mode

To leave the logs press Ctrl+C. This might take a while, but you can speed it up/force it by either resetting the ESP or unplugging the USB to Serial adapter.

Over the air updates (OTA)

Best case scenario, you connect your ESP to a power source, run esphome livingroom.yaml run and it just works

INFO Successfully compiled program.
INFO Resolving IP address of livingroom.local
INFO Address not available when adding xxx.xxx.xxx.xxx to multicast group, it is expected to happen on some systems
INFO Address not available when adding xxx.xxx.xxx.xxx to multicast group, it is expected to happen on some systems
INFO  -> 192.168.124.57
INFO Uploading livingroom\.pioenvs\livingroom\firmware.bin (370304 bytes)
Uploading: [============================================================] 100% Done...

If you don't have mqtt set up and aren't connected by serial anymore you can't see any logs at this point.

If serial is still connected, esphome will even ask you by which means to flash.

INFO Successfully compiled program.
Found multiple options, please choose one:
  [1] COM5 (USB-SERIAL CH340 (COM5))
  [2] Over The Air (livingroom.local)
(number):

Just choose "2" and everything works like magic! You should also see logs now (logs are delivered by serial).

What if it doesn't: Troubleshooting OTA

The .local address, is just like google.com but for your local network. If I understand correctly the system telling your PC what IP address your ESP actually has is called zeroConf (mDNS) and I've had some problems with that system in the past.

You can also talk to your ESP directly by its IP address. You can find your ESP's IP address either in your router or in the debug logs, after flashing:

[23:45:38][C][wifi:316]:   Subnet: 255.255.255.0
[23:45:38][C][wifi:317]:   Gateway: 192.168.124.1
[23:45:38][C][wifi:318]:   DNS1: 192.168.124.1
[23:45:38][C][wifi:319]:   DNS2: (IP unset)
[23:45:38][D][wifi:466]: Disabling AP...
[23:45:38][C][ota:029]: Over-The-Air Updates:
[23:45:38][C][ota:030]:   Address: 192.168.124.57:8266
[23:45:38][C][ota:032]:   Using Password.
[23:45:38][W][ota:036]: Last Boot was an unhandled reset, will proceed to safe mode in 8 restarts
[23:45:38][I][app:059]: setup() finished successfully!
[23:45:38][I][app:105]: ESPHome version 1.15.3 compiled on Dec  1 2020, 22:59:03

Now that you have the IP address, you can tell esphome to access your ESP by that address, by adding the use_address to the wifi section of your .yaml:

wifi:
  ssid: "MyDeliciousWifi"
  password: "MySuperSecurePassword"
  use_address: 192.168.124.57

Now the dialogue might look like this or it will just run through if serial is not connected.

INFO Successfully compiled program.
Found multiple options, please choose one:
  [1] COM5 (USB-SERIAL CH340 (COM5))
  [2] Over The Air (192.168.124.57)
(number):

This trick also comes in very handy when you want to change the name of your ESP in OTA mode.

Wireless logging with MQTT

If your ESP is not connected to serial, you can upload by OTA, but you can't see what's going on. To solve this you can activate the MQTT component:

mqtt:
# my PCs IP address
  broker: 192.168.124.31
#mqtt broker on my raspberry pi
#  broker: 192.168.124.78

For this you need a MQTT broker. I recommend the mosquitto broker. If you have a broker set up, you will automatically see logs, after OTA updates. If your ESP is still connected to serial you can even choose from where to get your logs.

It has proven to be very useful to have a terminal as a dedicated subscriber to the ESP. The necessary mosquitto command is:

.\mosquitto_sub.exe -t livingroom/#

Exiting logging mode

Same as with logging in serial mode, you can leave the logs by pressing Ctrl+C.  This might take a while, but you can speed it up by resetting the ESP.

MQTT explained

MQTT is like texting but for machines. But to explain MQTT I would like to introduce a post office metaphor. The broker is the post office. In the post office there are lots of post boxes. In MQTT lingo these are called topics. There are publishers and subscribers. A publisher brings messages to a certain postbox and a subscriber gets a copy of every message that goes to a postbox/topic he subscribes to. Topics are organized hierarchically. Our ESP publishes to the topics:
 

livingroom/status
livingroom/debug

If you would for example add a neopixel to your ESP, you might additionally get the topics:

livingroom/light/neopixellight/state
livingroom//light/neopixellight/command

Useful commands for mosquitto

For these commands you need to navigate to where mosquitto is installed: e.g C:\Program Files\mosquitto
It has proven very useful to have a powershell subscribed to your ESPs output

mosquitto client/subscriber: get everything posted in this topic and dependent topics

.\mosquitto_sub.exe -t livingroom/#<br>

mosquitto server verbose

.\mosquitto.exe -v

purge topic:

.\mosquitto_pub.exe -t livingroom/ota -r -n

.\mosquitto_pub.exe -t <topic> -r -n<br>

post: ON

.\mosquitto_pub.exe -t livingroom/ota -m "ON"

Closing remarks

This was all kind of a headache. ESP8266 has been the go-to module for Wifi related projects for quite some time now, but information about it still seem spread out. I hope this guide gives you an idea where to start.

You should also know, that if you want to use deep sleep on your ESP-01 you will need to hack it a bit, as the GPIO-15 pin is not easily accessible. You can read about that hack here on Hackaday.