The Espressif ESP32 is a great and very popular processor used on lots of development boards. However, its lack of native USB has kept it from getting a CircuitPython build - for reasons... Until now!

The new web workflow feature being added to CircuitPython 8 has brought the ESP32 back to the scene. For wifi enabled boards, like the ESP32, web workflow allows connecting to a board running CircuitPython over the local network using a web browser. Now it's easy to use the REPL or upload/download files using a browser!

In this guide, we show how to get the CircuitPython web workflow up and running on a supported ESP32 based board.

Remember! There Will Be No CIRCUITPY Folder

It is important to remember that the ESP32 lacks native USB support and therefore no CIRCUITPY folder will show up. Loading CircuitPython firmware and getting wifi set up is done over a serial connection (a.k.a a COM port) instead of a folder.

That's really the whole point of this guide. Because of this, the process for getting things set up on the ESP32 is different and more involved than other boards. So we're giving it some special attention. However, once set up, using web workflow is generally the same as other boards - you will upload library files, assets like fonts and images, and .py files for running your project

Variants with Native USB

Web Workflow can be used on wifi capable boards with native USB, like ones based on the EPS32-S2 or ESP32-S3. However, the native USB also allows for direct editing of code stored on the CircuitPython board, which is the generally easier and "standard" approach. This guide mainly focuses on the non-native USB ESP32 since it is more involved to get set up with CircuitPython and Web Workflow. But this does not mean Web Workflow is only available on ESP32.

