ESP32 Getting Started: Your First Project in the Arduino IDE

The ESP32 gives you a dual-core 240MHz processor, Wi-Fi, and Bluetooth on a board that costs less than a sandwich. You can program it with the same Arduino IDE you already know. This guide takes you from a blank PC to a working Wi-Fi web server that switches an LED from your phone. It covers driver installs, board selection, pinout traps, and the errors that stop most first uploads.

Quick Takeaways

• Install Arduino IDE 2.x, add the Espressif board URL, and install the esp32 by Espressif Systems package. You need no extra toolchain.
• The ESP32 runs at 3.3V logic. GPIO pins are not 5V tolerant.
• If upload fails with “Wrong boot mode,” hold the BOOT button while the IDE shows “Connecting…”.
• Your first project is a Blink sketch. Your second is a Wi-Fi web server that toggles GPIO2.

What You Need

Step 1: Install Arduino IDE and USB Drivers

Download Arduino IDE 2.x from arduino.cc and install it. Then check which USB-to-serial chip your board uses. Look at the small square IC near the USB port.

Plug in the board. Windows should list a new COM port in Device Manager. Linux shows /dev/ttyUSB0 or /dev/ttyACM0. On Linux, add your user to the serial group so the IDE can open the port:

sudo usermod -a -G dialout $USER   # Debian/Ubuntu; log out and back in afterward

Step 2: Add the ESP32 Board Package

The IDE does not ship with ESP32 support. Add Espressif’s package index.

1. Open File → Preferences.
2. Paste this URL into Additional boards manager URLs:

https://espressif.github.io/arduino-esp32/package_esp32_index.json

3. Click OK.
4. Open Tools → Board → Boards Manager (or press the board icon in the left sidebar).
5. Search for esp32 and install esp32 by Espressif Systems.

The download is several hundred MB because it bundles compilers and tools. Let it finish. This guide targets the 3.x core. If you see older tutorials using ledcSetup(), they target the 2.x core. The 3.x API changed.

Step 3: Select Your Board and Port

Go to Tools → Board → esp32 and pick the entry that matches your hardware.

Then set Tools → Port to the new COM or tty port. Leave Upload Speed at 921600. Drop it to 115200 if uploads fail midway.

Pinout Configuration: Read This Before Wiring

Most first-project failures come from wrong pin choices, not code. Know these rules for the classic ESP32.

Each GPIO supplies at most about 12mA safely. The absolute maximum per pin is 40mA. Always use a 220Ω–330Ω series resistor with an LED.

Project 1: Blink an LED

Wiring

Many DevKit boards have an onboard LED on GPIO2. If yours does not, wire an external one:

• GPIO2 → 220Ω resistor → LED anode (long leg)
• LED cathode (short leg) → GND

Code

// Blink: toggles an LED on GPIO2 every 500 ms
#define LED_PIN 2            // GPIO2: onboard LED on most DevKit boards

void setup() {
  pinMode(LED_PIN, OUTPUT);  // configure GPIO2 as a push-pull output
}

void loop() {
  digitalWrite(LED_PIN, HIGH);  // drive pin to 3.3V, LED on
  delay(500);                   // wait 500 ms
  digitalWrite(LED_PIN, LOW);   // drive pin to 0V, LED off
  delay(500);
}

Upload

1. Click the Verify (checkmark) button to compile. The first build takes a minute or two.
2. Click Upload (right arrow).
3. When the console shows Connecting........, press and hold BOOT if it stalls. Release it once the upload begins.
4. The LED should blink twice per second.

If it works, your toolchain, drivers, and board are all good.

Project 2: Wi-Fi Web Server to Control the LED

Now use the feature that sets the ESP32 apart from an Arduino Uno. This sketch connects to your 2.4GHz network and hosts a page with ON and OFF buttons. The ESP32 does not support 5GHz Wi-Fi.

Circuit

Reuse the Blink wiring: GPIO2 → 220Ω → LED → GND.

Code

// ESP32 Wi-Fi LED controller using the built-in WebServer library
#include <WiFi.h>
#include <WebServer.h>

const char* WIFI_SSID = "YOUR_SSID";      // 2.4 GHz network name
const char* WIFI_PASS = "YOUR_PASSWORD";  // network password

#define LED_PIN 2
WebServer server(80);                     // HTTP server on TCP port 80
bool ledState = false;

