Adafruit QT Py RP2040 User manual

Name: Adafruit QT Py RP2040
Brand: Adafruit
SKU: 17905914
Rating: 4.5 (2 reviews)

4.5 (2)

Adafruit QT Py RP2040

Created by Kattni Rembor

Last updated on 2021-05-04 03:50:29 PM EDT

Guide Contents
Guide Contents	2
Overview	5
Plug-and-play STEMMA QT	6
Software Support	7
QT Py RP2040 Specifications	7
About the RP2040	9
Pinouts	11
STEMMA QT	11
Power and USB	11
Input/Output Pins	12
I2C and SPI on RP2040	13
PWM on RP2040	13
Analog Pins	13
Digital Pins	13
CircuitPython I2C, SPI and UART	14
GPIO Pins by Pin Functionality	14
I2C Pins	14
SPI Pins	14
UART Pins	14
PWM Pins	14
Buttons	15
Onboard NeoPixel	15
RP2040 and QSPI Flash	15
USB Host Jumper	16
CircuitPython	17
CircuitPython Quickstart	17
Flash Resetting UF2	18
Installing Mu Editor	20
Download and Install Mu	20
Using Mu	20
Creating and Editing Code	22
Creating Code	22
Editing Code	24
Your code changes are run as soon as the file is done saving.	24
1. Use an editor that writes out the file completely when you save it.	25
2. Eject or Sync the Drive After Writing	26
Oh No I Did Something Wrong and Now The CIRCUITPY Drive Doesn't Show Up!!!	26
Back to Editing Code...	26
Exploring Your First CircuitPython Program	26
Imports & Libraries	27
Setting Up The LED	27
Loop-de-loops	27
What Happens When My Code Finishes Running?	28
What if I don't have the loop?	28
More Changes	28
Naming Your Program File	29
Connecting to the Serial Console	30
Are you using Mu?	30
Setting Permissions on Linux	31

https://learn.adafruit.com/adafruit-qt-py-2040

Page 2 of 90

Using Something Else?	31
Interacting with the Serial Console	32
The REPL	35
Returning to the serial console	38
CircuitPython Pins and Modules	39
CircuitPython Pins	39
import board	39
I2C, SPI, and UART	40
What Are All the Available Names?	41
Microcontroller Pin Names	42
CircuitPython Built-In Modules	42
CircuitPython Libraries	43
Installing the CircuitPython Library Bundle	44
Example Files	45
Copying Libraries to Your Board	45
Example: ImportError Due to Missing Library	46
Library Install on Non-Express Boards	47
Updating CircuitPython Libraries/Examples	47
Frequently Asked Questions	48
I have to continue using an older version of CircuitPython; where can I find compatible libraries?	48
Is ESP8266 or ESP32 supported in CircuitPython? Why not?	48
How do I connect to the Internet with CircuitPython?	48
Is there asyncio support in CircuitPython?	48
My RGB NeoPixel/DotStar LED is blinking funny colors - what does it mean?	48
What is a MemoryError?	49
What do I do when I encounter a MemoryError?	49
Can the order of my import statements affect memory?	49
How can I create my own .mpy files?	49
How do I check how much memory I have free?	49
Does CircuitPython support interrupts?	49
Does Feather M0 support WINC1500?	49
Can AVRs such as ATmega328 or ATmega2560 run CircuitPython?	50
Commonly Used Acronyms	50
Welcome to the Community!	51
Adafruit Discord	51
Adafruit Forums	52
Adafruit Github	53
ReadTheDocs	54
Advanced Serial Console on Windows	55
Windows 7 Driver	55
What's the COM?	55
Install Putty	56
Advanced Serial Console on Mac and Linux	58
What's the Port?	58
Connect with screen	60
Permissions on Linux	61
Troubleshooting	63
Always Run the Latest Version of CircuitPython and Libraries	63
I have to continue using CircuitPython 5.x, 4.x, 3.x or 2.x, where can I find compatible
libraries?	63

https://learn.adafruit.com/adafruit-qt-py-2040

Page 3 of 90

