How To Create a CircuitPython Library

2023-08-07 | By Maker.io Staff

CircuitPython is a lightweight and beginner-friendly, open-source programming language based on MicroPython, specifically designed for use on microcontrollers and small embedded devices. It supports a wide array of devices from various manufacturers and offers simplified and consistent interfaces for interacting with hardware. However, sharing custom code between different projects or with other developers can become tricky, which is where software libraries come into play. This article explores best practices you can utilize when creating libraries to make writing, sharing, finding, and importing reusable code easier.

Understanding Libraries, Python Packages, and Modules

In software engineering, the term library encapsulates reusable code that can be useful across ‎multiple projects. Instead of re-writing the same piece of code in every single project, you can ‎pull out this common code and place it in a library to import into another project. In both Python ‎and MicroPython, these libraries are called packages. Each package may contain multiple ‎modules — for example, one per supported development board architecture.

Boilerplate Code, Contracts, and APIs

Developers, especially those in embedded software engineering, often refer to common code ‎that’s required in most single projects as boilerplate code. These are typically low-level calls, but ‎also functions that you might commonly need across a wide project range. A custom logging ‎function is one example of typical boilerplate code.

Finally, an API is the communication interface of a module, class, or web service. These are the publicly accessible functions that other code can call. The caller must, however, ensure that it passes all necessary arguments in the correct order and supplies valid values. In return, the callee guarantees that it returns the expected result. This principle is referred to as design-by-contract in software engineering.

Creating CircuitPython Libraries with Cookiecutter

Cookiecutter is a tool for Python that helps create projects based on pre-defined templates (called cookie cutters), thereby saving time, and ensuring consistency. You can use a ready-‎made template or create your own to fit a project's needs. For example, it's commonly used to ‎generate project structures and code skeletons when packaging custom code into a CircuitPython library.

Either way, begin by installing cookiecutter using pip. If using MacOS or Linux, you can ‎accomplish this by typing the following command:

Copy Code

pip install cookiecutter

Then, choose or create a project template. This article uses the default example provided by ‎Adafruit in their official GitHub repository. You can either download the template, extract it, and ‎run cookiecutter from within the extracted folder or supply cookiecutter with the template ‎location at runtime:

Copy Code

python -m cookiecutter 
gh:adafruit/cookiecutter-adafruit-circuitpython

Running this command instructs Cookiecutter to fetch the template from the specified GitHub ‎repository. The remainder of the library creation process is implemented in a wizard where ‎Cookiecutter presents you with prompts asking you to make specific inputs:

How To Create a CircuitPython Library This screenshot shows all the questions found in the Cookiecutter wizard

Inputs marked without brackets are mandatory. You may omit those with brackets — brackets ‎with enclosed values denote that the wizard chooses that value per default if you don’t supply ‎any input.

While most of the inputs should be self-explanatory, it’s worth pointing out that the library name ‎must match the spelling of the GitHub URL where the library will be hosted. Further, ‎other_requirements are a comma-separated list of Python libraries used by this library. Keep in ‎mind that this value will only be used for PyPI, and it’s not critical if the library won’t be published there.

Populating the Created Library

Once done, the wizard creates a folder containing the new library’s files according to the chosen ‎template. However, that newly generated library is still lacking custom functionality. Navigate to ‎the folder in your user folder created by Cookiecutter:

How To Create a CircuitPython Library The folder, created by Cookiecutter following the Adafruit CircuitPython template, contains the ‎files shown in this screenshot.

This folder contains many files and subfolders, most of which are not crucial at this point. ‎However, the single Python file named after your library, in this case, awesomehelpers.py, ‎contains the library’s main code. Open this file and add your custom code. If your library has ‎large quantities of code, you may add subfolders containing additional Python files and import them into the library’s main Python file.

Aside from this, you can add as many examples as you’d like to the examples folder, ‎demonstrating how to use your library. The docs folder contains auto-generated documentation ‎for your library, and the .github folder and .gitignore file configure the git repository in this folder. ‎The requirements and optional_requirements files contain the values entered in the wizard earlier, ‎and they can be used to quickly install all necessary dependencies, such as restoring a virtual ‎environment. The various readme and license files also contain additional documentation for ‎library users.

Summary and Where to Take it From Here

CircuitPython is an open-source, lightweight programming language based on MicroPython, ‎designed for microcontrollers and small embedded devices. The language provides beginner-‎friendly features and supports various devices from different manufacturers, making it ‎accessible for hardware projects.

To facilitate code reuse and sharing, you can create software libraries, also known as packages, ‎which contain reusable code and modules. These libraries help avoid duplication of standard ‎code across projects and provide consistent interfaces for interacting with hardware. They also ‎define APIs specifying how different project components should communicate, following design-‎by-contract principles in software engineering.

Cookiecutter is a Python tool that streamlines project creation using pre-defined templates such ‎as the CircuitPython library template, saving time, ensuring consistency, and facilitating the ‎process through a guided wizard with prompts and inputs. After generating the new library folder ‎with Cookiecutter, you can customize the library's functionality by adding your code to the main ‎Python file, along with additional files or subfolders if needed. At the same time, the generated ‎folder also includes other components such as examples, documentation, git configuration, and ‎readme/license files for a comprehensive library package.

Once you create a library, you can share the code on GitHub, which can be done as usual. ‎However, note that the GitHub repository URL must match the library folder's name to prevent ‎issues with links generated in the library's documentation.