// Build the HTML page; the button label reflects the current state
String buildPage() {
  String html = "<!DOCTYPE html><html><head>";
  html += "<meta name='viewport' content='width=device-width, initial-scale=1'>";
  html += "<title>ESP32 LED</title></head><body style='font-family:sans-serif;text-align:center'>";
  html += "<h1>ESP32 LED Control</h1>";
  html += "<p>LED is <b>" + String(ledState ? "ON" : "OFF") + "</b></p>";
  html += ledState ? "<a href='/off'><button>Turn OFF</button></a>"
                   : "<a href='/on'><button>Turn ON</button></a>";
  html += "</body></html>";
  return html;
}

void handleRoot() { server.send(200, "text/html", buildPage()); }

void handleOn() {
  ledState = true;
  digitalWrite(LED_PIN, HIGH);
  server.sendHeader("Location", "/");     // redirect back to the main page
  server.send(303);
}

void handleOff() {
  ledState = false;
  digitalWrite(LED_PIN, LOW);
  server.sendHeader("Location", "/");
  server.send(303);
}

void setup() {
  Serial.begin(115200);                   // UART0 at 115200 baud for debug output
  pinMode(LED_PIN, OUTPUT);
  digitalWrite(LED_PIN, LOW);

  WiFi.mode(WIFI_STA);                    // station mode: join an existing network
  WiFi.begin(WIFI_SSID, WIFI_PASS);
  Serial.print("Connecting to Wi-Fi");
  while (WiFi.status() != WL_CONNECTED) { // wait for the DHCP lease
    delay(500);
    Serial.print(".");
  }
  Serial.println();
  Serial.print("IP address: ");
  Serial.println(WiFi.localIP());         // open this address in your browser

  server.on("/", handleRoot);             // register URL handlers
  server.on("/on", handleOn);
  server.on("/off", handleOff);
  server.begin();
}

void loop() {
  server.handleClient();                  // process incoming HTTP requests
}

Run It

1. Replace YOUR_SSID and YOUR_PASSWORD with your network credentials.
2. Upload the sketch.
3. Open Tools → Serial Monitor and set the baud rate to 115200.
4. Press the EN (reset) button on the board.
5. Wait for the printed IP address, such as 192.168.1.57.
6. Enter that address in a browser on the same network. Tap the button and watch the LED respond.

How the Code Works

• WiFi.mode(WIFI_STA) makes the chip a client. Use WIFI_AP if you want the board to create its own network.
• server.on() maps a URL path to a handler function. This is lightweight routing.
• The 303 redirect stops the browser from re-sending /on when you refresh the page.
• server.handleClient() must run often. Avoid long delay() calls in loop(), or the page will feel unresponsive.

ESP32 vs. ESP8266 vs. Arduino Uno

Common Upload and Boot Errors

Practical Next Steps

Once Blink and the web server run, pick a small build that adds one new skill each time.

Follow these habits from the start:

• Keep Wi-Fi credentials in a separate secrets.h file and exclude it from version control.
• Use the ADC1 pins for analog reads whenever Wi-Fi is on.
• Add a level shifter between the ESP32 and any 5V sensor output.
• Print debug messages with Serial.println() early. They save hours later.

FAQ

Is the ESP32 compatible with the Arduino IDE?

Yes. The esp32 by Espressif Systems board package adds full support to Arduino IDE 1.8.x and 2.x. You use standard functions like digitalWrite() and Serial.begin(), plus ESP32-specific libraries for Wi-Fi and Bluetooth.

Why won’t my ESP32 upload code?

The usual causes are a charge-only USB cable, a missing CP210x or CH340 driver, or the chip not entering download mode. Use a data cable, install the driver, and hold the BOOT button while the IDE shows “Connecting…”. Lowering Upload Speed to 115200 fixes many stalls.

Can I power the ESP32 with 5V?

Yes, through the VIN or 5V pin or the USB port. The onboard regulator drops it to 3.3V. The GPIO pins are 3.3V only. Connecting a 5V signal directly to a GPIO can damage the chip, so use a level shifter or a voltage divider.

Which ESP32 board should a beginner buy?

Buy a 30-pin or 38-pin ESP32 DevKit with a WROOM-32 module and a CP2102 USB chip. It has the most tutorials and library support. It also fits a standard breadboard. Choose the ESP32-S3 if you need native USB or more RAM, and the ESP32-C3 if you want a cheap RISC-V board.