Adafruit ItsyBitsy nRF52840 Express User guide

Adafruit ItsyBitsy nRF52840 Express

Created by Kattni Rembor

https://learn.adafruit.com/adafruit-itsybitsy-nrf52840-express

Last updated on 2023-07-02 01:29:03 PM EDT

©Adafruit Industries Page 1 of 217

Table of Contents

Overview

Update Bootloader

Use UF2

• Download update-bootloader UF2

• Enter Bootloader Mode

• Drap & Drop UF2

Use Arduino IDE

Use Command Line

• Download Bootloader Package

• Download adafruit-nrfutil

• Update Bootloader

Pinouts

• Power Pins

• Analog Inputs

• PWM Outputs

• I2C Pins

• Logic pins

• QSPI Flash and DotStar

• Other Pins

9

12

13

14

17

19

Arduino Support Setup

• 1. BSP Installation

• 2. LINUX ONLY: adafruit-nrfutil Tool Installation

• 3. Update the bootloader (nRF52832 ONLY)

• Advanced Option: Manually Install the BSP via 'git'

Arduino Examples

Arduino Bluefruit nRF52 API

nRF52 ADC

• Analog Reference Voltage

• Analog Resolution

• Default ADC Example (10-bit, 3.6V Reference)

• Advanced Example (12-bit, 3.0V Reference)

FAQs

What is CircuitPython?

• CircuitPython is based on Python

• Why would I use CircuitPython?

25

28

28

28

31

39

CircuitPython for ItsyBitsy nRF52840 Express

• Set up CircuitPython Quick Start!

• Further Information

©Adafruit Industries Page 2 of 217

41

Installing the Mu Editor

• Download and Install Mu

• Starting Up Mu

• Using Mu

43

Creating and Editing Code

• Creating Code

• Editing Code

• Back to Editing Code...

• Naming Your Program File

Connecting to the Serial Console

• Are you using Mu?

• Serial Console Issues or Delays on Linux

• Setting Permissions on Linux

• Using Something Else?

Interacting with the Serial Console

The REPL

• Entering the REPL

• Interacting with the REPL

• Returning to the Serial Console

CircuitPython Libraries

• The Adafruit Learn Guide Project Bundle

• The Adafruit CircuitPython Library Bundle

• Downloading the Adafruit CircuitPython Library Bundle

• The CircuitPython Community Library Bundle

• Downloading the CircuitPython Community Library Bundle

• Understanding the Bundle

• Example Files

• Copying Libraries to Your Board

• Understanding Which Libraries to Install

• Example: ImportError Due to Missing Library

• Library Install on Non-Express Boards

• Updating CircuitPython Libraries and Examples

• CircUp CLI Tool

46

51

54

57

61

Frequently Asked Questions

• Using Older Versions

• Python Arithmetic

• Wireless Connectivity

• Asyncio and Interrupts

• Status RGB LED

• Memory Issues

• Unsupported Hardware

Welcome to the Community!

• Adafruit Discord

• CircuitPython.org

• Adafruit GitHub

• Adafruit Forums

• Read the Docs

©Adafruit Industries Page 3 of 217

72

77

Advanced Serial Console on Windows

• Windows 7 and 8.1

• What's the COM?

• Install Putty

86

Advanced Serial Console on Mac

• What's the Port?

• Connect with screen

"Uninstalling" CircuitPython

• Backup Your Code

• Moving Circuit Playground Express to MakeCode

• Moving to Arduino

Troubleshooting

• Always Run the Latest Version of CircuitPython and Libraries

• I have to continue using CircuitPython 5.x or earlier. Where can I find compatible libraries?

• Bootloader (boardnameBOOT) Drive Not Present

• Windows Explorer Locks Up When Accessing boardnameBOOT Drive

• Copying UF2 to boardnameBOOT Drive Hangs at 0% Copied

• CIRCUITPY Drive Does Not Appear or Disappears Quickly

• Device Errors or Problems on Windows

• Serial Console in Mu Not Displaying Anything

• code.py Restarts Constantly

• CircuitPython RGB Status Light

• CircuitPython 7.0.0 and Later

• CircuitPython 6.3.0 and earlier

• Serial console showing ValueError: Incompatible .mpy file

• CIRCUITPY Drive Issues

• Safe Mode

• To erase CIRCUITPY: storage.erase_filesystem()

• Erase CIRCUITPY Without Access to the REPL

• For the specific boards listed below:

• For SAMD21 non-Express boards that have a UF2 bootloader:

• For SAMD21 non-Express boards that do not have a UF2 bootloader:

• Running Out of File Space on SAMD21 Non-Express Boards

• Delete something!

• Use tabs

• On MacOS?

• Prevent & Remove MacOS Hidden Files

• Copy Files on MacOS Without Creating Hidden Files

• Other MacOS Space-Saving Tips

• Device Locked Up or Boot Looping

90

92

95

Getting Started with BLE and CircuitPython

• Guides

CircuitPython Essentials

CircuitPython Pins and Modules

• CircuitPython Pins

• import board

• I2C, SPI, and UART

• What Are All the Available Names?

• Microcontroller Pin Names

©Adafruit Industries Page 4 of 217

113

114

115

• CircuitPython Built-In Modules

CircuitPython Built-Ins

• Thing That Are Built In and Work

• Flow Control

• Math

• Tuples, Lists, Arrays, and Dictionaries

• Classes, Objects and Functions

• Lambdas

• Random Numbers

CircuitPython Digital In & Out

• Find the pins!

• Read the Docs

CircuitPython Analog In

• Creating the analog input

• get_voltage Helper

• Main Loop

• Changing It Up

• Wire it up

• Reading Analog Pin Values

CircuitPython Analog Out

• Creating an analog output

• Setting the analog output

• Main Loop

• Find the pin

121

122

127

134

CircuitPython PWM

• PWM with Fixed Frequency

• Create a PWM Output

• Main Loop

• PWM Output with Variable Frequency

• Installing Project Code

• Wire it up

• Where's My PWM?

CircuitPython Servo

• Servo Wiring

• Standard Servo Code

• Continuous Servo Code

CircuitPython Internal RGB LED

• Create the LED

• Brightness

• Main Loop

• Making Rainbows (Because Who Doesn't Love 'Em!)

• Circuit Playground Express Rainbow

CircuitPython NeoPixel

• Wiring It Up

• The Code

• Create the LED

• NeoPixel Helpers

139

150

155

161

©Adafruit Industries Page 5 of 217

• Main Loop

• NeoPixel RGBW

• The Code

• Read the Docs

CircuitPython DotStar

• Wire It Up

• The Code

• Create the LED

• DotStar Helpers

• Main Loop

• Is it SPI?

• Read the Docs

CircuitPython UART Serial

• The Code

• Wire It Up

• Where's my UART?

• Trinket M0: Create UART before I2C

CircuitPython I2C

• Wire It Up

• Find Your Sensor

• I2C Sensor Data

• Installing Project Code

• Where's my I2C?

CircuitPython HID Keyboard and Mouse

• CircuitPython Keyboard Emulator

• Create the Objects and Variables

• The Main Loop

• Non-US Keyboard Layouts

• CircuitPython Mouse Emulator

• Create the Objects and Variables

• CircuitPython HID Mouse Helpers

• Main Loop

168

175

182

191

CircuitPython Storage

• boot.py

• Installing Project Code

• Logging the Temperature

CircuitPython CPU Temp

CircuitPython Expectations

• Always Run the Latest Version of CircuitPython and Libraries

• I have to continue using CircuitPython 3.x or 2.x, where can I find compatible libraries?

• Switching Between CircuitPython and Arduino

• The Difference Between Express And Non-Express Boards

• Non-Express Boards: Gemma, Trinket, and QT Py

• Differences Between CircuitPython and MicroPython

• Differences Between CircuitPython and Python

Software Resources

• Bluefruit LE Client Apps and Libraries

©Adafruit Industries Page 6 of 217

198

203

204

208

• Bluefruit LE Connect(Android/Java)

• Bluefruit LE Connect (iOS/Swift)

• Bluefruit LE Connect for OS X(Swift)

• Bluefruit LE Command Line Updater for OS X (Swift)

• Deprecated:Bluefruit Buddy(OS X)

• ABLE(Cross Platform/Node+Electron)

• Bluefruit LE Python Wrapper

• Debug Tools

• AdaLink(Python)

• Adafruit nRF51822 Flasher(Python)

Using nRF52840 SPI on Battery Power

Downloads

• Files:

• Module Details

• Schematic

• Board Design

214

215

©Adafruit Industries Page 7 of 217

©Adafruit Industries Page 8 of 217

Overview

Your board's bootloader must be 0.6.1 or later to be able to load CircuitPython

8.2.0 or later. See the Update Bootloader section in this guide.

What's smaller than a Feather but larger than a Trinket? It's an Adafruit ItsyBitsy

nRF52840 Express featuring the Nordic nRF52840 Bluetooth LE processor! Teensy &

powerful, with an fast nRF52840 Cortex M4 processor running at 64 MHz and 1 MB of

FLASH - this microcontroller board is perfect when you want something very compact,

with a heap-load of memory and Bluetooth LE support This Itsy is your best option for

tiny wireless connectivity - it can act as both a BLE central and peripheral, with

support in both Arduino and CircuitPython.

©Adafruit Industries Page 9 of 217

ItsyBitsy nRF52840 Expressis only 1.4" long by 0.7" wide, but has 6 power pins, 21

digital GPIO pins (6 of which can be analog in). It's the same chip as the Feather

nRF52840() but really really small. So it's great for those really compact builds. It

even comes with 2MB of QSPI Flash built in, for data logging, file storage, or

CircuitPython code.

The most exciting part of the ItsyBitsy is that while we ship it with an Arduino IDE

compatible demo, you can also install CircuitPython on board with only a few clicks.

When you plug it in, it will show up as a very small disk drive with code.py on it. Edit c

ode.py with your favorite text editor to build your wireless-enabled project using

Python, the most popular programming language. No installs, IDE or compiler needed,

©Adafruit Industries Page 10 of 217

so you can use it on any computer, even ChromeBooks or computers you can't install

software on. When you're done, unplug the Itsy and your code will go with you.

Here are some of the updates you can look forward to when using ItsyBitsy nRF52:

Same size, form-factor as the remaining ItsyBitsy mainboards() - with a similar

•

