Chapter 2 · First Upload10 min

First Upload

Build a minimal YAML, flash your ESP32 over USB, and watch it appear on Wi-Fi.

Two flashes. First: get the ESP32 on Wi-Fi. Second: add display + LVGL and see it render. Don't skip the first - a working network connection makes everything after trivial to debug.

Which board are you using?

All YAML and instructions adapt to your pick.

Cheap Yellow Display (CYD)Selected

ILI9341320×240ESP32Touch

ESP32 + 2.8" TFT + touch. No wiring. Under $10.

Search "ESP32-2432S028"

WT32-SC01 Plus

ST7796480×320ESP32-S3Touch

ESP32-S3 + 3.5" capacitive touch. USB-C. ~$20.

Search "WT32-SC01 Plus"

Waveshare ESP32-P4-WIFI6 Touch-LCD-4B

MIPI-DSI720×720ESP32-P4Touch

ESP32-P4 + 4" 720×720 MIPI-DSI + GT911 capacitive touch. WiFi 6 via ESP32-C6 co-processor.

Search "Waveshare ESP32-P4-WIFI6 Touch-LCD-4B"

ESP32 + ILI9341 module

ILI9341320×240ESP32

Separate board + display. Requires 8 wires.

Any ESP32 DevKit + ILI9341 SPI module

ESP32 + ST7789 module

ST7789V240×240ESP32

Separate board + small display. Compact builds.

Any ESP32 DevKit + ST7789 SPI module

Don't have a board yet? See the Buying Guide

No wiring needed! The Cheap Yellow Display (CYD) has the display built in.

Phase 1 of 2

Get the ESP32 online

No display yet - just Wi-Fi + API. By the end your device says ONLINE.

A Create a new device

Click + NEW DEVICE

Green button, bottom-right corner of the ESPHome dashboard.

ESPHome dashboard with + NEW DEVICE button

Choose New Device Setup

The guided wizard. You can also use "Empty Configuration" and paste YAML directly.

Enter name + Wi-Fi credentials

Type device name, Wi-Fi SSID, and password. Click NEXT.

Secrets handled automatically. Wi-Fi credentials saved in secrets.yaml. Edit anytime via SECRETS in the top bar.

Select device type: ESP32

Pick ESP32 for your Cheap Yellow Display (CYD). Leave "Use recommended settings" checked.

Configuration created - click INSTALL

You will see a celebration screen with an encryption key. It is auto-saved. Click INSTALL.

Choose how to flash

Pick "Plug into this computer" or "Plug into the computer running ESPHome Device Builder".

First flash must be USB. "Wirelessly" won't work yet. After this, all future updates go OTA.

Pick the serial port

ESPHome detects your ESP32. Click the USB Serial device listed.

Wait for compile + upload

First time takes about 2 minutes. Watch for the green "INFO Successfully uploaded program." line.

Don't unplug! Wait for "Successfully uploaded program" in green. The ESP32 reboots and connects to Wi-Fi automatically.

Your device is ONLINE

Dashboard shows ONLINE in green.

Don't see a port?

Run ls /dev/ttyUSB* /dev/ttyACM* - usually /dev/ttyUSB0.

You should see

[I][wifi]: WiFi Connected!

[C][wifi]: SSID: 'YOUR_WIFI_SSID'

[C][wifi]: IP: 192.168.1.42

[I][api]: Client connected ✓

🎉Your ESP32 is online! Hardest part done. All future updates go wirelessly (OTA).

Phase 1 of 2