CircuitPython Introduction

CircuitPython is a dialect of Python available for a large number of microcontrollers. We will be using it to write programs for embedded computing within our projects.

Overview

Python is the most common programming language used in our introductory courses. For this reason, CircuitPython offers a familiar path to embedded programming, since the language syntax works the same as regular Python. The chief difference is the addition of library modules which add support for hardware input and output (I/O).

CircuitPython is a self-hosting system: programs are stored directly on the device as source files and internally compiled as needed. The only software tools required on your laptop are a Python-friendly program code editor and a serial port terminal emulator to interact with the console. You may use any editor and terminal programs you prefer, but the simplest beginner-friendly system is a browser-based system at https://code.circuitpython.org/

When a CircuitPython board is attached to a host computer using USB, it presents itself a disk drive named CIRCUITPY, i.e., it acts like a USB stick. On that drive is a file named code.py which is run whenever the board powers up. The CIRCUITPY drive may also store additional source, library, and data files used by code.py at runtime.

The interactive debugging workflow is just two steps: edit code.py, then save it. CircuitPython will detect the file update and automatically compile and run your modified code.

The board also presents itself as a USB serial port for text-based console input and output. When connected to a terminal emulator, this can be used to display debugging output and accept interactive input. The console also offers a command line interpreter for direct evaluation of Python expressions.

Adafruit Tutorials

The most beginner-friendly documentation is provided by Adafruit as narrative tutorials. The following are particularly relevant to this course.

1. Welcome to CircuitPython. A general guide to using CircuitPython, applicable to multiple devices.

2. Installing CircuitPython. A general guide to installing the CircuitPython system on a microcontroller.

CircuitPython Code Editors

There are many options for editing CircuitPython code. Here are a few suggestions.

• The simplest tool is the browser-based CircuitPython Code Editor which works in Chromium-based browsers. It provides both a Python editor and a terminal emulator.

• Adafruit previously recommended the Mu Python Editor for beginners starting with CircuitPython. However, as of 2025, the Mu system is no longer in development, so while it is still usable, you may wish to choose another.

• Many students successfully use Microsoft Visual Studio Code, often known simply as VS Code, since it is often now the editor used in introductory Python courses. Please note that Visual Studio Code is different from Visual Studio. VS Code is an editor but can provide a terminal emulator with plug-ins.

• The editor and terminal program can be separate. For example, for the old-timers, Emacs to edit Python and minicom to emulate a terminal.

Screen shot of the browser-based CircuitPython Code Editor.

Core System and Libraries

The CircuitPython firmware includes a number of modules for low-level interfacing. A list of included modules can be discovered by entering the following at the CircuitPython command line:

help('modules')

The specific modules available depend on the exact board version; some boards with a lot of memory include many additional modules.

If you need additional hardware support, many more modules are available to be installed as files on the CIRCUITPY drive presented by the board. Many of these are packaged into collections available at CircuitPython Libraries.

Each library bundle includes precompiled modules as .mpy files and sample code. The bundle version must match the installed CircuitPython version. The bundle is large and only a fraction can or should be installed on your microcontroller. Please see the individual board notes for specific suggestions.

CircuitPython Command Line

The CircuitPython console command line is known as the REPL, which stands for “Read-Eval-Print Loop”. It is an interactive prompt at which you may enter expressions and define short programs; it is very useful for testing individual code fragments.

After attaching a CircuitPython device to USB, you can test it using your terminal emulator to interact directly with CircuitPython. You may need to enter a keystroke in the serial pane to see the >>> input prompt. It will also show a banner including the specific CircuitPython version.

At the prompt you can enter commands: you might try help('modules') to see the available built-in libraries.

Control-D will reload and rerun code.py; control-C will interrupt a running program. The prompt offers tab-completion which is handy for exploring modules.

As an example for interactively testing out code fragments, you might try examining the internal time by entering the following expressions. First import the time module to make these functions available:

import time

You can then see the contents of the module using the help function:

help(time)

To read the clock in seconds:

time.time()

To see this broken out in a structure:

time.localtime()

Note that unless your device has a real-time clock, this will not be the correct wall clock time.

To see the number of nanoseconds since the device was reset:

time.monotonic_ns()