Skip to content
gunkslab

Primers

The ESP32

The ESP32 is a microcontroller, a whole small computer on one chip, made by Espressif. It has Wi-Fi and Bluetooth built in, two processor cores, and dozens of pins to read sensors and drive motors with. It costs little, and it can be programmed with the Arduino tools many people already know. That mix makes it a common choice for hobby robots and connected gadgets.

Pick your level at the top of the page.

High school

A computer the size of a stamp

A laptop runs many programs, has a screen and a keyboard, and takes a minute to start. A microcontroller is a whole small computer on one chip that runs just one program, from the moment it gets power, forever. It has no screen. Instead it has pins: little metal legs it can switch on and off, or read, to work lights, motors, buttons and sensors.

The ESP32 is a popular one because it also has Wi-Fi and Bluetooth built in, so a gadget made with it can talk to a phone or the internet with no extra parts.

Setup, then loop

A typical ESP32 program has two parts. setup() runs once at the start: “this pin drives a light, start talking over USB”. Then loop() runs again and again, thousands of times a second: “read the sensor, decide, set the motors”. Everything the gadget does happens in that loop.

On and off, very fast

A pin is either on (3.3 volts) or off (0 volts). So how does it run a motor at half speed? It switches the pin on and off thousands of times a second, on half the time. The motor can’t follow that fast, so it just runs at half power. This is called PWM, and it’s how most small robots set their speed.

Careful with the volts

The ESP32’s pins work at 3.3 volts. Many older sensors and boards use 5 volts, and 5 volts on an ESP32 pin can damage it. So a 5 V part needs a small converter in between.

The board you buy

The ESP32 chip on its own is tiny and hard to use. You usually buy a dev board: the chip, its memory and an antenna under a little metal cover, on a board with a USB socket. Plug it into a computer, and you can put a new program on it in under a minute.

Check yourself

  1. What does a microcontroller have instead of a screen and keyboard?
  2. A motor runs on a pin switched on 25% of the time. Roughly how fast does it go?
  3. Why can’t you wire a 5 V sensor’s output straight to an ESP32 pin?

<details><summary>Answers</summary>

  1. Pins, which it can switch on and off or read, to work lights, motors, buttons and sensors.
  2. About a quarter of full power. (Real motors need some power just to start turning, so it might not move at all.)
  3. The ESP32’s pins work at 3.3 V, and 5 V can damage them.

</details>

College

The chip, the module and the board

The ESP32 chip needs a flash memory chip, a crystal and an antenna beside it. A module such as the ESP-WROOM-32 puts all of that under one small metal shield, with 4 MB of flash. A dev board puts the module on a board with a USB-to-serial chip and a voltage regulator, ready to plug in.

Inside: two cores at up to 240 MHz, 520 KB of RAM, Wi-Fi on 2.4 GHz, and Bluetooth, both the classic kind and Low Energy.

Pins with jobs

Most pins can be inputs or outputs, but not all:

  • GPIO 34 to 39 are inputs only, with no pull-up resistors.
  • Strapping pins (0, 2, 5, 12 and 15) are read at power-on to decide how the chip boots. Pull one the wrong way and the board won’t start, or won’t take a new program. GPIO 12 high at boot sets the wrong voltage for the flash. After boot they’re ordinary pins, so they suit outputs that don’t care what happens during boot, like an LED.
  • GPIO 6 to 11 are wired to the flash chip on most modules. Don’t use them.
  • Of the two analogue-to-digital converters, ADC2 can’t be read while Wi-Fi is on. Anything measured with Wi-Fi running goes on an ADC1 pin (GPIO 32 to 39).

The ADC isn’t very linear, especially near the ends of its range. For a voltage that matters, like a battery’s, use the calibrated reading (analogReadMilliVolts()), keep the input in the middle of the range, and check it against a meter.

Hardware that works on its own

The ESP32 has peripherals: parts that do a job without the processor’s attention.

