Before We Get Started

If you're new to programming and CircuitPython, check out the Welcome to CircuitPython guide.

We recommend using Mu as your code editor, as it has the serial console built right in, and you can get immediate feedback from your code right inside the editor. For help getting Mu setup, read through Installing Mu Editor. A few of the features of this library work really well with the plotter function available in the Mu editor. Be sure to install the latest version to make sure you have access to this feature of Mu.

Connecting to the serial console in Mu is as simple as clicking the serial button, shown above in magenta. To activate the plotter feature, click the Plotter button, shown above in green.

If you already have a favorite editor, feel free to use it for this guide. Many of the examples will utilise the serial console, so if you opt not to use Mu, and you've never connected to the serial console before, read through the Advanced Serial Console on Mac and Linux, or the Advanced Serial Console on Windows for help getting connected.

Installing and Updating CircuitPython

This process is covered in the Installing CircuitPython section of the Welcome to CircuitPython guide. Even if your board arrived with CircuitPython installed, it may not be the latest version. You always want to have the most up-to-date version of CircuitPython on your board - this ensures the latest features and best functionality. Please take the time to go through the Welcome to CircuitPython: Installing CircuitPython page (if you haven't already) and make sure you've got CircuitPython installed and up to date.

Updating CircuitPython is especially important on the Circuit Playground Express because the Circuit Playground Library is built into CircuitPython for the Express, and this guide expects the most up-to-date version of the library.

Installing the Circuit Playground Library on Circuit Playground Bluefruit

Before you can use the Circuit Playground library with the Circuit Playground Bluefruit, you must install the library and the modules it depends on. Follow the steps found on the Installing CircuitPython Libraries on Circuit Playground Bluefruit section in the Circuit Playground Bluefruit guide to get all the necessary libraries installed.

The Circuit Playground library requires the following additional libraries

• adafruit_bus_device
• adafruit_lis3dh
• adafruit_thermister
• neopixel

If you try to run the code found within this guide without following these steps, the code will fail with the following error or one similar:

If you receive an ImportError: no module named 'module_name` error, verify that you have installed all the libraries by going through the steps in the Installing CircuitPython Libraries on Circuit Playground Bluefruit section again until your lib folder looks the same as the image found on that page.

Creating and Editing Code

This is covered in more detail in the Welcome to CircuitPython guide. However, since workflow is a key part of going through this guide, we're including a short explanation here.

Your Circuit Playground shows up on your computer as a USB drive called CIRCUITPY. You may already have some files on your CIRCUITPY drive. CircuitPython looks for specific files to run the code they contain, including code.py. We'll be putting each piece of code from this guide into code.py on your CIRCUITPY drive. This is easy to remember: code.py is where your code lives. As you progress through this guide, you have a couple of options to get the code from the guide onto your board.

1. You can download the file, rename it to code.py and copy the file to your CIRCUITPY drive, replacing the current code.py if one already exists.
2. You can copy and paste the contents of the code from the guide into your current code.py file on your CIRCUITPY drive using your editor. Be sure to replace all the code currently in your code.py. Do not add it to the end.

Both of these options work. It's entirely up to you which one to use. If you're unsure which to pick, give them both a try and see which workflow is best for you!

Using the Circuit Playground Library

Regardless of which type of board you're using, to use the Circuit Playground library, simply include the following line at the beginning of code.py:

from adafruit_circuitplayground import cp

That's it! After that, you can begin telling the board what to do.

Now, we'll take a look at all of the different things you can do with this library. Let's get started!