Python CircuitPython for Hardware — Core Concepts

What CircuitPython Is

CircuitPython is a fork of MicroPython created and maintained by Adafruit Industries. It prioritizes ease of use over raw performance and is specifically designed for beginners and educators. The project launched in 2017 and has grown to support over 400 boards.

The defining feature is the USB drive workflow. When you plug a CircuitPython board into your computer, it appears as a removable drive named CIRCUITPY. You edit code.py on that drive, save, and the board automatically reloads and runs your updated code. No IDE, no compile step, no flash tool.

How It Differs from MicroPython

While CircuitPython is built on MicroPython’s core, the projects have diverged significantly:

• USB mass storage. CircuitPython always exposes a USB drive. MicroPython typically uses serial REPL only.
• Unified hardware API. CircuitPython uses consistent module names (board, digitalio, analogio, neopixel) across all boards. MicroPython’s APIs vary by port.
• Library management. CircuitPython libraries are distributed as .mpy bundles you copy to a lib/ folder on the board. No package manager needed.
• Single file execution. CircuitPython runs code.py (or main.py) on every save. MicroPython requires manual execution or boot configuration.
• Community focus. Adafruit provides extensive tutorials, a dedicated Discord community, and weekly “Show and Tell” streams.

The Hardware Ecosystem

Adafruit designs boards specifically for CircuitPython:

• Circuit Playground Express and Bluefruit — All-in-one boards with 10 NeoPixel LEDs, accelerometer, temperature sensor, speaker, microphone, and buttons built in. Popular in classrooms.
• Feather series — Compact boards with battery connectors, available with Wi-Fi (ESP32-S2/S3), Bluetooth (nRF52840), or RP2040 processors.
• QT Py and XIAO — Thumb-sized boards for tiny projects.
• MatrixPortal and MagTag — Purpose-built boards for LED matrices and e-ink displays.

Third-party boards from Raspberry Pi (Pico), SparkFun, and Seeed also support CircuitPython.

Writing CircuitPython Code

A typical project reads sensors and controls outputs:

import board
import digitalio
import analogio
import time

# Set up an LED on a specific pin
led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT

# Set up a light sensor
light = analogio.AnalogIn(board.LIGHT)

while True:
    brightness = light.value  # 0 to 65535
    if brightness < 10000:
        led.value = True   # dark: turn LED on
    else:
        led.value = False  # bright: turn LED off
    time.sleep(0.1)

The board module provides pin names that match the labels printed on the physical board. You never need to look up GPIO numbers.

The Library Bundle

Adafruit maintains a curated library bundle with hundreds of drivers for specific hardware — display screens, motor controllers, GPS modules, environmental sensors, and more. Each library is a .mpy file or a folder you drop into the lib/ directory on the CIRCUITPY drive.

For example, to use a BME280 temperature and humidity sensor, you copy adafruit_bme280 to lib/, then:

import board
import adafruit_bme280.basic as adafruit_bme280

i2c = board.I2C()
sensor = adafruit_bme280.Adafruit_BME280_I2C(i2c)

print(f"Temperature: {sensor.temperature:.1f} °C")
print(f"Humidity: {sensor.humidity:.1f} %")

Common Misconception

People often think CircuitPython is only for Adafruit boards. In reality, CircuitPython runs on boards from many manufacturers. The Raspberry Pi Pico, SparkFun Thing Plus, and Seeed XIAO all have official CircuitPython support. Adafruit maintains the project but welcomes community board definitions.

When to Choose CircuitPython vs Alternatives

CircuitPython excels when you want the fastest path from idea to working hardware, especially for education, art installations, and personal projects. Choose Arduino or MicroPython when you need maximum performance, deep sleep with minimal overhead, or access to ESP-IDF features that CircuitPython does not expose.

One thing to remember: CircuitPython removes every barrier it can between writing Python code and seeing electronics respond, making it the most approachable way to start programming hardware.