← Back to ESP32 Build Finder

Beginner's guide to the ESP32

Everything you need to go from "what is an ESP32?" to a working project: choosing a board, setting up, your first program, the electronics you actually need to know, and five easy first builds with complete step-by-step guides.

What is an ESP32?

An ESP32 is a tiny, low-cost computer chip made by Espressif, built into a small circuit board you can plug into a computer. It runs one program that you write, over and over, and it has Wi-Fi and Bluetooth built in. You connect sensors, lights, motors and displays to its pins, and the program decides what to do with them.

People use it for smart-home devices, weather stations, plant monitors, alarms, LED displays, robots, cameras and anything else that needs a bit of logic and an internet connection. A typical board costs a few dollars.

Arduino UnoESP32Raspberry Pi
What it isSimple microcontrollerMicrocontroller with Wi-Fi and BluetoothFull Linux computer
Wi-Fi / BluetoothNo (add-on needed)Built inBuilt in on most models
Speed16 MHzUp to 240 MHz, often two coresOver 1000 MHz, multiple cores
Pin voltage5V3.3V3.3V
Power useLowLow (deep sleep possible)Much higher
Runs an operating systemNoNo (runs your program directly)Yes
Best forLearning basicsConnected gadgets and sensorsAnything that needs a full computer

The one thing to remember. ESP32 pins run at 3.3 volts. Many cheap parts are 5V. You will learn how to handle that, but never connect a 5V signal straight to an ESP32 pin.

Which board should I get?

There are many ESP32 chips and boards. For learning, get the classic ESP32 development board (often sold as "ESP32 DevKit V1" or "ESP-WROOM-32", with 30 or 38 pins). It has the most tutorials, the most pins, and the widest support, and every guide on this site works with it. You can move to newer chips later.

Not sure? See the ESP32 board comparison for every board in the Build Finder, with a "which should I pick?" table. If you want a screen for a smart-home panel, see the touch panel guide after you finish the basics.

USB ENBOOT ESP32 moduleWi-Fi + Bluetooth USB portEN (reset)BOOT buttonBlue LEDChip + Wi-FiAntennaPins along both edges: power, GND, GPIOPins Generic layout. Positions and pin order differ between makers, so always read the labels printed on your board.
The parts of a typical ESP32 development board. The USB port is how you power it and load programs. Power pins (3V3, 5V, GND) and signal pins (GPIO) run along both long edges.

What to buy

A starter set is cheap. Everything below has a buy link. Required items first, then the optional parts each of the five projects uses, so you can buy them as you go.

Some links are affiliate links, so I may earn a commission at no extra cost to you. As an Amazon Associate I earn from qualifying purchases. Details. Buy buttons open a store search; check the product matches before you order.

Cheap tip: a "starter kit" that bundles a breadboard, wires, LEDs, resistors and buttons is often cheaper than buying each separately. Buy the ESP32 board separately so you choose the right one.

Set up your computer

You will use the Arduino IDE, a free program for writing code and sending it to the board. (Despite the name, it works with ESP32 boards too.)

  1. Install the Arduino IDE 2. Download it free from arduino.cc/en/software and run the installer. Accept the defaults.
  2. Add ESP32 support. The IDE does not know about ESP32 boards until you add them.
    1. Open File, Preferences (on Mac, Arduino IDE, Settings).
    2. Find Additional boards manager URLs and paste this address, then click OK:
    3. Open Tools, Board, Boards Manager (or click the board icon on the left). Search for esp32 and click Install on the one by Espressif Systems. It is a large download, so give it a few minutes.
  3. Connect the board. Plug it into your computer with the USB data cable. A light on the board usually comes on. If your computer does not show a new port (on Windows, check Device Manager, Ports (COM & LPT)), install the USB driver for the chip on your board, usually CH340 or CP210x. Search for those names plus "driver". On Linux, add yourself to the dialout group.
  4. Choose your board and port. In Tools, Board, esp32 select ESP32 Dev Module. In Tools, Port select the new port (for example COM3, or /dev/ttyUSB0).
  5. Keep the defaults for everything else under the Tools menu. You are ready.

If any step differs on your computer (menus change slightly between versions), the official Espressif installation guide has the current instructions.