CPLAYBOOT, TRINKETBOOT, FEATHERBOOT, or GEMMABOOT Drive Not Present	63
You may have a different board.	63
MakeCode	63
MacOS	64
Windows 10	64
Windows 7 or 8.1	64
Windows Explorer Locks Up When Accessing boardnameBOOT Drive	65
Copying UF2 to boardnameBOOT Drive Hangs at 0% Copied	65
CIRCUITPY Drive Does Not Appear	65
Windows 7 and 8.1 Problems	66
Serial Console in Mu Not Displaying Anything	66
CircuitPython RGB Status Light	66
ValueError: Incompatible .mpy file.	67
CIRCUITPY Drive Issues	67
Easiest Way: Use storage.erase_filesystem()	68
Old Way: For the Circuit Playground Express, Feather M0 Express, and Metro M0 Express:	68
Old Way: For Non-Express Boards with a UF2 bootloader (Gemma M0, Trinket M0):	69
Old Way: For non-Express Boards without a UF2 bootloader (Feather M0 Basic Proto, Feather Adalogger,
Arduino Zero):	69
Running Out of File Space on Non-Express Boards	70
Delete something!	70
Use tabs	70
MacOS loves to add extra files.	70
Prevent & Remove MacOS Hidden Files	70
Copy Files on MacOS Without Creating Hidden Files	71
Other MacOS Space-Saving Tips	71
Device locked up or boot looping	72
CircuitPython Essentials	74
Blink	75
NeoPixel Location	75
Blinking a NeoPixel LED	75
RGB LED Colors	77
Digital Input	78
NeoPixel and Button	78
Controlling the NeoPixel with a Button	78
Built-In NeoPixel LED	81
NeoPixel Location	81
NeoPixel Color and Brightness	81
RGB LED Colors	83
NeoPixel Rainbow	83
CPU Temperature	86
Microcontroller Location	86
Reading the Microcontroller Temperature	86
Downloads	88
Files:	88
Schematic and Fab Print	88

https://learn.adafruit.com/adafruit-qt-py-2040

Page 4 of 90

Overview

What a cutie pie! Or is it... a QT Py? This diminutive dev board comes with one of our new favorite chip, the RP2040. It's been made famous in the new Raspberry Pi Pico (https://adafru.it/RLd) and our Feather RP2040 (https://adafru.it/4884) and ItsyBitsy RP2040 (https://adafru.it/RLe), but what if we wanted something really smol?

A new chip means a new QT Py, and the Raspberry Pi RP2040 is no exception. When we saw this chip we thought "this chip is going to be awesome when we give it the cuuutie QT Py Treatment", and so we did! This QT Py features the RP2040, and all niceties you know and love about the original QT

