CHIPS

ESP32 Setup · CHIPS

Installing the Arduino IDE and the ESP32 board.
Free for parents and teachers.

Instructor? Enter your access code
← back to the ESP32 centre

Set up the Arduino IDE for ESP32

Everything from a blank computer to a blinking LED on the board in your kit. Pick your computer first - every step below changes to match it. Tick them off as you go; the page remembers where you were.

Showing the Windows instructions.

Downloads

Every link below goes to the manufacturer, never to a driver-download site. Those sites wrap drivers in adware and are the usual reason a school laptop ends up in a worse state than it started.

⬇ Arduino IDE 2.x Pick Windows Win 10 and newer, 64 bit. "Just Download" is free. Pick macOS Apple Silicon or macOS Intel. "Just Download" is free. arduino.cc 🔌 CP210x driver Silicon Labs, official. Use this if Device Manager or System Information shows CP210x. silabs.com 🔌 CH340 driver WCH, official. Use this if you see CH340 or CH9102. The file is CH341SER.EXE. wch-ic.com 🔌 CH340 driver Try without it first. macOS has bundled a CH34x driver since Mojave, so most Macs need nothing. Only install this if the port never appears. wch-ic.com 📚 Espressif's official guide The manufacturer's own install walkthrough, with current screenshots. Useful if your IDE looks different from the diagrams below. docs.espressif.com

Part 1 · Install the software

About 15 minutes, most of it waiting for downloads. Do this before class, not during it.

01Download the Arduino IDE

Go to arduino.cc/en/software and take Arduino IDE 2.x, the big download button.

Choose Windows Win 10 and newer, 64 bit. You will get an .exe installer.

Choose macOS Apple Silicon if your Mac is M1/M2/M3/M4, or macOS Intel, 10.15 or newer if it is older. If you are not sure: Apple menu → About This Mac. It says either "Apple M..." or "Intel".

The site will ask you to donate. "Just Download" is free and fine.

02Install it

Run the .exe. Accept the licence, keep the default folder, and say yes to every driver box Windows offers during the install - those are the USB drivers you will need in step 3.

Open the .dmg and drag Arduino IDE into Applications. Open it from Applications, not from the disk image.

If macOS blocks it: "Arduino IDE cannot be opened because the developer cannot be verified." Go to System Settings → Privacy & Security, scroll down, and click Open Anyway. This is normal on a first run.

03Install the USB driver

The ESP32 board talks to your computer through a small USB-to-serial chip. Your computer needs its driver, or the board will never appear. Boards in this kit use one of two chips, and you cannot tell by looking - install whichever matches, or simply install both.

Plug the board in, then open Device Manager (Win + X, then Device Manager) and look under Ports (COM & LPT).

Plug the board in, then hold Option and click the Apple menu → System Information → USB.

Device Manager ▾ DESKTOP-PC ▸ Monitors ▾ Ports (COM & LPT) Silicon Labs CP210x USB to UART Bridge (COM5) ← the chip, and the port ▸ Sound, video and game controllers
Win + X → Device Manager → Ports (COM & LPT). The name tells you which driver you need; the number in brackets is the port you pick in step 6.
System Information Hardware Thunderbolt USB USB 3.1 Bus CP2102 USB to UART Bridge ← the chip Manufacturer: Silicon Labs If this list is empty, it is the cable.
Hold Option, click the Apple menu → System Information → USB. If nothing appears here, no driver will help - it is the cable or the port.

If you see CP210x or CP2102, install the Silicon Labs driver above. If you see CH340 or CH9102, install the WCH driver. If you see nothing at all, jump to the troubleshooting section below.

Restart after installing a driver. On both Windows and Mac the port often does not appear until you have unplugged the board, restarted, and plugged it back in.

Part 2 · Teach the IDE about ESP32

Out of the box the Arduino IDE only knows Arduino boards. Two short steps add ESP32.

04Add the ESP32 board URL

In the IDE: File → Preferences.

In the IDE: Arduino IDE → Settings (or Cmd + ,).

Find Additional boards manager URLs and paste this in:

https://espressif.github.io/arduino-esp32/package_esp32_index.json
Preferences Settings Sketchbook location: Editor font size: Additional boards manager URLs: https://espressif.github.io/arduino-esp32/... paste it here OK
File → Preferences. The field sits on the right, below the font settings.
Arduino IDE → Settings, or Cmd + comma. The field sits on the right, below the font settings.

05Install the ESP32 boards

Open Tools → Board → Boards Manager (or the second icon down the left edge). Search for esp32 and install esp32 by Espressif Systems.

BOARDS MANAGER esp32 Type: All esp32 by Espressif Systems Boards included in this package: ESP32 Dev Module, ESP32-S3, ESP32-C3, and 100+ more INSTALL Roughly 200 MB. Let the progress bar finish before touching anything.
Tools → Board → Boards Manager, or the second icon down the left edge. Install the one published by Espressif Systems.

This download is large, roughly 200 MB, and can take several minutes. Let it finish before doing anything else.

06Choose the board and the port

With the board plugged in: Tools → Board → esp32 → ESP32 Dev Module. That is the right choice for the board in this kit.

Then Tools → Port and pick the COM number that appeared when you plugged the board in. Unplug and replug to see which one changes.

Then Tools → Port and pick /dev/cu.usbserial-... or /dev/cu.SLAB_USBtoUART. Avoid anything with "Bluetooth" in the name.

