The first thing you will need to do is make sure you are running version 8.0.0-beta.2 or later of CircuitPython. You can download it from the downloads page on circuitpython.org.

If you have previously installed it and you're not sure which version of CircuitPython your board is currently running, you can check the boot_out.txt file in the root folder of your device. Assuming your mass storage has not been disabled, this should be in the CIRCUITPY drive.

Once you have that downloaded, you will want to check out the appropriate learn guide for your specific board for installation instructions. If you are running an ESP32 board, the setup process is a little different and you will want to check out the CircuitPython on ESP32 Quick Start guide. If you would like a more general overview of installing CircuitPython, you can check out the Welcome to CircuitPython guide.

The web workflow is not yet available for the Raspberry Pi Pico W.

Creating an Environment File

Once you have the correct version of CircuitPython installed and running, the next step is to create an .env file in the root of the CIRCUITPY drive. Then configure it by adding the following contents and changing the values as appropriate:

For boards with native USB (like ESP32-S2, or ESP32-S3), you can do this by creating a file on the disk drive that appears when plugging in the board. For boards without native USB (like ESP32-C3 or ESP32) you will need to use the REPL. See https://learn.adafruit.com/circuitpython-with-esp32-quick-start/ for more info
# To auto-connect to Wi-Fi
CIRCUITPY_WIFI_SSID='yourwifissid'
CIRCUITPY_WIFI_PASSWORD='yourpassword'

# To enable modifying files from the web. Change this too!
# Leave the User field blank in the browser.
CIRCUITPY_WEB_API_PASSWORD='passw0rd'

CIRCUITPY_WEB_API_PORT=80

A summary of the values is as follows:

  • CIRCUITPY_WIFI_SSID: This is the name of the WiFi network that you usually see advertised in a list of available WiFi networks on your computer. It should match exactly.
  • CIRCUITPY_WIFI_PASSWORD: This is the password for your WiFi network. It should also match exactly.
  • CIRCUITPY_WEB_API_PASSWORD: This is the password that is used to protect access to the files on your device when connecting with Web Workflow. This is what you will type in when prompted for a password. You will want to change it to something that you'll remember.
  • CIRCUITPY_WEB_API_PORT: This is the TCP port that the built-in Web Workflow web server on the device will use. At this point in time, the Code Editor hasn't been thoroughly tested with ports other than the default, so leaving it at port 80 is recommended.

If you would like a more technical detail of the underlying aspects of Web Workflow, be sure to check out the official CircuitPython documentation.

Disabling USB Mass Storage

One of the more challenging aspects of using web workflow is that in order to avoid corrupting files, the USB mass storage device needs to be disabled on native USB chipsets like ESP32-S2/ESP32-S3, otherwise the files will only be available in read-only mode over the WiFi link.

The easiest way to do this is to simply eject the CIRCUITPY drive in your OS. However, this will only be temporary until the next time you reset the device or plug it back in. If you'd like it to stay disabled, you can create a boot.py file in the root folder of the CIRCUITPY drive with the following contents:

import storage

storage.disable_usb_drive()

Once you have saved the file, go ahead and perform a hard reset on the board by pressing the reset button or by temporarily disconnecting it from power. After it starts back up, the CIRCUITPY drive should no longer appear. If you'd like to learn more about editing boot.py to customize the device, check out the Customizing USB Devices in CircuitPython guide.

Re-enabling USB Mass Storage

If you find you want to access the mass storage device after you have disabled it, there are a couple of ways you can do it. The first way to temporarily enable it is to boot it into safe mode. To do this, just reset the device and while it is booting, pay attention to the status NeoPixel. When it starts flashing yellow, press the boot button.

Alternatively, if you'd like to permanently re-enable it, you can run the following code from a serial terminal to remove the boot.py file:

import storage
import os
storage.remount("/", False)
os.remove("/boot.py")

After hard resetting your device, the CIRCUITPY drive should reappear, though re-enabling it will cause web workflow to be in read-only mode again.

Dealing with Multiple WiFi Networks

If you need to switch between multiple WiFi networks and would like to do so without re-enabling the Mass Storage Device and editing the .env file, you can use the following script to automatically switch between different .env files.

# SPDX-FileCopyrightText: 2022 Melissa LeBlanc-Williams for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import os
import storage
import microcontroller

# Get all files in the format of .env.xxxxxxxxxx
def enumerate_env_files():
    found_files = []
    all_files = os.listdir("/")
    for current_file in all_files:
        if current_file[:4] == ".env" and len(current_file) > 4:
            found_files.append(current_file)
    return found_files


# Compare .env to enumerated env files
def get_current_env_file(enumerated_files):
    with open(".env") as env:
        env_lines = env.readlines()
        for env_file in enumerated_files:
            with open(env_file) as f:
                lines = f.readlines()
                if len(env_lines) != len(lines):
                    continue
                file_may_match = True
                for line_no, env_line in enumerate(env_lines):
                    if env_line != lines[line_no]:
                        file_may_match = False
                        break
                if not file_may_match:
                    continue
                return env_file
    return None


# Erase .env then write the contents of the new env file
def change_env_file(env_file):
    try:
        storage.remount("/", False)
        open(".env", "w").close()
        with open(".env", "w") as env, open(env_file) as f:
            for line in f.readlines():
                env.write(line)
        env.close()
        print("Done. Hard resetting board...")
        microcontroller.reset()
    except RuntimeError:
        print("You can't change the env file with this script while USB is mounted")


# Return a prettier name than the env file
def pretty_name(env_file):
    name = env_file[5:]
    name = name[0].upper() + name[1:]
    return f"{name} .env file"

env_files = enumerate_env_files()

if len(env_files) < 2:
    print("You need to have at least 2 env files to change")

result = get_current_env_file(env_files)
if result:
    env_files.remove(result)
print("WARNING: This will overwrite all of your current .env file settings.")
if len(env_files) == 1:
    answer = input(f"Change to {pretty_name(env_files[0])}? ")
    answer = answer.lower()
    if answer in ("y", "yes"):
        change_env_file(env_files[0])
else:
    valid_selection = False
    while not valid_selection:
        print("Select an option:")
        for index, file in enumerate(env_files):
            print(f"{index + 1}: {pretty_name(file)}")
        answer = input("Which option would you like? ")
        if answer.isdigit() and 0 < int(answer) <= len(env_files):
            valid_selection = True
            change_env_file(env_files[int(answer) - 1])
        print(f"{answer} was an invalid selection.\n")

To use the script, just copy it into the root folder of your CIRCUITPY drive. Then you will want to create at least 2 copies of the .env file in the root folder as well. Just name them something like .env.home, .env.school, or .env.work. Make any changes to each file for the particular environment that you will be in.

To run the script, just connect to the device with a serial terminal, press a key to enter the REPL, and type import env. If you only have two files and one of them is identical to the .env file, it will just ask you if you want to change to the other file. Just type 'y' or 'yes' followed by pressing enter to change it. Anything else will abort. If you have more files or at least 2 of them are different from the current .env file, it will prompt you to select the one you want to change to. Just enter the number of next to the file and press enter or you can press Control+C to stop the script and abort making changes.

Once you select a file, it will overwrite the contents of the current .env file, so be sure you don't have anything unique in there that you wouldn't want to lose.

After you select a file, it will automatically hard reset the board and immediately start using the new .env file. This makes it very easy to use the board in a variety of settings or even switch between different WiFi networks in the same location.

This guide was first published on Sep 07, 2022. It was last updated on Sep 07, 2022.

This page (Device Setup) was last updated on Sep 02, 2022.

Text editor powered by tinymce.