empowering creative people

Introducing CircuitPython: Adafruit Circuit Playground Express

CircuitPython is a variant of MicroPython that is designed with ease of use and simplicity in mind, and it works great with the Adafruit Circuit Playground Express. CircuitPython is based on the very popular Python programming language, they have just added in hardware support to make it work with a microcontroller! Adafruit created CircuitPython specifically to support microcontroller boards and to create an easy to learn language to support compatible boards. Although some of the functions of Python are not available in CircuitPython, it is still a very capable language with many libraries out there to help you out.

CircuitPython makes programming easy by removing the need for a dedicated editor, and the need to compile the code. All you need to start programming is a text editor! There are some great free editors for CircuitPython that make coding even easier. We recommend Mu for editing in CircuitPython. Mu is free and easy to use, and it has a built-in serial monitor so interacting with your code in real time is very easy. As if that wasn’t enough Mu is made to be compatible with the Circuit Playground express and it works great. It also has an error checking option that gives easy to understand explanations of errors in your code! We will be using Mu in our CircuitPython Tutorials.

You can download the latest version of Mu here!

Before we get started editing code, we need to install or update CircuitPython on our Circuit Playground Express! 

Installing CircuitPython on the Circuit Playground Express

The firmware for CircuitPython is a .uf2 file. This is a file format specifically made for writing to flash storage, which is what the Circuit Playground Express uses. To use CircuitPython we must first install or update the .uf2 file or firmware.

You can find the latest Circuit Playground Express CircuitPython UF2 here!

  1. Download the latest UF2 file for the Circuit Playground express
  2. Connect the Circuit Playground Express via USB and enter bootloader mode
  3. Drag the UF2 file into the CPLAYBOOT drive. 

CPLAYBOOT should now change to CIRCUITPY. 

Installing the Circuit Playground Express Library

The way that CircuitPython keeps programming so easy is that large parts of the code are included in files called libraries. To include them in your code you make a simple statement like "import board” and then that code is included in the background. The Circuit Playground Express usually comes with some libraries already installed, but if you and to use the onboard sensors and NeoPixels you will need the additional libraries.

To install libraries follow these directions:
Start out by getting the latest stable release of the library bundle. Unzip the file and open the folder named lib. Connect your Circuit Playground Express to the computer using a micro usb cable. You should have a library folder on the Circuit Playground Express already titled lib. if needed create a lib folder on your CIRCUITPY drive on the Circuit Playground Express. Copy the contents of the lib folder from the library bundle you just unzipped to your lib folder on the Circuit Playground Express, CIRCUITPY/lib. Some boards don’t have enough memory to store all the libraries, but you’ve got an impressive 2MB on the Circuit Playground Express, so you can fit it all. If you need to save memory you can pick and choose the libraries that you need only.

Button Press

Circuit Playground Express comes with 10 onboard RGB (red, green, blue) Neopixel LEDs capable of displaying any color individually or together. They are numbered 0 – 9 counter-clockwise on the board.
Contained within each Neopixel LED is three LEDs of different colors, one red, one blue and one green. The full spectrum of color is created by varying the levels of each LED within the Neopixel. To make a red light you only turn on the red portion of the Neopixel and leave the blue and green off. To create purple, you turn on red and blue, and to create white you turn on all three. If you’re not sure what combination of colors will give you the desired result you can.

Adafruit Circuit Playground Express Neopixels Labeled

For this example, we are going to start by making the Neopixel 0-4 turn red while the B button is pressed, and Neopixel 5-9 turn blue when button A is pressed.


The Code

From within Mu, we want to create a new file and name it code.py. This is the file that the Circuit Playground Express will run whenever it starts up. Save the file to your CIRCUITPY drive. Whenever you make a change and save, the Circuit Playground Express will reboot and start the program immediately. Remember that code.py is where the code lives. Whenever you make changes to your code you will overwrite this file.

The following code activates half of the lights with each button press:

 
from adafruit_circuitplayground.express import cpx # imports the CPX library from its subfolder

cpx.pixels.brightness = 0.1 # set pixel brightness
cpx.pixels.fill((0, 0, 0)) # turns all pixels off
cpx.pixels.show() # sends data to pixels


