Installing CircuitPython

Once you have UF2 installed on your board, you will need to download and install the latest version of CircuitPython for your particular board. Note that the steps are the same for installing and updating CircuitPython.

Caveats for CircuitPython on Non-Express Boards

On one hand, its pretty cool we can install CircuitPython on any SAMD21 processor. But there's a few gotchas:

  • Boards that don't have SPI flash on them need to put the filesystem in flash, that means you only get about 48 KB of filesystem space
  • That extra filesystem allocation means less CircuitPython firmware space
  • So some things like long-ints and audio playback, are not supported on these builds!

You will have plain digital IO, I2C, SPI, UART, analog inputs, basic DAC output, capacitive touch.

Download the Latest Version of CircuitPython

Navigate to the CircuitPython GitHub repository, and click on the Releases tab. Alternatively, this link will take you there:

You only have to install CircuitPython ONCE, after that you are free to code all you like without going through this process again until it's time to upgrade!

Up until March, 2019, CircuitPython releases were downloaded from the Adafruit CircuitPython GitHub repository. 

Starting April, 2019, Adafruit encourages developers to download CircuitPython from the CircuitPython.org website. The site is arranged by board and it makes finding code easier. The board must have a pull request in by a developer to add CircuitPython capability and have it accepted by the CircuitPython team to be listed in the CircuitPython.org repository. Both Adafruit and non-Adafruit boards are on that site.

For now, the releases will also be on GitHub under the Adafruit umbrella, but this may change as the migration continues to CircuitPython.org.

Scroll down, and look for the latest release for your particular board. Specifically, you will want the .uf2 file for your board.

Note that the most recent releases are located at the top of the page. The file will have the following naming scheme (with [your board's name] replaced by the name of your board and x.x.x replaced by the newest release number):

adafruit-circuitpython-[your board's name]-x.x.x.uf2

For example, if you wanted to download the CircuitPython installation file for the Arduino MKRZero, you look for the filename adafruit-circuitpython-arduino_mkrzero-x.x.x.uf2. Click on the name to download the .uf2 file.

Want to check out the bleeding edge? The latest automated buildes are in https://adafruit-circuit-python.s3.amazonaws.com/index.html?prefix=bin

Plug in your board using a USB cable.

Start the UF2 Bootloader

If you just uploaded UF2 to your board, it should run the UF2 bootloader by default.

A bootloader is a program that runs on your microcontroller that waits to receive a new program. Once it receives that program, it writes the new program to the microcontroller's memory. Upon reset, the microcontroller will begin running the new program instead of the bootloader (unless you specifically tell the microcontroller to run the bootloader instead).

If, at any point, you need to access the UF2 bootloader, you can tap the RESET button on your board twice in quick succession.

Almost all microcontroller boards will have a Reset button. Note that it might be labeled RESET or RST. For example, the MKR Zero has a Reset button located next to the battery connector.

With UF2, you need to tap this button twice. If it does not work on the first try, give it another shot! It might take a few tries to get the rhythm correct.

If your board has an onboard LED, it should begin to fade on and off slowly. Additionally, you should see a new drive appear on your computer with the name [your board's name]BOOT. For example, a MKR Zero will appear as MKRZEROBOOT.

If you see the -BOOT drive, it means that you are in bootloader mode. We can now install or update CircuitPython.

Locate the .uf2 file that you downloaded and copy it to the -BOOT drive.

Wait a moment, and the -BOOT drive should disappear. Your board will reset, and a CIRCUITPY drive will show up on your computer. If you see this, you know that you've installed CircuitPython correctly!

This guide was first published on Dec 14, 2018. It was last updated on Dec 14, 2018. This page (Installing CircuitPython) was last updated on Aug 19, 2019.