The smallest real config
Save this as hello.yaml (pick the board line matching yours):
esphome:
name: hello-latent
esp32:
board: esp32-s3-devkitc-1
framework:
type: esp-idf
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
logger:
level: INFO
Create secrets.yaml beside it, then:
esphome run hello.yaml
What happens now
- Compile — the first build downloads the toolchain and takes minutes. Later builds are fast.
- Port pick — ESPHome lists serial ports; pick
/dev/cu.usbmodem…(macOS) orCOMx(Windows). - Flash — progress bars, a reboot…
- Logs — you should see WiFi connecting and an IP address. That IP is your proof of life.
When it does not work
- No port listed → wrong cable (data vs charge), or hold the BOOT button while plugging in, then retry.
- Port busy → something else holds it open (a serial monitor, a background relay/daemon). Close it and retry — on shared lab machines this is the most common flash killer.
- "Auth Expired" WiFi loops on a phone hotspot → add
fast_connect: trueunderwifi:and set the hotspot to WPA2-Personal. ESP32s only join 2.4 GHz networks, never 5 GHz-only. - Boot loops after flashing → power. Use a real 5V adapter or a powered hub, not a low-power laptop port.
You are now dangerous
Every solution in the catalog is this same loop with a richer YAML: download config → set secrets → esphome run. That is the entire skill.