Peripheral Does Used for
LEDC PWM on up to 16 channels motor speed, LED brightness, servos
PCNT counts pulses, up or down wheel encoders
I²C a two-wire bus shared by many devices, each with an address sensors, displays
SPI a faster bus with a select line per device displays, SD cards
UART serial, one wire each way USB to a computer, GPS
RMT sends and times precise pulse trains addressable LEDs, IR remotes

Most of these can be routed to almost any pin, through the GPIO matrix.

PWM: frequency against resolution

LEDC counts at up to 80 MHz. One PWM cycle at frequency f with n bits of resolution needs f × 2ⁿ counts a second, so f × 2ⁿ ≤ 80 MHz. At 20 kHz, just above hearing (motors whine at lower PWM frequencies), that’s up to 11 bits, 2,048 steps. At 1 kHz it’s 16 bits.

Programs and updates

Programs are usually written with the Arduino core (setup() and loop()), or with ESP-IDF, Espressif’s own framework, which the Arduino core is built on. Both run on FreeRTOS, a small real-time operating system, so a program can have several tasks.

The flash is divided by a partition table. The usual 4 MB layout has two program slots of 1.25 MB, which is what makes over-the-air updates possible: the new program goes into the spare slot, and the chip switches to it on restart, or stays on the old one if it’s bad. The rest holds settings (NVS) and a small file system.

The family

There are newer chips beside the original: the ESP32-S3 (two faster cores and USB built in), the ESP32-C3 (one RISC-V core, smaller and cheaper), the ESP32-C6 (Wi-Fi 6, plus Thread and Zigbee radios), and more. The pin rules above are the original ESP32’s. Each chip has its own.

Check yourself

  1. You need four inputs with pull-ups and two outputs. Why not use GPIO 34 to 39?
  2. A board won’t boot when a sensor is plugged in. The sensor’s output is on GPIO 12. What’s happening?
  3. You want 10-bit PWM. What’s the highest frequency LEDC can give?
  4. Why measure a battery on GPIO 35 rather than GPIO 25, on a robot that uses Wi-Fi?

<details><summary>Answers</summary>

  1. They’re inputs only and have no internal pull-ups. Use them only as inputs with pull-ups of your own.
  2. GPIO 12 is a strapping pin. The sensor holds it high at power-on, which sets the flash voltage wrong. Move it to another pin.
  3. 80 MHz ÷ 2¹⁰ ≈ 78 kHz.
  4. GPIO 35 is on ADC1. GPIO 25 is on ADC2, which can’t be read while Wi-Fi is on.

</details>

University

Two cores and FreeRTOS

The original ESP32 has two Xtensa LX6 cores. Under the Arduino core, Wi-Fi and the network stack run as tasks pinned to core 0, and loop() runs in a task on core 1 by default. Tasks you create can be pinned to either. FreeRTOS schedules by priority, preemptively: a higher-priority task that becomes ready runs at once.

Two consequences:

  • Code on two cores shares memory, so a variable written by one task and read by another needs a mutex, a queue, or an atomic.
  • A loop() that blocks (a long delay(), a network call waiting for a reply) holds up everything else in that loop. A control loop that must run on time belongs in a task of its own, or must never block for longer than its deadline allows.

Memory and the flash cache

The 520 KB of SRAM is split by use: instruction RAM (IRAM) for code that must run fast or always, data RAM (DRAM) for variables, the heap and Wi-Fi’s buffers. Most code runs from the external flash, through a cache. While the flash is being written (saving settings, an over-the-air update), the cache is turned off. An interrupt handler that runs then must be in IRAM (IRAM_ATTR), with its data in DRAM, or the chip crashes.

Watchdogs and resets

A task watchdog resets the chip when a watched task stops checking in, and an interrupt watchdog when interrupts are blocked too long. The brownout detector resets it when the supply sags too low to run reliably. After a reset, esp_reset_reason() says which: power-on, a brownout, a watchdog, a crash (a panic) or software. Logging the reason at boot is the cheapest debugging tool a deployed device has.

Brownouts are common on battery and motor projects. Wi-Fi transmits in bursts of a couple of hundred milliamps, and motors starting pull the battery down too. A supply that sags during either resets the chip. Bulk capacitance near the module, and a regulator with headroom, are the usual fixes.