Py (https://adafru.it/RLf)

https://learn.adafruit.com/adafruit-qt-py-2040

Page 5 of 90

Plug-and-play STEMMA QT

The star of the QT Py is our favorite connector - the STEMMA QT (https://adafru.it/HMB), a chainable I2C port that can be used with any of our STEMMA QT sensors and accessories (https://adafru.it/NmD). Having this connector means you don't need to do any soldering to get started.

What can you pop into the QT port? How about OLEDs (https://adafru.it/NB-)! Inertial Measurment Units (https://adafru.it/NC0)! Sensors a-plenty (https://adafru.it/NC1). All plug-and-play thanks to the innovative chainable design: SparkFun Qwiic (https://adafru.it/Fpw)-compatible STEMMA

QT (https://adafru.it/Ft4) connectors for the I2C bus so you don't even need to solder. Just plug in a compatible cable and attach it to your MCU of choice, and you’re ready to load up some software and measure some light.

Use any SparkFun Qwiic (https://adafru.it/NC2) boards! Seeed Grove I2C boards (https://adafru.it/Ndk) will also work with this adapter cable.

https://learn.adafruit.com/adafruit-qt-py-2040

Page 6 of 90

Software Support

At the time of launch, there is no Arduino core support for the chip on this board. There is great C/C++ support (https://adafru.it/Qa3), an official MicroPython port (https://adafru.it/Qa4), and a CircuitPython port (https://adafru.it/Em8)! We of course recommend CircuitPython because we think it's the easiest way to get started (https://adafru.it/cpy-welcome) and it has support with most of our drivers, displays, sensors, and more, supported out of the box so you can follow along with our CircuitPython projects and tutorials.

QT Py RP2040 Specifications

Pinout and shape is Seeed Xiao (https://adafru.it/NC3) compatible, with castellated pads so you can solder it to a PCB with a cut out to allow the bottom components some breathing room. In addition to the QT

https://learn.adafruit.com/adafruit-qt-py-2040

Page 7 of 90

connector, we also added an RGB NeoPixel (with a controllable power pin to allow for ultra-low-power usage), and both boot-mode and reset buttons (great for restarting your program or entering the bootloader). This QT Py comes with loose 0.1" headers you can solder in for breadboard use

While the RP2040 has lots of onboard RAM (264KB), it does not have built-in FLASH memory. Instead, that is provided by the external QSPI flash chip. On this board there is 8MB, which is shared between the program it's running and any file storage used by MicroPython or CircuitPython. When using C/C++ you get the whole flash memory, if using Python you will have about 7 MB remaining for code, files, images, fonts, etc.

Same size, form-factor, and pin-out as our SAMD-based QT Py (https://adafru.it/Ofl)

USB Type C connector - If you have only Micro B cables, this adapter will come in handy (https://adafru.it/FQR)!

RP2040 32-bit Cortex M0+ dual-core running at ~125 MHz @ 3.3V logic and power

264 KB RAM

8 MB SPI FLASH chip for storing files and CircuitPython/MicroPython code storage. No EEPROM

Native USB supported by every OS - can be used as USB serial console, MIDI, Keyboard/Mouse HID, even a little disk drive for storing Python scripts.

Can be used with MicroPython or CircuitPython

Built-in RGB NeoPixel LED

13 GPIO pins (11 breakout pads and two QT pads):

Four 12 bit ADCs (one more than Pico)

Two I2C ports (one on the QT connector, one on the breakout pads)

SPI and UART peripherals, in standard QT Py locations,

PWM outputs on every IO pin - for servos, LEDs, etc

There are 6 GPIO in consecutive order for PIO compatibility

3.3V regulator with 600mA peak output (https://adafru.it/NC4)

12 MHz crystal

Both Reset button and Bootloader select buttons for quick restarts (no unplugging-replugging to relaunch code)

Really really small

https://learn.adafruit.com/adafruit-qt-py-2040

Page 8 of 90

About the RP2040

Inside the RP2040 is a 'permanent ROM' USB UF2 bootloader . What that means is when you want to program new firmware, you can hold down the BOOT button while plugging it into USB (or pulling down the RUN/Reset pin to ground) and it will appear as a USB disk drive you can drag the firmware onto. Folks who have been using Adafruit products will find this very familiar - we use the technique on all our nativeUSB boards. Just note you don't double-click reset, instead hold down BOOTSEL during boot to enter the bootloader!

The RP2040 is a powerful chip, which has the clock speed of our M4 (SAMD51), and two cores that are equivalent to our M0 (SAMD21). Since it is an M0 chip, it does not have a floating point unit or DSP hardware support - so if you're doing something with heavy floating point math, it will be done in software and thus not as fast as an M4. For many other computational tasks, you'll get close-to-M4 speeds!

For peripherals, there are two I2C controllers, two SPI controllers, and two UARTs that are multiplexed across the GPIO - check the pinout for what pins can be set to which. There are 16 PWM channels, each pin has a channel it can be set to (ditto on the pinout).

You'll note there's no I2S peripheral, or SDIO, or camera, what's up with that? Well, instead of having specific hardware support for serial-data-like peripherals like these, the RP2040 comes with the PIO state machine system which is a unique and powerful way to create custom hardware logic and data processing blocks that run on their own without taking up a CPU. For example, NeoPixels - often we bitbang the timing-specific protocol for these LEDs. For the RP2040, we instead use PIO object that reads in the data buffer and clocks out the right bitstream with perfect accuracy. Same with I2S audio in or out, LED matrix displays, 8-bit or SPI based TFTs, even VGA (https://adafru.it/Qa2)! In MicroPython and CircuitPython you can create PIO control commands to script the peripheral and load it in at runtime. There are 2 PIO peripherals with 4 state machines each.

https://learn.adafruit.com/adafruit-qt-py-2040

Page 9 of 90

https://learn.adafruit.com/adafruit-qt-py-2040

Page 10 of 90

Pinouts

The QT Py RP2040 packs all kinds of microcontroller goodness into a super tiny package. Time to take a tour of the board!

STEMMA QT

On the opposite end of the board from the USB connector is the STEMMA QT connector. This connector, labeled I2C1, allows you to plug in all sorts of breakout

boards (https://adafru.it/HMF) with no soldering needed! All you need is a STEMMA QT cable (https://adafru.it/RLA).

NOTE: To use this connector with CircuitPython, you need to use board.SCL1 and board.SDA1 in your code!

The I2C breakout pads are *separate* from the STEMMA QT I2C pads! We give you two I2C ports, so you can connect two identical sensors if needed, one on each I2C bus.

Power and USB

https://learn.adafruit.com/adafruit-qt-py-2040

Page 11 of 90

USB C connector - This is used for power and data. Connect to your computer via a USB C cable to update firmware and edit code.

GND - This is the common ground for all power and logic.

3V - this is the regulated output from the onboard regulator. You can draw 500mA

5V - This is 5v out from the USB port. You can also use this as a voltage input but you must have some sort of diode (schottky, signal, power, really anything) between your external power source and this pin with anode to battery, cathode to 5V pin. Note that you cannot power the USB port by supplying 5V to this pin: there is a protection diode that prevents the 5V from reaching the USB connector (unless you bridge the jumper on the back!). This is to protect host computer USB ports, etc. You can draw 1A peak through the diode, but we recommend keeping it lower than that, about 500mA

Input/Output Pins

https://learn.adafruit.com/adafruit-qt-py-2040

Page 12 of 90

I2C and SPI on RP2040

The RP2040 is capable of handling I2C, SPI and UART on many pins. However, there are really only two peripherals each of I2C, SPI and UART: I2C0 and I2C1, SPI0 and SPI1, and UART0 and UART1. So while many pins are capable of I2C, SPI and UART, you can only do two at a time, and only on separate peripherals, 0 and 1. I2C, SPI and UART peripherals are included and numbered below.

PWM on RP2040

The RP2040 supports PWM on all pins. However, it is not capable of PWM on all pins at the same time. There are 8 PWM "slices", each with two outputs, A and B. Each pin on the QT Py is assigned a PWM slice and output. For example, D6 is PWM2 A, which means it is the first output of the second slice. You can have multiple PWM objects on the QT Py RP2040. The important thing to know is that you cannot use the same slice and output more than once at the same time. So, if you have a PWM object on pin D6, you cannot also put a PWM object on D9, because they are both PWM2 A. The PWM slices and outputs are indicated below.

Analog Pins

The RP2040 has four ADCs. These pins are the only pins capable of handling analog, and they can also do digital.

A0/D0 - This pin is ADC3. It is also SPI1 CS, I2C0 SCL and PWM6 B.

A1/D1 - This pin is ADC2. It is also SPI1 MISO, I2C1 SDA and PWM6 A.

A2/D2 - This pin is ADC1. It is also SPI1 MOSI, I2C1 SCL and PWM5 B.

A3/D3 - This pin is ADC0. It is also SPI1 SCK, I2C1 SDA and PWM5 A.

Digital Pins

These are the digital I/O pins. They all have multiple capabilities.

SDA/D4 - I2C0 SDA, and digital I/O pin 4. It is also UART1 TX and PWM4 A. SCL/D5 - I2C0 SCL, and digital I/O pin 5. It is also UART1 RX and PWM4 B. TX/D6 - The main UART1 TX pin. It is also I2C0 SDA and PWM2 A.

https://learn.adafruit.com/adafruit-qt-py-2040

Page 13 of 90

RX/D7 - The main UART1 RX pin. It is also SPI0 CS, I2C0 SCL and PWM2 B.

SCK/D8 - The main SPI0 SCK and digital I/O pin 8. It is also I2C1 SDA and PWM3 A.

MI/D9 - The main SPI0 MISO and digital I/O pin 9. It is also UART1 TX, I2C0 SDA and PWM2 A.

MO/D10 - The main SPI0 MOSI and digital I/O pin 10. It is also I2C1 SCL and PWM1 B.

SDA1 - I2C1 SDA for the STEMMA QT connector. It is also SPI0 SCK and PWM3 A.

SCL1 - I2C1 SCL for the STEMMA QT connector. It is also SPI0 MOSI and PWM3 B.

CircuitPython I2C, SPI and UART

Note that in CircuitPython, there is a board object each for I2C, SPI and UART that use the pins labeled on the QT Py. You can use these objects to initialise these peripherals in your code.

board.I2C() uses SCL/SDA (not for the STEMMA QT connector!)

board.SPI() uses SCK/MO/MI

board.UART() uses RX/TX

GPIO Pins by Pin Functionality

Primary pins based on QT Py RP2040 silk are bold.

I2C Pins

I2C0 SCL: SCL, A0, RX

I2C0 SDA: SDA, TX, MISO

I2C1 SCL: SCL1, A2, MOSI

I2C1 SDA: SDA1, A1, A3, SCK

SPI Pins

SPI0 SCK: SCK, SDA1

SPI0 MOSI: MO, SCL1

SPI0 MISO: MI

SPI0 CS: RX

SPI1 SCK: A3

SPI1 MOSI: A2

SPI1 MISO: A1

SPI1 CS: A0

UART Pins

UART0 TX: (none)

UART0 RX: (none)

UART1 TX: TX, SDA, MISO

UART1 RX: RX, SCL

PWM Pins

PWM0 A: (none)

PWM0 B: (none)

PWM1 A: (none)

PWM1 B: MOSI

PWM2 A: TX, MISO

PWM2 B: RX

PWM3 A: SCK, SDA1 PWM3 B: SCL1

https://learn.adafruit.com/adafruit-qt-py-2040

Page 14 of 90

board.NEOPIXEL .

PWM4 A: SDA

PWM4 B: SCL

PWM5 A: A3

PWM5 B: A2

PWM6 A: A1

PWM6 B: A0

Buttons

The button on the opposite end of the board from the USB connector is the reset (RST) button. This button restarts the board and helps enter the bootloader. You can click it to reset the board without unplugging the USB cable or battery.

The button towards the middle of the board is the boot select (BOOT) button. This button is used to enter the bootloader. To enter the bootloader, press and hold BOOT and then power up the board (either by plugging it into USB or pressing RESET). The bootloader is used to install/update CircuitPython. This button is also usable as an input in code, on pin board.BUTTON .

Onboard NeoPixel

The onboard NeoPixel is a built-in addressable RGB LED. It can be accessed in CircuitPython with pin

RP2040 and QSPI Flash

The square under the "QT Py RP2040" label on the back is the RP2040 microcontroller, the "brains" of the QT Py RP2040 board.

The smaller square near USB side of the board is the QSPI Flash. It is connected to 6 pins that are not brought out on the GPIO pads. This way you don't have to worry about the SPI flash colliding with other devices on the main SPI connection.

https://learn.adafruit.com/adafruit-qt-py-2040

Page 15 of 90

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.

USB Host Jumper

There is a jumper on the back next to the QSPI flash chip. If you bridge this jumper, it will connect the USB 5V pin to the breakout 5V pin. This is necessary if you want to use the QT Py RP2040 in USB host mode.

https://learn.adafruit.com/adafruit-qt-py-2040

Page 16 of 90

CircuitPython

CircuitPython (https://adafru.it/tB7) is a derivative of MicroPython (https://adafru.it/BeZ) 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.

CircuitPython Quickstart

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

https://adafru.it/RLD

Click the link above to download the latest CircuitPython

UF2 file.

Save it wherever is convenient for you.

To enter the bootloader, hold down the BOOT/BOOTSEL button (highlighted in red above), and while continuing to hold it (don't let go!), press and release the reset button (highlighted in blue above).

Continue to hold the BOOT/BOOTSEL button until the RPI-RP2 drive appears!

If the drive does not appear, release all the buttons, and then repeat the process above.

https://learn.adafruit.com/adafruit-qt-py-2040

Page 17 of 90

You can also start with your board unplugged from USB, press and hold the BOOTSEL button (highlighted in red above), continue to hold it while plugging it into USB, and wait for the drive to appear before releasing the button.

A lot of people end up using charge-only USB cables and it is very frustrating! Make sure you have a USB cable you know is good for data sync.

You will see a new disk drive appear called RPI-RP2.

Drag the adafruit_circuitpython_etc.uf2 file to RPI-RP2.

The RPI-RP2 drive will disappear and a new disk drive called

CIRCUITPY will appear.

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

Flash Resetting UF2

If your board ever gets into a really weird state and doesn't even show up as a disk drive when installing CircuitPython, try loading this 'nuke' UF2 which will do a 'deep clean' on your Flash Memory. You will lose all the files on the board, but at least you'll be able to revive it! After loading this UF2, follow the steps above to re-install CircuitPython.

https://learn.adafruit.com/adafruit-qt-py-2040

Page 18 of 90

https://adafru.it/RLE

https://learn.adafruit.com/adafruit-qt-py-2040

Page 19 of 90

Installing Mu Editor

Mu is a simple code editor that works with the Adafruit CircuitPython boards. It's written in Python and works on Windows, MacOS, Linux and Raspberry Pi. The serial console is built right in so you get immediate feedback from your board's serial output!

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

Download and Install Mu

Download Mu from https://codewith.mu (https://adafru.it/Be6). Click the Download or Start Here links there for downloads and installation instructions. The website has a wealth of other information, including extensive tutorials and and how-to's.

Using Mu

The first time you start Mu, you will be prompted to select your 'mode' - you can always change your mind later. For now please select CircuitPython!

The current mode is displayed in the lower right corner of the window, next to the "gear" icon. If the mode says "Microbit" or something else, click the Mode button in the upper left, and then choose "CircuitPython" in the dialog box that appears.

https://learn.adafruit.com/adafruit-qt-py-2040

Page 20 of 90

Mu attempts to auto-detect your board, so please plug in your CircuitPython device and make sure it shows up as

a CIRCUITPY drive before starting Mu

You can now explore Mu! The three main sections of the window are labeled below; the button bar, the text editor, and the serial console / REPL.

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

https://learn.adafruit.com/adafruit-qt-py-2040

Page 21 of 90

Creating and Editing Code

One of the best things about CircuitPython is how simple it is to get code up and running. In this section, we're going to cover how to create and edit your first CircuitPython program.

To create and edit code, all you'll need is an editor. There are many options. We strongly recommend using Mu! It's designed for CircuitPython, and it's really simple and easy to use, with a built in serial console!

If you don't or can't use Mu, there are basic text editors built into every operating system such as Notepad on Windows, TextEdit on Mac, and gedit on Linux. However, many of these editors don't write back changes immediately to files that you edit. That can cause problems when using CircuitPython. See the Editing Code (https://adafru.it/id3) section below. If you want to skip that section for now, make sure you do "Eject" or "Safe Remove" on Windows or "sync" on Linux after writing a file if you aren't using Mu. (This is not a problem on MacOS.)

Creating Code

Open your editor, and create a new file. If you are using Mu, click the New button in the top left

Copy and paste the following code into your editor:

import board import digitalio import time

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

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

led.value = False time.sleep(0.5)

The QT Py does not have a D13 LED! There is an addressable RGB NeoPixel LED. The above example will NOT work on the QT Py!

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

https://learn.adafruit.com/adafruit-qt-py-2040

Page 22 of 90

The QT Py blink example uses the onboard NeoPixel, but the time code is the same. You can use the linked QT Py example to follow along with this guide page.

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

For Adafruit CLUE, you'll need to use board.D17 instead of board.D13 . The rest of the code remains the same. Make the following change to the led = line:

led = digitalio.DigitalInOut(board.D17)

If you are using Adafruit ItsyBitsy nRF52840, you will need to edit the code to use board.BLUE_LED as shown below!

For Adafruit ItsyBitsy nRF52840, you'll need to use board.BLUE_LED instead of board.D13 . The rest of the code remains the same. Make the following change to the led = line:

led = digitalio.DigitalInOut(board.BLUE_LED)

It will look like this - note that under the while True: line, the next four lines have spaces to indent them, but they're indented exactly the same amount. All other lines have no spaces before the text.

https://learn.adafruit.com/adafruit-qt-py-2040

Page 23 of 90

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

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

The little LED should now be blinking. Once per second. Congratulations, you've just run your first CircuitPython program!

Editing Code

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

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

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

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

Don't Click Reset or Unplug!

https://learn.adafruit.com/adafruit-qt-py-2040

Page 24 of 90

CIRCUITPY .

The CircuitPython code on your board detects when the files are changed or written and will automatically re-start your code. This makes coding very fast because you save, and it re-runs.

However, you must wait until the file is done being saved before unplugging or resetting your board! On Windows using some editors this can sometimes take up to 90 seconds, on Linux it can take 30 seconds to complete because the text editor does not save the file completely. Mac OS does not seem to have this delay, which is nice!

This is really important to be aware of. If you unplug or reset the board before your computer finishes writing the file to your board, you can corrupt the drive. If this happens, you may lose the code you've written, so it's important to backup your code to your computer regularly.

There are a few ways to avoid this:

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

Recommended editors:

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

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

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

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

gedit on Linux appears to safely write all changes

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

thonny (https://adafru.it/Qb6) fully writes files on save Recommended only with particular settings or with add-ons:

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

swapfiles (https://adafru.it/ELO) (.swp files: temporary records of your edits) to CIRCUITPY. Run vim with vim -n , set the no swapfile option, or set the directory option to write swapfiles elsewhere. Otherwise the swapfile writes trigger restarts of your program.

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

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

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

SlickEdit (https://adafru.it/DdP) works only if you add a macro to flush the disk (https://adafru.it/ven). We don't recommend these editors:

notepad (the default Windows editor) and Notepad++ can be slow to write, so we recommend the editors above! If you are using notepad, be sure to eject the drive (see below)

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

nano (on Linux) does not force out changes

geany (on Linux) does not force out changes

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

If you are dragging a file from your host computer onto the CIRCUITPY drive, you still need to do step 2. Eject or Sync (below) to make sure the file is completely written.

https://learn.adafruit.com/adafruit-qt-py-2040

Page 25 of 90

2. Eject or Sync the Drive After Writing

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

On Windows, you can Eject or Safe Remove the CIRCUITPY drive. It won't actually eject, but it will force the operating system to save your file to disk. On Linux, use the sync command in a terminal to force the write to disk.

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

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

Don't worry! Corrupting the drive isn't the end of the world (or your board!). If this happens, follow the steps found on the Troubleshooting (https://adafru.it/Den) page of every board guide to get your board up and running again.

Back to Editing Code...

Now! Let's try editing the program you added to your board. Open your code.py file into your editor. We'll make a simple change. Change the first 0.5 to 0.1 . The code should look like this:

import board import digitalio import time

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

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

led.value = False time.sleep(0.5)

Leave the rest of the code as-is. Save your file. See what happens to the LED on your board? Something changed! Do you know why? Let's find out!

Exploring Your First CircuitPython Program

First, we'll take a look at the code we're editing. Here is the original code again:

https://learn.adafruit.com/adafruit-qt-py-2040

Page 26 of 90

import board import digitalio import time

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

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

led.value = False time.sleep(0.5)

Imports & Libraries

Each CircuitPython program you run needs to have a lot of information to work. The reason CircuitPython is so simple to use is that most of that information is stored in other files and works in the background. The files built into CircuitPython are called modules, and the files you load separately are called libraries. Modules are built into CircuitPython. Libraries are stored on your CIRCUITPY drive in a folder called lib.

import board import digitalio import time

The import statements tells the board that you're going to use a particular library in your code. In this example, we imported three modules: board , digitalio , and time . All three of these modules are built into CircuitPython, so no separate library files are needed. That's one of the things that makes this an excellent first example. You don't need any thing extra to make it work! board gives you access to the hardware on your board, digitalio lets you access that hardware as inputs/outputs and time let's you pass time by 'sleeping'

Setting Up The LED

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

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

Your board knows the red LED as D13 . So, we initialise that pin, and we set it to output. We set led to equal the rest of that information so we don't have to type it all out again later in our code.

Loop-de-loops

The third section starts with a while statement. while True: essentially means, "forever do the following:". while True: creates a loop. Code will loop "while" the condition is "true" (vs. false), and as True is never False, the code will loop forever. All code that is indented under while True: is "inside" the loop.

Inside our loop, we have four items:

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

led.value = False time.sleep(0.5)

https://learn.adafruit.com/adafruit-qt-py-2040

Page 27 of 90

+ 63 hidden pages