This is the tricky part. Well, the first tricky part at least. It's really just a simple matter of downloading the proper CircuitPython firmware .bin file and loading it onto the board. But since this is done over serial, it's not as easy as dragging a .uf2 file to a BOOT folder, which is the more typical CircuitPython experience. (Remember, there's no CIRCUITPY or BOOT drive on the original ESP32!)

Download Firmware

First the firmware .bin file for the board must be downloaded. These can be downloaded from the main CircuitPython site linked below - just find specific board being used:

Installing the Firmware

This must be done over serial. There are two options:

• Use the web serial browser based tool (easier, but requires a Chrome webbrowser)
• Use the command line based esptool.py tool (harder, unless you happen to have esptool.py installed already and you know how to use it!)

The following pages cover these options in more detail. Choose your adventure!

Before you can load your firmware, you'll need to install esptool. Follow the instructions found here.

Next up you need to determine the Serial Port the board is connected to.

• For ESP32 boards, just plug it into your computer.
• For ESP32-S2/S3/C3 boards, plug in and then launch 'bootloader' mode by holding down BOOT or B0 button while clicking reset. Then release both buttons.

If you're on something like a Mac or Linux, run ls /dev/tty.* to find all serial devices, it will be called something like /dev/tty.usbserial or /dev/ttyUSB0 or /dev/ttyACM0 or /dev/tty.SLABtoUSB or similar!

It will probably not be a shorter name /dev/tty23.

Once you have esptool installed, you will first want to erase the flash on your ESP32 board, it's also a great way to determine that you are able to connect. You can do so by running something similar to the following command. Make sure you update the port to match the serial port to which your board is connected, i.e. change /dev/tty.usbserial-1144440 to match your connection.

esptool.py --chip esp32 --port /dev/tty.usbserial-1144440 erase_flash

or - if you're not 100% sure which ESP32 chip you have, you can just specify the port

esptool.py --port COM13 erase_flash

Once the flash is successfully erased, you can load your firmware .bin file by running something similar to the command below. Make sure you update the following:

• The port to match the serial port to which your board is connected, i.e. change /dev/tty.usbserial-1144440 to match your connection.
• The firmware.bin file name to match the firmware you downloaded, i.e. change firmware.bin to something like esp32spiram-20220117-v1.18.bin or adafruit-circuitpython-esp32-8.0.bin
• This command assumes you will be loading it to address 0x0, as we do for circuitpython. This may not be true for your firmware! check the documentation for the offset if necessary

Load the firmware using something similar to the following command, with the above changes:

esptool.py --port /dev/tty.usbserial-1144440 write_flash -z 0x0 firmware.bin

To keep things simple we don't specify the chip or a faster upload speed - you can always add those options if you need to upload to many chips quickly

It's always a good idea to power cycle by unplugging-replugging, or pressing the reset button, to make sure the new firmware is running.

Web workflow is enabled when a file named settings.toml is added to the root folder of the CircuitPython file system. This file contains local wifi info and other settings. More info here.

Now, normally creating a file is super easy when the board shows up as a disk drive...but as mentioned before, that's not possible on the original ESP32 because it does not have native USB so it cannot show up as a disk drive. So we have to be a little more creative!

To start out, the minimal contents of this file are:

CIRCUITPY_WIFI_SSID = "wifissid"
CIRCUITPY_WIFI_PASSWORD = "wifipassword"
CIRCUITPY_WEB_API_PASSWORD= "webpassword"

CIRCUITPY_WIFI_SSID = "wifissid"
CIRCUITPY_WIFI_PASSWORD = "wifipassword"
CIRCUITPY_WEB_API_PASSWORD= "webpassword"

with each item updated with local specifics.

• wifissid - replace with local wifi network name
• wifipassword - replace with local wifi network password
• webpassword - used when connecting to the board via web browser, set to whatever

There are a couple of options for creating this file.

Option 1: Create settings.toml file via REPL

The settings.toml file is simple enough that it can be created with a few simple Python commands directly via the REPL.

Here are the basic commands to use. Note these need to be updated with local wifi specifics. Note also where double quotes and single quotes are used.

f = open('settings.toml', 'w')
f.write('CIRCUITPY_WIFI_SSID = "wifissid"\n')
f.write('CIRCUITPY_WIFI_PASSWORD = "wifipassword"\n')
f.write('CIRCUITPY_WEB_API_PASSWORD = "webpassword"\n')
f.close()

f = open('settings.toml', 'w')
f.write('CIRCUITPY_WIFI_SSID = "wifissid"\n')
f.write('CIRCUITPY_WIFI_PASSWORD = "wifipassword"\n')
f.write('CIRCUITPY_WEB_API_PASSWORD = "webpassword"\n')
f.close()

• Replace wifissid with the name of your local wifi network
• Replace wifipassword with your local wifi password
• The other password, webpassword, is used when you access the board via a web browser. Set this to whatever you want.

Once connected, you can press the Reset button to kick the firmware, then hit return a few times to get to the REPL prompt. Now you can copy and paste the lines above (with your correct SSID/password!

Don't forget, ESP32 does not support 5 GHz networks, so use your 2.4 GHz SSID if you have two.

Now press the Reset button again, you will see the ESP32 reboot. This time, it should get an IP address. If you have a fairly smart terminal program, the IP address will appear in the title bar.

Alternatively, or if you want more deets - you can always query the board over the REPL to ask it the MAC address and IP address:

import wifi

print("My MAC addr: %02X:%02X:%02X:%02X:%02X:%02X" % tuple(wifi.radio.mac_address))
print("My IP address is", wifi.radio.ipv4_address)

import wifi

print("My MAC addr: %02X:%02X:%02X:%02X:%02X:%02X" % tuple(wifi.radio.mac_address))
print("My IP address is", wifi.radio.ipv4_address)

If that's not working either, try asking what SSID's it thinks it's seeing to make sure you have no typos!

import wifi

print("Available WiFi networks:")
for n in wifi.radio.start_scanning_networks():
    print("\t%s\t\tRSSI: %d\tChannel: %d" % (str(n.ssid, "utf-8"), n.rssi, n.channel))
wifi.radio.stop_scanning_networks()

import wifi

print("Available WiFi networks:")
for n in wifi.radio.start_scanning_networks():
    print("\t%s\t\tRSSI: %d\tChannel: %d" % (str(n.ssid, "utf-8"), n.rssi, n.channel))
wifi.radio.stop_scanning_networks()

Note that since this code has an indented part in it, you shouldn't just paste it in directly into the REPL because it won't handle the tab/spaces correctly. Instead, once you hit Return to get to the REPL, type in Control-E to enter paste mode . Then paste in the text and type Control-D to finish and run

Check that your SSID appears properly - if not, maybe its 5 GHz, maybe its not typed correctly, etc!

Option 2: Create settings.toml file using Thonny

This option requires installing additional software - the Thonny Python IDE. Thonny provides file access and a text editor which makes creating the settings.toml file a little more streamlined than using direct REPL commands. This technique requires Thonny 4.0.0 or later.

Once the web workflow is enabled and the board connects to the local wifi network with an IP address, the board can be accessed by opening a web browser and entering the board's network address. But what is the address to enter?

Connect using MDNS Address

The CircuitPython web workflow uses MDNS so that connecting to the board can be as simple as using the address circuitpython.local. Try using that first and if it works, great. Open a web browser and navigate to:

http://circuitpython.local

http://circuitpython.local

Or just click the button below:

Connect using IP Address

If MDNS does not work for some reason, the fallback approach is to use the actual IP address, like 192.168.0.121, the CircuitPython board was assigned when it connected to the local wifi network.

http://192.168.0.121

http://192.168.0.121

There are several options for determining this address.

Terminal Window Title Bar

The web workflow serial output includes some special escape sequences that are intended to update the window title bar of the terminal program being used.

For example, here's what a terminal window running screen to connect to the board looks like:

Via REPL

The IP address can be obtained fairly easily via the REPL with a few commands:

>>> import wifi
>>> wifi.radio.ipv4_address
192.168.0.121
>>>

>>> import wifi
>>> wifi.radio.ipv4_address
192.168.0.121
>>>

Serial output in Thonny

Welcome! Page

This is the initial page seen when first connecting.

Password Entry

When first accessing things from the Welcome! page, a password must be entered.

Serial Terminal

From the Welcome! page, click the serial terminal link to access the serial output as well as REPL for entering commands.

File Browser

From the Welcome! page, click the file browser link on the Welcome! page to access files and folders.

Here's a simple example showing how to blink the on board NeoPixel of either the Feather ESP32 V2 or the QT PY ESP32 Pico. It covers addings a library file, neopixel.mpy, as well as editting code.py directly in the browser.

Adding a Library File

Follow these steps to add neopixel.mpy to the /lib folder.

Edit code.py

Follow these steps to write a simple NeoPixel blink example and save it as code.py so it will run automatically.

Here's the simple example code used:

import time
import board
import neopixel

pixels = neopixel.NeoPixel(board.NEOPIXEL, 1)

while True:
    pixels.fill(0xADAF00)
    time.sleep(1)
    pixels.fill(0)
    time.sleep(1)

import time
import board
import neopixel

pixels = neopixel.NeoPixel(board.NEOPIXEL, 1)

while True:
    pixels.fill(0xADAF00)
    time.sleep(1)
    pixels.fill(0)
    time.sleep(1)