but not identical pinout (there's no pins at the end of the board like most other

Itsy's due to the radio antenna being there.

Floating point support with Cortex M4 DSP instructions ()

•

32-bit, 3.3V logic and power with power/enable pin

•

1024 KB flash, 256 KB RAM

•

2 MB QSPI FLASH chip for storing files and CircuitPython code storage.

•

Native Open Source USB stack - pre-programmed with UF2 bootloader

•

Bluetooth Low Energy compatible 2.4GHz radio (Details available in the

•

nRF52840 product specification)

FCC / IC / TELEC certified module

•

Up to +8dBm output power

•

21 GPIO, 6 x 12-bit ADC pins, up to 12 PWM outputs (3 PWM modules with 4

•

outputs each)

Blue LED for general purpose blinking, mini DotStar RGB LED for colorful

•

feedback

1 x Special Vhigh output pin gives you the higher voltage from VBAT or VUSB,

•

for driving NeoPixels, servos, and other 5V-logic devices. Digital 5 level-shifted

output for high-voltage logic level output.

Native USB supported by every OS- can be used in Arduino or CircuitPython as

•

USB serial console, Keyboard/Mouse HID, even a little disk drive for storing

Python scripts.

©Adafruit Industries Page 11 of 217

Can be used withArduino IDEorCircuitPython

•

Comes pre-loaded with theUF2 bootloader(), which looks like a USB storage

•

key. Simply drag firmware on to program, no special tools or drivers needed! It

can be used to load up CircuitPython or Arduino IDE

Each order comes with one assembled and tested ItsyBitsy nRF52840, with headers

that can be soldered in for use with a breadboard.

So what are you waiting for? Pick up a ItsyBitsy nRF today and be amazed at how

easy and fast it is to get started with the teensiest Bluetooth dev board we have.

Update Bootloader

Your board's bootloader must be 0.6.1 or later to be able to load CircuitPython

8.2.0 or later.

Older versions of Adafruit's nRF52840 boards were shipped with a bootloader that

does not handle large UF2's, including CircuitPython 8.2.0 and later, and has other

issues. To check whether you need to update the bootloader, double-click the reset
button, and look in the ...BOOT drive for INFO_UF2.TXT. Inside that file, check the

version number. It should be 0.6.1 or newer. This one is older:

UF2 Bootloader 0.2.9 lib/nrfx (v1.1.0-1-g096e770) lib/tinyusb (legacy-755­g55874813) s140 6.1.1
Model: Adafruit Feather nRF52840 Express
Board-ID: nRF52840-Feather-revD

©Adafruit Industries Page 12 of 217

Bootloader: s140 6.1.1
Date: Feb 22 2019

The dafruit nRF52 Bootloader can be upgraded/downgraded without any additional

hardware. There are 3 different ways to update bootloader, each has its pros and

cons:

Use UF2:This is the fastest and safest way to update bootloader. However, it

•

requires your existing bootloader version is at least 0.4.0and only work with

nRF52840 (not nRF52832).

Use Arduino IDE: work with all Adafruit nRF52 boards and bootloader version,

•

typo free but may not be the latest bootloader version due to the BSP release

cycle.

Use Command Line: work with all boards and bootloader version (including 3rd

•

party one). This command line uses the back-end of the Arduino IDE method

above.

Use UF2

This is the fastest and safest way to update bootloader. However, it requires your

existing bootloader is at least 0.4.0and only work with nRF52840 (not nRF52832)

since UF2 make use of USB MSC interface.

Download update-bootloader UF2

You need a . uf2 file containing the latest version of the bootloader. Use the link

below to download it.

Latest .uf2 of Feather nRF52840

bootloader

Enter Bootloader Mode

Double-click theResetbutton on your board, and you will see the NeoPixel RGB LED

turn green (identified by the arrow in the image). If it turns red, check the USB cable,

try another USB port, etc.

Note: on nRF52840 USB Key with TinyUF2 (PID 5199) you need to hold its button

while plugging into your PC.

©Adafruit Industries Page 13 of 217

Drap & Drop UF2

You will see a new BOOT disk drive appear e.g FTHR840BOOT. Drag the downloaded
. uf2 file to FTHR840BOOT.The LED will flash. Then, theFTHR840BOOT drive will

disappear. That's it, you have successfully update your board to the latest version.

Use Arduino IDE

Arduino IDE Burn Bootloader menu option will pick the correct bootloader binary for

your selected board and prevent any command typos or other common errors.

Close the Serial Monitor before you click "Burn Bootloader". Afterwards, you

shouldn't close the Arduino IDE, unplug the board, launch Serial Monitor etc ... to

abort the process. There is a high chance it will brick your device! Do this with

care and caution.

This is an advanced method: if your existing bootloader version is 0.4.0 or later,

you can use the UF2 method, which is faster and safer.

Make sure no other program is attached to the serial port on the board, such as Mu,

the Serial Monitor in Arduino, or a terminal program. Then, to start, select the correct

board you are using under Tools -> Board

©Adafruit Industries Page 14 of 217

Then select "Bootloader DFU for Bluefruit nRF52" for Tools->Programmer

Double check all of the following: Board, Programmer...

Then select Tools->Burn Bootloader to start the upgrade.

©Adafruit Industries Page 15 of 217

After receiving the new Bootloader over the serial connection, the old Bootloader will

erase itself! The new bootloader will then be flashed. The process typically takes

30-60 seconds to complete. Make sure you see the "Device programmed" in the

output log before launching Serial monitor or uploadinga new sketch.

Upgrading target on /dev/ttyACM0 with DFU package /Adafruit_nRF52_Arduino/
bootloader/feather_nrf52840_express/
feather_nrf52840_express_bootloader-0.6.2_s140_6.1.1.zip. Flow control is disabled,
Dual bank, Touch 1200
Touched serial port /dev/ttyACM0
Opened serial port /dev/ttyACM0
Starting DFU upgrade of type 3, SoftDevice size: 151016, bootloader size: 39000,
application size: 0
Sending DFU start packet
Sending DFU init packet
Sending firmware file
########################################
########################################
########################################
########################################
########################################
########################################
########################################
########################################
########################################
############
Activating new firmware

DFU upgrade took 20.50154972076416s
Device programmed.

Drawbacks of this method are that you will need to install the Arduino IDE, and the

bundled bootloader may not be the latest one. Check out the next page for a more

advanced command line version.

©Adafruit Industries Page 16 of 217

Use Command Line

This is advanced method: if your existing bootloader version is 0.4.0 or later, you

can use the UF2 method, which is faster and safer.

Download Bootloader Package

To update the bootloader, you need a . zip file containing the latest version of the
bootloader. Use the link below to download it. Then unzip the .zip you downloaded.

Latest .zip of Feather nRF52840

bootloader and associated files

Download adafruit-nrfutil

You will also need the utility program "adafruit-nrfutil", which has slightly different

names on different platforms.

On Linux, you can download and install adafruit-nrfutil by doing:

$ pip3 install --user adafruit-nrfutil

On MacOS, if you have python3 and pip3 installed, you can install via pip3 , as
above for Linux. Otherwise download adafruit-nrfutil-macos from this link:

adafruit-nrfutil-macos for MacOS

Then make it executable by doing:

chmod +x adafruit-nrfutil-macos

On Windows, download adafruit-nrfutil.exe from this link:

adafruit-nrfutil.exe (for Windows)

©Adafruit Industries Page 17 of 217

Update Bootloader

To update the bootloader, first connect the board, and then double-click to get NRF52

BOOT . In the commands below,substitute the name of the .zip file you downloaded

for file given there.

On Linux, run this command:

adafruit-nrfutil --verbose dfu serial --package
feather_nrf52840_express_bootloader-0.2.9_s140_6.1.1.zip -p /dev/ttyACM0 -b 115200

--singlebank --touch 1200

On MacOS, find out the device name for the connected board, by doing:

ls /dev/cu.*

The device name will be something like /dev/cu.usbmodem411 . Use this command,

substituting the device name you've discovered. If you are running it other than where
you downloaded adafruit-nrfutil-macos , change the path to the command
accordingly. If you installed it via pip3, it's just called adafruit-nrfutil , and it

should be in your PATH.

./adafruit-nrfutil-macos --verbose dfu serial --package
feather_nrf52840_express_bootloader-0.2.9_s140_6.1.1.zip -p /dev/cu.usbmodem411 -b
115200 --singlebank --touch 1200

On Windows, use this command, in the folder where you downloaded the other two
files above. You'll need to specify the correct COM port, instead of COMxx . Look in De

vice Manager for the name of the COM port (it will be listed as a "USB Serial Device"

on Windows 10) after you have double-clicked the reset button.

adafruit-nrfutil.exe --verbose dfu serial --package
feather_nrf52840_express_bootloader-0.2.9_s140_6.1.1.zip --port COMxx -b 115200 -­singlebank --touch 1200

Once done, click the reset button again - the bootloader will be running!

©Adafruit Industries Page 18 of 217

Pinouts

Click here to view a PDF version of the pinout diagram()

©Adafruit Industries Page 19 of 217

Power Pins

The ItsyBitsy nRF52840 Express has BAT

G USB on the top left, next to the micro

USB port

These pins are:

BAT - battery input for an alternative

power source to USB, the voltage can only

be from 3.5V to 6VDC

GND - Power/data ground

USB - This is the same pin as the

MicroUSB connector's 5V USB power pin.

This should be used as an output to get

5V power from the USB port. Say if you

need to power a bunch of NeoPixels or

servos.

You can always put any voltage you like into BAT and the circuitry will switch between

BAT and USB dynamically for you. That means you can have a Battery backup that

only gets enabled when USB is disconnected.

If you want to add rechargeable power, a LiPoly backpack can be soldered into these

three pins that will let you have a battery that is automatically recharged whenever

USB is plugged in, then switches to LiPoly when on the go:

Adafruit LiIon/LiPoly Backpack Add-On for

Pro Trinket/ItsyBitsy

If you have an ItsyBitsy or Pro Trinket you

probably know it's the perfect little size

for a portable project. This LiPoly

backpack makes it really easy to do!

Instead of wiring 2...

https://www.adafruit.com/product/2124

©Adafruit Industries Page 20 of 217

In addition to the three standard power pins, the ItsyBitsy nRF52840 Express has a

few more pins available for power sourcing:

3V - this 3.3V pin is the regulated output from the onboard regulator. You can

•

draw 500mA whether powered by USB or battery.

EN - connected to the regulator enable, it will let you shut off power - when

•

running on battery only. But at least you don't have to cut a trace or wire to your

battery. This pin does not affect power when using USB

Vhi - this is a special pin! It is a dual-Schottky-diode connected output from BAT

•

and USB. This means this will always have the higher-of-the-two voltages, but

will always have power output. The voltage will be about 5VDC when powered

by USB, but can range from 3.5-6VDC when powered from battery. It's not

regulated, but it is high-current, great for driving servos and NeoPixels.

Analog Inputs

The 7 available analog inputs (A0 .. A5 and D10 which is called A6) can be configured

to generate 8, 10 or 12-bit data (or 14-bits with over-sampling), at speeds up to

200kHz (depending on the bit-width of the values generated), based on an internal

0.6V reference

The following default values are used for Arduino. See this guide's nRF52 ADC page(

) for details about changing these settings.

Default voltage range: 0-3.6V (uses the internal 0.6V reference with 1/6 gain)

•

Default resolution: 12-bit (0..4096)

•

Default mV per lsb (assuming 3.6V and 12-bit resolution): 1 LSB = 0.87890625

•

mV

CircuitPython uses 1/4 gain with a VDD/4 reference voltage.

Unlike digital functions, which can be remapped to any GPIO/digital pin, the ADC

functionality is tied to specified pins, A0 thru A5 and also D10/A6

PWM Outputs

Any GPIO pin can be configured as a PWM output, using the dedicated PWM block.

©Adafruit Industries Page 21 of 217

Three PWM modules can provide up to 12 PWM channels with individual frequency

control in groups of up to four channels.

I2C Pins

I2C pins on the nRF52840 require external pullup resistors to function, which are not

present on the Adafruit nRF52840 Itsy Bitsy by default. You will need to supply

external pullups to use these. All Adafruit I2C breakouts have appropriate pullups on

them already, so this normally won't be an issue for you.

Logic pins

This is the general purpose I/O pin set for the microcontroller. All logic except for pin

5 is 3.3V output and input. You can usually use 3V logic as an input to 5V, but the 3V

Itsy pins should not be connected to 5V!

All pins can do PWM output - nRF52840 will assign a PWM to any pin you like

All pins can be interrupt inputs - nRF52840 will assign an IRQ to any pin you like

D2 and A1 thru A5 are 'low speed' pins, they can be used for < 10KHz signals but

not recommended for higher frequencies so as to avoid radio interference. Any

other pins will work at high speeds!

Special GPIO

Since you have PWM/IRQ on any pin, there's not a lot of special pins - they can all

pretty much do anything, like connect a PDM microphone or encoder. Here are the

somewhat special pins:

#0 / RX - GPIO #0, also receive (input) pin for Serial1

•

#1 / TX - GPIO #1, also transmit (output) pin for Serial1

•

SDA and SCL - these are the I2C hardware interface pins. There's no pull up on

•

this pin by default so when using with I2C, you may need a 2.2K-10K pullup on

each to 3.3V. PWM output

#3 - GPIO #3 is connected to the blue LED next to the Reset button - it isn't

•

available on the pin breakouts

#4 - GPIO #4 is connected to the SW button to the right of the micro USB

•

connector - it isn't available on the pin breakouts

©Adafruit Industries Page 22 of 217

#5 - GPIO #5. This is a special OUTPUT-only pin that can PWM. It is level-shifted

•

up to Vhi voltage, so it's perfect for driving NeoPixels that want a ~5V logic level

input.

SCK/MOSI/MISO - the hardware SPI port for connecting SPI devices, you can

•

use any pin for CS

These pins are available in CircuitPython under the board module. Names that start

with # are prefixed with D and other names are as is. So #0 / RX above is available as

board.D0 and board.RX for example.

QSPI Flash and DotStar

As part of the 'Express' series of boards,

this ItsyBitsy is designed for use with

CircuitPython.

To make that easy, we have added two

extra parts: a mini DotStar (RGB LED) and a

2 MB QSPI (Quad SPI) Flash chip.

The DotStar is connected to pin #6 (clock)

and #8 (data) in Arduino, so just use our

DotStar library() and set it up as a single-

LED strand on pins 6 & 8. The DotStar is

powered by the 3.3V power supply but

that hasn't shown to make a big difference

in brightness or color. In CircuitPython, the
pins are APA102_MOSI and APA102_SCK .

The QSPI Flash is connected to 6 pins that are not brought out on the GPIO pads.

QSPI is neat because it allows you to have 4 data in/out lines instead of just SPI's

single line in and single line out. This means that QSPI is at least 4 times faster. But in

reality is at least 10x faster because you can clock the QSPI peripheral much faster

than a plain SPI peripheral

©Adafruit Industries Page 23 of 217

We have an Arduino library here which provides QSPI interfacing for Arduino(). In

CircuitPython, the QSPI flash is used natively by the interpreter and is read-only to

user code, instead the Flash just shows up as the writable disk drive!

Other Pins

A tactile switch is provided for use in your

projects, which is connected
to P0.29 and is accessible in code asD4.

Holding this button down coming out of a

board reset will also force the device to

enter and remain in USB bootloader mode,

which can be useful if you lock your board

up with bad application code!

RST - this is the Reset pin, tie to ground to

manually reset the nRF52840, as well as

launch the bootloader manually

SWCLK & SWDIO - These are the debug-

interface pins, used if you want to

reprogram the chip directly or attach a

debugger.

©Adafruit Industries Page 24 of 217

Arduino Support Setup

You caninstall the Adafruit Bluefruit nRF52 BSP (Board Support Package) in two

steps:

nRF52 support requires at least Arduino IDE version 1.8.15! Please make sure you

have an up to date version before proceeding with this guide!

