Analog Data

MicroPython

MicroPython on ESP32 — Flash & Connect

Flash MicroPython onto your ESP32 and start coding in Python immediately. This guide covers firmware download, flashing with esptool or Thonny, and connecting to the REPL.

Step 1 — Download the MicroPython Firmware

Go to the official downloads page:

micropython.org/download/ESP32_GENERIC

Select the correct firmware for your ESP32 variant:

BoardFirmware
ESP32 (standard, e.g., DevKit)ESP32_GENERIC-*.bin
ESP32 with PSRAMESP32_GENERIC-SPIRAM-*.bin
ESP32-S3ESP32_GENERIC_S3-*.bin
ESP32-S3 with PSRAMESP32_GENERIC_S3-SPIRAM_OCT-*.bin
ESP32-C3ESP32_GENERIC_C3-*.bin
ESP32-C6ESP32_GENERIC_C6-*.bin

Download the latest stable .bin file.

Step 2 — Install esptool

esptool.py is the official tool for flashing ESP32 firmware.

shell
# Install via pip
pip install esptool

# Verify
esptool.py version

On Windows, you may need to use py -m esptool or python -m esptool if esptool.py isn't in PATH.

Step 3 — Connect the ESP32

  1. Connect your ESP32 board via USB
  2. Identify the serial port:
    • Windows: Check Device Manager → COM ports (e.g., COM3)
    • Ubuntu: ls /dev/ttyUSB* (usually /dev/ttyUSB0)
    • macOS: ls /dev/cu.* (e.g., /dev/cu.SLAB_USBtoUART)

Step 4 — Erase the Flash

Before flashing MicroPython, erase the existing firmware:

shell
# Windows
esptool.py --port COM3 erase_flash

# Ubuntu / macOS
esptool.py --port /dev/ttyUSB0 erase_flash

Erase removes all existing firmware

This deletes everything on the ESP32's flash, including any existing MicroPython files or Arduino firmware. Make sure you have backups if needed.

Step 5 — Flash MicroPython

shell
# Windows
esptool.py --chip esp32 --port COM3 --baud 460800 \
  write_flash -z 0x1000 ESP32_GENERIC-*.bin

# Ubuntu / macOS
esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 \
  write_flash -z 0x1000 ESP32_GENERIC-*.bin

For ESP32-S3:

shell
esptool.py --chip esp32s3 --port /dev/ttyUSB0 --baud 460800 \
  write_flash -z 0x0 ESP32_GENERIC_S3-*.bin

For ESP32-C3 / C6 (RISC-V):

shell
esptool.py --chip esp32c3 --port /dev/ttyUSB0 --baud 460800 \
  write_flash -z 0x0 ESP32_GENERIC_C3-*.bin

A successful flash ends with:

text
Hash of data verified.
Leaving...
Hard resetting via RTS pin...

Alternative: Flash via Thonny

If you prefer not to use the command line, Thonny can flash MicroPython for you:

  1. Open Thonny
  2. Go to Tools → Options → Interpreter
  3. Select "MicroPython (ESP32)"
  4. Click "Install or update MicroPython" (link at the bottom right)
  5. Select:
    • Port: Your ESP32's COM port or /dev/ttyUSB0
    • MicroPython variant: Select your ESP32 variant
    • Version: Latest stable
  6. Click Install
  7. Wait for flashing to complete, then click Close

Step 6 — Connect to the REPL

After flashing, reconnect via Thonny or a serial terminal:

Via Thonny

Go to Tools → Options → Interpreter, select MicroPython (ESP32) and your port, click OK. Press the Stop/Restart button. You should see:

text
MicroPython v1.xx.x on 2025-xx-xx; ESP32 module with ESP32
Type "help()" for more information.
>>>

Via Serial Terminal (any OS)

shell
# Ubuntu / macOS — using minicom
minicom -D /dev/ttyUSB0 -b 115200

# macOS — using screen
screen /dev/cu.SLAB_USBtoUART 115200

# Windows — using PuTTY or Windows Terminal
# Serial port: COM3, Speed: 115200, Data bits: 8, Stop bits: 1, Parity: None

Press Enter once connected to get the >>> prompt.

Step 7 — Test ESP32-Specific Features

python
1# Check available flash memory
2import uos
3fs_stat = uos.statvfs('/')
4print(f"Free flash: {fs_stat[0] * fs_stat[3] / 1024:.0f} KB")
5
6# Connect to Wi-Fi
7import network
8wlan = network.WLAN(network.STA_IF)
9wlan.active(True)
10wlan.connect('YourSSID', 'YourPassword')
11import time
12while not wlan.isconnected():
13    time.sleep(0.5)
14print('IP:', wlan.ifconfig()[0])
15
16# Make an HTTP GET request
17import urequests
18r = urequests.get('http://api.open-meteo.com/v1/forecast?latitude=12.97&longitude=77.59&current_weather=true')
19print(r.json()['current_weather']['temperature'], '°C')
20r.close()

ESP32 GPIO Quick Reference

python
1from machine import Pin, ADC, PWM, I2C, SPI
2
3# Digital output
4led = Pin(2, Pin.OUT)
5led.on(); led.off(); led.toggle()
6
7# Digital input with pull-up
8btn = Pin(0, Pin.IN, Pin.PULL_UP)
9print(btn.value())   # 0=pressed, 1=released
10
11# Analog input (ADC1 pins: GPIO 32–39)
12adc = ADC(Pin(34))
13adc.atten(ADC.ATTN_11DB)   # 0–3.6V range
14raw = adc.read()            # 0–4095
15
16# PWM
17pwm = PWM(Pin(13), freq=1000)
18pwm.duty(512)   # 50% duty (0–1023 scale)
19
20# I2C
21i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=400_000)
22devices = i2c.scan()

Troubleshooting

A fatal error occurred: Failed to connect to Espressif device

  • Hold the BOOT button on the ESP32 while running the esptool command
  • Release once the tool starts writing
  • Some ESP32 boards require BOOT to be held for the entire flash process

esptool.py: command not found

shell
# Try explicitly
python3 -m esptool --port /dev/ttyUSB0 erase_flash

Port is busy

Close Thonny, Arduino IDE Serial Monitor, and any other program using the port.

Next Steps

Previous
Thonny IDE Setup
Next
mpremote CLI Guide