Lessons · Lesson K1 · Code basics · 30 min
Your first program: connect and upload code to your ESP32
From a box of parts to a blinking LED and your first message on screen, one step at a time. About 30 minutes, with a troubleshooting table for when something refuses to work.
New here? Install the tools first: Get set up.
What you need
- An ESP32 development board. This lesson uses the ESP32-DevKitC, the board Espressif designs itself. It is small, and it has pins on both sides so you can plug it into a breadboard [7].
- A USB cable that carries data. The DevKitC V4 has a Micro-USB socket and the cable goes between that socket and your computer [7]. Some cables are made only for charging and have no data wires inside. With one of those, your computer will never see the board [6]. If the board does not show up later, swapping the cable is the first thing to try.
- A computer. Arduino IDE 2 runs on 64-bit Windows 10 or newer, on macOS 10.15 “Catalina” or newer, and on 64-bit Linux [2].
- For the blink part: a breadboard, one LED, one 220 Ω resistor and two jumper wires. Lesson E3 explains why the resistor is there.
Check your board’s USB socket. Clone boards come with different sockets. Match your cable to the socket you actually see on your board.
Step 1: Install Arduino IDE 2
The Arduino IDE is the program where you write code, press one button, and send it to your board. Download it from the Arduino software page (arduino.cc/en/software) [2].
- Windows: run the file you downloaded and follow the installer. It may take a few minutes [2].
- macOS: copy the downloaded file into your Applications folder [2].
- Linux: download the 64-bit AppImage. Before the first launch, make it executable: right-click the file, open Properties, then the Permissions tab, and tick “Allow executing file as program”. Then double-click it [2]. If it refuses to start, your system may be missing a small helper called FUSE. On Ubuntu 22.04 or newer the Arduino guide gives
sudo add-apt-repository universefollowed bysudo apt install libfuse2; on Fedora,dnf install fuse[2].
Open the IDE once to make sure it starts. You will see an empty sketch. A sketch is just Arduino’s word for a program [12].
Step 2: Teach the IDE about the ESP32
Out of the box, the IDE knows Arduino’s own boards. A board package is an add-on that translates the usual Arduino commands into what one particular family of chips understands [3]. For the ESP32 the package comes from Espressif, the company that makes the chip [1].
2a. Tell the IDE where to find it.
- Open the Preferences window [1]. In current versions it sits under File on Windows and Linux. On macOS it is not in the File menu: look in the application menu (the one named Arduino IDE) for Preferences or Settings, depending on your version.
- Find the field Additional boards manager URLs and paste this address [1]:
https://espressif.github.io/arduino-esp32/package_esp32_index.json
- Click OK. If the field already holds another address, separate the two with a comma [1].
2b. Install the package.
- In the left-hand column of the IDE, click the Boards Manager icon (the board icon) [3].
- Type
esp32in the search field. Pick the package made by Espressif, then press INSTALL [3]. - Wait for it to finish. It can take a few minutes. The installed version number shows under the package name [3].
- Restart the IDE [1].
Step 3: Plug in the board and find its port
Connect the board to your computer with the data cable. A small LED lights up on the DevKitC when it receives 5 V from USB. That is only the power light, and it tells you nothing about the data connection [7].
Your computer talks to the ESP32 through a small helper chip on the board, a USB-to-UART bridge. The computer gives it a name, called a port: COM3 on Windows, something like /dev/ttyUSB0 on Linux, /dev/cu.usbserial-... on macOS [5][7].
Find your port. The IDE lists the ports it finds under Tools > Port. You can also check by hand [5]:
- Windows: open Device Manager and look at the list of COM ports. Unplug the board, plug it back in, and note which entry disappears and reappears.
- Linux: run
ls /dev/tty*once with the board unplugged and once with it plugged in. The new name is your port. - macOS: same trick with
ls /dev/cu.*.
If no new port appears, you may need a driver. Most of the time you need to do nothing: the driver comes with your operating system and installs itself when you plug the board in [5]. When it does not, you have to know which bridge chip your board carries:
- How to read the chip name. Find the small square chip near the USB socket and read the text printed on its top. A magnifier helps. Espressif’s guide links CP210x and FTDI drivers; your board’s user guide names its chip [5]. Many clone boards use a CH340 chip made by WCH [10]. Once the board is plugged in, the name also shows up in your system’s device list, for example “Silicon Labs CP210x UART Bridge” [6].
- CP210x: download the driver from Silicon Labs (the Espressif guide links to the “USB to UART Bridge VCP Drivers” page at silabs.com/developers/usb-to-uart-bridge-vcp-drivers) [5].
- CH340: SparkFun keeps a step-by-step guide with the driver files for Windows, macOS and Linux [10].
- macOS extra: after installing a driver, the system may ask you to allow it. On macOS 13 and later, look in System Settings > Privacy & Security; on older versions, in System Preferences > Security & Privacy > General [5]. Either way you are looking for a message about software from the developer (Silicon Labs or FTDI).
Then unplug the board, plug it back in, and look at the port list again.
Step 4: Pick the board and the port
At the top of the IDE, next to the verify and upload buttons, there is a drop-down menu. If it does not show your board by itself, choose “Select other board and port…”, or go to Tools > Board and Tools > Port and pick them by hand [4].
- Board: under the esp32 entries, choose ESP32 Dev Module. It is the generic ESP32 entry and it works well for the DevKitC. If your board carries a different chip, such as an ESP32-S3, pick the entry named for that chip instead.
- Port: choose the one you found in the last step.
The board name appears in bold once the IDE sees a connection [4].
Step 5: Build the LED circuit
Most DevKitC boards have no LED you can control from code. The official DevKitC V4 lists only a power light, which switches on when 5 V arrives [7]. Some clone boards do carry a small blue LED, often on GPIO 2, but this varies from board to board. We add our own LED on GPIO 26 so that everyone gets the same result. (GPIO means “general-purpose input/output”: a pin your code can switch on and off or read [16].)
Wire it like this, with the board unplugged:
- Plug the DevKitC into the breadboard (it is designed for that [7]). Many ESP32 boards are wide and cover every hole on one side of a standard breadboard. If yours does, use two breadboards side by side, or plug your jumper wires into the free side only.
- Connect a jumper wire from the pin marked 26 to one end of the 220 Ω resistor.
- Connect the other end of the resistor to the long leg of the LED, called the anode. The long leg is the positive side [15].
- Connect the short leg (the cathode) to a pin marked GND [15].
Why 220 Ω? The ESP32 runs on 3.3 V logic, so a pin that is switched on gives 3.3 V [17]. A red LED keeps about 2 V for itself, so about 1.3 V is left across the resistor, and Ohm’s law gives (3.3 − 2) ÷ 220 ≈ 0.006 A, about 6 mA, a gentle current for an LED. Lesson E3 walks through this calculation.
Step 6: Your first sketch, Blink
In the IDE, go to File > New Sketch (or simply use the empty one) and replace everything with this:
// Tinker Mission, lesson K1: Blink an external LED
// Wiring: GPIO 26 -> 220 ohm resistor -> LED long leg (anode); LED short leg (cathode) -> GND
const int LED_PIN = 26; // the pin the LED is wired to
void setup() {
// Runs once, when the board powers up or is reset.
pinMode(LED_PIN, OUTPUT); // this pin sends signals out
}
void loop() {
// Runs again and again, forever.
digitalWrite(LED_PIN, HIGH); // pin at 3.3 V: LED on
delay(500); // wait 500 ms (half a second)
digitalWrite(LED_PIN, LOW); // pin at 0 V: LED off
delay(500);
}
Download the sketch folder (.zip)
Read it like a recipe:
const int LED_PIN = 26;gives the number 26 a name, so the rest of the code says what it means. If you move the wire later, you change one line [12].pinMode(LED_PIN, OUTPUT);tells the board that this pin will send signals out [12].digitalWrite(LED_PIN, HIGH);puts the pin at its high voltage, which is 3.3 V on the ESP32 [17], and the LED lights up.LOWbrings it back to 0 V and the LED goes dark [12].delay(500);makes the board wait 500 milliseconds. There are 1000 milliseconds in a second [12]. While it waits, the board does nothing else [15].
What setup() and loop() do. Every sketch needs these two functions [12]. setup() runs once, when the board starts or is reset. It is the place to prepare things, such as pin modes [13]. loop() runs again and again, as long as the board has power. It is where your program does its actual work [13].
Swipe the drawing sideways to see all of it.
The board starts (power on or reset).
Step 7: Upload
- Click the verify button (the checkmark). The IDE checks your code and builds it without sending anything. Errors, if any, appear in the console at the bottom [4].
- Click the upload button (the right arrow). The IDE builds the code again and sends it to the board [4].
- Watch the console. When the upload starts it prints
Connectingfollowed by a row of dots [8]. When it finishes, a message pops up at the bottom right of the IDE [4], and the LED starts blinking.
If the dots keep going and the upload fails. Nothing is broken. The ESP32 has to be put into a special listening state called download mode before it accepts new code. Many boards do this on their own. When yours does not, you do it with the buttons [5][6]:
- Easy way: hold down the BOOT button while the upload runs [6].
- Manual way: hold BOOT, press EN (the reset button) once, then release BOOT. On Espressif’s DevKitC, holding BOOT while pressing EN is exactly what starts download mode [7]. Then start the upload [5].
Inside the chip, BOOT works by pulling a pin called GPIO 0 down to 0 V while the chip restarts [6][9].
Still failing? Look at the table at the end of this lesson.
Step 8: Say hello with the Serial Monitor
A blinking LED shows that something runs. The Serial Monitor lets the board talk back, with words and numbers on your screen. It is also your best tool for finding out what your code is really doing.
Replace the sketch with this one and upload it:
// Tinker Mission, lesson K1: say hello to the Serial Monitor
// Open the Serial Monitor and set it to 115200 baud.
int counter = 0; // a place to store a number
void setup() {
Serial.begin(115200); // start the serial link at 115200 bits per second
}
void loop() {
Serial.print("Hello from my ESP32! Count: ");
Serial.println(counter); // print the number, then go to a new line
counter = counter + 1; // add one
delay(1000); // wait one second
}
Download the sketch folder (.zip)
Now open the Serial Monitor with the button at the top right of the IDE. It opens as a tab in the bottom panel [14]. Look for the baud rate setting there and choose 115200 [14].
Baud rate is the speed of the conversation, in bits per second [11]. Both sides must use the same one. The ESP32’s default console speed is 115200 [5], which is why our sketch says Serial.begin(115200). You should see a new line every second, counting up.
Right after a reset, you may also see some extra text before your own lines. That is the chip’s start-up report, printed at the same 115200 speed [9].
When something goes wrong
Take it one row at a time, and change one thing before you try again.
| What you see | Likely reason | What to try |
|---|---|---|
| No port in the list, or the port appears and disappears | Charge-only cable, missing driver, or a worn port | Use another cable that carries data. Try another USB port on the computer, plugged in directly rather than through a hub. Install the driver for your bridge chip (CP210x or CH340, see Step 3). Unplug and replug [5][6][10] |
| “Permission denied” on the port (Linux) | Your user account is not allowed to use the serial port | Add yourself to the dialout group: sudo usermod -a -G dialout $USER (on Arch Linux the group is uucp). Then log out and back in for it to apply [4][5] |
| “Failed to connect” or “Timed out waiting for packet header” | The board did not enter download mode, or the link is poor | Hold BOOT during upload. Change the cable and the USB port. Disconnect anything wired to the TX and RX pins. Close any other program that has the port open, such as another serial terminal [6][9] |
| Upload starts, then stops with random errors part-way | Unstable link or a weak power supply | Use a shorter, good-quality cable. Avoid hubs. Plug into a port on the computer itself [9] |
| Compile errors mention the wrong board, or the code builds but nothing works as expected | Wrong board selected | Check Tools > Board and pick ESP32 Dev Module (or the entry named for your chip). The board package is what translates your code for one specific chip, so a mismatch matters [3][6] |
| Serial Monitor shows strange symbols | Baud rate mismatch | Set the monitor to 115200 to match Serial.begin(115200) [11] |
| Serial Monitor shows nothing at all | Your board has two USB sockets, or the monitor is attached to another port | Press EN once to restart the sketch while the monitor is open. On boards with a UART socket and a separate native USB socket, use the right socket and setting. The classic ESP32 DevKitC has just the UART one [6] |
| The IDE says the port is busy | Another program holds the port | Close other serial monitors or terminals, then retry [9] |
No board yet? Try a simulator
If your board has not arrived, you can still practise the ideas of this lesson in an online ESP32 simulator called Wokwi: https://wokwi.com/. It runs in the browser, so there is nothing to install. It is a good way to try the Blink sketch before touching any wire.
Check yourself
Three short questions. Nothing is saved, take your time.
How many times does the code inside setup() run after you power up the board?
- Once
- Over and over
- Once per second
Show the answer
Once. setup() runs a single time, at power-up or after a reset; loop() is the part that repeats [13].
You open the Serial Monitor and see a stream of strange symbols instead of your text. What is the most likely cause?
- The LED is on the wrong pin
- The baud rate in the Serial Monitor does not match the one in the sketch
- The resistor is too small
The upload stays stuck at "Connecting......" and ends in "Failed to connect". What do you try first?
- Rewrite the sketch from scratch
- Try another USB cable that carries data and hold the BOOT button during the upload
- Install a second copy of the IDE
Show the answer
Try another USB cable that carries data and hold the BOOT button during the upload. Some cables only charge and carry no data, and on some boards you must hold BOOT while uploading [6].
Sources
Show the 17 sources
- Espressif, Arduino-ESP32 documentation, “Installing” (the stable Boards Manager URL,
https://espressif.github.io/arduino-esp32/package_esp32_index.json; add it in Preferences under “Additional Boards Manager URLs”; install the esp32 platform; restart the IDE) — https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html - Arduino, “Downloading and installing the Arduino IDE 2” (system requirements; install steps for Windows, macOS and Linux; AppImage and FUSE) — https://docs.arduino.cc/software/ide-v2/tutorials/getting-started/ide-v2-downloading-and-installing/
- Arduino, “Installing a board package in the IDE 2” (what a board package is; Boards Manager icon, search, INSTALL; version tag) — https://docs.arduino.cc/software/ide-v2/tutorials/ide-v2-board-manager/
- Arduino, “How to upload a sketch with the Arduino IDE 2” (verify and upload buttons; board drop-down; Tools > Board and Tools > Port; the “Permission denied” fix on Linux) — https://docs.arduino.cc/software/ide-v2/tutorials/getting-started/ide-v2-uploading-a-sketch/
- Espressif, ESP-IDF Programming Guide, “Establish Serial Connection with ESP32” (USB-to-UART drivers for CP210x and FTDI; driver normally bundled with the OS; finding the port on Windows, Linux and macOS; dialout/uucp group; default console baud 115200; manual download mode) — https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/establish-serial-connection.html
- Espressif, Arduino-ESP32 documentation, “Troubleshooting” (charge-only cables; “Failed to connect… Timed out waiting for packet header”; hold BOOT while uploading; download mode and GPIO 0; board not detected; ESP32 Dev Module; bridge name such as Silicon Labs CP210x) — https://docs.espressif.com/projects/arduino-esp32/en/latest/troubleshooting.html
- Espressif, ESP32-DevKitC V4 User Guide (Micro-USB port; power LED; BOOT and EN buttons; USB-to-UART bridge; breadboard use) — https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp32-devkitc/user_guide.html
- Espressif, esptool documentation, “Flashing firmware” (example output with “Connecting………” while the tool reaches the chip) — https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/flashing-firmware.html
- Espressif, esptool documentation, “Troubleshooting” (bootloader won’t respond; permissions and other programs holding the port; unstable cables and hubs; boot log at 115200; GPIO 0 held low enters the serial bootloader) — https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html and https://docs.espressif.com/projects/esptool/en/latest/esp32/advanced-topics/boot-mode-selection.html
- SparkFun, “How to Install CH340 Drivers” (CH340 is a USB-to-serial chip made by WCH; found on development boards; driver files and steps) — https://learn.sparkfun.com/tutorials/how-to-install-ch340-drivers
- SparkFun, “Serial Communication” (baud rate; both sides must match; mismatch produces garbage; 115200 as a common rate) — https://learn.sparkfun.com/tutorials/serial-communication
- Arduino, “Arduino Sketches” (a sketch is a program; setup() and loop(); pinMode, digitalWrite, delay; milliseconds) — https://docs.arduino.cc/learn/programming/sketches/
- Arduino, “BareMinimum” example (setup() runs once after power-up or reset; loop() repeats) — https://docs.arduino.cc/built-in-examples/basics/BareMinimum/
- Arduino, “Using the Serial Monitor tool” (IDE 2 Serial Monitor button at top right, tab in the bottom panel, baud rate setting) — https://docs.arduino.cc/software/ide-v2/tutorials/ide-v2-serial-monitor/
- Arduino, “Blink” example (long leg anode, short leg cathode to GND; resistor in series; delay() stops everything else for that time) — https://docs.arduino.cc/built-in-examples/basics/Blink/
- Espressif, Arduino-ESP32 documentation, “GPIO” (GPIO = general-purpose input/output; pinMode, digitalWrite) — https://docs.espressif.com/projects/arduino-esp32/en/latest/api/gpio.html
- Adafruit, “Adafruit HUZZAH32 ESP32 Feather: Pinouts” (the ESP32 runs on 3.3 V power and logic; GPIO pins are not 5 V safe unless stated otherwise) — https://learn.adafruit.com/adafruit-huzzah32-esp32-feather/pinouts