Adafruit CircuitPython User Manual

Welcome to CircuitPython!

Created by Kattni Rembor

Last updated on 2021-04-26 11:59:33 AM EDT

2 5

6 6

8 8 8 8 8 9 9 9 9 9 9

9 10 10

11 11 11 13 13 14 14 16

18 18 18

18 19 20 20

21 22

22 24

25 26 26

26 26

27 27

Guide Contents

Guide Contents Welcome To CircuitPython

This guide will get you started with CircuitPython!

What is CircuitPython? CircuitPython is based on Python

Why would I use CircuitPython?

Frequently Asked Questions

I have to continue using an older version of CircuitPython; where can I find compatible libraries? Is ESP8266 or ESP32 supported in CircuitPython? Why not? How do I connect to the Internet with CircuitPython? Is there asyncio support in CircuitPython? My RGB NeoPixel/DotStar LED is blinking funny colors - what does it mean? What is a MemoryError? What do I do when I encounter a MemoryError? Can the order of my import statements affect memory? How can I create my own .mpy files? How do I check how much memory I have free? Does CircuitPython support interrupts? Does Feather M0 support WINC1500? Can AVRs such as ATmega328 or ATmega2560 run CircuitPython? Commonly Used Acronyms

Installing Mu Editor Download and Install Mu Using Mu Installing CircuitPython Download the latest version! Windows 7 and 8.1 Drivers Start the UF2 Bootloader What's the difference between CIRCUITPY and boardnameBOOT?

Bootloader Drive Names

The CIRCUITPY Drive Working with Multiple Devices Renaming CIRCUITPY

Renaming CIRCUITPY on Mac Renaming CIRCUITPY on Windows Renaming CIRCUITPY on Linux Renaming CIRCUITPY through CircuitPython

Reverting to CIRCUITPY Creating and Editing Code

Creating Code Editing Code

Your code changes are run as soon as the file is done saving.

1. Use an editor that writes out the file completely when you save it.

2. Eject or Sync the Drive After Writing Oh No I Did Something Wrong and Now The CIRCUITPY Drive Doesn't Show Up!!!

Back to Editing Code... Exploring Your First CircuitPython Program

Imports & Libraries Setting Up The LED

27 28 28

28 29 30 30

31 32 35 38 39

39 40 40 41 42

42 43

44 45

46 47 47

48 49 50 51

52 52 52 53 55 55 57 58 60 67 67 67 67

67 68 68 68 69

Loop-de-loops What Happens When My Code Finishes Running? What if I don't have the loop?

More Changes Naming Your Program File Connecting to the Serial Console Are you using Mu?

Setting Permissions on Linux

Using Something Else? Interacting with the Serial Console The REPL Returning to the serial console CircuitPython Hardware

Trinket M0 Gemma M0 Circuit Playground Express Feather M0 Express Metro M0 Express

What's Next? CircuitPython Libraries

Installing the CircuitPython Library Bundle Example Files

Copying Libraries to Your Board

Example: ImportError Due to Missing Library Library Install on Non-Express Boards Updating CircuitPython Libraries/Examples

Welcome to the Community!

Adafruit Discord Adafruit Forums Adafruit Github ReadTheDocs

Advanced Serial Console on Windows Windows 7 Driver What's the COM? Install Putty Advanced Serial Console on Mac and Linux What's the Port? Connect with screen Permissions on Linux PyCharm and CircuitPython CircuitPython for ESP8266 Why are we dropping support for ESP8266? About ESP8266 for CircuitPython (3.x) Installing CircuitPython on the ESP8266

Download esptool Download Latest CircuitPython Firmware Get ESP8266 Ready For Bootloading Erase ESP8266 Program ESP8266

70 70 71

71 72 74

74 74 74

76 76 77 77

77 78

80 80

80 80 81 81 81

82 82 82 83 83 83 84 84

85 85 86

87 87 87 87 88 88

89 91

Upload Libraries & Files Using Ampy! Other Stuff To Know! Uninstalling CircuitPython

Backup Your Code

Moving Circuit Playground Express to MakeCode Moving to Arduino Non-UF2 Installation

Flashing with Bossac - For Non-Express Feather M0's & Arduino Zero Command-Line ahoy! Download Latest CircuitPython Firmware

Alternatively, use GitHub

Download BOSSA Test bossac Get Into the Bootloader Run the bossac Command

