U1/Start here
Getting Started with ESP32
From an empty desk to a blinking LED and your first live sensor reading - each step below links to the exact page you need next.
Already know your board? Open its page for tailored setup →$ esptool.py write_flash 0x0 blink.bin Connecting.... Chip is ESP32-D0WD-V3 (revision v3.1) Writing at 0x00008000... (23 %) Writing at 0x00018000... (61 %) Writing at 0x00028000... (100 %)
Your first flash - about two minutes, start to blink
Step 1: Get an ESP32 board
any devkit works
No board yet?
An ESP32-S3 DevKit is the best first board
An ESP32-S3 DevKit - Espressif's DevKitC-1 (~$15) or the YD-ESP32-S3 clone (~$10) - breaks out every pin and adds native USB: no driver to install, and usually no holding BOOT to flash. Already following a tutorial written for the classic ESP32 DevKit (~$5)? That board is still fine - only the pin numbers differ. Tight on space or budget? A XIAO, or a Super Mini from ~$3.
Already have one?
Open your board's page - setup is tailored there
Every board page has its own Getting started section: the exact Arduino Tools-menu rows, the PlatformIO and ESPHome board IDs, the flash command, and which USB driver it needs - for that specific board.
Our picks for a first board. All with full setup pages. Start with an S3 devkit, go tiny with a XIAO or a Super Mini (no-brand, so quality varies by batch), or get a screen from day one with the CYD.
Step 2: Pick how you'll program it
you can switch any time
Arduino IDE
C+++ Easiest start. Biggest community, most tutorials - every code example on this site works with it. - Hides the chip's native APIs; large projects eventually outgrow the IDE itself.
Setup guide →
ESPHome
YAML+ No code at all. Describe the device in YAML; first-class Home Assistant integration. - Built for smart-home devices - custom logic beyond what YAML offers gets awkward.
Setup guide →
MicroPython
Python+ Fastest to experiment. Live REPL, no compile step - great if you already know Python. - Slower and more RAM-hungry than compiled C++; timing-critical work suffers.
Setup guide →
PlatformIO
C+++ Arduino code, proper tooling. VSCode, real dependency management, per-project configs. - More setup than the Arduino IDE - not worth it for your very first sketch.
Setup guide →
ESP-IDF
C+ Espressif's native SDK. Every chip feature, full control - what serious products ship on. - Steepest learning curve of the five; overkill for a first blink. Come back to it.
Setup guide →Also worth knowing: esptool. Not a framework - it is the low-level flasher every tool above uses under the hood. You will meet it whenever you flash prebuilt .bin firmware from the terminal. esptool basics →
Step 3: Flash your first blink
the hardware hello-world
1
Connect over USB
Use a data cable, not a charge-only one. If no port shows up, your board likely needs a CH340 or CP210x driver - its board page says which. Still nothing? Hold BOOT while plugging in.
2
Copy the code & upload
Select your board and port in the IDE, paste the code from the tab, hit Upload. If the log stalls at "Connecting...", hold BOOT until it moves.
3
Watch it blink
The onboard LED sits on GPIO2 on most classic devkits - your board's page lists the exact pin if yours differs. The ESP32-S3 DevKits have an addressable RGB LED instead, so on those wire an LED and resistor to the pin.
// Blink the onboard LED (GPIO2 on most devkits)
#define LED_PIN 2
void setup() {
pinMode(LED_PIN, OUTPUT);
}
void loop() {
digitalWrite(LED_PIN, HIGH);
delay(500);
digitalWrite(LED_PIN, LOW);
delay(500);
}Board: "ESP32 Dev Module" · your exact board's Tools rows are on its board page.
esphome:
name: my-esp32
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
output:
- platform: gpio
pin: GPIO2
id: onboard_led
interval:
- interval: 1s
then:
- output.turn_on: onboard_led
- delay: 500ms
- output.turn_off: onboard_ledRun with esphome run blink.yaml - add your wifi/api blocks when you connect it to Home Assistant.
# Blink the onboard LED (GPIO2 on most devkits)
from machine import Pin
from time import sleep
led = Pin(2, Pin.OUT)
while True:
led.value(1)
sleep(0.5)
led.value(0)
sleep(0.5)Flash the MicroPython firmware first, then run this from Thonny or the REPL.
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200#include <Arduino.h>
#define LED_PIN 2
void setup() {
pinMode(LED_PIN, OUTPUT);
}
void loop() {
digitalWrite(LED_PIN, HIGH);
delay(500);
digitalWrite(LED_PIN, LOW);
delay(500);
}Run with pio run -t upload - same Arduino code, just with
#include <Arduino.h> on top.#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/gpio.h"
#define LED_PIN GPIO_NUM_2
void app_main(void)
{
gpio_reset_pin(LED_PIN);
gpio_set_direction(LED_PIN, GPIO_MODE_OUTPUT);
while (1) {
gpio_set_level(LED_PIN, 1);
vTaskDelay(pdMS_TO_TICKS(500));
gpio_set_level(LED_PIN, 0);
vTaskDelay(pdMS_TO_TICKS(500));
}
}Build and flash with idf.py flash monitor (ESP-IDF v5.x).
Step 4: Wire your first sensor
All 126 sensors →Recommendations, not a random sample. Cheap, well-documented and satisfying on day one - every card links to wiring, pinout and working code for all five frameworks.
Default pins I2C: SDA GPIO21 · SCL GPIO22 UART2: TX GPIO17 · RX GPIO16 Analog: ADC1 pins GPIO32-39 Logic level: 3.3V - never feed 5V into a GPIO
Step 5: When something goes wrong
Full troubleshooting library →Upload timeout
"Connecting..." never ends - the BOOT button dance
Port not detected
No COM port / tty device - drivers and cables
Brownout resets
Board reboots under load - it's the power supply
Wi-Fi won't connect
2.4 GHz only, and other classic gotchas
Flash read error
failed to connect / invalid head of packet
Manual boot mode
Forcing the chip into download mode by hand
Common questions
Which ESP32 board should a beginner buy?▾
An ESP32-S3 devkit - Espressif's ESP32-S3-DevKitC-1 (~$15) or the cheaper YD-ESP32-S3 clone (~$10). Native USB means no driver and usually no holding BOOT to flash, and every pin is broken out. Many older tutorials assume the classic ESP32 DevKit (~$5), which still works fine if you are following one. For something tiny, a XIAO ESP32S3 or a ~$3-5 Super Mini.
Do I need to install a USB driver?▾
Depends on the board. Boards with a CH340 or CP210x USB-serial bridge need that driver installed (mostly an issue on Windows and older macOS). Boards with native USB - most S2, S3 and C3 boards - usually show up as a port with no driver at all. If no port appears when you plug in, the driver is the first thing to check; each board page on this site says which chip it uses.
Why does my upload fail with "Connecting..."?▾
The chip isn't in download mode. Hold the BOOT button (sometimes labeled IO0) while the IDE prints "Connecting...", then release it once the upload starts. Also make sure your USB cable carries data - charge-only cables are the most common cause of a board that powers on but never shows a port.
Can the ESP32 run Python?▾
Yes - MicroPython runs on all ESP32 variants. You flash the MicroPython firmware once, then write Python over the live REPL or with an editor like Thonny. It is the fastest way to experiment, at some cost in performance compared to compiled C++.
Is the ESP32 5V tolerant?▾
No. All GPIO pins are 3.3V - feeding 5V into a pin can damage the chip. Powering the board through its USB port or VIN pin with 5V is fine (an onboard regulator steps it down), but 5V sensor signals need a level shifter or a voltage divider before they touch a GPIO.
Should I start with Arduino or ESP-IDF?▾
Start with Arduino - the community, libraries and tutorials make every beginner problem already-solved. ESP-IDF is Espressif's official C framework and worth learning when you need full chip control or production features, but it is a much steeper first step. PlatformIO sits in between: Arduino code with professional tooling.