Blink is the "Hello, world" of electronics: flash a light on and off. It proves your whole set-up works, and every project after this builds on the same idea.

Wire an LED

Board unplugged from USB. An LED must always have a resistor in series (220 ohms is fine) or it can burn out. The LED also has a direction: the longer leg is positive.

Blink wiring. The resistor can go on either side of the LED. If your board has a built-in LED you can skip the wiring and use GPIO 2 in the code instead.

The code

  1. In the Arduino IDE choose File, New Sketch, delete what is there and paste this:
  2. Click the Upload arrow (the right-pointing arrow at the top left). The IDE compiles, then sends the program to the board. If it says "Connecting..." and stalls, hold the BOOT button on the board until it starts uploading.
  3. The LED should blink once a second. Open Tools, Serial Monitor, set the speed to 115200 baud in the corner, and you will see "LED on" and "LED off" messages.

Congratulations if it blinked! You have set up everything you need. If it did not, see Troubleshooting below before going further.

Electronics basics you actually need

Voltage, current and ground

Safe 3.3V sensor signal→ ESP32 pin3.3V parts, I2C sensors, most modules Not safe on its own 5V signal → ESP32 pincan damage the pin or the chipuse a voltage divider or level shifter
Powering a part from 5V is fine. Putting a 5V signal into an ESP32 pin is not.

The breadboard

A solderless breadboard lets you build circuits by pushing wires and components into holes. Inside, the holes in each short column are connected together, so two things plugged into the same column are connected. The long rows along the edges (the rails) are usually used for power and ground.

center gap: the two halves are NOT connected these 5 holes are connected +– power railground rail
Holes in each highlighted group of five are connected. Chips and modules go across the center gap so each leg gets its own group.

Digital, analog and PWM

KindWhat it isExample
Digital in/outJust two states: HIGH (3.3V) or LOW (0V).Button, PIR sensor, LED on/off, relay
Analog inputMeasures a voltage and returns 0 to 4095.Soil sensor, light sensor, dial
PWM outputSwitches on and off very fast to fake an in-between level.Dimming an LED, servo position
I2CTwo wires (SDA, SCL) shared by many chips, each with an address.BME280, OLED displays
UART (serial)Two wires (TX, RX) to talk to one device.GPS, some radar and fingerprint sensors
SPIFour wires, fast. Used for big displays and SD cards.TFT displays, microSD

Which pins can I use?

An ESP32 has many pins, but not all are equal. This is the short, safe version for a classic ESP32 DevKit (pin names are the numbers after "GPIO"):

PinsUse
4, 13, 14, 16, 17, 18, 19, 21, 22, 23, 25, 26, 27, 32, 33Good all-round choices for buttons, LEDs, relays and sensors.
32, 33, 34, 35, 36, 39Analog inputs that keep working with Wi-Fi on (ADC1). Pins 34, 35, 36 and 39 are input only.
21 and 22The default I2C pins (SDA and SCL) for sensors and displays.
0, 2, 12, 15"Strapping" pins that affect how the board starts. Avoid them, or connect only light loads, until you know what you are doing.
6 to 11Connected to the board's flash memory. Never use these.
1 and 3Used for the USB serial connection. Avoid.
3V3, 5V (VIN), GNDPower pins. 3V3 powers 3.3V parts; 5V (VIN) comes from USB; GND is ground.

Analog trap. On the classic ESP32, analog pins in the "ADC2" group (GPIO 0, 2, 4, 12 to 15, 25 to 27) stop working while Wi-Fi is on. For analog sensors in a Wi-Fi project, use GPIO 32 to 39.

Programming basics (the 5-minute version)

An Arduino program is called a sketch, and it always has two parts:

You writeIt means
pinMode(4, OUTPUT);Pin 4 will send signals out. (INPUT to read; INPUT_PULLUP for a button.)
digitalWrite(4, HIGH);Switch pin 4 on (3.3V). LOW is off.
int v = digitalRead(27);Read pin 27: 1 (HIGH) or 0 (LOW).
int a = analogRead(34);Read an analog value from 0 to 4095.
delay(500);Pause for 500 milliseconds. The board does nothing else meanwhile.
Serial.println("Hi");Print a line to the Serial Monitor. Your best debugging tool.
if (x > 10) { ... }Only do this when the condition is true.
const int LED_PIN = 4;Give a name to a number so the code is readable and easy to change.