Power

Active with Wi-Fi, the chip draws tens to hundreds of milliamps. Modem sleep turns the radio off between beacons while staying connected. Light sleep pauses the cores and keeps RAM. Deep sleep keeps only the real-time-clock domain, about 10 µA, and wakes on a timer or a pin, through a full restart. A sensor that wakes, reports and sleeps can last months on a battery. A robot that drives can’t sleep its way to a long run time: the motors dominate.

Security

Anyone with the board and a USB cable can read its flash. Flash encryption keys the flash to the chip, and secure boot makes the chip refuse firmware not signed with your key. Both are one-way: they burn eFuses, bits that can be set once and never cleared. Credentials compiled into firmware are readable without them.

Check yourself

  1. An encoder’s interrupt handler crashes the chip only while settings are being saved. Why?
  2. A robot resets every time it starts driving with Wi-Fi on. What does esp_reset_reason() probably say, and what would you try?
  3. A task on core 1 updates a 64-bit position that a task on core 0 reads. Why can the reader see a wrong value?
  4. Why is an over-the-air update safe to lose power halfway through?

<details><summary>Answers</summary>

  1. Writing the flash turns its cache off. A handler that isn’t in IRAM, or whose data isn’t in DRAM, can’t be fetched then. Mark it IRAM_ATTR.
  2. A brownout. The motors’ start and Wi-Fi’s bursts sag the supply together. Add capacitance near the module, give the regulator headroom, or power the logic from its own supply.
  3. The 32-bit cores write it in two halves, so the reader can see one half old and one new. Guard it with a mutex or critical section, or pass it through a queue.
  4. The new program goes into the spare slot. The chip switches slots only once the whole image is written and checked, so a cut leaves the old program in place.

</details>

Try it

No board needed to start. You need only a container runtime. Start a shell with Python in it:

container

container run --rm -it docker.io/library/python:3.14 bash

docker

docker run --rm -it python:3.14 bash

podman

podman run --rm -it docker.io/library/python:3.14 bash

Inside it, install PlatformIO, a build tool for microcontrollers, and make a small project: a program that blinks an LED and says what chip it’s on.

pip install platformio==6.2.0
mkdir -p blink/src && cd blink
cat > platformio.ini <<'EOF'
[env:esp32dev]
platform = espressif32@6.5.0
board = esp32dev
framework = arduino
monitor_speed = 115200
EOF
cat > src/main.cpp <<'EOF'
#include <Arduino.h>

const int LED = 2;   // the blue LED on many ESP32 dev boards

void setup() {
  Serial.begin(115200);
  pinMode(LED, OUTPUT);
  Serial.printf("%s, %d cores at %d MHz, %d KB free\n", ESP.getChipModel(), ESP.getChipCores(),
                ESP.getCpuFreqMHz(), ESP.getFreeHeap() / 1024);
}

void loop() {
  digitalWrite(LED, !digitalRead(LED));
  delay(500);
}
EOF
pio run

The first build downloads the compiler and the Arduino core, a few minutes. It ends with how much of the chip the program uses:

RAM:   [=         ]   6.5% (used 21416 bytes from 327680 bytes)
Flash: [==        ]  20.4% (used 267185 bytes from 1310720 bytes)

Even a blink takes a fifth of the flash: most of it is the Arduino core and FreeRTOS. The flash figure is out of one program slot, 1.25 MB, not the whole 4 MB: the rest holds the second slot for updates, settings and a file system. The RAM figure is out of 320 KB, not 520 KB: that’s the part set aside for data. Type exit to leave.

With a board, install PlatformIO on your own computer the same way (containers on a Mac can’t reach USB), plug the board in, and from the project folder:

pio run -t upload
pio device monitor

The LED blinks, and the monitor shows a line naming the chip, its two cores at 240 MHz, and how much RAM is free. Press the board’s EN button to restart it and see the line again. GPIO 2 is a strapping pin, which is fine for an LED: it only matters at power-on.

Learn more