CircuitPython

CircuitPython 是 Adafruit 基于 MicroPython 派生出的 Python 实现，主打「把开发板当 U 盘用」：插上 USB，出现一个 CIRCUITPY 盘符，编辑其中的 code.py，保存后板子自动重启运行。适合教育、入门和 Adafruit 生态用户。

概览

CircuitPython 的主体采用 MIT 许可。它并不只面向乐鑫，但 ESP32 系列是其重要的支持平台之一。

查看 GitHub 发布页（2026-10-14）：

• 最新稳定版是 10.3.1（Bug 修复版）。
• 同时存在预发布版本 10.4.0-alpha.2 与 11.0.0-alpha.1，发布说明提到下一个稳定大版本将是 11.0.0。
• 10.3.1 说明中的稳定支持芯片包括 ESP32、C2、C3、C5、C6、C61、H2、S2、S3；ESP32-P4 仍标为 alpha。
• 10.3.1 新增 ESP32-C5 支持，并修复了 BLE 通知丢失、触摸输入回退等问题。

具体到每块开发板是否有现成固件，请到 circuitpython.org/downloads 按板型搜索。该页面区分稳定版与最新测试版。

关键信息

安装

1. 到 circuitpython.org/downloads 找到你的板子，下载 .bin 或 .uf2。
2. 对带 UF2 引导程序的板子（如多数 Adafruit 的 ESP32-S2 / S3 板）：双击复位进入引导模式，把 .uf2 拖进出现的盘符即可。
3. 对没有 UF2 引导的通用 ESP32 板，可以使用网页安装器（官方下载页提供 Web Serial 安装）或 esptool，见 烧录工具。
4. 安装完成后出现 CIRCUITPY 盘符，里面放 code.py 与 lib/。

示例

把下面内容保存为 CIRCUITPY/code.py，在板子上运行：

# 运行于 CircuitPython 设备
import time, board, digitalio

led = digitalio.DigitalInOut(board.LED)   # 不同板子的 board.LED 可能不存在，查看 dir(board)
led.direction = digitalio.Direction.OUTPUT

while True:
    led.value = not led.value
    time.sleep(0.5)

联网示例使用 wifi 与 socketpool 内置模块，凭据放在 settings.toml 里：

# CIRCUITPY/settings.toml
CIRCUITPY_WIFI_SSID = "你的SSID"
CIRCUITPY_WIFI_PASSWORD = "你的密码"

只要设置了这两项，板子会自动尝试联网；代码里可直接 import wifi 并使用。

库与 Blinka

Adafruit 为数百种传感器和显示器维护了统一的 CircuitPython 库，通过 circup 工具安装：

pip install circup
circup install adafruit_bme280   # 本地电脑执行，设备需已通过 USB 连接

另外，Blinka 兼容层可让这些库在树莓派等 Linux 板上运行。

与 MicroPython 的差异

项目	CircuitPython	MicroPython
开发方式	USB 盘符 + 自动重载	REPL + 工具拷贝文件
API 风格	跨板统一（board、busio、digitalio）	贴近硬件（machine）
库生态	Adafruit 官方库	社区库较分散
底层灵活度	较低，部分功能刻意不暴露	较高
低功耗与深睡	提供 alarm 模块，能力不如 IDF	提供 machine.deepsleep 等

板载 USB 盘符的取舍

USB 盘符方便，但如果设备同时被电脑与程序写入，文件系统可能损坏。发布到现场的设备建议设置只读文件系统，或使用只在需要时才挂载的方案，细节参考官方文档的 storage 模块。

适合谁 / 不适合谁

适合学生、教学工作坊，以及购买 Adafruit Feather、QT Py、MatrixPortal 等开发板的用户。不适合需要 ESP-IDF 全部功能、对性能或内存极致要求，或想使用大量 MicroPython 社区库的项目，后者看 MicroPython。

参考资料

• CircuitPython 官网：https://circuitpython.org/
• CircuitPython 下载页：https://circuitpython.org/downloads
• CircuitPython 发布页：https://github.com/adafruit/circuitpython/releases
• CircuitPython 文档：https://docs.circuitpython.org/