There are two parts to the CircuitPython ecosystem:

  • CircuitPython firmware, written in C and built to run on various microcontroller boards (not PCs). The firmware includes the CircuitPython interpreter, which reads and executes CircuitPython programs, and chip-specific code that controls the hardware peripherals on the microcontroller, including things like USB, I2C, SPI, GPIO pins, and all the rest of the hardware features the chip provides.
  • CircuitPython libraries, written in Python to use the native (built into the firmware) modules provided by CircuitPython to control the microcontroller peripherals and interact with various breakout boards.

But suppose you'd like to use CircuitPython libraries on a board or computer that does not have a native CircuitPython firmware build. For example, on a PC running Windows or macOS. Can that be done? The answer is yes, via a separate piece of software called Blinka. Details about Blinka follow, however it is important to realize that the CircuitPython firmware is never used.

CircuitPython firmware is NOT used when using Blinka.

Adafruit Blinka: a CircuitPython Compatibility Library

Enter Adafruit Blinka. Blinka is a software library that emulates the parts of CircuitPython that control hardware. Blinka provides non-CircuitPython implementations for board, busio, digitalio, and other native CircuitPython modules. You can then write Python code that looks like CircuitPython and uses CircuitPython libraries, without having CircuitPython underneath.

There are multiple ways to use Blinka: 

  • Linux based Single Board Computers, for example a Raspberry Pi
  • Desktop Computers + specialized USB adapters
  • Boards running MicroPython

More details on these options follow.

Raspberry Pi and Other Single-Board Linux Computers

On a Raspberry Pi or other single-board Linux computer, you can use Blinka with the regular version of Python supplied with the Linux distribution. Blinka can control the hardware pins these boards provide.

Desktop Computers 

On Windows, macOS, or Linux desktop or laptop ("host") computers, you can use special USB adapter boards that that provide hardware pins you can control. These boards include MCP221A and FT232H breakout boards, and Raspberry Pi Pico boards running the u2if software. These boards connect via regular USB to your host computer, and let you do GPIO, I2C, SPI, and other hardware operations.

MicroPython

You can also use Blinka with MicroPython, on MicroPython-supported boards. Blinka will allow you to import and use CircuitPython libraries in your MicroPython program, so you don't have to rewrite libraries into native MicroPython code. Fun fact - this is actually the original use case for Blinka.

Installing Blinka

Installing Blinka on your particular platform is covered elsewhere in this guide. The process is different for each platform. Follow the guide section specific to your platform and make sure Blinka is properly installed before attempting to install any libraries.

Be sure to install Blinka before proceeding.

Installing CircuitPython Libraries

Once Blinka is installed the next step is to install the CircuitPython libraries of interest. How this is down is different for each platform. Here are the details.

Linux Single-Board Computers

On Linux single-board computers, such as Raspberry Pi, you'll use the Python pip3 program (sometimes named just pip) to install a library. The library will be downloaded from pypi.org automatically by pip3.

How to install a particular library using pip3 is covered in the guide page for that library. For example, here is the pip3 installation information for the library for the LIS3DH accelerometer.

The library name you give to pip3 is usually of the form adafruit-circuitpython-libraryname. This is not the name you use with import. For example, the LIS3DH sensor library is known by several names:

  • The GitHub library repository is Adafruit_CircuitPython_LIS3DH.
  • When you import the library, you write import adafruit_lis3dh.
  • The name you use with pip3 is adafruit-circuitpython-lis3dh. This the name used on pypi.org.

Libraries often depend on other libraries. When you install a library with pip3, it will automatically install other needed libraries.

Desktop Computers using a USB Adapter

When you use a desktop computer with a USB adapter, like the MCP2221A, FT232H, or u2if firmware on an RP2040, you will also use pip3. However, do not install the library with sudo pip3, as mentioned in some guides. Instead, just install with pip3

MicroPython

For MicroPython, you will not use pip3. Instead you can get the library from the CircuitPython bundles. See this guide page for more information about the bundles, and also see the Libraries page on circuitPython.org.

This guide was first published on Sep 29, 2019. It was last updated on Jul 25, 2024.

This page (Running CircuitPython Code without CircuitPython) was last updated on Mar 08, 2024.

Text editor powered by tinymce.