while True: # loop
if cpx.button_b: # if button is pushed then everything in hanging indent is executed
print("Button B Pressed!") # prints text in the serial monitor
cpx.pixels[0] = (255, 0, 0) # sets a single neopixel to given color pixel[number] = (R,G,B)
cpx.pixels[1] = (255, 0, 0)
cpx.pixels[2] = (255, 0, 0)
cpx.pixels[3] = (255, 0, 0)
cpx.pixels[4] = (255, 0, 0)
if cpx.button_a: # button is pushed
print("Button A Pressed!")
cpx.pixels[5] = (0, 0, 255)
cpx.pixels[6] = (0, 0, 255)
cpx.pixels[7] = (0, 0, 255)
cpx.pixels[8] = (0, 0, 255)
cpx.pixels[9] = (0, 0, 255)
if not(cpx.button_a or cpx.button_b):
cpx.pixels.fill((0, 0, 0)) # will turn the lights off when buttons arent pressed

cpx.pixels.show() # sends accumulated data to pixels

Let’s break down the code and explain the parts. One of the ways that CircuitPython simplifies code is with indentation. In most programming language the indentation is used to organize code and keep it easy to understand, but {} are used to show the constraints of operators. For example, in CircuitPython there are no brackets used to show what is included in an "if” statement, instead everything that is included in an if statement will have a hanging indent from the "if” statement. This helps keep the code clean and removes unnecessary characters.

The first step to writing a program in CircuitPython is to import Libraries. We need just one library to run this program, the CPX (Circuit Playground Express)  library. The CPX library allows us to make use of the on-board buttons easily. The CPX library is in a subfolder in lib, so to add it we must include the folder as well. 

from adafruit_circuitplayground.express import cpx  # imports the CPX library from its subfolder

The next section of our code sets the conditions for the NeoPixels. 
The next two lines set all the NeoPixels to off, just in case they were somehow illuminated at the start of the program. This is mostly precautionary as its very unlikely that this would be the case.

cpx.pixels.brightness = 0.1                         # set pixel brightness
cpx.pixels.fill((0, 0, 0)) # turns all pixels off
cpx.pixels.show() # sends data to pixels

The main body of our code contains our loop, in this case, a “while True” loop. Notice how everything contained within the while true loop is indented once. For the logic of this program, we are using if statements. The first if statement looks for a press of button B. To use an onboard button we use the cpx.button_a command. CircuitPython allows you to keep your code simple here by not requiring an if true/false statement. Within our If statement we print “Button B Pressed!” in the serial monitor or the REPL if you are using Mu, and set the color of NeoPixel 0-4. We then do the same for button A. We then have an If statement to turn off the NeoPixels if neither button A or B is being pressed. Finally we write the commands to the NeoPixels with cpx.pixel.show(). 

while True:                            # loop
if cpx.button_b: # if button is pushed then everything in hanging indent is executed
print("Button B Pressed!") # prints text in the serial monitor
cpx.pixels[0] = (255, 0, 0) # sets a single neopixel to given color pixel[number] = (R,G,B)
cpx.pixels[1] = (255, 0, 0)
cpx.pixels[2] = (255, 0, 0)
cpx.pixels[3] = (255, 0, 0)
cpx.pixels[4] = (255, 0, 0)
if cpx.button_a: # button is pushed
print("Button A Pressed!")
cpx.pixels[5] = (0, 0, 255)
cpx.pixels[6] = (0, 0, 255)
cpx.pixels[7] = (0, 0, 255)
cpx.pixels[8] = (0, 0, 255)
cpx.pixels[9] = (0, 0, 255)
if not(cpx.button_a or cpx.button_b):
cpx.pixels.fill((0, 0, 0)) # will turn the lights off when buttons arent pressed

cpx.pixels.show() # sends accumulated data to pixels

Uploading your program to your board is as easy as saving the program as code.py on the Circuit Playground Express! The Circuit Playground Express will look for a program file and run the first one it finds, starting with code.py, then main.py. Now you are free to take your button press lights anywhere you want! Check out our tutorials section if you want to learn more about the Adafruit Circuit Playground Express. We also have tutorials about programming the Circuit Playground Express using MakeCode. Let's not forget about Arduino! If you want to learn about programming the Circuit Playground Express using Arduino check out our dedicated Arduino tutorials!

CircuitPython is a variant of MicroPython that is designed with ease of use and simplicity in mind, and it works great with t...

Have a question? Ask the Author of this guide today!