File Edit Sketch Tools Auto Format Board: "ESP32 Dev Module" ▸ Port: ▸ COM5 cu.usbserial-0001 Upload Speed: 921600 Serial Monitor COM5 (ESP32 Dev Module) COM1 Unplug and replug to see which changes /dev/cu.usbserial-0001 /dev/cu.Bluetooth-Incoming Never pick a Bluetooth one
Tools → Board → esp32 → ESP32 Dev Module, then Tools → Port and take the COM number that appeared when you plugged in.
Tools → Board → esp32 → ESP32 Dev Module, then Tools → Port and take the cu.usbserial or cu.SLAB_USBtoUART entry.
Leave Upload Speed alone for now. If uploading fails later, dropping it to 115200 fixes it more often than anything else.

07Upload the blink test

Paste this in, then press the arrow button to upload. The small blue LED on the board should start blinking one second on, one second off.

void setup(){ pinMode(2, OUTPUT); } void loop(){ digitalWrite(2, HIGH); delay(1000); digitalWrite(2, LOW); delay(1000); }

When the IDE prints Connecting........, press and hold the BOOT button on the board until it starts writing. On many ESP32 boards this is required every time, and it is not a fault.

If it blinks, you are done. The whole toolchain works: driver, board package, port and upload. Everything in the course builds on this.

Common problems and quick fixes

Tap a symptom. These are in the order they actually happen in a classroom.

By far the most common problem, and it is almost never the board.
  1. Swap the USB cable first. Most micro-USB cables sold with phones and power banks are charge-only, with no data wires. They power the board, its red LED lights, and nothing else works. Borrow a cable you know carries data.
  2. Install the USB driver from step 3, then restart the computer and replug.
  3. Check Device Manager. A yellow triangle, or an "Unknown device", means the driver did not take. Right-click → Update driver.
  4. Check System Information → USB. If the device is not listed there at all, it is the cable or the port, not the software.
  5. Try a different USB port, directly on the computer rather than through a hub or a monitor.
The computer found the board but the board is not listening.
  1. Hold the BOOT button. Start the upload, and when Connecting.... appears, press and hold BOOT until the progress bar moves. Release it then.
  2. If there is also an EN or RST button: hold BOOT, tap EN, release EN, keep holding BOOT, then upload.
  3. Set Tools → Upload Speed to 115200.
  4. Close the Serial Monitor. It holds the port open and blocks uploads.
Something else is already using the port.
  1. Close the Serial Monitor and any second Arduino IDE window.
  2. Close other serial software - Putty, Thonny, another student's session on a shared machine.
  3. If it persists, unplug the board, wait five seconds, replug, then reselect the port.
  4. If it persists, quit the IDE completely (Cmd + Q) and reopen it. Closing the window is not enough on a Mac.
The board is not getting enough steady power. Almost always the cable or the port.
  1. Use a shorter, thicker USB cable. Long thin cables drop too much voltage.
  2. Plug straight into the computer, not a hub.
  3. If a servo or the relay is connected, power those from their own supply rather than the board's 5V pin. A servo under load will brown out an ESP32 every time.
The speed does not match.
  1. Set the dropdown at the bottom right of the Serial Monitor to 115200. That is what every sketch in this course uses.
  2. Check your sketch calls Serial.begin(115200); in setup().
  3. A short burst of gibberish at the moment of reset is normal - that is the ESP32 boot message at a different speed. Ignore it.
Usually the school network.
  1. Try a phone hotspot. School filters often block the download host, and this is the fastest way to prove it.
  2. Check the URL in step 4 for a stray space at either end.
  3. If it stops partway, delete the partial install from Boards Manager and run it again rather than retrying on top.
  4. Install it before class day. On a room full of machines sharing one connection, 200 MB each will not finish in a lesson.
  1. System Settings → Privacy & Security → Open Anyway. The button appears for about an hour after the blocked attempt.
  2. For a driver, the same panel may say "System software was blocked" with an Allow button. Click it, then restart.
  3. On Apple Silicon you may be asked to restart into a security screen to permit the driver. Follow the prompts; it is legitimate.
  1. Click "More info", then "Run anyway". The Arduino installer is unsigned for SmartScreen's taste, not unsafe.
  2. If the school account blocks installs entirely, this needs an IT administrator. Plan that a week ahead, not on the morning.
The upload worked; the wiring or the pin number did not.
  1. Check the pin number against the board, not the tutorial. The built-in LED is GPIO 2 on most boards in this kit, but some use a different pin.
  2. Press the EN or RST button once after uploading. Some boards need a manual reset to start the new sketch.
  3. Open the Serial Monitor and add Serial.println("alive"); to loop() to prove the sketch is actually running.
  4. On a breadboard, check the component is in the row you think it is. Count the holes twice.
  1. The port number changed. Windows gives a different COM number on a different USB socket. Reselect it under Tools → Port.
  2. A different board was picked up by a student. Boards look identical - label each one.
  3. The IDE updated itself and lost the board selection. Redo step 6.

Before class day

The five minutes that save a lesson.

✓Run the blink test on every machine the students will use

Not one machine - every one. Driver problems are per-computer, and finding eight of them at 2:50 PM with twelve children waiting is the single most common way one of these lessons goes wrong.

Label each board and its cable with the same number. A cable that works stays with the board it works with.