delay() vs millis(). delay() is simple but freezes the program. millis() returns the time since power-on, so you can check "has 5 seconds passed?" while doing other things. The motion alarm guide shows how.

When code will not compile, read the first red error line. Common causes: a missing semicolon ;, a missing closing brace }, a library you have not installed, or the wrong board selected.

Wi-Fi in one minute

Troubleshooting the usual problems

ProblemWhat to try
No port in the Tools menuTry another USB cable (it must carry data) and port. Install the CH340 or CP210x driver. Unplug and replug.
"Failed to connect to ESP32" or "Wrong boot mode detected"Hold the BOOT button from the moment the upload says "Connecting..." until it starts writing. Release it after.
Upload works but nothing happensPress the EN (reset) button. Check the Serial Monitor is set to 115200 baud.
Garbled text in the Serial MonitorThe baud rate is wrong. Set it to 115200 to match Serial.begin(115200).
"Brownout detector was triggered" or random restartsThe board is not getting enough power. Use a different USB cable or port, and keep wires from motors and relays short.
"fatal error: WiFi.h: No such file"The wrong board is selected. Choose ESP32 Dev Module under Tools, Board, esp32.
"Port busy" or "Access denied"Another program (such as an open Serial Monitor in another window) is using the port. Close it.
A circuit does not workRe-check every wire against the diagram. Confirm GND is connected. Check power with a multimeter. Read the part's labels: pin order varies.

Staying safe

Your five first projects

Each one introduces one new idea and has a complete guide with a parts list (with buy links), a wiring diagram, full code and troubleshooting. Do them in order.

1 Alarmdigital in / outmillis() 2 RelayWi-Fiweb server 3 WeatherI2C sensorlibraries 4 ClockOLED displayinternet time 5 Plantanalog + calibrationputting it together
Each project adds one new skill to the last.
Project 1 · about 45 min

Motion alarm

A PIR sensor triggers a buzzer when someone moves.

  • Digital input and output
  • Timing with millis()
  • Parts: PIR sensor, buzzer
Start the guide →
Project 2 · about 1 hour

Wi-Fi relay switch

Turn a low-voltage device on and off from a web page on your phone.

  • Wi-Fi and a web server
  • What a relay is
  • Parts: relay module
Start the guide →
Project 3 · about 1 hour

Wi-Fi weather station

Show temperature, humidity and pressure on a web page.

  • I2C sensors
  • Installing libraries
  • Parts: BME280 sensor
Start the guide →
Project 4 · about 1 hour

Wi-Fi clock on an OLED

A desk clock that sets itself from the internet.

  • Drawing on a display
  • Network time and time zones
  • Parts: OLED display
Start the guide →
Project 5 · about 1 hour

Plant moisture monitor

Know when your plant needs water, on a web page, with an LED alert.

  • Analog readings
  • Calibration
  • Parts: soil moisture sensor
Start the guide →

Where to go next

Glossary

GPIO
General-purpose input/output: a pin you can control from your program.
ADC
Analog-to-digital converter: turns a voltage into a number. ESP32 has two (ADC1 and ADC2).
I2C
A two-wire bus (SDA and SCL) that connects many chips, each with its own address.
UART / Serial
Two-wire (TX and RX) text-style connection, used for the Serial Monitor and some sensors.
PWM
Pulse-width modulation: switching a pin on and off fast to fake an analog level.
Baud
The speed of a serial connection. Both ends must use the same number (115200 here).
Sketch
An Arduino program.
Library
Ready-made code someone else wrote for a part, which you add to your sketch.
NTP
Network Time Protocol: how devices get the exact time from the internet.
Breadboard
A reusable board for building circuits without soldering.
Pull-up
A resistor (or built-in setting) that holds a pin HIGH until a button pulls it LOW. INPUT_PULLUP turns it on.

This guide is written from standard Arduino and ESP32 practice and the official Espressif and Arduino documentation. Menus and screens change slightly between software versions. Not affiliated with Espressif, Arduino or any store.

← Back to the build finder