Adafruit QT Py Created by Kattni Rembor Last updated on 2021-09-27 12:13:36 PM EDT Guide Contents Guide Contents 2 Overview 8 Pinouts 12 Power Pins 12 Input/Output Pins 12 General Purpose / Analog Inputs 12 I2C Pins 13 Hardware Serial Pins 13 SPI Pins 13 Onboard Neopixel pins 13 Capacitive touch pins 13 Analog output pin 13 Analog input pins 14 PWM output pins 14 I2S pins 14 SWD Debug Pins 14 Reverse Side SPI FLASH 14 About STEMMA QT 16 What is CircuitPython? 17 CircuitPython is based on Python 17 Why would I use CircuitPython? 17 CircuitPython 19 Set up CircuitPython Quick Start! 19 Installing Mu Editor 22 Download and Install Mu 22 Using Mu 22 Creating and Editing Code 24 Creating Code 24 Editing Code 26 Your code changes are run as soon as the file is done saving. 27 1. Use an editor that writes out the file completely when you save it. 27 2. Eject or Sync the Drive After Writing 28 Oh No I Did Something Wrong and Now The CIRCUITPY Drive Doesn't Show Up!!! 28 Back to Editing Code... 29 Exploring Your First CircuitPython Program 30 Imports & Libraries 30 Setting Up The LED 30 Loop-de-loops 31 What Happens When My Code Finishes Running? 31 What if I don't have the loop? 32 More Changes 33 Naming Your Program File 33 Connecting to the Serial Console 34 Are you using Mu? 34 Setting Permissions on Linux 35 Using Something Else? 36 Interacting with the Serial Console 37 The REPL 41 © Adafruit Industries https://learn.adafruit.com/adafruit-qt-py Page 2 of 214 Returning to the serial console 44 CircuitPython Libraries 45 Installing the CircuitPython Library Bundle 46 Example Files 47 Copying Libraries to Your Board 48 Example: ImportError Due to Missing Library 48 Library Install on Non-Express Boards 49 Updating CircuitPython Libraries/Examples 50 Frequently Asked Questions 51 I have to continue using an older version of CircuitPython; where can I find compatible libraries? 51 Is ESP8266 or ESP32 supported in CircuitPython? Why not? 51 How do I connect to the Internet with CircuitPython? 52 Is there asyncio support in CircuitPython? 53 My RGB NeoPixel/DotStar LED is blinking funny colors - what does it mean? 54 What is a MemoryError? 55 What do I do when I encounter a MemoryError? 55 Can the order of my import statements affect memory? 56 How can I create my own .mpy files? 56 How do I check how much memory I have free? 56 Does CircuitPython support interrupts? 56 Does Feather M0 support WINC1500? 57 Can AVRs such as ATmega328 or ATmega2560 run CircuitPython? 57 Commonly Used Acronyms 57 Troubleshooting 58 Always Run the Latest Version of CircuitPython and Libraries 58 I have to continue using CircuitPython 5.x, 4.x, 3.x or 2.x, where can I find compatible libraries? 58 CPLAYBOOT, TRINKETBOOT, FEATHERBOOT, or GEMMABOOT Drive Not Present 58 You may have a different board. 59 MakeCode 59 MacOS 59 Windows 10 59 Windows 7 or 8.1 59 Windows Explorer Locks Up When Accessing boardnameBOOT Drive 60 Copying UF2 to boardnameBOOT Drive Hangs at 0% Copied 61 CIRCUITPY Drive Does Not Appear 61 Device Errors or Problems on Windows 61 Serial Console in Mu Not Displaying Anything 62 CircuitPython RGB Status Light 62 ValueError: Incompatible .mpy file. 63 CIRCUITPY Drive Issues 64 Easiest Way: Use storage.erase_filesystem() 64 Old Way: For the Circuit Playground Express, Feather M0 Express, and Metro M0 Express: 64 Old Way: For Non-Express Boards with a UF2 bootloader (Gemma M0, Trinket M0): 66 Old Way: For non-Express Boards without a UF2 bootloader (Feather M0 Basic Proto, Feather Adalogger, Arduino Zero): 66 Running Out of File Space on Non-Express Boards 67 Delete something! 67 Use tabs 67 MacOS loves to add extra files. 67 Prevent & Remove MacOS Hidden Files 68 Copy Files on MacOS Without Creating Hidden Files 68 © Adafruit Industries https://learn.adafruit.com/adafruit-qt-py Page 3 of 214 Other MacOS Space-Saving Tips 69 Device locked up or boot looping 70 Uninstalling CircuitPython 72 Backup Your Code 72 Moving Circuit Playground Express to MakeCode 72 Moving to Arduino 73 Welcome to the Community! 76 Adafruit Discord 76 Adafruit Forums 77 Adafruit Github 78 ReadTheDocs 79 CircuitPython Essentials 81 CircuitPython Pins and Modules 82 CircuitPython Pins 82 import board 82 I2C, SPI, and UART 83 What Are All the Available Names? 84 Microcontroller Pin Names 85 CircuitPython Built-In Modules 86 CircuitPython Built-Ins 87 Thing That Are Built In and Work 87 Flow Control 87 Math 87 Tuples, Lists, Arrays, and Dictionaries 87 Classes, Objects and Functions 87 Lambdas 87 Random Numbers 88 CircuitPython Digital In & Out 89 Find the pins! 90 Read the Docs 92 CircuitPython Analog In 93 Creating the analog input 93 get_voltage Helper 93 Main Loop 93 Changing It Up 94 Wire it up 94 Reading Analog Pin Values 97 CircuitPython Analog Out 98 Creating an analog output 98 Setting the analog output 98 Main Loop 98 Find the pin 99 CircuitPython Audio Out 103 Play a Tone 103 Play a Wave File 105 Wire It Up 107 CircuitPython PWM 112 PWM with Fixed Frequency 112 Create a PWM Output 113 Main Loop 113 PWM Output with Variable Frequency 114 Wire it up 115 © Adafruit Industries https://learn.adafruit.com/adafruit-qt-py Page 4 of 214 Where's My PWM? 119 CircuitPython Servo 121 Servo Wiring 121 Standard Servo Code 124 Continuous Servo Code 124 CircuitPython Cap Touch 126 Create the Touch Input 126 Main Loop 126 Find the Pin(s) 127 CircuitPython Internal RGB LED 131 Create the LED 132 Brightness 132 Main Loop 132 Making Rainbows (Because Who Doesn't Love 'Em!) 133 Circuit Playground Express Rainbow 134 CircuitPython NeoPixel 136 Wiring It Up 136 The Code 137 Create the LED 138 NeoPixel Helpers 139 Main Loop 139 NeoPixel RGBW 139 Read the Docs 141 CircuitPython DotStar 142 Wire It Up 142 The Code 143 Create the LED 145 DotStar Helpers 146 Main Loop 146 Is it SPI? 147 Read the Docs 147 CircuitPython UART Serial 149 The Code 150 Wire It Up 151 Where's my UART? 154 Trinket M0: Create UART before I2C 155 CircuitPython I2C 157 Wire It Up 157 Find Your Sensor 160 I2C Sensor Data 161 Where's my I2C? 162 CircuitPython HID Keyboard and Mouse 164 CircuitPython Keyboard Emulator 164 Create the Objects and Variables 166 The Main Loop 166 CircuitPython Mouse Emulator 167 Create the Objects and Variables 169 CircuitPython HID Mouse Helpers 169 Main Loop 170 CircuitPython Storage 171 Logging the Temperature 173 CircuitPython CPU Temp 176 CircuitPython Expectations 177 © Adafruit Industries https://learn.adafruit.com/adafruit-qt-py Page 5 of 214 Always Run the Latest Version of CircuitPython and Libraries 177 I have to continue using CircuitPython 3.x or 2.x, where can I find compatible libraries? 177 Switching Between CircuitPython and Arduino 177 The Difference Between Express And Non-Express Boards 178 Non-Express Boards: Gemma, Trinket, and QT Py 178 Small Disk Space 178 No Audio or NVM 178 Differences Between CircuitPython and MicroPython 178 Differences Between CircuitPython and Python 179 Python Libraries 179 Integers in CircuitPython 179 Floating Point Numbers and Digits of Precision for Floats in CircuitPython 179 Differences between MicroPython and Python 179 Arduino IDE Setup 180 https://adafruit.github.io/arduino-board-index/package_adafruit_index.json 181 Using with Arduino IDE 183 Install SAMD Support 183 Install Adafruit SAMD 184 Install Drivers (Windows 7 & 8 Only) 185 Blink 187 Successful Upload 188 Compilation Issues 189 Manually bootloading 189 Ubuntu & Linux Issue Fix 190 NeoPixel Blink 191 Adapting Sketches to M0 & M4 192 Analog References 192 Pin Outputs & Pullups 192 Serial vs SerialUSB 192 AnalogWrite / PWM on Feather/Metro M0 193 analogWrite() PWM range 194 analogWrite() DAC on A0 194 Missing header files 194 Bootloader Launching 195 Aligned Memory Access 195 Floating Point Conversion 195 How Much RAM Available? 196 Storing data in FLASH 196 Pretty-Printing out registers 196 M4 Performance Options 197 CPU Speed (overclocking) 197 Optimize 198 Cache 198 Max SPI and Max QSPI 198 Enabling the Buck Converter on some M4 Boards 199 UF2 Bootloader Details 200 Entering Bootloader Mode 201 © Adafruit Industries https://learn.adafruit.com/adafruit-qt-py Page 6 of 214 Using the Mass Storage Bootloader 203 Using the BOSSA Bootloader 204 Windows 7 Drivers 204 Verifying Serial Port in Device Manager 205 Running bossac on the command line 207 Using bossac Versions 1.7.0, 1.8 207 Using bossac Versions 1.9 or Later 207 Updating the bootloader 208 Getting Rid of Windows Pop-ups 209 Making your own UF2 210 Installing the bootloader on a fresh/bricked board 211 Downloads 212 Files 212 Schematic & Fabrication Print 212 © Adafruit Industries https://learn.adafruit.com/adafruit-qt-py Page 7 of 214 Overview What a cutie pie! Or is it... a QT Py? This diminutive dev board comes with our favorite li'l chip, the SAMD21 (as made famous in our GEMMA M0 and Trinket M0 boards). This time it comes with 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). © Adafruit Industries https://learn.adafruit.com/adafruit-qt-py Page 8 of 214 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.