Using bossac Version 1.7.0 Using bossac Versions 1.8, and 1.9 or Later

Troubleshooting Always Run the Latest Version of CircuitPython and Libraries I have to continue using CircuitPython 5.x, 4.x, 3.x or 2.x, where can I find compatible libraries? CPLAYBOOT, TRINKETBOOT, FEATHERBOOT, or GEMMABOOT Drive Not Present

You may have a different board. MakeCode MacOS Windows 10 Windows 7 or 8.1

Windows Explorer Locks Up When Accessing boardnameBOOT Drive Copying UF2 to boardnameBOOT Drive Hangs at 0% Copied CIRCUITPY Drive Does Not Appear Windows 7 and 8.1 Problems Serial Console in Mu Not Displaying Anything CircuitPython RGB Status Light ValueError: Incompatible .mpy file. CIRCUITPY Drive Issues

Easiest Way: Use storage.erase_filesystem() Old Way: For the Circuit Playground Express, Feather M0 Express, and Metro M0 Express: Old Way: For Non-Express Boards with a UF2 bootloader (Gemma M0, Trinket M0): Old Way: For non-Express Boards without a UF2 bootloader (Feather M0 Basic Proto, Feather Adalogger, Arduino Zero):

Running Out of File Space on Non-Express Boards

Delete something! Use tabs MacOS loves to add extra files. Prevent & Remove MacOS Hidden Files Copy Files on MacOS Without Creating Hidden Files Other MacOS Space-Saving Tips

Device locked up or boot looping CircuitPython Essentials

Welcome To CircuitPython

So, you've got this new CircuitPython compatible board. You plugged it in. Maybe it showed up as a disk

drive called CIRCUITPY. Maybe it didn't! Either way, you need to know where to go from here. Well, we've

got you covered!

This guide will get you started with CircuitPython!

There are many amazing things about your new board. One of them is the ability to run CircuitPython. You

may have seen that name on the Adafruit site somewhere. Not sure what it is? We can help!

"But I've never coded in my life. There's no way I do it!" You absolutely can! CircuitPython is designed to

help you learn from the ground up. If you're new to everything, this is the place to start!

This guide will walk you through how to get started with CircuitPython. You'll learn how to install

CircuitPython, get updated to the newest version of CircuitPython, how to setup a serial connection, and

how to edit the files.

Welcome to CircuitPython!

What is CircuitPython?

CircuitPython is a programming language designed to simplify experimenting and learning to program on

low-cost microcontroller boards. It makes getting started easier than ever with no upfront desktop

downloads needed. Once you get your board set up, open any text editor, and get started editing code.

It's that simple.

CircuitPython is based on Python

Python is the fastest growing programming language. It's taught in schools and universities. It's a high-

level programming language which means it's designed to be easier to read, write and maintain. It

supports modules and packages which means it's easy to reuse your code for other projects. It has a built

in interpreter which means there are no extra steps, like

compiling

, to get your code to work. And of

course, Python is Open Source Software which means it's free for anyone to use, modify or improve upon.

CircuitPython adds hardware support to all of these amazing features. If you already have Python

knowledge, you can easily apply that to using CircuitPython. If you have no previous experience, it's really

simple to get started!

Why would I use CircuitPython?

CircuitPython is designed to run on microcontroller boards. A microcontroller board is a board with a

microcontroller chip that's essentially an itty-bitty all-in-one computer. The board you're holding is a

microcontroller board! CircuitPython is easy to use because all you need is that little board, a USB cable,

and a computer with a USB connection. But that's only the beginning.

Other reasons to use CircuitPython include:

You want to get up and running quickly. Create a file, edit your code, save the file, and it runs

immediately. There is no compiling, no downloading and no uploading needed.

You're new to programming. CircuitPython is designed with education in mind. It's easy to start

learning how to program and you get immediate feedback from the board.

Easily update your code. Since your code lives on the disk drive, you can edit it whenever you like,

you can also keep multiple files around for easy experimentation.

The serial console and REPL. These allow for live feedback from your code and interactive

programming.

File storage. The internal storage for CircuitPython makes it great for data-logging, playing audio

clips, and otherwise interacting with files.

Strong hardware support. There are many libraries and drivers for sensors, breakout boards and

other external components.

It's Python! Python is the fastest-growing programming language. It's taught in schools and

universities. CircuitPython is almost-completely compatible with Python. It simply adds hardware

