CircuitPython Essentials Created by Kattni Rembor Last updated on 2021-09-27 12:10:49 PM EDT Guide Contents Guide Contents 2 CircuitPython Essentials 5 CircuitPython Pins and Modules 6 CircuitPython Pins 6 import board 6 I2C, SPI, and UART 7 What Are All the Available Names? 8 Microcontroller Pin Names 9 CircuitPython Built-In Modules 10 CircuitPython Built-Ins 11 Thing That Are Built In and Work 11 Flow Control 11 Math 11 Tuples, Lists, Arrays, and Dictionaries 11 Classes, Objects and Functions 11 Lambdas 11 Random Numbers 12 CircuitPython Digital In & Out 13 Find the pins! 14 Read the Docs 16 CircuitPython Analog In 17 Creating the analog input 17 get_voltage Helper 17 Main Loop 17 Changing It Up 18 Wire it up 18 Reading Analog Pin Values 21 CircuitPython Analog Out 22 Creating an analog output 22 Setting the analog output 22 Main Loop 22 Find the pin 23 CircuitPython Audio Out 27 Play a Tone 27 Play a Wave File 29 Wire It Up 31 CircuitPython MP3 Audio 36 CircuitPython PWM 38 PWM with Fixed Frequency 38 Create a PWM Output 39 Main Loop 39 PWM Output with Variable Frequency 40 Wire it up 41 Where's My PWM? 45 CircuitPython Servo 47 Servo Wiring 47 Standard Servo Code 50 Continuous Servo Code 50 CircuitPython Cap Touch 52 Create the Touch Input 52 © Adafruit Industries https://learn.adafruit.com/circuitpython-essentials Page 2 of 117 Main Loop 52 Find the Pin(s) 53 CircuitPython Internal RGB LED 57 Create the LED 58 Brightness 58 Main Loop 58 Making Rainbows (Because Who Doesn't Love 'Em!) 59 Circuit Playground Express Rainbow 60 CircuitPython NeoPixel 62 Wiring It Up 62 The Code 63 Create the LED 64 NeoPixel Helpers 65 Main Loop 65 NeoPixel RGBW 65 Read the Docs 67 CircuitPython DotStar 68 Wire It Up 68 The Code 69 Create the LED 71 DotStar Helpers 72 Main Loop 72 Is it SPI? 73 Read the Docs 73 CircuitPython UART Serial 75 The Code 76 Wire It Up 77 Where's my UART? 80 Trinket M0: Create UART before I2C 81 CircuitPython I2C 83 Wire It Up 83 Find Your Sensor 86 I2C Sensor Data 87 Where's my I2C? 88 CircuitPython HID Keyboard and Mouse 90 CircuitPython Keyboard Emulator 90 Create the Objects and Variables 92 The Main Loop 92 CircuitPython Mouse Emulator 93 Create the Objects and Variables 95 CircuitPython HID Mouse Helpers 95 Main Loop 96 CircuitPython Storage 97 Logging the Temperature 99 CircuitPython CPU Temp 102 CircuitPython Expectations 103 Always Run the Latest Version of CircuitPython and Libraries 103 I have to continue using CircuitPython 3.x or 2.x, where can I find compatible libraries? 103 Switching Between CircuitPython and Arduino 103 The Difference Between Express And Non-Express Boards 104 Non-Express Boards: Gemma, Trinket, and QT Py 104 Small Disk Space 104 © Adafruit Industries https://learn.adafruit.com/circuitpython-essentials Page 3 of 117 No Audio or NVM 104 Differences Between CircuitPython and MicroPython 104 Differences Between CircuitPython and Python 105 Python Libraries 105 Integers in CircuitPython 105 Floating Point Numbers and Digits of Precision for Floats in CircuitPython 105 Differences between MicroPython and Python 105 CircuitPython Resetting 106 Soft Reset 106 Hard Reset 106 Reset Into Specific Mode 107 More Info 107 CircuitPython Libraries and Drivers 108 CircuitPython Libraries 109 Adafruit CircuitPython Libraries 109 Drivers: 109 Helpers: 114 © Adafruit Industries https://learn.adafruit.com/circuitpython-essentials Page 4 of 117 CircuitPython Essentials You've gone through the Welcome to CircuitPython guide (https://adafru.it/cpy-welcome). You've already gotten everything setup, and you've gotten CircuitPython running. Great! Now what? CircuitPython Essentials! There are a number of core modules built into CircuitPython and commonly used libraries available. This guide will introduce you to these and show you an example of how to use each one. Each section will present you with a piece of code designed to work with different boards, and explain how to use the code with each board. These examples work with any board designed for CircuitPython, including Circuit Playground Express, Trinket M0, Gemma M0, QT Py, ItsyBitsy M0 Express, ItsyBitsy M4 Express, Feather M0 Express, Feather M4 Express, Metro M4 Express, Metro M0 Express, Trellis M4 Express, and Grand Central M4 Express. Some examples require external components, such as switches or sensors. You'll find wiring diagrams where applicable to show you how to wire up the necessary components to work with each example. Let's get started learning the CircuitPython Essentials! © Adafruit Industries https://learn.adafruit.com/circuitpython-essentials Page 5 of 117 CircuitPython Pins and Modules CircuitPython is designed to run on microcontrollers and allows you to interface with all kinds of sensors, inputs and other hardware peripherals. There are tons of guides showing how to wire up a circuit, and use CircuitPython to, for example, read data from a sensor, or detect a button press. Most CircuitPython code includes hardware setup which requires various modules, such as board or digitalio . You import these modules and then use them in your code. How does CircuitPython know to look for hardware in the specific place you connected it, and where do these modules come from? This page explains both. You'll learn how CircuitPython finds the pins on your microcontroller board, including how to find the available pins for your board and what each pin is named. You'll also learn about the modules built into CircuitPython, including how to find all the modules available for your board. CircuitPython Pins When using hardware peripherals with a CircuitPython compatible microcontroller, you'll almost certainly be utilising pins. This section will cover how to access your board's pins using CircuitPython, how to discover what pins and board-specific objects are available in CircuitPython for your board, how to use the board-specific objects, and how to determine all available pin names for a given pin on your board. import board When you're using any kind of hardware peripherals wired up to your microcontroller board, the import list in your code will include import board . The board module is built into CircuitPython, and is used to provide access to a series of board-specific objects, including pins. Take a look at your microcontroller board. You'll notice that next to the pins are pin labels. You can always access a pin by its pin label. However, there are almost always multiple names for a given pin. To see all the available board-specific objects and pins for your board, enter the REPL ( >>> ) and run the following commands: import board dir(board) Here is the output for the QT Py. The following pins have labels on the physical QT Py board: A0, A1, A2, A3, SDA, SCL, TX, RX, SCK, MISO, and MOSI. You see that there are many more entries available in board than the labels on the QT Py. © Adafruit Industries https://learn.adafruit.com/circuitpython-essentials Page 6 of 117 You can use the pin names on the physical board, regardless of whether they seem to be specific to a certain protocol. For example, you do not have to use the SDA pin for I2C - you can use it for a button or LED. On the flip side, there may be multiple names for one pin. For example, on the QT Py, pin A0 is labeled on the physical board silkscreen, but it is available in CircuitPython as both A0 and D0 . For more information on finding all the names for a given pin, see the What Are All the Available Pin Names? (https://adafru.it/QkA) section below. The results of dir(board) for CircuitPython compatible boards will look similar to the results for the QT Py in terms of the pin names, e.g. A0, D0, etc. However, some boards, for example, the Metro ESP32-S2, have different styled pin names. Here is the output for the Metro ESP32-S2. Note that most of the pins are named in an IO# style, such as IO1 and IO2. Those pins on the physical board are labeled only with a number, so an easy way to know how to access them in CircuitPython, is to run those commands in the REPL and find the pin naming scheme. If your code is failing to run because it can't find a pin name you provided, verify that you have the proper pin name by running these commands in the REPL. I2C, SPI, and UART You'll also see there are often (but not always!) three special board-specific objects included: I2C , SPI , and UART - each one is for the default pin-set used for each of the three common protocol busses they are named for. These are called singletons. What's a singleton? When you create an object in CircuitPython, you are instantiating ('creating') it. Instantiating an object means you are creating an instance of the object with the unique values that are provided, or "passed", to it. For example, When you instantiate an I2C object using the busio module, it expects two pins: clock and data, typically SCL and SDA. It often looks like this: i2c = busio.I2C(board.SCL, board.SDA) © Adafruit Industries https://learn.adafruit.com/circuitpython-essentials Page 7 of 117 Then, you pass the I2C object to a driver for the hardware you're using. For example, if you were using the TSL2591 light sensor and its CircuitPython library, the next line of code would be: tsl2591 = adafruit_tsl2591.TSL2591(i2c) However, CircuitPython makes this simpler by including the I2C singleton in the board module.