CircuitPython Guide

CircuitPython is a dialect of Python available for particular microcontrollers. We will be using it to write programs for embedded computing within our projects. It will fill a role similar to Arduino sketches, but we believe it will be easier to learn and use.

CircuitPython is a open-source derivative of MicroPython developed by Adafruit. It extends MicroPython with an extensive set of hardware interface libraries, a more convenient code upload system, and precompiled binaries for a large set of microcontrollers. It omits a few advanced MicroPython features and several hardware platforms in favor of ease of use.

Online Guides

The CircuitPython information online is scattered over several sites, so the following notes may help you locate needed information.

CircuitPython Downloads

The CircuitPython home page is primarily useful for hosting downloads. The following are particularly relevant to this course.

  1. CircuitPython Installer Downloads. Index of individual pages for downloading precompiled binaries to install on specific microcontrollers.

  2. CircuitPython Libraries Bundle download.

    The library bundle include precompiled modules as .mpy files and sample code. The bundle version must match the installed CircuitPython version. The bundle is inclusive and only a fraction should be installed on your microcontroller; please see the individual board notes.

  3. Code with Mu.

    This is the Adafruit-recommended editor for creating CircuitPython programs. Note that this is convenient but not strictly necessary if you already have a favorite Python editor and a terminal emulator.

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 microcontrollers. A few specific pages are outlined below.

    • Installing Mu Editor.

      The Mu Editor provides a convenient desktop application for editing and running CircuitPython code. Please note that it isn’t strictly necessary; CircuitPython is self-hosting, so any Python-compatible code editor works fine.

    • Installing CircuitPython.

      A general guide to installing CircuitPython on a microcontroller.

  2. Adafruit Circuit Playground Bluefruit guide.

    This is a a step-by-step guide to the Bluefruit microcontroller. See also the Adafruit Circuit Playground Bluefruit guide on this course site.

  3. Adafruit Circuit Playground Library - Tutorial.

    This is a convenience library provided for the Bluefruit which simplifies access to the onboard hardware. This narrative tutorial walks through the examples using the specific sensors and functions. The API documentation below provides the formal specification.

  4. CircuitPython Bluetooth LE Libraries on any computer.

    Bluetooth Low Energy (BLE) is a system for wireless communication. This guide addresses installing support in a desktop or laptop Python for communicating with microcontrollers using Bluetooth.

Technical (API) Software Documentation

The following sub-sites primarily contain the technical details on the language and library API (Application Programming Interface). These are extracted from the source code and reflect the precise software specifications.

  1. Adafruit Circuit Playground Library - API Reference.

    Technical documentation on the high-level library for driving the onboard hardware on the Adafruit Circuit Playground Bluefruit and Circuit Playground Express.

  2. Adafruit CircuitPython Library Bundle - API Reference.

    Technical documentation on the individual modules in the library bundle. This covers drivers for an inclusive set of hardware, and only a fraction will apply to our microcontrollers.

  3. Adafruit CircuitPython - API Reference.

    Technical documentation on the core Python modules, including both standard library implementations like the math module and common microcontroller-specific modules like digitalio.

Source Code Repositories

The Adafruit github account hosts the source code for both the libraries and the core system. Note also that the API documentation frequently has source code links for inspecting the code.

  1. Adafruit CircuitPython Library Bundle (github).

    Source code for the main Adafruit library bundle required for most examples. This is primarily a host module for submodules and refers to many other individual repositories.

  2. Adafruit CircuitPlayground Library (github).

    Source code for the high-level convenience library for the Bluefruit, used in drive the on-board hardware in the sample code.

  3. CircuitPython Community Library Bundle (github).

    Source code for additional library support for interfacing to a wide variety of devices.

  4. CircuitPython (github).

    Source code for the core language system itself, derived from MicroPython. It includes the C sources for the interpreter and compiler, the mpy-cross cross-compiler for creating .mpy files, and low-level hardware drivers for each target system.

  5. MicroPython (github).

    Source code for the MicroPython system for embedded microcontrollers. Note that this upstream version supports a wider variety of microcontrollers than CircuitPython, notably including the ESP8266 which is no longer supported by CircuitPython.