CircuitPython is a derivative of MicroPython designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. ESP32 CircuitPython firmware is uploaded to the board via the USB serial port.

Follow this step-by-step to get CircuitPython running on your board.

Driver Install

If this is your first time using an ESP32 board on Windows or MacOS, you may need to install the USB to serial drivers. There are two options for the USB to serial chipset on your board. If you are unsure which one you have, install both drivers.

For instructions and more information regarding the CH9102F chip and driver install, please visit the How To Install Drivers for WCH USB to Serial Chips guide.

For driver downloads for the CP2104 and CP2012N, please visit the Silicon Labs Downloads page.

For those running Linux, the drivers are already included.

CircuitPython Download

Click the link above to download the latest CircuitPython .bin file.

Save it wherever is convenient for you.

Connecting to the Web Flasher

To begin, plug your board into your computer via USB, using a known-good data-sync cable, directly, or via an adapter if needed.

You will have to use the Chrome or a Chromium-based browser to install CircuitPython. For example, Edge and Opera are Chromium based.

Safari and Firefox, etc are not supported - they have not implemented Web Serial!

In the Chrome browser visit https://adafruit.github.io/Adafruit_WebSerial_ESPTool/

The main page of the ESP Web Flasher should look something like this.

Note: The site now displays an alert that it is no longer maintained, and suggests using a different option. The ESP Web Flasher has still proven to be more consistent and easier to use, so it is highly suggested that you continue with this version.

You should remove all other USB devices so only the target board is attached. This eliminates confusion over multiple ports!

Press the Connect button in the top right of the web browser. You will get a pop up asking you to select the COM or Serial port. Look for USB Single Serial.

On some systems, such as MacOS, there may be additional system ports that appear in the list (as shown in the image).

The Javascript code will now try to connect to the board. It may timeout for a bit until it succeeds. On success, you will see that it is Connected and will print out a unique MAC address identifying the board along with other information that was detected.

Once you have successfully connected, the command toolbar will appear.

Erasing the Board Contents

If you would like to erase the entire flash area so that you can start with a clean slate, you can use the erase feature. We recommend doing this every time before installing or updating CircuitPython.

To erase the contents, click the Erase button. You will be prompted as to whether you want to continue. Click OK to continue. If you do not wish to continue, click Cancel.

You'll see "Erasing flash memory. Please wait..." This will eventually be followed by "Finished." and the amount of time it took to erase.

Do not disconnect! Immediately continue on to Programming the Board.

Do not disconnect after erasing! You should immediately continue on to programming your board. If you do not, you may end up with your board in a bad state that makes it more difficult to continue. You can avoid this!

Programming the Board

You can click on Choose a file... from any of the available buttons. It will only attempt to program buttons with a file and a unique location. Select the  .bin file you downloaded at the beginning of this page from the file chooser dialogue.

Verify that the Offset box next to the file location you used is 0x0. The offset defaults to 0x0, so unless you changed it manually, it should be good to go.

Once you choose a file, the button text will change to match your filename. You can then click the Program button to start flashing.

A progress bar will appear and after a minute or two, you will have written the firmware.

You've now successfully programmed CircuitPython onto your board! As suggested in the output, press reset to run the new firmware.

As the ESP32 does not have native USB, no USB drive will show up on your computer when you reset. With CircuitPython firmware loaded, the REPL can be accessed over a serial/COM port.

For more details on installation, how to configure your ESP32, and info on getting started with CircuitPython on your ESP32 using the Web Workflow, check out the CircuitPython on ESP32 Quick Start guide.

This guide was first published on Mar 16, 2022. It was last updated on Apr 17, 2024.

This page (CircuitPython) was last updated on Apr 02, 2024.

Text editor powered by tinymce.