Please consult the FAQ section at the bottom of this page if you run into any

problems installing or using this BSP!

1. BSP Installation

Recommended: Installing the BSPvia the Board Manager

Download and install the Arduino IDE() (At least v1.8)

•

Start the Arduino IDE

•

Go into Preferences

•

Add https://adafruit.github.io/arduino-board-index/

•

package_adafruit_index.json as an 'Additional Board Manager URL' (see

image below)

Restart the Arduino IDE

•

Open the Boards Manageroption from the Tools -> Board menu and install 'Adaf

•

ruit nRF52 by Adafruit' (see image below)

©Adafruit Industries Page 25 of 217

It will take up to a few minutes to finish installing the cross-compiling toolchain and

tools associated with this BSP.

The delay during the installation stage shown in the image below is normal, please be

patient and let the installation terminate normally:

Once the BSP is installed, select

Adafruit Bluefruit nRF52832 Feather (for the nRF52 Feather)

•

Adafruit Bluefruit nRF52840 Feather Express (for the nRF52840 Feather)

•

Adafruit ItsyBitsy nRF52840 (for the Itsy '850)

•

Adafruit Circuit Playground Bluefruit (for the CPB)

•

etc...

•

from the Tools -> Board menu, which will update your system config to use the right

compiler and settings for the nRF52:

2. LINUX ONLY: adafruit-nrfutil Tool Installation

adafruit-nrfutil()is amodified versionof Nordic's nrfutil(), which is used to flash

boards using the built in serial bootloader. It is originally written for python2, but have

been migrated to python3 and renamed toadafruit-nrfutilsince BSP version 0.8.5.

©Adafruit Industries Page 26 of 217

This step is only required on Linux, pre-built binaries of adafruit-nrfutil for

Windows and MacOS are already included in the BSP. That should work out of

the box for most setups.

Install python3 if it is not installed in your system already

$ sudo apt-get install python3

Then run the following command to install the tool from PyPi

$ pip3 install --user adafruit-nrfutil

Add pip3 installation dir to your PATH if it is not added already. Make sure adafruit-

nrfutil can be executed in terminal by running

$ adafruit-nrfutil version
adafruit-nrfutil version 0.5.3.post12

3. Update the bootloader (nRF52832 ONLY)

To keep up with Nordic's SoftDevice advances, you will likely need to update your

bootloader if you are using the original nRF52832 basedBluefruit nRF52 Feather

boards.

Follow this link for instructions on how to do that

This step ISN'T required for the newer nRF52840 Feather Express, which has a

different bootloader entirely!

Update the nRF52832 Bootloader

Advanced Option: Manually Install the BSP via 'git'

If you wish to do any development against the core codebase (generate pull requests,

etc.), you can also optionally install the Adafruit nRF52 BSP manually using 'git', as

decribed below:

©Adafruit Industries Page 27 of 217

Adafruit nRF52 BSP via git (for core development and PRs only)

Install BSP via Board Manager as above to install compiler & tools.

1.

Delete the core folder nrf52 installed by Board Manager in Adruino15,

2.

depending on your OS. It could be
macOS: ~/Library/Arduino15/packages/adafruit/hardware/nrf52
Linux: ~/.arduino15/packages/adafruit/hardware/nrf52
Windows: %APPDATA%

\Local\Arduino15\packages\adafruit\hardware\nrf52

Go tothe sketchbook folder on your command line, which should be one of the

3.

following:
macOS: ~/Documents/Arduino
Linux: ~/Arduino
Windows: ~/Documents/Arduino
Create a folder named hardware/Adafruit , if it does not exist, and change

4.

directories into it.

Clone the Adafruit_nRF52_Arduino() repo in the folder described in step 2:

5.

git clone --recurse-submodules [e-mail]:adafruit/

Adafruit_nRF52_Arduino.git

This should result in a final folder name like ~/Documents/Arduino/hardware/

6.

Adafruit/Adafruit_nRF52_Arduino (macOS).

Restart the Arduino IDE

7.

Arduino Examples

Arduino Examples()

Arduino Bluefruit nRF52 API

Arduino Bluefruit nRF52 API()

nRF52 ADC

The nRF52 family includes an adjustable 'successive-approximation ADC' which can

be configured to convert data with up to 14-bit resolution (0..16383), and the reference

voltage can be adjusted up to 3.6V internally.

The default values for the ADC are 10-bit resolution (0..1023) with a 3.6V reference

voltage, meaning every digit returned from the ADC =3600mV/1024 =3.515625mV.

©Adafruit Industries Page 28 of 217

Analog Reference Voltage

The internal reference voltage is 0.6V with a variable gain setting, and can be adjust

via theanalogReference(...) function, providing one of the following values:

AR_INTERNAL(0.6V Ref * 6 = 0..3.6V) <-- DEFAULT

•

AR_INTERNAL_3_0(0.6V Ref * 5 = 0..3.0V)

•

AR_INTERNAL_2_4(0.6V Ref * 4 = 0..2.4V)

•

AR_INTERNAL_1_8(0.6V Ref * 3 = 0..1.8V)

•

AR_INTERNAL_1_2(0.6V Ref * 2 = 0..1.6V)

•

AR_VDD4(VDD/4 REF * 4 = 0..VDD)

•

For example:

// Set the analog reference to 3.0V (default = 3.6V)
analogReference(AR_INTERNAL_3_0);

Analog Resolution

The ADC resolution can be set to 8, 10, 12 or 14 bits using theanalogReadResolution(..

.) function, with the default value being 10-bit:

// Set the resolution to 12-bit (0..4095)
analogReadResolution(12); // Can be 8, 10, 12 or 14

Default ADC Example (10-bit, 3.6V Reference)

The original source for this code is included in the nRF52 BSP and can be viewed

online here().

#include <Arduino.h>
#include <Adafruit_TinyUSB.h> // for Serial

int adcin = A5;
int adcvalue = 0;
float mv_per_lsb = 3600.0F/1024.0F; // 10-bit ADC with 3.6V input range

void setup() {
Serial.begin(115200);
while ( !Serial ) delay(10); // for nrf52840 with native usb
}

void loop() {

©Adafruit Industries Page 29 of 217

// Get a fresh ADC value
adcvalue = analogRead(adcin);

// Display the results
Serial.print(adcvalue);
Serial.print(" [");
Serial.print((float)adcvalue * mv_per_lsb);
Serial.println(" mV]");

delay(100);
}

Advanced Example (12-bit, 3.0V Reference)

The original source for this code is included in the nRF52 BSP and can be viewed

online here().

#include <Arduino.h>
#include <Adafruit_TinyUSB.h> // for Serial

#if defined ARDUINO_NRF52840_CIRCUITPLAY
#define PIN_VBAT A8 // this is just a mock read, we'll use the light
sensor, so we can run the test
#endif

uint32_t vbat_pin = PIN_VBAT; // A7 for feather nRF52832, A6 for
nRF52840

#define VBAT_MV_PER_LSB (0.73242188F) // 3.0V ADC range and 12-bit ADC
resolution = 3000mV/4096

#ifdef NRF52840_XXAA
#define VBAT_DIVIDER (0.5F) // 150K + 150K voltage divider on VBAT
#define VBAT_DIVIDER_COMP (2.0F) // Compensation factor for the VBAT
divider
#else
#define VBAT_DIVIDER (0.71275837F) // 2M + 0.806M voltage divider on VBAT =
(2M / (0.806M + 2M))
#define VBAT_DIVIDER_COMP (1.403F) // Compensation factor for the VBAT
divider
#endif

#define REAL_VBAT_MV_PER_LSB (VBAT_DIVIDER_COMP * VBAT_MV_PER_LSB)

float readVBAT(void) {
float raw;

// Set the analog reference to 3.0V (default = 3.6V)
analogReference(AR_INTERNAL_3_0);

// Set the resolution to 12-bit (0..4095)
analogReadResolution(12); // Can be 8, 10, 12 or 14

// Let the ADC settle
delay(1);

// Get the raw 12-bit, 0..3000mV ADC value
raw = analogRead(vbat_pin);

// Set the ADC back to the default settings
analogReference(AR_DEFAULT);
analogReadResolution(10);

©Adafruit Industries Page 30 of 217

// Convert the raw value to compensated mv, taking the resistor­ // divider into account (providing the actual LIPO voltage)
// ADC range is 0..3000mV and resolution is 12-bit (0..4095)
return raw * REAL_VBAT_MV_PER_LSB;
}

uint8_t mvToPercent(float mvolts) {
if(mvolts<3300)
return 0;

if(mvolts <3600) {
mvolts -= 3300;
return mvolts/30;
}

mvolts -= 3600;
return 10 + (mvolts * 0.15F ); // thats mvolts /6.66666666
}

void setup() {
Serial.begin(115200);
while ( !Serial ) delay(10); // for nrf52840 with native usb

// Get a single ADC sample and throw it away
readVBAT();
}

void loop() {
// Get a raw ADC reading
float vbat_mv = readVBAT();

// Convert from raw mv to percentage (based on LIPO chemistry)
uint8_t vbat_per = mvToPercent(vbat_mv);

// Display the results

Serial.print("LIPO = ");
Serial.print(vbat_mv);
Serial.print(" mV (");
Serial.print(vbat_per);
Serial.println("%)");

delay(1000);
}

FAQs

NOTE: For FAQs relating to the BSP, see the dedicated BSP FAQ list().

What are the differences between the nRF51 and nRF52 Bluefruit boards? Which one should I be using?

The two board families take very different design approaches.

All of the nRF51 based modules are based on an AT command set (over UART or

SPI), and require two MCUs to run: the nRF51 hosting the AT command parser, and

an external MCU sending AT style commands.

©Adafruit Industries Page 31 of 217

The nRF52 boards run code directly on the nRF52, executing natively and calling

the Nordic S132 SoftDevice (their proprietary Bluetooth Low Energy stack) directly.

This allows for more efficient code since there is no intermediate AT layer or

transport, and also allows for lower overall power consumption since only a single

device is involved.

The nRF52 will generally give you better performance, but for situation where you

need to use an MCU with a feature the nRF52 doesn't have (such as USB), the

nRF51 based boards will still be the preferable solution.

Can I run nRF51 Bluefruit sketches on the nRF52?

No. The two board families are fundamentally different, and have entirely separate

APIs and programming models. If you are migrating from the nRF51 to the nRF52,

you will need to redesign your sketches to use the newer API, enabling you to

build code that runs natively on the nRF52832 MCU.

Can I use the nRF52 as a Central to connect to other BLE peripherals?

The S132 Soft Device and the nRF52832 HW support Central mode, so yes this

ispossible. At this early development stage, though, there is only bare bones

support for Central mode in the Adafruit nRF52 codebase, simply to test the HW

and S132 and make sure that everything is configured properly. An example is

provided of listening for incoming advertising packets, printing the packet contents

and meta-data out to the Serial Monitor. We hope to add further Central mode

examples in the future, but priority has been given to the Peripheral API and

examples for the initial release.

How are Arduino sketches executed on the nRF52? Can I do hard real time processing (bit-banging NeoPixels, Software Serial etc.)?

In order to run Arduino code on the nRF52 at the same time as the low level

Bluetooth Low Energy stack, the Bluefruit nRF52 Feather uses FreeRTOS as a task

scheduler. The scheduler will automatically switch between tasks, assigning clock

cycles to the highest priority task at a given moment. This process is generally

transparent to you, although it can have implications if you have hard real time

requirements. There is no guarantee on the nRF52 to meet hard timing

requirements when the radio is enabled an being actively used for Bluetooth Low

Energy. This isn'tpossible on the nRF52 even without FreeRTOS, though, since the

©Adafruit Industries Page 32 of 217

SoftDevice (Nordic's propietary binary blob stack) has higher priority than any user

code, including control over interrupt handlers.

Can I use GDB to debug my nRF52?

You can, yes, but it will require a Segger J-Link (that's what we've tested against

anyway, other options exist), and it's an advanced operation. But if you're asking

about it, you probably know that.

Assuming you have the Segger J-Link drivers installed, you can start Segger's GDB

Server from the command line as follows (OSX/Linux used here):

$ JLinkGDBServer -device nrf52832_xxaa -if swd -speed auto

Then open a new terminal window, making sure that you have access to gcc-arm-

none-eabi-gdb from the command line, and enter the following command:

$ ./arm-none-eabi-gdb something.ino.elf

` something.ino.elf ` is the name of the .elf file generated when you built your

sketch. You can find this by enabling 'Show verbose output during: [x] compilation'

in the Arduino IDE preferences. You CAN run GDB without the .elf file, but pointing

to the .elf file will give you all of the meta data like displaying the actual source

code at a specific address, etc.

Once you have the (gdb) prompt, enter the following command to connect to the

Segger GDB server (updating your IP address accordingly, since the HW isn't

necessarily local!):

(gdb) target remote 127.0.0.1:2331

If everything went well, you should see the current line of code where the device is

halted (normally execution on the nRF52 will halt as soon as you start the Segger

GDB Server).

At this point, you can send GDB debug commands, which is a tutorial in itself! As a

crash course, though:

To continue execution, type ' monitor go ' then ' continue '

•

To stop execution (to read register values, for example.), type

•

' monitor halt '
To display the current stack trace (when halted) enter ' bt '

•

©Adafruit Industries Page 33 of 217

To get information on the current stack frame (normally the currently

•

executing function), try these:

info frame : Display info on the current stack frame

◦

info args : Display info on the argumentspassed into the stack frame

◦

info locals : Display local variables in the stack frame

◦

info registers : Dump the core ARM register values, which can be

◦

useful for debugging specific fault conditions

Are there any other cross platform or free debugging options other than GDB?

If you have a Segger J-Link(), you can also use Segger's OZone debugger GUI() to

interact with the device, though check the license terms since there are usage

restrictions depending on the J-Link module you have.

You will need to connect your nRF52 to the J-Link via the SWD and SWCLK pins on

the bottom of the PCB, or if you are OK with fine pitch soldering via the SWD

header.

You can either solder on a standard 2x5 SWD header()on the pad available in the

board, or you can solder wires to the SWD and SWCLK pads on the bottom of the

PCB and use an SWD Cable Breakout Board(), or just connect cables directly to

your J-Link via some other means.

You will also need to connect the VTRef pin on the JLink to3.3V on the Feather to

let the J-Link know what voltage level the target has, and share a common GND by

connecting the GND pins on each device.

Before you can start to debug, you will need to get the .elf file that contains all the

debug info for your sketch. You can find this file by enablingShow Verbose Output

During: compilation in theArduino Preferencesdialogue box. When you build your

sketch, you need to look at the log output, and find the .elf file, which will resemble
something like this (it will vary depending on the OS used): /var/folders/86/

hb2vp14n5_5_yvdz_z8w9x_c0000gn/T/arduino_build_118496/
ancs_oled.ino.elf

In the OZone New Project Wizard, when prompted to select a target device in

OZone selectnRF52832_xxAA, then make sure that you have set the Target

Interface for the debugger toSWD, and finally point to the .elf file above:

©Adafruit Industries Page 34 of 217

©Adafruit Industries Page 35 of 217

Next select theAttach to running program option in the top-left hand corner, or via the

menu system, which will cause the debugger to connect to the nRF52 over SWD:

At this point, you can click thePAUSE icon to stop program execution, and then

analyze variables, or set breakpoints at appropriate locations in your program

execution, and debug as you would with most other embedded IDEs!

©Adafruit Industries Page 36 of 217

Clicking on the left-hand side of the text editor will set a breakpoint on line 69 in the

image below, for example, and the selecting Debug > Reset > Reset & Run from the

menu or icon will cause the board to reset, and you should stop at the breakpoint you

set:

You can experiment with adding some of the other debug windows and options via

theView menu item, such as theCall Stack which will show you all of the functions

that were called before arriving at the current breakpoint:

Can I make two Bluefruit nRF52's talk to each other?

Yes, by running one board in peripheral mode and one board in central mode,

where the central will establish a connection with the peripheral board and you can

communicate using BLE UART or a custom service. See the following Central BLE

©Adafruit Industries Page 37 of 217

UART example to help you get started:https://github.com/adafruit/

Adafruit_nRF52_Arduino/tree/master/libraries/Bluefruit52Lib/examples/Central

On Linux I'm getting 'arm-none-eabi-g++: no such file or directory', even though 'arm-none-eabi-g++' exists in the path specified. What should I do?

This is probably caused by a conflict between 32-bit and 64-bit versions of the

compiler, libc and the IDE. The compiler uses 32-bit binaries, so you also need to

have a 32-bit version of libc installed on your system (details()). Try running the

following commands from the command line to resolve this:

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install libc6:i386

what should I do when Arduino failed to upload sketch to my Feather ?

If you get this error:

Timed out waiting for acknowledgement from device.

Failed to upgrade target. Error is: No data received on serial
port. Not able to proceed.
Traceback (most recent call last):
 File "nordicsemi\__main__.py", line 294, in serial
 File "nordicsemi\dfu\dfu.py", line 235, in dfu_send_images
 File "nordicsemi\dfu\dfu.py", line 203, in _dfu_send_image
 File "nordicsemi\dfu\dfu_transport_serial.py", line 155, in
send_init_packet
 File "nordicsemi\dfu\dfu_transport_serial.py", line 243, in
send_packet
 File "nordicsemi\dfu\dfu_transport_serial.py", line 282, in
get_ack_nr
nordicsemi.exceptions.NordicSemiException: No data received on
serial port. Not able to proceed.

This is probably caused by the bootloader version mismatched on your feather and

installed BSP. Due to the difference in flash layout (more details()) and Softdevice

API (which is bundled with bootloader), sketch built with selected bootloader can

©Adafruit Industries Page 38 of 217

only upload to board having the same version. In short, you need to upgrade/burn

bootloader to match on your Feather, follow aboveUpdate The Bootloader()guide

It only has to be done once to update your Feather

Do Feather/Metro nRF52832 and nRF52840 support BLE Mesh ?

They all support BLE Mesh, but we don't provide Arduino library for Mesh. You

need to write code based on Nordic sdk mesh.

Unable to upload sketch/update bootloader with macOS

If you get error similar to this:

Arduino: 1.8.8 (Mac OS X), Board: "Adafruit Bluefruit nRF52832

Feather, 0.2.9 (s132 6.1.1), Level 0 (Release)"

[1716] Error loading Python lib '/var/folders/gw/
b0cg4zm508qf_rf2m655gd3m0000gn/T/_MEIE6ec69/Python': dlopen:
dlopen(/var/folders/gw/b0cg4zm508qf_rf2m655gd3m0000gn/T/_MEIE6ec69/
Python, 10): Symbol not found: _futimens

 Referenced from: /var/folders/gw/b0cg4zm508qf_rf2m655gd3m0000gn/
T/_MEIE6ec69/Python (which was built for Mac OS X 10.13)

 Expected in: /usr/lib/libSystem.B.dylib

in /var/folders/gw/b0cg4zm508qf_rf2m655gd3m0000gn/T/_MEIE6ec69/
Python

exit status 255

Error compiling for board Adafruit Bluefruit nRF52832 Feather.

It is probably due to the pre-built adafruit-nrfutil cannot run on your Mac. The

binary is generated on MacOS 10.13, if your Mac is older than that. Please update

your macOS, or you could follow this repo's readme herehttps://github.com/

adafruit/Adafruit_nRF52_nrfutil()to manual install it ( tried with pip3 first, or install

from source if it doesn't work). Then use the installed binary to replace the one in

the BSP.

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

©Adafruit Industries Page 39 of 217

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.

©Adafruit Industries Page 40 of 217

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. CircuitPython has builtin support for microcontroller

•

hardware features like digital I/O pins, hardware buses (UART, I2C, SPI), audio I/

O, and other capabilities. There are also 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. Adafruit welcomes and encourages feedback from the community, and

incorporate it into the development of CircuitPython. That's the core of the open

source concept. This makes CircuitPython better for you and everyone who uses it!

CircuitPython for ItsyBitsy nRF52840 Express

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. Simply copy and

edit files on the CIRCUITPY drive to iterate.

Set up CircuitPython Quick Start!

Follow this quick step-by-step for super-fast Python power :)

©Adafruit Industries Page 41 of 217

Download the latest version of

CircuitPython for this board via

CircuitPython.org

Further Information

For more detailed info on installing CircuitPython, check out Installing CircuitPython().

Click the link above and download the

latest UF2 file.

Download and save it to your desktop (or

wherever is handy).

Plug your Itsy nRF52840 into your

computer using a known-good USB cable.

A lot of people end up using charge-only

USB cables and it is very frustrating! So

make sure you have a USB cable you

know is good for data sync.

In the image, the Reset button is indicated

by the magenta arrow, and the BTLE status

LED is indicated by the green arrow.

Double-click the Reset button on your

board (magenta arrow), and you will see

the BTLE LED (green arrow) will pulse

quickly then slowly blue. If the DotStar LED

turns red, check the USB cable, try another

USB port, etc.

If double-clicking doesn't work the first

time, try again. Sometimes it can take a

few tries to get the rhythm right!

©Adafruit Industries Page 42 of 217

You will see a new disk drive appear called

ITSY840BOOT.

Drag the adafruit_circuitpython_etc.uf2 file

to ITSY840BOOT.

The LED will flash. Then, the

ITSY840BOOT drive will disappear and a

new disk drive called CIRCUITPY will

appear.

That's it, you're done! :)

Installing the 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!

©Adafruit Industries Page 43 of 217

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

Click theDownload link for downloads and

installation instructions.

Click Start Hereto find a wealth of other

information, including extensive tutorials

and and how-to's.



Windows users: due to the nature of MSI installers, please remove old versions of

Mu before installing the latest version.

Ubuntu users: Mu currently (checked May 4, 2022) does not install properly on

Ubuntu 22.04. See https://github.com/mu-editor/mu/issues to track this issue.

See https://learn.adafruit.com/welcome-to-circuitpython/recommended-editors

and https://learn.adafruit.com/welcome-to-circuitpython/pycharm-and-

circuitpython for other editors to use.

©Adafruit Industries Page 44 of 217

Starting Up 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 on

startup, so if you do not have a

CircuitPython board plugged in with a

CIRCUITPY drive available, Mu will inform

you where it will store any code you save

until you plug in a board.

To avoid this warning, plug in a board and

ensure that the CIRCUITPY drive is

mounted before starting Mu.

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

©Adafruit Industries Page 45 of 217

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

Creating and Editing Code

One of the best things about CircuitPython is how simple it is to get code up and

running. This section covers 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. Adafruit

strongly recommends 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 a number of other editors that work quite well.

The Recommended Editors page() has more details. Otherwise, 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

Installing CircuitPython generates a

code.py file on your CIRCUITPY drive. To

begin your own program, open your editor,

and load the code.py file from the

CIRCUITPY drive.

If you are using Mu, click the Load button

in the button bar, navigate to the

CIRCUITPY drive, and choose code.py.

©Adafruit Industries Page 46 of 217

Copy and paste the following code into your editor:

import board
import digitalio
import time

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

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

The KB2040, QT Py and the Trinkeys do not have a built-in little red LED! There is

an addressable RGB NeoPixel LED. The above example will NOT work on the

KB2040, QT Py or the Trinkeys!

If you're using a KB2040, QT Py or a Trinkey, please download the NeoPixel blink

example().

The NeoPixel blink example uses the onboard NeoPixel, but the time code is the

same. You can use the linked NeoPixel Blink example to follow along with this

guide page.

It will look like this. Note that under the

while True: line, the next four lines

begin with four spaces to indent them, and

they're indented exactly the same amount.

All the lines before that have no spaces

before the text.

©Adafruit Industries Page 47 of 217

Save the code.py file on your CIRCUITPY

drive.

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

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

On most boards you'll find a tiny red LED.

On the ItsyBitsy nRF52840, you'll find a tiny blue LED.

On QT Py M0, QT Py RP2040, and the Trinkey series, you will find only an RGB

NeoPixel LED.

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 one warning before you continue...

Don't click reset or unplug your board!

©Adafruit Industries Page 48 of 217

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. 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 couple of ways to avoid filesystem corruption.

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

Check out the Recommended Editors page() for details on different editing options.

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() page of every board

guide to get your board up and running again.

©Adafruit Industries Page 49 of 217

Back to Editing Code...

Now! Let's try editing the program you added to your board. Open your code.py file
into your editor. You'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.LED)
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?

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

Now it blinks really fast! You decreased the both time that the code leaves the LED on

and off!

Now try increasing both of the 0.1 to 1 . Your LED will blink much more slowly

because you've increased the amount of time that the LED is turned on and off.

Well done! You're doing great! You're ready to start into new examples and edit them

to see what happens! These were simple changes, but major changes are done using

the same process. Make your desired change, save it, and get the results. That's

really all there is to it!

Naming Your Program File

CircuitPython looks for a code file on the board to run. There are four options: code.tx

t, code.py, main.txt and main.py. CircuitPython looks for those files, in that order, and

then runs the first one it finds. While code.py is the recommended name for your code

©Adafruit Industries Page 50 of 217

file, it is important to know that the other options exist. If your program doesn't seem

to be updating as you work, make sure you haven't created another code file that's

being read instead of the one you're working on.

Connecting to the Serial Console

One of the staples of CircuitPython (and programming in general!) is something called

a "print statement". This is a line you include in your code that causes your code to

output text. A print statement in CircuitPython (and Python) looks like this:

print("Hello, world!")

This line in your code.py would result in:

Hello, world!

However, these print statements need somewhere to display. That's where the serial

console comes in!

The serial console receives output from your CircuitPython board sent over USB and

displays it so you can see it. This is necessary when you've included a print statement

in your code and you'd like to see what you printed. It is also helpful for

troubleshooting errors, because your board will send errors and the serial console will

display those too.

The serial console requires an editor that has a built in terminal, or a separate

terminal program. A terminal is a program that gives you a text-based interface to

perform various tasks.

Are you using Mu?

If so, good news! The serial consoleis built into Mu and willautodetect your board

making using the serial console really really easy.

©Adafruit Industries Page 51 of 217

First, make sure your CircuitPython board

is plugged in.

If you open Mu without a board plugged

in, you may encounter the error seen here,

letting you know no CircuitPython board

was found and indicating where your code

will be stored until you plug in a board.

If you are using Windows 7, make sure you

installed the drivers().

Once you've opened Mu with your board plugged in, look for the Serial button in the

button bar and click it.

The Mu window will split in two, horizontally, and display the serial console at the

bottom.

If nothing appears in the serial console, it may mean your code is done running

or has no print statements in it. Click into the serial console part of Mu, and press

CTRL+D to reload.

Serial Console Issues or Delays on Linux

If you're on Linux, and are seeing multi-second delays connecting to the serial

console, or are seeing "AT" and other gibberish when you connect, then the

modemmanager service might be interfering. Just remove it; it doesn't have much use

unless you're still using dial-up modems.

To remove modemmanager , type the following command at a shell:

©Adafruit Industries Page 52 of 217

sudo apt purge modemmanager

Setting Permissions on Linux

On Linux, if you see an error box something like the one below when you press the S

erial button, you need to add yourself to a user group to have permission to connect

to the serial console.

On Ubuntu and Debian, add yourself to the dialout group by doing:

sudo adduser $USER dialout

After running the command above, reboot your machine to gain access to the group.

On other Linux distributions, the group you need may be different. See the Advanced

Serial Console on Linux()for details on how to add yourself to the right group.

Using Something Else?

If you're not using Mu to edit, are using or if for some reason you are not a fan of its

built in serial console, you can run the serial console from a separate program.

Windows requires you to download a terminal program. Check out the Advanced

Serial Console on Windows page for more details.()

MacOS has Terminal built in, though there are other options available for download. C

heck the Advanced Serial Console on Mac page for more details.()

Linux has a terminal program built in, though other options are available for

download. Check the Advanced Serial Console on Linux page for more details.()

Once connected, you'll see something like the following.

©Adafruit Industries Page 53 of 217

Interacting with the Serial Console

Once you've successfully connected to the serial console, it's time to start using it.

The code you wrote earlier has no output to the serial console. So, you're going to

edit it to create some output.

Open your code.py file into your editor, and include a print statement. You can print

anything you like! Just include your phrase between the quotation marks inside the

parentheses. For example:

import board
import digitalio
import time

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

while True:
print("Hello, CircuitPython!")
led.value = True
time.sleep(1)
led.value = False
time.sleep(1)

Save your file.

Now, let's go take a look at the window with our connection to the serial console.

Excellent! Our print statement is showing up in our console! Try changing the printed

text to something else.

import board
import digitalio
import time

©Adafruit Industries Page 54 of 217

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

while True:
print("Hello back to you!")
led.value = True
time.sleep(1)
led.value = False
time.sleep(1)

Keep your serial console window where you can see it. Save your file. You'll see what

the serial console displays when the board reboots. Then you'll see your new change!

The Traceback (most recent call last): is telling you the last thing your board

was doing before you saved your file. This is normal behavior and will happen every

time the board resets. This is really handy for troubleshooting. Let's introduce an error

so you can see how it is used.

Delete the e at the end of True from the line led.value = True so that it says le

d.value = Tru

import board
import digitalio
import time

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

while True:
print("Hello back to you!")
led.value = Tru
time.sleep(1)
led.value = False
time.sleep(1)

Save your file. You will notice that your red LED will stop blinking, and you may have a

colored status LED blinking at you. This is because the code is no longer correct and

can no longer run properly. You need to fix it!

©Adafruit Industries Page 55 of 217

Usually when you run into errors, it's not because you introduced them on purpose.

You may have 200 lines of code, and have no idea where your error could be hiding.

This is where the serial console can help. Let's take a look!

The Traceback (most recent call last): is telling you that the last thing it was
able to run was line 10 in your code. The next line is your error: NameError: name

'Tru' is not defined . This error might not mean a lot to you, but combined with

knowing the issue is on line 10, it gives you a great place to start!

Go back to your code, and take a look at line 10. Obviously, you know what the

problem is already. But if you didn't, you'd want to look at line 10 and see if you could

figure it out. If you're still unsure, try googling the error to get some help. In this case,

you know what to look for. You spelled True wrong. Fix the typo and save your file.

Nice job fixing the error! Your serial console is streaming and your red LED Is blinking

again.

The serial console will display any output generated by your code. Some sensors,

such as a humidity sensor or a thermistor, receive data and you can use print

©Adafruit Industries Page 56 of 217

statements to display that information. You can also use print statements for

troubleshooting, which is called "print debugging". Essentially, if your code isn't

working, and you want to know where it's failing, you can put print statements in

various places to see where it stops printing.

The serial console has many uses, and is an amazing tool overall for learning and

programming!

The REPL

The other feature of the serial connection is the Read-Evaluate-Print-Loop, or REPL.

The REPL allows you to enter individual lines of code and have them run immediately.

It's really handy if you're running into trouble with a particular program and can't

figure out why. It's interactive so it's great for testing new ideas.

Entering the REPL

To use the REPL, you first need to be connected to the serial console. Once that

connection has been established, you'll want to press CTRL+C.

If there is code running, in this case code measuring distance, it will stop and you'll
see Press any key to enter the REPL. Use CTRL-D to reload. Follow those

instructions, and press any key on your keyboard.

The Traceback (most recent call last): is telling you the last thing your board
was doing before you pressed Ctrl + C and interrupted it. The KeyboardInterrupt

is you pressing CTRL+C. This information can be handy when troubleshooting, but for

now, don't worry about it. Just note that it is expected behavior.

If your code.py file is empty or does not contain a loop, it will show an empty output
and Code done running. . There is no information about what your board was

doing before you interrupted it because there is no code running.

©Adafruit Industries Page 57 of 217

If you have no code.py on your CIRCUITPY drive, you will enter the REPL immediately

after pressing CTRL+C. Again, there is no information about what your board was

doing before you interrupted it because there is no code running.

Regardless, once you press a key you'll see a >>> prompt welcoming you to the

REPL!

If you have trouble getting to the >>> prompt, try pressing Ctrl + C a few more times.

The first thing you get from the REPL is information about your board.

This line tells you the version of CircuitPython you're using and when it was released.

Next, it gives you the type of board you're using and the type of microcontroller the

board uses. Each part of this may be different for your board depending on the

versions you're working with.

This is followed by the CircuitPython prompt.

Interacting with the REPL

From this prompt you can run all sorts of commands and code. The first thing you'll do
is run help() . This will tell you where to start exploring the REPL. To run code in the

REPL, type it in next to the REPL prompt.

Type help() next to the prompt in the REPL.

©Adafruit Industries Page 58 of 217

Then press enter. You should then see a message.

First part of the message is another reference to the version of CircuitPython you're

using. Second, a URL for the CircuitPython related project guides. Then... wait. What's
this? To list built-in modules type `help("modules")`. Remember the

modules you learned about while going through creating code? That's exactly what

this is talking about! This is a perfect place to start. Let's take a look!

Type help("modules") into the REPL next to the prompt, and press enter.

This is a list of all the core modules built into CircuitPython, including board .
Remember, board contains all of the pins on the board that you can use in your

code. From the REPL, you are able to see that list!

Type import board into the REPL and press enter. It'll go to a new prompt. It might
look like nothing happened, but that's not the case! If you recall, the import

statement simply tells the code to expect to do something with that module. In this

case, it's telling the REPL that you plan to do something with that module.

Next, type dir(board) into the REPL and press enter.

©Adafruit Industries Page 59 of 217

This is a list of all of the pins on your board that are available for you to use in your

code. Each board's list will differ slightly depending on the number of pins available.
Do you see LED ? That's the pin you used to blink the red LED!

The REPL can also be used to run code. Be aware that any code you enter into the

REPL isn't saved anywhere. If you're testing something new that you'd like to keep,

make sure you have it saved somewhere on your computer as well!

Every programmer in every programming language starts with a piece of code that

says, "Hello, World." You're going to say hello to something else. Type into the REPL:

print("Hello, CircuitPython!")

Then press enter.

That's all there is to running code in the REPL! Nice job!

You can write single lines of code that run stand-alone. You can also write entire

programs into the REPL to test them. Remember that nothing typed into the REPL is

saved.

There's a lot the REPL can do for you. It's great for testing new ideas if you want to

see if a few new lines of code will work. It's fantastic for troubleshooting code by

entering it one line at a time and finding out where it fails. It lets you see what

modules are available and explore those modules.

Try typing more into the REPL to see what happens!

Everything typed into the REPL is ephemeral. Once you reload the REPL or return

to the serial console, nothing you typed will be retained in any memory space. So

be sure to save any desired code you wrote somewhere else, or you'll lose it

when you leave the current REPL instance!

©Adafruit Industries Page 60 of 217

Returning to the Serial Console

When you're ready to leave the REPL and return to the serial console, simply press CT

RL+D. This will reload your board and reenter the serial console. You will restart the

program you had running before entering the REPL. In the console window, you'll see

any output from the program you had running. And if your program was affecting

anything visual on the board, you'll see that start up again as well.

You can return to the REPL at any time!

CircuitPython Libraries

As CircuitPython development continues and there are new releases, Adafruit

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.

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. These files are called libraries. Some of them

are built into CircuitPython. Others are stored on your CIRCUITPY drive in a folder

called lib. Part of what makes CircuitPython so great is its ability to store code

separately from the firmware itself. Storing code separately from the firmware makes

it easier to update both the code you write and the libraries you depend.

Your board may ship with a lib folder already, it's in the base directory of the drive. If

not, simply create the folder yourself. When you first install CircuitPython, an empty lib

directory will be created for you.

©Adafruit Industries Page 61 of 217

CircuitPython libraries work in the same way as regular Python modules so the Python

docs() are an excellent reference for how it all should work. In Python terms, you can

place our library files in the lib directory because it's part of the Python path by

default.

One downside of this approach of separate libraries is that they are not built in. To

use them, one needs to copy them to the CIRCUITPY drive before they can be used.

Fortunately, there is a library bundle.

The bundle and the library releases on GitHub also feature optimized versions of the

libraries with the .mpy file extension. These files take less space on the drive and

have a smaller memory footprint as they are loaded.

Due to the regular updates and space constraints, Adafruit does not ship boards with

the entire bundle. Therefore, you will need to load the libraries you need when you

begin working with your board. You can find example code in the guides for your

board that depends on external libraries.

Either way, as you start to explore CircuitPython, you'll want to know how to get

libraries on board.

The Adafruit Learn Guide Project Bundle

The quickest and easiest way to get going with a project from the Adafruit Learn

System is by utilising the Project Bundle. Most guides now have a Download Project

Bundle button available at the top of the full code example embed. This button

downloads all the necessary files, including images, etc., to get the guide project up

and running. Simply click, open the resulting zip, copy over the right files, and you're

good to go!

The first step is to find the Download Project Bundle button in the guide you're

working on.

©Adafruit Industries Page 62 of 217

The Download Project Bundle button is only available on full demo code

embedded from GitHub in a Learn guide. Code snippets will NOT have the

button available.

When you copy the contents of the Project Bundle to your CIRCUITPY drive, it

will replace all the existing content! If you don't want to lose anything, ensure you

copy your current code to your computer before you copy over the new Project

Bundle content!

The Download Project Bundle button downloads a zip file. This zip contains a series

of directories, nested within which is the code.py, any applicable assets like images or

audio, and the lib/ folder containing all the necessary libraries. The following zip was

downloaded from the Piano in the Key of Lime guide.

The Piano in the Key of Lime guide was chosen as an example. That guide is

specific to Circuit Playground Express, and cannot be used on all boards. Do not

©Adafruit Industries Page 63 of 217

expect to download that exact bundle and have it work on your non-CPX

microcontroller.

When you open the zip, you'll find some nested directories. Navigate through them

until you find what you need. You'll eventually find a directory for your CircuitPython

version (in this case, 7.x). In the version directory, you'll find the file and directory you

need: code.py and lib/. Once you find the content you need, you can copy it all over

to your CIRCUITPY drive, replacing any files already on the drive with the files from

the freshly downloaded zip.

In some cases, there will be other files such as audio or images in the same

directory as code.py and lib/. Make sure you include all the files when you copy

things over!

Once you copy over all the relevant files, the project should begin running! If you find

that the project is not running as expected, make sure you've copied ALL of the

project files onto your microcontroller board.

That's all there is to using the Project Bundle!

The Adafruit CircuitPython Library Bundle

Adafruit provides CircuitPython libraries for much of the hardware they provide,

including sensors, breakouts and more. To eliminate the need for searching for each

library individually, the libraries are available together in the Adafruit CircuitPython

Library Bundle. The bundle contains all the files needed to use each library.

Downloading the Adafruit CircuitPython Library Bundle

You can download the latest Adafruit CircuitPython Library Bundle release by clicking

the button below. The libraries are being constantly updated and improved, so you'll

always want to download the latest bundle.

Match up the bundle version with the version of CircuitPython you are running. For

example, you would download the 6.x library bundle if you're running any version of

CircuitPython 6, or the 7.x library bundle if you're running any version of CircuitPython

7, etc. If you mix libraries with major CircuitPython versions, you will get incompatible

mpy errors due to changes in library interfaces possible during major version

changes.

©Adafruit Industries Page 64 of 217

Click to visit circuitpython.org for the

latest Adafruit CircuitPython Library

Bundle

Download the bundle version that matches your CircuitPython firmware version. If you

don't know the version, check the version info in boot_out.txt file on the CIRCUITPY

drive, or the initial prompt in the CircuitPython REPL. For example, if you're running

v7.0.0, download the 7.x library bundle.

There's also a py bundle which contains the uncompressed python files, you probably

don't want that unless you are doing advanced work on libraries.

The CircuitPython Community Library Bundle

The CircuitPython Community Library Bundle is made up of libraries written and

provided by members of the CircuitPython community. These libraries are often

written when community members encountered hardware not supported in the

Adafruit Bundle, or to support a personal project. The authors all chose to submit

these libraries to the Community Bundle make them available to the community.

These libraries are maintained by their authors and are not supported by Adafruit. As

you would with any library, if you run into problems, feel free to file an issue on the

GitHub repo for the library. Bear in mind, though, that most of these libraries are

supported by a single person and you should be patient about receiving a response.

Remember, these folks are not paid by Adafruit, and are volunteering their personal

time when possible to provide support.

Downloading the CircuitPython Community Library Bundle

You can download the latest CircuitPython Community Library Bundle release by

clicking the button below. The libraries are being constantly updated and improved,

so you'll always want to download the latest bundle.

Click for the latest CircuitPython

Community Library Bundle release

The link takes you to the latest release of the CircuitPython Community Library

Bundle on GitHub. There are multiple versions of the bundle available. Download the

bundle version that matches your CircuitPython firmware version. If you don't know

©Adafruit Industries Page 65 of 217

the version, check the version info in boot_out.txt file on the CIRCUITPY drive, or the

initial prompt in the CircuitPython REPL. For example, if you're running v7.0.0,

download the 7.x library bundle.

Understanding the Bundle

After downloading the zip, extract its contents. This is usually done by double clicking

on the zip. On Mac OSX, it places the file in the same directory as the zip.

Open the bundle folder. Inside you'll find two information files, and two folders. One

folder is the lib bundle, and the other folder is the examples bundle.

Now open the lib folder. When you open the folder, you'll see a large number of .mpy

files, and folders.

Example Files

All example files from each library are now included in the bundles in an examples

directory (as seen above), as well as an examples-only bundle. These are included for

two main reasons:

Allow for quick testing of devices.

•

©Adafruit Industries Page 66 of 217

Provide an example base of code, that is easily built upon for individualized

•

purposes.

Copying Libraries to Your Board

First open the lib folder on your CIRCUITPY drive. Then, open the lib folder you

extracted from the downloaded zip. Inside you'll find a number of folders and .mpy

files. Find the library you'd like to use, and copy it to the lib folder on CIRCUITPY.

If the library is a directory with multiple .mpy files in it, be sure to copy the entire

folder to CIRCUITPY/lib.

This also applies to example files. Open the examples folder you extracted from the

downloaded zip, and copy the applicable file to your CIRCUITPY drive. Then, rename

it to code.py to run it.

If a library has multiple .mpy files contained in a folder, be sure to copy the entire

folder to CIRCUITPY/lib.

Understanding Which Libraries to Install

You now know how to load libraries on to your CircuitPython-compatible

microcontroller board. You may now be wondering, how do you know which libraries

you need to install? Unfortunately, it's not always straightforward. Fortunately, there is

an obvious place to start, and a relatively simple way to figure out the rest. First up:

the best place to start.

When you look at most CircuitPython examples, you'll see they begin with one or
more import statements. These typically look like the following:

import library_or_module

•

©Adafruit Industries Page 67 of 217

However, import statements can also sometimes look like the following:

from library_or_module import name

•

from library_or_module.subpackage import name

•

from library_or_module import name as local_name

•

They can also have more complicated formats, such as including a try / except

block, etc.

The important thing to know is that an import statement will always include the

name of the module or library that you're importing.

Therefore, the best place to start is by reading through the import statements.

Here is an example import list for you to work with in this section. There is no setup or

other code shown here, as the purpose of this section involves only the import list.

import time
import board
import neopixel
import adafruit_lis3dh
import usb_hid
from adafruit_hid.consumer_control import ConsumerControl
from adafruit_hid.consumer_control_code import ConsumerControlCode

Keep in mind, not all imported items are libraries. Some of them are almost always

built-in CircuitPython modules. How do you know the difference? Time to visit the

REPL.

In the Interacting with the REPL section() on The REPL page() in this guide, the

help("modules") command is discussed. This command provides a list of all of the

built-in modules available in CircuitPython for your board. So, if you connect to the
serial console on your board, and enter the REPL, you can run help("modules") to
see what modules are available for your board. Then, as you read through the impor

t statements, you can, for the purposes of figuring out which libraries to load, ignore

the statement that import modules.

The following is the list of modules built into CircuitPython for the Feather RP2040.

Your list may look similar or be anything down to a significant subset of this list for

smaller boards.

©Adafruit Industries Page 68 of 217

Now that you know what you're looking for, it's time to read through the import
statements. The first two, time and board , are on the modules list above, so they're

built-in.

The next one, neopixel , is not on the module list. That means it's your first library!

So, you would head over to the bundle zip you downloaded, and search for neopixel.

There is a neopixel.mpy file in the bundle zip. Copy it over to the lib folder on your CI
RCUITPY drive. The following one, adafruit_lis3dh , is also not on the module list.

Follow the same process for adafruit_lis3dh, where you'll find adafruit_lis3dh.mpy,

and copy that over.

The fifth one is usb_hid , and it is in the modules list, so it is built in. Often all of the

built-in modules come first in the import list, but sometimes they don't! Don't assume

that everything after the first library is also a library, and verify each import with the

modules list to be sure. Otherwise, you'll search the bundle and come up empty!

The final two imports are not as clear. Remember, when import statements are
formatted like this, the first thing after the from is the library name. In this case, the
library name is adafruit_hid . A search of the bundle will find an adafruit_hid folder.

When a library is a folder, you must copy the entire folder and its contentsas it is in

the bundle to the lib folder on your CIRCUITPY drive. In this case, you would copy the

entire adafruit_hid folder to your CIRCUITPY/lib folder.

Notice that there are two imports that begin with adafruit_hid . Sometimes you will

need to import more than one thing from the same library. Regardless of how many

times you import the same library, you only need to load the library by copying over

the adafruit_hid folder once.

That is how you can use your example code to figure out what libraries to load on

your CircuitPython-compatible board!

©Adafruit Industries Page 69 of 217

There are cases, however, where libraries require other libraries internally. The

internally required library is called a dependency. In the event of library

dependencies, the easiest way to figure out what other libraries are required is to
connect to the serial console and follow along with the ImportError printed there.
The following is a very simple example of an ImportError , but the concept is the

same for any missing library.

Example: ImportError Due to Missing Library

If you choose to load libraries as you need them, or you're starting fresh with an

existing example, you may end up with code that tries to use a library you haven't yet

loaded. This section will demonstrate what happens when you try to utilise a library

that you don't have loaded on your board, and cover the steps required to resolve the

issue.

This demonstration will only return an error if you do not have the required library

loaded into the lib folder on your CIRCUITPY drive.

Let's use a modified version of the Blink example.

import board
import time
import simpleio

led = simpleio.DigitalOut(board.LED)

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

Save this file. Nothing happens to your board. Let's check the serial console to see

what's going on.

©Adafruit Industries Page 70 of 217

You have an ImportError . It says there is no module named 'simpleio' . That's

the one you just included in your code!

Click the link above to download the correct bundle. Extract the lib folder from the

downloaded bundle file. Scroll down to find simpleio.mpy. This is the library file you're

looking for! Follow the steps above to load an individual library file.

The LED starts blinking again! Let's check the serial console.

No errors! Excellent. You've successfully resolved an ImportError !

If you run into this error in the future, follow along with the steps above and choose

the library that matches the one you're missing.

Library Install on Non-Express Boards

If you have an M0 non-Express board such as Trinket M0, Gemma M0, QT Py M0, or

one of the M0 Trinkeys, you'll want to follow the same steps in the example above to
install libraries as you need them. Remember, you don't need to wait for an ImportEr

ror if you know what library you added to your code. Open the library bundle you

downloaded, find the library you need, and drag it to the lib folder on your CIRCUITPY

drive.

You can still end up running out of space on your M0 non-Express board even if you

only load libraries as you need them. There are a number of steps you can use to try

to resolve this issue. You'll find suggestions on the Troubleshooting page().

Updating CircuitPython Libraries and Examples

Libraries and examples are updated from time to time, and it's important to update the

files you have on your CIRCUITPY drive.

To update a single library or example, follow the same steps above. When you drag

the library file to your lib folder, it will ask if you want to replace it. Say yes. That's it!

©Adafruit Industries Page 71 of 217

A new library bundle is released every time there's an update to a library. Updates

include things like bug fixes and new features. It's important to check in every so

often to see if the libraries you're using have been updated.

CircUp CLI Tool

There is a command line interface (CLI) utility called CircUp() that can be used to

easily install and update libraries on your device. Follow the directions on the install

page within the CircUp learn guide(). Once you've got it installed you run the

command circup update in a terminal to interactively update all libraries on the

connected CircuitPython device. See the usage page in the CircUp guide() for a full

list of functionality

Frequently Asked Questions

These are some of the common questions regarding CircuitPython and CircuitPython

microcontrollers.

What are some common acronyms to know?

CP or CPy = CircuitPython()

CPC = Circuit Playground Classic()(does not run CircuitPython)

CPX = Circuit Playground Express()

CPB = Circuit Playground Bluefruit()

Using Older Versions

As CircuitPython development continues and there are new releases, Adafruit

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 CircuitPython 6.x or earlier. Where can I find compatible libraries?

We are no longer building or supporting the CircuitPython 6.x or earlier library

bundles. We highly encourage you to update CircuitPython to the latest version()

©Adafruit Industries Page 72 of 217

and use the current version of the libraries(). However, if for some reason you

cannot update, here are the last available library bundles for older versions:

2.x bundle()

•

3.x bundle()

•

4.x bundle()

•

5.x bundle()

•

6.x bundle()

•

Python Arithmetic

Does CircuitPython support floating-point numbers?

All CircuitPython boards support floating point arithmetic, even if the

microcontroller chip does not support floating point in hardware. Floating point

numbers are stored in 30 bits, with an 8-bit exponent and a 22-bit mantissa. Note

that this is two bits less than standard 32-bit single-precision floats. You will get

about 5-1/2 digits of decimal precision.

(Thebroadcomport may provide 64-bit floats in some cases.)

Does CircuitPython support long integers, like regular Python?

Python long integers (integers of arbitrary size) are available on most builds, except

those on boards with the smallest available firmware size. On these boards,

integers are stored in 31 bits.

Boards without long integer support are mostly SAMD21 ("M0") boards without an

external flash chip, such as the Adafruit Gemma M0, Trinket M0, QT Py M0, and the

Trinkey series. There are also a number of third-party boards in this category.

There are also a few small STM third-party boards without long integer support.

time.localtime() , time.mktime() , time.time() , and

time.monotonic_ns() are available only on builds with long integers.

Wireless Connectivity

©Adafruit Industries Page 73 of 217

How do I connect to the Internet with CircuitPython?

If you'd like to include WiFi in your project, your best bet is to use a board that is

running natively on ESP32 chipsets - those have WiFi built in!

If your development board has an SPI port and at least 4 additional pins, you can

check out this guide() on using AirLift with CircuitPython - extra wiring is required

and some boards like the MacroPad or NeoTrellis do not have enough available

pins to add the hardware support.

For further project examples, and guides about using AirLift with specific hardware,

check out the Adafruit Learn System().

How do I do BLE (Bluetooth Low Energy) with CircuitPython?

The nRF52840 and nRF52833 boards have the most complete BLE

implementation. Your program can act as both a BLE central and peripheral. As a

central, you can scan for advertisements, and connect to an advertising board. As a

peripheral, you can advertise, and you can create services available to a central.

Pairing and bonding are supported.

ESP32-C3 and ESP32-S3 boards currently provide an incomplete()BLE

implementation. Your program can act as a central, and connect to a peripheral.

You can advertise, but you cannot create services. You cannot advertise

anonymously. Pairing and bonding are not supported.

The ESP32 could provide a similar implementation, but it is not yet available. Note

that the ESP32-S2 does not have Bluetooth capability.

On most other boards with adequate firmware space, BLE is available for use with

AirLift() or other NINA-FW-based co-processors. Some boards have this

coprocessor on board, such as the PyPortal(). Currently, this implementation only

supports acting as a BLE peripheral. Scanning and connecting as a central are not

yet implemented. Bonding and pairing are not supported.

Are there other ways to communicate by radio with CircuitPython?

Check out Adafruit's RFM boards ()for simple radio communication supported by

CircuitPython, which can be used over distances of 100m to over a km, depending

on the version. The RFM SAMD21 M0 boards can be used, but they were not

©Adafruit Industries Page 74 of 217

designed for CircuitPython, and have limited RAM and flash space; using the RFM

breakouts or FeatherWings with more capable boards will be easier.

Asyncio and Interrupts

Is there asyncio support in CircuitPython?

There is support for asyncio starting with CircuitPython 7.1.0, on all boards except

the smallest SAMD21 builds. Read about using it in the Cooperative Multitasking in

CircuitPython() Guide.

Does CircuitPython support interrupts?

No. CircuitPython does not currently support interrupts - please use asyncio for

multitasking / 'threaded' control of your code

Status RGB LED

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!()

Memory Issues

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.

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.

©Adafruit Industries Page 75 of 217

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() 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 here(). Builds are

available for Windows, macOS, x64 Linux, and Raspberry Pi Linux. Choose the
latest mpy-cross whose version matches the version of CircuitPython you are

using.

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?

Run the following to see the number of bytes available for use:

import gc

gc.mem_free()

Unsupported Hardware

©Adafruit Industries Page 76 of 217

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()!

As of CircuitPython 8.x we have started to support ESP32 and ESP32-C3 and have

added a WiFi workflow for wireless coding!()

We also support ESP32-S2 & ESP32-S3, which have native USB.

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.

Welcome to the Community!

CircuitPython is a programming language that's super simple to get started with and

great for learning. It runs on microcontrollers and works out of the box. You can plug it

in and get started with any text editor. The best part? CircuitPython comes with an

amazing, supportive community.

Everyone is welcome! CircuitPython is Open Source. This means it's available for

anyone to use, edit, copy and improve upon. This also means CircuitPython becomes

better because of you being a part of it. Whether this is your first microcontroller

©Adafruit Industries Page 77 of 217

board or you're a seasoned software engineer, you have something important to offer

the Adafruit CircuitPython community. This page highlights some of the many ways

you can be a part of it!

Adafruit Discord

The Adafruit Discord server is the best place to start. Discord is where the community

comes together to volunteer and provide live support of all kinds. From general

discussion to detailed problem solving, and everything in between, Discord is a digital

maker space with makers from around the world.

There are many different channels so you can choose the one best suited to your

needs. Each channel is shown on Discord as "#channelname". There's the #help-with-

projects channel for assistance with your current project or help coming up with ideas

for your next one. There's the #show-and-tell channel for showing off your newest

creation. Don't be afraid to ask a question in any channel! If you're unsure, #general is

a great place to start. If another channel is more likely to provide you with a better

answer, someone will guide you.

The help with CircuitPython channel is where to go with your CircuitPython questions.

#help-with-circuitpython is there for new users and developers alike so feel free to

ask a question or post a comment! Everyone of any experience level is welcome to

join in on the conversation. Your contributions are important! The #circuitpython-dev

channel is available for development discussions as well.

The easiest way to contribute to the community is to assist others on Discord.

Supporting others doesn't always mean answering questions. Join in celebrating

successes! Celebrate your mistakes! Sometimes just hearing that someone else has

gone through a similar struggle can be enough to keep a maker moving forward.

©Adafruit Industries Page 78 of 217

The Adafruit Discord is the 24x7x365 hackerspace that you can bring your

granddaughter to.

Visit https://adafru.it/discord ()to sign up for Discord. Everyone is looking forward to

meeting you!

CircuitPython.org

Beyond the Adafruit Learn System, which you are viewing right now, the best place to

find information about CircuitPython is circuitpython.org(). Everything you need to get

started with your new microcontroller and beyond is available. You can do things like

download CircuitPython for your microcontroller() or download the latest

CircuitPython Library bundle(), or check out which single board computers support

Blinka(). You can also get to various other CircuitPython related things like Awesome

CircuitPython or the Python for Microcontrollers newsletter. This is all incredibly

useful, but it isn't necessarily community related. So why is it included here? The Cont

ributing page().

CircuitPython itself is written in C. However, all of the Adafruit CircuitPython libraries

are written in Python. If you're interested in contributing to CircuitPython on the

Python side of things, check out circuitpython.org/contributing(). You'll find

information pertaining to every Adafruit CircuitPython library GitHub repository, giving

you the opportunity to join the community by finding a contributing option that works

for you.

©Adafruit Industries Page 79 of 217

Note the date on the page next to Current Status for:

If you submit any contributions to the libraries, and do not see them reflected on the

Contributing page, it could be that the job that checks for new updates hasn't yet run

for today. Simply check back tomorrow!

Now, a look at the different options.

Pull Requests

The first tab you'll find is a list of open pull requests.

GitHub pull requests, or PRs, are opened when folks have added something to an

Adafruit CircuitPython library GitHub repo, and are asking for Adafruit to add, or

merge, their changes into the main library code. For PRs to be merged, they must first

be reviewed. Reviewing is a great way to contribute! Take a look at the list of open

pull requests, and pick one that interests you. If you have the hardware, you can test

code changes. If you don't, you can still check the code updates for syntax. In the

case of documentation updates, you can verify the information, or check it for spelling

and grammar. Once you've checked out the update, you can leave a comment letting

us know that you took a look. Once you've done that for a while, and you're more

comfortable with it, you can consider joining the CircuitPythonLibrarians review team.

The more reviewers we have, the more authors we can support. Reviewing is a crucial

part of an open source ecosystem, CircuitPython included.

Open Issues

The second tab you'll find is a list of open issues.

©Adafruit Industries Page 80 of 217

GitHub issues are filed for a number of reasons, including when there is a bug in the

library or example code, or when someone wants to make a feature request. Issues

are a great way to find an opportunity to contribute directly to the libraries by

updating code or documentation. If you're interested in contributing code or

documentation, take a look at the open issues and find one that interests you.

If you're not sure where to start, you can search the issues by label. Labels are

applied to issues to make the goal easier to identify at a first glance, or to indicate the

difficulty level of the issue. Click on the dropdown next to "Sort by issue labels" to see

the list of available labels, and click on one to choose it.

If you're new to everything, new to contributing to open source, or new to

contributing to the CircuitPython project, you can choose "Good first issue". Issues

with that label are well defined, with a finite scope, and are intended to be easy for

someone new to figure out.

If you're looking for something a little more complicated, consider "Bug" or

"Enhancement". The Bug label is applied to issues that pertain to problems or failures

found in the library. The Enhancement label is applied to feature requests.

©Adafruit Industries Page 81 of 217

Don't let the process intimidate you. If you're new to Git and GitHub, there is a guide()

to walk you through the entire process. As well, there are always folks available on Di

scord() to answer questions.

Library Infrastructure Issues

The third tab you'll find is a list of library infrastructure issues.

This section is generated by a script that runs checks on the libraries, and then

reports back where there may be issues. It is made up of a list of subsections each

containing links to the repositories that are experiencing that particular issue. This

page is available mostly for internal use, but you may find some opportunities to

contribute on this page. If there's an issue listed that sounds like something you could

help with, mention it on Discord, or file an issue on GitHub indicating you're working

to resolve that issue. Others can reply either way to let you know what the scope of it

might be, and help you resolve it if necessary.

CircuitPython Localization

The fourth tab you'll find is the CircuitPython Localization tab.

If you speak another language, you can help translate CircuitPython! The translations

apply to informational and error messages that are within the CircuitPython core. It

means that folks who do not speak English have the opportunity to have these

messages shown to them in their own language when using CircuitPython. This is

incredibly important to provide the best experience possible for all users.

©Adafruit Industries Page 82 of 217

CircuitPython uses Weblate to translate, which makes it much simpler to contribute

translations. You will still need to know some CircuitPython-specific practices and a

few basics about coding strings, but as with any CircuitPython contributions, folks are

there to help.

Regardless of your skill level, or how you want to contribute to the CircuitPython

project, there is an opportunity available. The Contributing page() is an excellent

place to start!

Adafruit GitHub

Whether you're just beginning or are life-long programmer who would like to

contribute, there are ways for everyone to be a part of the CircuitPython project. The

CircuitPython core is written in C. The libraries are written in Python. GitHub is the

best source of ways to contribute to the CircuitPython core(), and the CircuitPython

libraries(). If you need an account, visit https://github.com/()and sign up.

If you're new to GitHub or programming in general, there are great opportunities for

you. For the CircuitPython core, head over to the CircuitPython repository on GitHub,

click on "Issues()", and you'll find a list that includes issues labeled "good first issue()"

. For the libraries, head over to the Contributing page Issues list(), and use the drop

down menu to search for "good first issue()". These issues are things that have been

identified as something that someone with any level of experience can help with.

These issues include options like updating documentation, providing feedback, and

fixing simple bugs. If you need help getting started with GitHub, there is an excellent

guide on Contributing to CircuitPython with Git and GitHub().

Already experienced and looking for a challenge? Checkout the rest of either issues

list and you'll find plenty of ways to contribute. You'll find all sorts of things, from new

driver requests, to library bugs, to core module updates. There's plenty of

opportunities for everyone at any level!

©Adafruit Industries Page 83 of 217

When working with or using CircuitPython or the CircuitPython libraries, you may find

problems. If you find a bug, that's great! The team loves bugs! Posting a detailed issue

to GitHub is an invaluable way to contribute to improving CircuitPython. For

CircuitPython itself, file an issue here(). For the libraries, file an issue on the specific

library repository on GitHub. Be sure to include the steps to replicate the issue as well

as any other information you think is relevant. The more detail, the better!

Testing new software is easy and incredibly helpful. Simply load the newest version of

CircuitPython or a library onto your CircuitPython hardware, and use it. Let us know

about any problems you find by posting a new issue to GitHub. Software testing on

both stable and unstable releases is a very important part of contributing

CircuitPython. The developers can't possibly find all the problems themselves! They

need your help to make CircuitPython even better.

On GitHub, you can submit feature requests, provide feedback, report problems and

much more. If you have questions, remember that Discord and the Forums are both

there for help!

Adafruit Forums

The Adafruit Forums() are the perfect place for support. Adafruit has wonderful paid

support folks to answer any questions you may have. Whether your hardware is giving

you issues or your code doesn't seem to be working, the forums are always there for

you to ask. You need an Adafruit account to post to the forums. You can use the same

account you use to order from Adafruit.

While Discord may provide you with quicker responses than the forums, the forums

are a more reliable source of information. If you want to be certain you're getting an

Adafruit-supported answer, the forums are the best place to be.

There are forum categories that cover all kinds of topics, including everything

Adafruit. The Adafruit CircuitPython()category under "Supported Products & Projects"

is the best place to post your CircuitPython questions.

©Adafruit Industries Page 84 of 217

Be sure to include the steps you took to get to where you are. If it involves wiring,

post a picture! If your code is giving you trouble, include your code in your post!

These are great ways to make sure that there's enough information to help you with

your issue.

You might think you're just getting started, but you definitely know something that

someone else doesn't. The great thing about the forums is that you can help others

too! Everyone is welcome and encouraged to provide constructive feedback to any of

the posted questions. This is an excellent way to contribute to the community and

share your knowledge!

Read the Docs

Read the Docs() is a an excellent resource for a more detailed look at the

CircuitPython core and the CircuitPython libraries. This is where you'll find things like

API documentation and example code. For an in depth look at viewing and

understanding Read the Docs, check out the CircuitPython Documentation() page!

©Adafruit Industries Page 85 of 217

Advanced Serial Console on Windows

Windows 7 and 8.1

If you're using Windows 7 (or 8 or 8.1), you'll need to install drivers. See the Windows 7

and 8.1 Drivers page() for details. You will not need to install drivers on Mac, Linux or

Windows 10.

You are strongly encouraged to upgrade to Windows 10 if you are still using Windows

7 or Windows 8 or 8.1. Windows 7 has reached end-of-life and no longer receives

security updates. A free upgrade to Windows 10 is still available().

What's the COM?

First, you'll want to find out which serial port your board is using. When you plug your

board in to USB on your computer, it connects to a serial port. The port is like a door

through which your board can communicate with your computer using USB.

You'll use Windows Device Manager to determine which port the board is using. The

easiest way to determine which port the board is using is to first check without the

board plugged in. Open Device Manager. Click on Ports (COM & LPT). You should find

something already in that list with (COM#) after it where # is a number.

©Adafruit Industries Page 86 of 217

Now plug in your board. The Device Manager list will refresh and a new item will

appear under Ports (COM & LPT). You'll find a different (COM#) after this item in the

list.

Sometimes the item will refer to the name of the board. Other times it may be called

something like USB Serial Device, as seen in the image above. Either way, there is a

new (COM#) following the name. This is the port your board is using.

©Adafruit Industries Page 87 of 217

Install Putty

If you're using Windows, you'll need to download a terminal program. You're going to

use PuTTY.

The first thing to do is download the latest version of PuTTY(). You'll want to

download the Windows installer file. It is most likely that you'll need the 64-bit version.

Download the file and install the program on your machine. If you run into issues, you

can try downloading the 32-bit version instead. However, the 64-bit version will work

on most PCs.

Now you need to open PuTTY.

Under Connection type: choose the button next to Serial.

•

In the box under Serial line, enter the serial port you found that your board is

•

using.

In the box under Speed, enter 115200. This called the baud rate, which is the

•

speed in bits per second that data is sent over the serial connection. For boards

with built in USB it doesn't matter so much but for ESP8266 and other board

with a separate chip, the speed required by the board is 115200 bits per second.

So you might as well just use 115200!

If you want to save those settings for later, use the options under Load, save or delete

a stored session. Enter a name in the box under Saved Sessions, and click the Save

button on the right.

©Adafruit Industries Page 88 of 217

Once your settings are entered, you're ready to connect to the serial console. Click

"Open" at the bottom of the window. A new window will open.

If no code is running, the window will either be blank or will look like the window

above. Now you're ready to see the results of your code.

Great job! You've connected to the serial console!

©Adafruit Industries Page 89 of 217

Advanced Serial Console on Mac

Connecting to the serial console on Mac does not require installing any drivers or
extra software. You'll use a terminal program to find your board, and screen to
connect to it. Terminal and screen both come installed by default.

What's the Port?

First you'll want to find out which serial port your board is using. When you plug your

board in to USB on your computer, it connects to a serial port. The port is like a door

through which your board can communicate with your computer using USB.

The easiest way to determine which port the board is using is to first check without

the board plugged in. Open Terminal and type the following:

ls /dev/tty.*

Each serial connection shows up in the /dev/ directory. It has a name that starts with

tty. . The command ls shows you a list of items in a directory. You can use * as a

wildcard, to search for files that start with the same letters but end in something
different. In this case, you're asking to see all of the listings in /dev/ that start with t

ty. and end in anything. This will show us the current serial connections.

Now, plug your board. In Terminal, type:

ls /dev/tty.*

This will show you the current serial connections, which will now include your board.

©Adafruit Industries Page 90 of 217

A new listing has appeared called /dev/tty.usbmodem141441 . The tty.usbmodem1

41441 part of this listing is the name the example board is using. Yours will be called

something similar.

Using Linux, a new listing has appeared called /dev/ttyACM0 . The ttyACM0 part of

this listing is the name the example board is using. Yours will be called something

similar.

Connect with screen

Now that you know the name your board is using, you're ready connect to the serial
console. You're going to use a command called screen . The screen command is

included with MacOS. To connect to the serial console, use Terminal. Type the
following command, replacing board_name with the name you found your board is

using:

screen /dev/tty.board_name 115200

The first part of this establishes using the screen command. The second part tells

screen the name of the board you're trying to use. The third part tells screen what

baud rate to use for the serial connection. The baud rate is the speed in bits per

second that data is sent over the serial connection. In this case, the speed required

by the board is 115200 bits per second.

©Adafruit Industries Page 91 of 217

Press enter to run the command. It will open in the same window. If no code is

running, the window will be blank. Otherwise, you'll see the output of your code.

Great job! You've connected to the serial console!

"Uninstalling" CircuitPython

A lot of our boards can be used with multiple programming languages. For example,

the Circuit Playground Express can be used with MakeCode, Code.org CS

Discoveries, CircuitPython and Arduino.

Maybe you tried CircuitPython and want to go back to MakeCode or Arduino? Not a

problem. You can always remove or reinstall CircuitPython whenever you want! Heck,

you can change your mind every day!

There is nothing to uninstall. CircuitPython is "just another program" that is loaded

onto your board. You simply load another program (Arduino or MakeCode) and it will

overwrite CircuitPython.

Backup Your Code

Before replacing CircuitPython, don't forget to make a backup of the code you have

on the CIRCUITPY drive. That means your code.py any other files, the lib folder etc.

You may lose these files when you remove CircuitPython, so backups are key! Just

drag the files to a folder on your laptop or desktop computer like you would with any

USB drive.

©Adafruit Industries Page 92 of 217

Moving Circuit Playground Express to MakeCode

On the Circuit Playground Express (this currently does NOT apply to Circuit

Playground Bluefruit), if you want to go back to using MakeCode, it's really easy. Visit

makecode.adafruit.com() and find the program you want to upload. Click Download to

download the .uf2 file that is generated by MakeCode.

Now double-click your CircuitPython board until you see the onboard LED(s) turn

green and the ...BOOT directory shows up.

Then find the downloaded MakeCode .uf2 file and drag it to the CPLAYBOOT drive.

©Adafruit Industries Page 93 of 217

Your MakeCode is now running and CircuitPython has been removed. Going forward

you only have to single click the reset button to get to CPLAYBOOT. This is an

idiosyncrasy of MakeCode.

Moving to Arduino

If you want to use Arduino instead, you just use the Arduino IDE to load an Arduino

program. Here's an example of uploading a simple "Blink" Arduino program, but you

don't have to use this particular program.

Start by plugging in your board, and double-clicking reset until you get the green

onboard LED(s).

Within Arduino IDE, select the matching board, say Circuit Playground Express.

Select the correct matching Port:

Create a new simple Blink sketch example:

// the setup function runs once when you press reset or power the board
void setup() {
// initialize digital pin 13 as an output.
pinMode(13, OUTPUT);
}

©Adafruit Industries Page 94 of 217

// the loop function runs over and over again forever
void loop() {
digitalWrite(13, HIGH); // turn the LED on (HIGH is the voltage level)
delay(1000); // wait for a second
digitalWrite(13, LOW); // turn the LED off by making the voltage LOW
delay(1000); // wait for a second
}

Make sure the LED(s) are still green, then click Upload to upload Blink. Once it has

uploaded successfully, the serial Port will change so re-select the new Port!

Once Blink is uploaded you should no longer need to double-click to enter

bootloader mode. Arduino will automatically reset when you upload.

Troubleshooting

From time to time, you will run into issues when working with CircuitPython. Here are

a few things you may encounter and how to resolve them.

As CircuitPython development continues and there are new releases, Adafruit

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.

Always Run the Latest Version of CircuitPython and Libraries

As CircuitPython development continues and there are new releases, Adafruit will

stop supporting older releases. You need to update to the latest CircuitPython.().

You need to download the CircuitPython Library Bundle that matches your version of

CircuitPython. Please update CircuitPython and then download the latest bundle().

As new versions of CircuitPython are released, Adafruit will stop providing the

previous bundles as automatically created downloads on the Adafruit CircuitPython

Library Bundle repo. If you must continue to use an earlier version, you can still
download the appropriate version of mpy-cross from the particular release of

CircuitPython on the CircuitPython repo and create your own compatible .mpy library

files. However, it is best to update to the latest for both CircuitPython and the library

bundle.

©Adafruit Industries Page 95 of 217

I have to continue using CircuitPython 5.x or earlier. Where can I find compatible libraries?

Adafruit is no longer building or supporting the CircuitPython 5.x or earlier library

bundles. You are highly encourged to update CircuitPython to the latest version() and

use the current version of the libraries(). However, if for some reason you cannot

update, links to the previous bundles are available in the FAQ().

Bootloader (boardnameBOOT) Drive Not Present

You may have a different board.

Only Adafruit Express boards and the SAMD21 non-Express boards ship with the UF2

bootloader ()installed. The Feather M0 Basic, Feather M0 Adalogger, and similar

boards use a regular Arduino-compatible bootloader, which does not show a boardna

meBOOT drive.

MakeCode

If you are running a MakeCode() program on Circuit Playground Express, press the

reset button just onceto get the CPLAYBOOT drive to show up. Pressing it twice will

not work.

MacOS

DriveDx and its accompanything SAT SMART Driver can interfere with seeing the

BOOT drive. See this forum post() for how to fix the problem.

Windows 10

Did you install the Adafruit Windows Drivers package by mistake, or did you upgrade

to Windows 10 with the driver package installed? You don't need to install this

package on Windows 10 for most Adafruit boards. The old version (v1.5) can interfere

with recognizing your device. Go to Settings -> Apps and uninstall all the "Adafruit"

driver programs.

©Adafruit Industries Page 96 of 217

Windows 7 or 8.1

To use a CircuitPython-compatible board with Windows 7 or 8.1, you must install a

driver. Installation instructions are available here().

It is recommended() that you upgrade to Windows 10 if possible; an upgrade is

probably still free for you. Check here().

The Windows Drivers installer was last updated in November 2020 (v2.5.0.0) .

Windows 7 drivers for CircuitPython boards released since then, including

RP2040 boards, are not yet available. The boards work fine on Windows 10. A

new release of the drivers is in process.

You should now be done! Test by unplugging and replugging the board. You should

see the CIRCUITPY drive, and when you double-click the reset button (single click on

Circuit Playground Express running MakeCode), you should see the appropriateboar

dnameBOOT drive.

Let us know in the Adafruit support forums() or on the Adafruit Discord() if this does

not work for you!

Windows Explorer Locks Up When Accessing boardnameBOOT Drive

On Windows, several third-party programs that can cause issues. The symptom is that

you try to access the boardnameBOOTdrive, and Windows or Windows Explorer

seems to lock up. These programs are known to cause trouble:

AIDA64: to fix, stop the program. This problem has been reported to AIDA64.

•

They acquired hardware to test, and released a beta version that fixes the

problem. This may have been incorporated into the latest release. Please let us

know in the forums if you test this.

Hard Disk Sentinel

•

Kaspersky anti-virus: To fix, you may need to disable Kaspersky completely.

•

Disabling some aspects of Kaspersky does not always solve the problem. This

problem has been reported to Kaspersky.

ESET NOD32 anti-virus: There have been problems with at least version

•

9.0.386.0, solved by uninstallation.

©Adafruit Industries Page 97 of 217

Copying UF2 to boardnameBOOT Drive Hangs at 0% Copied

On Windows, a Western DIgital (WD) utility that comes with their external USB drives

can interfere with copying UF2 files to the boardnameBOOT drive. Uninstall that utility

to fix the problem.

CIRCUITPY Drive Does Not Appear or Disappears Quickly

Kaspersky anti-virus can block the appearance of the CIRCUITPY drive. There has not

yet been settings change discovered that prevents this. Complete uninstallation of

Kaspersky fixes the problem.

Norton anti-virus can interfere with CIRCUITPY. A user has reported this problem on

Windows 7. The user turned off both Smart Firewall and Auto Protect, and CIRCUITPY

then appeared.

Sophos Endpoint security software can cause CIRCUITPY to disappear() and the

BOOT drive to reappear. It is not clear what causes this behavior.

Device Errors or Problems on Windows

Windows can become confused about USB device installations. This is particularly

true of Windows 7 and 8.1. It is recommended() that you upgrade to Windows 10 if

possible; an upgrade is probably still free for you: see this link().

If not, try cleaning up your USB devices. Use Uwe Sieber's Device Cleanup Tool()(on

that page, scroll down to "Device Cleanup Tool"). Download and unzip the tool.

Unplug all the boards and other USB devices you want to clean up. Run the tool as

Administrator. You will see a listing like this, probably with many more devices. It is

listing all the USB devices that are not currently attached.

©Adafruit Industries Page 98 of 217

Select all the devices you want to remove, and then press Delete. It is usually safe

just to select everything. Any device that is removed will get a fresh install when you

plug it in. Using the Device Cleanup Tool also discards all the COM port assignments

for the unplugged boards. If you have used many Arduino and CircuitPython boards,

you have probably seen higher and higher COM port numbers used, seemingly

without end. This will fix that problem.

Serial Console in Mu Not Displaying Anything

There are times when the serial console will accurately not display anything, such as,

when no code is currently running, or when code with no serial output is already

running before you open the console. However, if you find yourself in a situation

where you feel it should be displaying something like an error, consider the following.

Depending on the size of your screen or Mu window, when you open the serial

console, the serial console panel may be very small. This can be a problem. A basic

CircuitPython error takes 10 lines to display!

Auto-reload is on. Simply save files over USB to run them or enter REPL to disable.
code.py output:
Traceback (most recent call last):
File "code.py", line 7
SyntaxError: invalid syntax

Press any key to enter the REPL. Use CTRL-D to reload.

More complex errors take even more lines!

©Adafruit Industries Page 99 of 217

Therefore, if your serial console panel is five lines tall or less, you may only see blank
lines or blank lines followed by Press any key to enter the REPL. Use CTRL-D

to reload. . If this is the case, you need to either mouse over the top of the panel to

utilise the option to resize the serial panel, or use the scrollbar on the right side to

scroll up and find your message.

This applies to any kind of serial output whether it be error messages or print

statements. So before you start trying to debug your problem on the hardware side,

be sure to check that you haven't simply missed the serial messages due to serial

output panel height.

code.py Restarts Constantly

CircuitPython will restart code.py if you or your computer writes to something on the

CIRCUITPY drive. This feature is called auto-reload, and lets you test a change to your

program immediately.

Some utility programs, such as backup, anti-virus, or disk-checking apps, will write to

the CIRCUITPY as part of their operation. Sometimes they do this very frequently,

causing constant restarts.

Acronis True Image and related Acronis programs on Windows are known to cause

this problem. It is possible to prevent this by disabling the "()Acronis Managed

Machine Service Mini"().

If you cannot stop whatever is causing the writes, you can disable auto-reload by

putting this code in boot.py or code.py:

import supervisor

supervisor.runtime.autoreload = False

CircuitPython RGB Status Light

Nearly all CircuitPython-capable boards have a single NeoPixel or DotStar RGB LED

on the board that indicates the status of CircuitPython. A few boards designed before

CircuitPython existed, such as the Feather M0 Basic, do not.

©Adafruit Industries Page 100 of 217