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:


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')
  • 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.

If you have a terminal program like PuTTY, minicom, screen or similar and you know how to use them - connect to the ESP32 board at the correct port name and 115200 baud

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)

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))

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.

In Thonny, open the Tools -> Options dialog and select the Interpreter tab.

Set interpreter to CircuitPython (generic) and the COM port as needed.

Enter the file contents in the editor window. Update wifissid etc. as needed.

Click save.

Select CircuitPython Device

Save the file as settings.toml.

Now the settings.toml file shows up on the CircuitPython device.

This guide was first published on Aug 18, 2022. It was last updated on Aug 18, 2022.

This page (Setting up Web Workflow) was last updated on Aug 16, 2022.

Text editor powered by tinymce.