Install the toolchain
Four things have to be installed before one line of code can reach the board, and the errors do not name which one is missing. Here they are in order, with the symptom each one produces.
What you are installing
Four separate things, from three different places. Nothing on your computer knows about the ESP32 until all four are present, and each one fails with a message that points somewhere else.
WiFi.h is always the board package.Do it in this order
- Arduino IDE 2.x, or Thonny if you are going the MicroPython route.
- The board package. In Arduino: File → Preferences → Additional boards
manager URLs, paste
https://espressif.github.io/arduino-esp32/package_esp32_index.json, then Boards Manager → esp32 → Install. - The USB driver, if your board needs one. Look at the small chip next to the USB socket: CP2102 and CH340 need a download, and anything with native USB — S3, C3, C6, P4 — needs nothing.
- Select the board and the port. Tools → Board → ESP32 Arduino, then the entry matching yours. If you are unsure, "ESP32 Dev Module" works for almost every classic board.
Prove it before you build anything
Upload the blink sketch below. It needs no components, so it tests exactly one thing: whether code written on your computer can reach the chip and run. Do this first, every time you set up a new machine or a new board — it turns a whole category of later confusion into a five-minute check.
The code
Upload this before anything else. It uses no wiring, so if it works the whole chain works, and if it fails you have a toolchain problem rather than a circuit problem.
void setup() {
Serial.begin(115200);
pinMode(LED_BUILTIN, OUTPUT);
}
void loop() {
digitalWrite(LED_BUILTIN, HIGH);
Serial.println("on");
delay(500);
digitalWrite(LED_BUILTIN, LOW);
Serial.println("off");
delay(500);
}LED_BUILTIN is defined by the board package, not by the chip. On a board with an addressable LED instead of a plain one it will not light — that is the board, not the upload.
MicroPython is a different install. You flash the interpreter onto the board once, then send it files. Type these lines into the REPL and the LED starts blinking immediately, with no compile step at all.
from machine import Pin
import time
led = Pin(2, Pin.OUT) # your board may use a different pin
while True:
led.value(1)
print("on")
time.sleep(0.5)
led.value(0)
print("off")
time.sleep(0.5)Save it as main.py on the board and it runs at every power-up. Anything else is just a file sitting there.
When it does not work
Nine times in ten this is the USB cable. Plenty of cables carry power and no data, and a board that lights up is not a board that is talking. Try another cable first, then the driver for your board's USB chip.
The board package is not installed. Boards Manager, search esp32, install the Espressif entry. It is a few hundred megabytes and takes a while, which is why people abandon it halfway and forget.
The port is right and the chip is not listening. Hold the BOOT button, tap EN, release BOOT, and upload again. If that works every time, your board has no auto-reset circuit.
The Serial Monitor baud rate has to match Serial.begin. Set both to 115200. Garbage characters mean a mismatch, silence usually means the monitor is on the wrong port.
The chain is proven. Now the first program you write yourself, and the two settings that decide whether you ever see its output.
Hello world over serial →Edit this page — content/esp32/install-the-toolchain.mdx
Discuss this article
Ask about this page. The answer stays here, on the page it belongs to, for whoever hits the same wall next.