support.

This is just the beginning. CircuitPython continues to evolve, and is constantly being updated. We

welcome and encourage feedback from the community, and we incorporate this into how we are

developing CircuitPython. That's the core of the open source concept. This makes CircuitPython better for

you and everyone who uses it!

Frequently Asked Questions

These are some of the common questions regarding CircuitPython and CircuitPython microcontrollers.

 As we continue to develop CircuitPython and create new releases, we will stop supporting older

releases. Visit https://circuitpython.org/downloads to download the latest version of CircuitPython for

your board. You must download the CircuitPython Library Bundle that matches your version of

CircuitPython. Please update CircuitPython and then visit https://circuitpython.org/libraries to

download the latest Library Bundle.

I have to continue using an older version of CircuitPython; where can I find compatible libraries?

We are no longer building or supporting library bundles for older versions of CircuitPython. We highly

encourage you to update CircuitPython to the latest version (https://adafru.it/Em8) and use the current

version of the libraries (https://adafru.it/ENC). However, if for some reason you cannot update, here are

points to the last available library bundles for previous versions:

2.x (https://adafru.it/FJA)

3.x (https://adafru.it/FJB)

4.x (https://adafru.it/QDL)

5.x (https://adafru.it/QDJ)



Is ESP8266 or ESP32 supported in CircuitPython? Why not?

We dropped ESP8266 support as of 4.x - For more information please read about it here!

https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-for-esp8266 (https://adafru.it/CiG)

We do not support ESP32 because it does not have native USB. We do support ESP32-S2, which does.



How do I connect to the Internet with CircuitPython?

If you'd like to add WiFi support, check out our guide on ESP32/ESP8266 as a co-

processor. (https://adafru.it/Dwa)



Is there asyncio support in CircuitPython?

We do not have asyncio support in CircuitPython at this time. However, async and await are turned on in

many builds, and we are looking at how to use event loops and other constructs effectively and easily.



My RGB NeoPixel/DotStar LED is blinking funny colors - what does it mean?

The status LED can tell you what's going on with your CircuitPython board. Read more here for what the

colors mean! (https://adafru.it/Den)

What is a MemoryError ?

Memory allocation errors happen when you're trying to store too much on the board. The CircuitPython

microcontroller boards have a limited amount of memory available. You can have about 250 lines of code

on the M0 Express boards. If you try to import too many libraries, a combination of large libraries, or run a

program with too many lines of code, your code will fail to run and you will receive a MemoryError in the

serial console (REPL).

What do I do when I encounter a MemoryError ?

Try resetting your board. Each time you reset the board, it reallocates the memory. While this is unlikely to

resolve your issue, it's a simple step and is worth trying.

Make sure you are using .mpy versions of libraries. All of the CircuitPython libraries are available in the

bundle in a .mpy format which takes up less memory than .py format. Be sure that you're using the latest

library bundle (https://adafru.it/uap) for your version of CircuitPython.

If that does not resolve your issue, try shortening your code. Shorten comments, remove extraneous or

unneeded code, or any other clean up you can do to shorten your code. If you're using a lot of functions,

you could try moving those into a separate library, creating a .mpy of that library, and importing it into

your code.

You can turn your entire file into a .mpy and import that into code.py . This means you will be unable to

edit your code live on the board, but it can save you space.

Can the order of my import statements affect memory?

It can because the memory gets fragmented differently depending on allocation order and the size of

objects. Loading .mpy files uses less memory so its recommended to do that for files you aren't editing.

How can I create my own .mpy files?

You can make your own .mpy versions of files with mpy-cross .

You can download mpy-cross for your operating system from https://adafruit-circuit-

python.s3.amazonaws.com/index.html?prefix=bin/mpy-cross/ (https://adafru.it/QDK). Almost any version

will do. The format for .mpy files has not changed since CircuitPython 4.x.

To make a .mpy file, run ./mpy-cross path/to/yourfile.py to create a yourfile.mpy in the same directory as the

original file.

How do I check how much memory I have free?

import gc gc.mem_free()

Will give you the number of bytes available for use.

Does CircuitPython support interrupts?

No. CircuitPython does not currently support interrupts. We do not have an estimated time for when they

will be included.

Does Feather M0 support WINC1500?

No, WINC1500 will not fit into the M0 flash space.

Can AVRs such as ATmega328 or ATmega2560 run CircuitPython?

No.

Commonly Used Acronyms

CP or CPy = CircuitPython (https://adafru.it/cpy-welcome)

CPC = Circuit Playground Classic (https://adafru.it/ncE)

CPX = Circuit Playground Express (https://adafru.it/wpF)

Installing Mu Editor

Mu is a simple code editor that works with the Adafruit CircuitPython boards. It's written in Python and

works on Windows, MacOS, Linux and Raspberry Pi. The serial console is built right in so you get

immediate feedback from your board's serial output!

 Mu is our recommended editor - please use it (unless you are an experienced coder with a favorite

editor already!)

Download and Install Mu

Download Mu from https://codewith.mu (https://adafru.it/Be6).

Click the Download or Start Here links there for downloads

and installation instructions. The website has a wealth of other

information, including extensive tutorials and and how-to's.

Using Mu

The first time you start Mu, you will be prompted to select

your 'mode' - you can always change your mind later. For now

please select CircuitPython!

The current mode is displayed in the lower right corner of the

window, next to the "gear" icon. If the mode says "Microbit" or

something else, click the Mode button in the upper left, and

then choose "CircuitPython" in the dialog box that appears.

Mu attempts to auto-detect your board, so please plug in your

CircuitPython device and make sure it shows up as

a CIRCUITPY drive before starting Mu

You can now explore Mu! The three main sections of the window are labeled below; the button bar, the

text editor, and the serial console / REPL.

Now you're ready to code! Let's keep going...

Installing CircuitPython

 As we continue to develop CircuitPython and create new releases, we will stop supporting older

releases. If you are running earlier versions of CircuitPython, you need to update to the latest.

Generally Adafruit will support the last two major versions.

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.

 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!

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 (https://adafru.it/Em8).

https://adafru.it/Em8

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.

Windows 7 and 8.1 Drivers

 If you're using Windows 7 or 8.1, you need to install a driver before plugging in your board.

If you're using Windows 7 or 8.1, use the link below to download the driver package. You will not need to

install drivers on Mac, Linux or Windows 10.

https://adafru.it/AB0

We recommend that you upgrade to Windows 10 if possible. Windows 10 makes the drivers unnecessary

and solves other problems. As of this writing, you can still upgrade

for free

from Windows 7 or 8.1 to

Windows 10, though it's not widely known this is possible. See these (https://adafru.it/RWb)

links (https://adafru.it/RWc).

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. (https://adafru.it/Bed)

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

https://adafru.it/AB0

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

The CIRCUITPY Drive

When CircuitPython finishes installing, or you plug a CircuitPython board into your computer with

CircuitPython already installed, the board shows up on your computer as a USB drive called CIRCUITPY.

The CIRCUITPY drive is where your code and the necessary libraries and files will live. You can edit your

code directly on this drive and when you save, it will run automatically. When you create and edit code,

you'll save your code in a code.py file located on the CIRCUITPY drive. If you're following along with a

Learn guide, you can paste the contents of the tutorial example into code.py on the CIRCUITPY drive and

save it to run the example.

With a fresh CircuitPython install, on your CIRCUITPY drive, you'll find a code.py file containing print("Hello

World!") and an empty lib folder. If your CIRCUITPY drive does not contain a code.py file, you can easily

create one and save it to the drive. CircuitPython looks for code.py and executes the code within the file

automatically when the board starts up or resets. Following a change to the contents of CIRCUITPY, such

as making a change to the code.py file, the board will reset, and the code will be run. You do not need to

manually run the code. This is what makes it so easy to get started with your project and update your

code!

Note that all changes to the contents of CIRCUITPY, such as saving a new file, renaming a current file, or

deleting an existing file will trigger a reset of the board.

Working with Multiple Devices

There are many boards that work with CircuitPython. You may find yourself in a situation where you're

working with more than one board at the same time. What happens when you have multiple boards

plugged into your computer? You have multiple CIRCUITPY drives! How do you know which one is which?

You can rename each CIRCUITPY drive to avoid confusion.

Renaming CIRCUITPY

When you rename CIRCUITPY, it writes the name to the filesystem. This means that the name change will

persist through disconnecting the board, as well as reloading CircuitPython!

The name must be 11 characters or less! This is a limitation of the filesystem. You will receive an error if

you choose a name longer than 11 characters.

Renaming CIRCUITPY on Mac

Renaming your CIRCUITPY drive on Mac is simple. Click on

the drive in Finder so you can see the contents. Then, right

click on the drive in Finder and choose "Rename".

Once you click "Rename", in the right-click menu, the drive

name will show up in a text box where you can rename the

drive. Type in the new name.

Renaming CIRCUITPY on Windows

Renaming the CIRCUITPY drive on Windows is easy. Open File Explorer and find the CIRCUITPY drive.

Right click on it, and click "Rename".

Renaming the CIRCUITPY drive on Windows is easy. Open

File Explorer and find the CIRCUITPY drive. Right click on it,

and click "Rename".

You can also rename the drive through the "Properties" menu,

which can be opened several different ways through the

Windows File Explorer, including right clicking on the

CIRCUITPY drive and choosing "Properties".

Once you click "Rename" in the right-click menu, the drive

name will show up in a text box where you can rename the

drive. Type in the new name.

Renaming CIRCUITPY on Linux

Renaming CIRCUITPY on Linux requires a couple of steps. You'll need to identify the mount point, and

then run a command to rename the drive.

Open a terminal program. Run the following to find out where your board is mounted:

df | grep CIRCUITPY

You will see CIRCUITPY on the right end of the resulting line. The dev/foo (where foo is the name of the

mount point) on the left end of that line is the mount point.

Next you can run the following to unmount the board, replacing foo with your specific mount point.

sudo umount /dev/foo

To rename the board, run the following:

sudo fatlabel /dev/foo NEW_NAME

Then, eject your board, unplug it, and plug it back in to force it to remount with the new name.

To check to see if it worked, look for the drive in your file manager. Or, you can run the following:

df | grep NEW_NAME

Renaming CIRCUITPY through CircuitPython

You can also rename the board using CircuitPython. Create a new file on your CIRCUITPY drive called

boot.py . Copy the following code into the new boot.py file:

import storage

storage.remount("/", readonly=True)

m = storage.getmount("/") m.label = "NEW_NAME"

storage.remount("/", readonly=False)

Eject your board, and reboot the board either by pressing the reset button once, or unplugging it and

plugging it back in. After a moment, it should show up in your file explorer with the NEW_NAME you

chose for it! You can delete boot.py after the newly named board shows up in your file explorer.

Reverting to CIRCUITPY

You can follow the same processes above to rename the drive back to CIRCUITPY.

You will also revert to CIRCUITPY by erasing the filesystem. If you are in a situation where you need to

erase the filesystem on your CircuitPython board, the drive name will revert to CIRCUITPY on completion.

Creating and Editing Code

One of the best things about CircuitPython is how simple it is to get code up and running. In this section,

we're going to cover how to create and edit your first CircuitPython program.

To create and edit code, all you'll need is an editor. There are many options. We strongly recommend

using Mu! It's designed for CircuitPython, and it's really simple and easy to use, with a built in serial

console!

If you don't or can't use Mu, there are basic text editors built into every operating system such as Notepad

on Windows, TextEdit on Mac, and gedit on Linux. However, many of these editors don't write back

changes immediately to files that you edit. That can cause problems when using CircuitPython. See the

Editing Code (https://adafru.it/id3) section below. If you want to skip that section for now, make sure you

do "Eject" or "Safe Remove" on Windows or "sync" on Linux after writing a file if you aren't using Mu. (This

is not a problem on MacOS.)

Creating Code

Open your editor, and create a new file. If you are using Mu,

click the New button in the top left

Copy and paste the following code into your editor:

import board import digitalio import time

led = digitalio.DigitalInOut(board.D13) led.direction = digitalio.Direction.OUTPUT

while True: led.value = True time.sleep(0.5) led.value = False time.sleep(0.5)

 The QT Py does not have a D13 LED! There is an addressable RGB NeoPixel LED. The above

example will NOT work on the QT Py!

If you're using QT Py, please download the QT Py blink example (https://adafru.it/PE0).

 The QT Py blink example uses the onboard NeoPixel, but the time code is the same. You can use the

linked QT Py example to follow along with this guide page.

 If you are using Adafruit CLUE, you will need to edit the code to use board.D17 as shown below!

For Adafruit CLUE, you'll need to use board.D17 instead of board.D13 . The rest of the code remains the

same. Make the following change to the led = line:

led = digitalio.DigitalInOut(board.D17)

 If you are using Adafruit ItsyBitsy nRF52840, you will need to edit the code to use board.BLUE_LED

as shown below!

For Adafruit ItsyBitsy nRF52840, you'll need to use board.BLUE_LED instead of board.D13 . The rest of the

code remains the same. Make the following change to the led = line:

led = digitalio.DigitalInOut(board.BLUE_LED)

It will look like this - note that under the while True: line, the

next four lines have spaces to indent them, but they're

indented exactly the same amount. All other lines have no

spaces before the text.

Save this file as code.py on your CIRCUITPY drive.

On each board (except the ItsyBitsy nRF52840) you'll find a tiny red LED. On the ItsyBitsy nRF52840, you'll

find a tiny blue LED.

The little LED should now be blinking. Once per second.

Congratulations, you've just run your first CircuitPython program!

Editing Code

To edit code, open the code.py file on your CIRCUITPY drive

into your editor.

Make the desired changes to your code. Save the file. That's

it!

Your code changes are run as soon as the file is done saving.

There's just one warning we have to give you before we continue...

 Don't Click Reset or Unplug!

The CircuitPython code on your board detects when the files are changed or written and will automatically

re-start your code. This makes coding very fast because you save, and it re-runs.

However, you must wait until the file is done being saved before unplugging or resetting your board! On

Windows using some editors this can sometimes take up to 90 seconds, on Linux it can take 30 seconds

to complete because the text editor does not save the file completely. Mac OS does not seem to have this

delay, which is nice!

This is really important to be aware of. If you unplug or reset the board before your computer finishes

writing the file to your board, you can corrupt the drive. If this happens, you may lose the code you've

written, so it's important to backup your code to your computer regularly.

There are a few ways to avoid this:

1. Use an editor that writes out the file completely when you save it.

Recommended editors:

mu (https://adafru.it/Be6) is an editor that safely writes all changes (it's also our recommended editor!)

emacs (https://adafru.it/xNA) is also an editor that will fulIy write files on save (https://adafru.it/Be7)

Sublime Text (https://adafru.it/xNB) safely writes all changes

Visual Studio Code (https://adafru.it/Be9) appears to safely write all changes

gedit on Linux appears to safely write all changes

IDLE (https://adafru.it/IWB), in Python 3.8.1 or later, was fixed (https://adafru.it/IWD) to write all changes

immediately

thonny (https://adafru.it/Qb6) fully writes files on save

Recommended

only

with particular settings or with add-ons:

vim (https://adafru.it/ek9) / vi safely writes all changes. But set up vim to not write

swapfiles (https://adafru.it/ELO) (.swp files: temporary records of your edits) to CIRCUITPY. Run vim

with vim -n , set the no swapfile option, or set the directory option to write swapfiles elsewhere.

Otherwise the swapfile writes trigger restarts of your program.

The PyCharm IDE (https://adafru.it/xNC) is safe if "Safe Write" is turned on in Settings->System

Settings->Synchronization (true by default).

If you are using Atom (https://adafru.it/fMG), install the fsync-on-save

package (https://adafru.it/E9m) so that it will always write out all changes to files on CIRCUITPY .

SlickEdit (https://adafru.it/DdP) works only if you add a macro to flush the disk (https://adafru.it/ven).

don't

recommend these editors:

notepad (the default Windows editor) and N otepad++ can be slow to write, so we recommend the

editors above! If you are using notepad, be sure to eject the drive (see below)

IDLE in Python 3.8.0 or earlier does not force out changes immediately

nano (on Linux) does not force out changes

geany (on Linux) does not force out changes

Anything else - we haven't tested other editors so please use a recommended one!

 If you are dragging a file from your host computer onto the CIRCUITPY drive, you still need to do step

2. Eject or Sync (below) to make sure the file is completely written.

2. Eject or Sync the Drive After Writing

If you are using one of our not-recommended-editors, not all is lost! You can still make it work.

On Windows, you can Eject or Safe Remove the CIRCUITPY drive. It won't actually eject, but it will force

the operating system to save your file to disk. On Linux, use the sync command in a terminal to force the

write to disk.

You also need to do this if you use Windows Explorer or a Linux graphical file manager to drag a file onto

CIRCUITPY



Oh No I Did Something Wrong and Now The CIRCUITPY Drive Doesn't Show Up!!!

Don't worry! Corrupting the drive isn't the end of the world (or your board!). If this happens, follow the

steps found on the Troubleshooting (https://adafru.it/Den) page of every board guide to get your board up

and running again.

Back to Editing Code...

Now! Let's try editing the program you added to your board. Open your code.py file into your editor. We'll

make a simple change. Change the first 0.5 to 0.1 . The code should look like this:

import board import digitalio import time

led = digitalio.DigitalInOut(board.D13) led.direction = digitalio.Direction.OUTPUT

while True: led.value = True time.sleep(0.1) led.value = False time.sleep(0.5)

Leave the rest of the code as-is. Save your file. See what happens to the LED on your board? Something

changed! Do you know why? Let's find out!

Exploring Your First CircuitPython Program

First, we'll take a look at the code we're editing.

Here is the original code again:

import board import digitalio import time

led = digitalio.DigitalInOut(board.D13) led.direction = digitalio.Direction.OUTPUT

while True: led.value = True time.sleep(0.5) led.value = False time.sleep(0.5)

Imports & Libraries

Each CircuitPython program you run needs to have a lot of information to work. The reason CircuitPython

is so simple to use is that most of that information is stored in other files and works in the background. The

files built into CircuitPython are called modules, and the files you load separately are called libraries.

Modules are built into CircuitPython. Libraries are stored on your CIRCUITPY drive in a folder called lib.

import board import digitalio import time

The import statements tells the board that you're going to use a particular library in your code. In this

example, we imported three modules: board , digitalio , and time . All three of these modules are built into

CircuitPython, so no separate library files are needed. That's one of the things that makes this an excellent

first example. You don't need any thing extra to make it work! board gives you access to the

hardware on

your board

, digitalio lets you

access that hardware as inputs/outputs

and time let's you pass time by

'sleeping'

Setting Up The LED

The next two lines setup the code to use the LED.

led = digitalio.DigitalInOut(board.D13) led.direction = digitalio.Direction.OUTPUT

Your board knows the red LED as D13 . So, we initialise that pin, and we set it to output. We set led to

equal the rest of that information so we don't have to type it all out again later in our code.

Loop-de-loops

The third section starts with a while statement. while True: essentially means, "forever do the following:".

while True: creates a loop. Code will loop "while" the condition is "true" (vs. false), and as True is never

False, the code will loop forever. All code that is indented under while True: is "inside" the loop.

Inside our loop, we have four items:

while True: led.value = True time.sleep(0.5) led.value = False time.sleep(0.5)

First, we have led.value = True . This line tells the LED to turn on. On the next line, we have time.sleep(0.5) .

This line is telling CircuitPython to pause running code for 0.5 seconds. Since this is between turning the

led on and off, the led will be on for 0.5 seconds.

The next two lines are similar. led.value = False tells the LED to turn off, and time.sleep(0.5) tells

CircuitPython to pause for another 0.5 seconds. This occurs between turning the led off and back on so

the LED will be off for 0.5 seconds too.

Then the loop will begin again, and continue to do so as long as the code is running!

So, when you changed the first 0.5 to 0.1 , you decreased the amount of time that the code leaves the

LED on. So it blinks on really quickly before turning off!

Great job! You've edited code in a CircuitPython program!

What Happens When My Code Finishes Running?

When your code finishes running, CircuitPython resets your microcontroller board to prepare it for the

next run of code. That means any set up you did earlier no longer applies, and the pin states are reset.

For example, try reducing the above example to led.value = True . The LED will flash almost too quickly to

see, and turn off. This is because the code finishes running and resets the pin state, and the LED is no

longer receiving a signal.

To that end, most CircuitPython programs involve some kind of loop, infinite or otherwise



What if I don't have the loop?

If you don't have the loop, the code will run to the end and exit. This can lead to some unexpected

behavior in simple programs like this since the "exit" also resets the state of the hardware. This is a

different behavior than running commands via REPL. So if you are writing a simple program that doesn't

seem to work, you may need to add a loop to the end so the program doesn't exit.

The simplest loop would be:

while True:

pass

And remember - you can press to exit the loop.

See also the Behavior section in the docs (https://adafru.it/Bvz).

More Changes

We don't have to stop there! Let's keep going. Change the second 0.5 to 0.1 so it looks like this:

while True: led.value = True time.sleep(0.1) led.value = False time.sleep(0.1)

+ 64 hidden pages

Adafruit CircuitPython User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual