Some of the CircuitPython compatible boards come with CircuitPython installed. Others are CircuitPython-ready, but need to have it installed. As well, you may want to update the version of CircuitPython already installed on your board. The steps are the same for installing and updating. Here we will cover how to install or update CircuitPython on your board.
Download the latest version!
The first thing you'll want to do is download the most recent version of CircuitPython.
If you're already running CircuitPython, make sure you're running the latest version! If you're unsure, you can follow the steps below to ensure you have the latest version installed.
ALWAYS BACKUP YOUR CODE BEFORE INSTALLING OR UPDATING CIRCUITPYTHON. Most of the time, nothing will be removed from your board during the update, but it can happen. If you already have code on your board, be sure to back it up to your computer before following the steps below.
Download the latest software for your board by clicking the green button below to go to CircuitPython.org.
Next, you'll want to plug in your board using a known-good USB data cable. Make sure the USB cable is a data cable! There are some that work only for charging and can lead to a lot of frustration.
If you're using Windows 7, use the link below to download the driver package. You will not need to install drivers on Mac, Linux or Windows 10.
Start the UF2 Bootloader
Nearly all CircuitPython boards ship with a bootloader called UF2 (USB Flashing Format) that makes installing and updating CircuitPython a quick and easy process. The bootloader is the mode your board needs to be in for the CircuitPython .uf2 file you downloaded to work. If the file you downloaded that matches the board name ends in uf2 then you want to continue with this section. However, if the file ends in .bin then you have to do a more complex installation - go to this page for how to do that.
Find the reset button on your board. It's a small, black button, and on most of the boards, it will be the only button available. (On Circuit Playground Express, it's the smaller button located in the center of the board.)
Tap this button twice to enter the bootloader. If it doesn't work on the first try, don't be discouraged. The rhythm of the taps needs to be correct and sometimes it takes a few tries. If you have a Circuit Playground Express, and it's fresh-out-of-the-bag try pressing the button once.
Once successful, the RGB LED on the board will flash red and then stay green. A new drive will show up on your computer. The drive will be called boardnameBOOT where boardname is a reference to your specific board. For example, a Feather will have FEATHERBOOT and a Trinket will have TRINKETBOOT etc. Going forward we'll just call the boot drive BOOT
The board is now in bootloader mode! This is what we need to install or update CircuitPython.
Now find the file you downloaded. Drag that file to the BOOT drive on your computer.
The lights should flash again, BOOT will disappear and a new drive will show up on your computer called CIRCUITPY.
Congratulations! You've successfully installed or updated CircuitPython!
What's the difference between CIRCUITPY and boardnameBOOT?
When you plug a CircuitPython board into your computer, your computer will see the board's flash memory as a USB flash drive where files can be stored. When you have successfully installed CircuitPython, you'll see the CIRCUITPY drive. When you double-tap the reset button, you'll see the boardnameBOOT drive. You can drag files to both, but only CIRCUITPY will run your CircuitPython code.
Normally, when you drag a file to a mounted USB drive, the file copies to the drive and then is able to be seen in your file explorer. However, when you drag the CircuitPython UF2 file to the boardnameBOOT drive, it seems to disappear, and the drive disconnects. This is normal! The UF2 is essentially an installer file, and does not simply sit on the drive, but installs CircuitPython if the board is in bootloader mode (i.e. boardnameBOOT).
You will be able to copy other files to the bootloader drive (boardnameBOOT) but they will not run or be accessible to CircuitPython. So make sure that once you're done installing CircuitPython, that you're dragging to and editing files on the CIRCUITPY drive!
Bootloader Drive Names
This list is not exhaustive, but should give you an idea what to look for in a bootloader drive name.
- Trinket M0 =
TRINKETBOOT - Gemma M0 =
GEMMABOOT - Circuit Playground Express =
CPLAYBOOT - ItsyBitsy M0 Express =
ITSYBOOT - ItsyBitsy M4 Express =
ITSYM4BOOT - Feather M0 Express =
FEATHERBOOT - Feather M4 Express =
FEATHERBOOT - Metro M0 Express =
METROBOOT - Metro M4 Express =
METROM4BOOT - Grand Central M4 Express =
GCM4BOOT - NeoTrelis M4 Express =
TRELM4BOOT
