如何使用CircuitPython

概述

因此，您有了这个新的 CircuitPython兼容板。您将其插入。也许它显示为名为CIRCUITPY的磁盘驱动器。也许不是！无论哪种方式，您都需要知道从这里出发的去向。好吧，我们已经覆盖了您！

本指南将帮助您开始使用CircuitPython！

关于您的新主板，有很多令人惊奇的事情。其中之一是能够运行CircuitPython的能力。您可能在Adafruit网站上的某个地方看到过该名称。不确定是什么？我们可以提供帮助！

“但是我一生从未编码过。我没有办法！”你绝对可以！ CircuitPython旨在帮助您从头开始学习。如果您不熟悉所有内容，那么这是开始的地方！

本指南将引导您逐步了解CircuitPython入门。您将学习如何安装CircuitPython，更新到CircuitPython的最新版本，如何设置串行连接以及如何编辑文件。

欢迎使用CircuitPython！

什么是CircuitPython？

CircuitPython是一种编程语言，旨在简化在低成本微控制器板上进行编程的实验和学习。它使入门变得比以往任何时候都更加轻松，无需预先下载桌面。设置好电路板后，打开任何文本编辑器，然后开始编辑代码。就是这么简单。

CircuitPython基于Python

Python是增长最快的编程语言。它在学校和大学中教授。这是一种高级编程语言，这意味着它的设计易于阅读，编写和维护。它支持模块和包，这意味着可以轻松地将代码重用于其他项目。它具有内置的解释器，这意味着无需其他步骤即可使代码正常工作，例如 compiling 。当然，Python是开源软件，这意味着任何人都可以免费使用，修改或改进它。

CircuitPython为所有这些令人惊奇的功能添加了硬件支持。如果您已经具备Python知识，则可以轻松地将其应用于CircuitPython。如果您以前没有经验，那么开始就非常简单！

为什么要使用CircuitPython？

CircuitPython设计为在微控制器板上运行。微控制器板是带有微控制器芯片的板，本质上是一台很小的多合一计算机。您拿着的板是微控制器板！ CircuitPython易于使用，因为您所需要的只是那块小板，一条USB电缆和一台具有USB连接的计算机。但这仅仅是开始。

使用CircuitPython的其他原因包括：

您要快速启动并运行。编辑您的代码，保存文件，它会立即运行。无需编译，无需下载，也不需要上传。

您是编程的新手。 CircuitPython在设计时就考虑了教育。开始学习编程的过程很容易，您会立即从董事会获得反馈。

轻松更新代码。由于代码位于磁盘驱动器上，因此您可以随时对其进行编辑您还可以保留多个文件，以方便进行实验。

串行控制台和REPL。这些功能可让您从代码和交互式编程中获得实时反馈。

文件存储。 CircuitPython的内部存储使其非常适合数据记录，播放音频剪辑以及与文件交互。

强大的硬件支持。 有许多用于传感器，分支板和其他外部组件的库和驱动程序。

它是Python！ Python是增长最快的编程语言。它在学校和大学中教授。 CircuitPython与Python几乎完全兼容。它只是增加了硬件支持。

这仅仅是开始。 CircuitPython不断发展，并不断更新。我们欢迎并鼓励社区提供反馈，并将其纳入开发CircuitPython的方式中。这是开源概念的核心。这使CircuitPython更适合您和使用它的每个人！

常见问题

这些是有关CircuitPython和CircuitPython微控制器的一些常见问题。

随着我们继续开发CircuitPython和创建新版本，我们将停止支持较早的版本。访问https://circuitpython.org/downloads为您的电路板下载最新版本的CircuitPython。您必须下载与您的CircuitPython版本匹配的CircuitPython库捆绑包。请更新CircuitPython，然后访问https://circuitpython.org/libraries下载最新的库捆绑包。

我必须继续使用CircuitPython 3.x或2.x，在哪里可以找到兼容的库？

我们不再构建或支持CircuitPython 2.x和3.x库包。我们强烈建议您将CircuitPython更新到最新版本并使用当前版本的库。。但是，如果由于某种原因而无法更新，则可以在此处找到最后一个可用的2.x版本和最后一个可用的3版本。 .x在此处构建。

CircuitPython是否支持ESP8266或ESP32？为什么不呢？

我们从4.x版本开始不再支持ESP8266-对于更多信息，请在这里阅读！

https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-for-esp8266

div》

如何使用CircuitPython连接到Internet？

如果您想添加WiFi支持，请参阅我们的ESP32/ESP8266作为协处理器的指南。

CircuitPython中是否有异步支持 》

我们目前在CircuitPython中没有异步支持

我的RGB NeoPixel/点星形LED闪烁有趣的颜色-这是什么意思？

状态LED可以告诉您CircuitPython开发板的最新动态。

什么是MemoryError？

当您尝试在板上存储过多存储空间时会发生内存分配错误。 CircuitPython微控制器板的可用内存量有限。 M0 Express板上可以包含约250行代码。如果您尝试import太多的库，大型库的组合，或者运行的程序包含太多的代码行，则您的代码将无法运行，并且您会在串行控制台中收到MemoryError （REPL）。

当我遇到MemoryError吗？

尝试重置主板。每次重置板卡时，它都会重新分配内存。虽然这不太可能解决您的问题，但这是一个简单的步骤，值得尝试。

请确保您使用的是库的 .mpy 版本。捆绑包中的所有CircuitPython库均以 .mpy 格式提供，与.py格式相比占用的内存更少。确保您使用的是最新版本的CircuitPython库包。

如果这不能解决问题，请尝试缩短代码。缩短注释，删除多余或不需要的代码，或执行其他任何清理操作以缩短代码。如果您使用了很多函数，则可以尝试将它们移至单独的库中，创建该库的.mpy并将其导入代码中。

您可以将整个函数文件放入.mpy，将import放入code.py。这意味着您将无法在板上实时编辑代码，但可以节省空间。

我的import语句的顺序会影响内存吗？

这可能是因为内存根据分配顺序和大小的不同而碎片化了对象。加载.mpy文件会占用较少的内存，因此建议您对未编辑的文件执行此操作。

如何创建自己的.mpy文件？

您可以使用以下方法制作自己的.mpy版本的文件： mpy-cross。

您可以从CircuitPython版本页面（最新的2.x版本）为您的操作系统下载mpy-cross的CircuitPython 2.x版本。

您可以通过克隆CircuitPython GitHub存储库并在mpy-cross目录中运行make来为CircuitPython 3.x构建circuitpython/mpy-cross/。然后运行。/mpy-cross path/to/foo.py在与原始文件相同的目录中创建foo.mpy。

如何查看我有多少可用内存？

import gc

gc.mem_free（）

将为您提供可用的字节数。

CircuitPython是否支持中断？

否。 CircuitPython当前不支持中断。我们尚无确定何时将其包含在内。

Feather M0是否支持WINC1500？

否，WINC1500将不适合M0闪存空间。

诸如ATmega328或ATmega2560的AVR可以运行CircuitPython吗？

否。

常用的首字母缩写

CP或CPy = CircuitPython

CPC =游乐场经典版

CPX =游乐场特快版

安装Mu编辑器

Mu是一个简单的代码编辑器，可与Adafruit CircuitPython板一起使用。它是用Python编写的，可在Windows，MacOS，Linux和Raspberry Pi上运行。内置了串行控制台，因此您可以立即从开发板的串行输出中获得反馈！

Mu是我们推荐的编辑器-请使用它（除非您已经是一位经验丰富的编码人员，并且拥有喜欢的编辑器！）

下载并安装Mu

从https://codewith.mu下载Mu。单击下载或从这里开始链接以获取下载和安装说明。该网站还有很多其他信息，包括广泛的教程和操作方法。

使用Mu

首次启动Mu时，系统会提示您选择“模式”-您可以以后总是要改变主意。现在，请选择 Adafruit ！

当前模式显示在窗口的右下角，在“齿轮”图标旁边。如果模式显示“ Microbit”或其他名称，请单击该名称，然后在出现的对话框中选择“ Adafruit”。

Mu会尝试自动检测您的电路板，因此请插入CircuitPython设备并确保其显示为 CIRCUITPY 驱动器，然后再启动Mu

，现在就可以编写代码了！让我们继续吧。。..

安装CircuitPython

在我们继续开发CircuitPython和创建新版本时，我们将停止支持较旧的版本。如果您正在运行CircuitPython 2.x，则需要更新到3.x。通常，Adafruit将支持最后两个主要版本。

一些与CircuitPython兼容的电路板已安装CircuitPython。其他的支持CircuitPython的，但需要安装它。同样，您可能想更新板上已经安装的CircuitPython的版本。安装和更新步骤相同。这里我们将介绍如何在您的板上安装或更新CircuitPython。

仅必须安装CircuitPython ONCE，之后，您可以自由地编写自己喜欢的代码，而无需再次进行此过程，直到需要升级为止！

下载最新版本！

您要做的第一件事就是下载最新版本版本的CircuitPython。

如果您已经在运行CircuitPython，请确保您正在运行最新版本！如果不确定，可以按照以下步骤操作，以确保安装了最新版本。

总是在安装或更新电路之前备份您的代码。在大多数情况下，在更新过程中不会从您的开发板上删除任何内容，但是这种情况可能会发生。如果板上已经有代码，请确保在执行以下步骤之前将其备份到计算机上。

CircuitPython代码的两个位置

在2019年4月之前，从Adafruit CircuitPython Github网站下载了代码。从2019年4月开始，创建了新网站CircuitPython.org来托管CircuitPython。支持的板的定义在那里进行了更新，更容易找到。创建板定义文件并将其上传到站点后，将添加来自Adafruit和其他各方的新板。

通过单击下面的绿色按钮前往CircuitPython.org下载适用于您板的最新软件。

点击此处从CircuitPython.org下载CircuitPython

目前，这些文件仍在Adafruit的CircuitPython GitHub存储库中仍然可用。这些文件将来可能会迁移到新的CircuitPython.org存储库。

单击此处查看最新的CircuitPython版本

向下滚动到以下列表： CircuitPython文件，然后选择适合您的电路板的文件。每个文件都包含与其兼容的板的名称。为您的电路板下载文件。

接下来，您将要使用已知良好的USB数据线插入板子。确保USB电缆是数据电缆！有些仅适用于充电，可能会导致很多挫败感。

Windows 7驱动程序

如果使用Windows 7，您需要在插入电路板之前安装驱动程序。

如果您使用的是Windows 7，请使用下面的链接下载驱动程序包。您无需在Mac，Linux或Windows 10上安装驱动程序。

下载Adafruit Windows 7驱动程序安装程序

启动UF2引导加载程序

几乎所有CircuitPython板均随附了名为UF2的引导加载程序（ U SB F 鞭打版本 2 ），这使得安装和更新CircuitPython变得快速而简单。引导加载程序是您的电路板需要使用的模式，才能使您下载的CircuitPython .uf2 文件工作。如果您下载的与电路板名称匹配的文件以 uf2 结尾，那么您想继续此部分。但是，如果文件以 .bin 结尾，则必须执行更复杂的安装-请转到此页面以了解如何执行此操作。

在板上找到重置按钮。 。这是一个小的黑色按钮，在大多数板上，它将是唯一可用的按钮。 （在Circuit Playground Express上，它是位于面板中央的较小按钮。）

点击两次此按钮进入引导程序。如果第一次尝试不起作用，请不要气disc。拍子的节奏需要正确，有时需要几次尝试。如果您有Circuit Playground Express，并且刚从背包中拿出来，请尝试按一下按钮。

成功后，板上的RGB LED将闪烁红色，然后保持绿色。新的驱动器将显示在您的计算机上。该驱动器将称为boardnameBOOT，其中 boardname 是对特定板的引用。例如，一根羽毛将具有FEATHERBOOT，小饰品将具有TRINKETBOOT等。向前，我们将其称为引导驱动器BOOT

该板现在处于引导加载程序模式！这就是我们安装或更新CircuitPython所需要的。

现在找到您下载的文件。将该文件拖到计算机上的BOOT驱动器上。

指示灯应再次闪烁，BOOT将消失，计算机上将出现一个 new 驱动器，称为CIRCUITPY。

恭喜！您已成功安装或更新CircuitPython！

CIRCUITPY和boardnameBOOT有什么区别？

将CircuitPython开发板插入计算机时，计算机会将开发板的闪存视为USB闪存驱动器，可以在其中存储文件被存储。成功安装CircuitPython后，您将看到CIRCUITPY驱动器。双击重置按钮时，您会看到boardnameBOOT驱动器。您可以将文件拖到两个文件，但是只有CIRCUITPY才能运行CircuitPython代码。

通常，将文件拖到已安装的USB驱动器时，该文件将复制到该驱动器中，然后能够在文件浏览器中显示。但是，将CircuitPython UF2文件拖到boardnameBOOT驱动器时，它似乎消失了，并且驱动器断开了连接。这个是正常的！ UF2本质上是一个安装程序文件，并且不仅位于驱动器上，而且如果该板处于引导加载程序模式（即boardnameBOOT）也可以安装CircuitPython。

您将能够复制其他文件文件加载到引导加载程序驱动器（boardnameBOOT），但它们将无法运行或无法被CircuitPython访问。因此，请确保在完成CircuitPython的安装后，将其拖到CIRCUITPY驱动器上并在其中编辑文件！

Bootloader驱动器名称

此列表并不详尽，但是应该让您知道在Bootloader驱动器名称中要查找的内容。

小饰品M0 = TRINKETBOOT

宝石M0 = GEMMABOOT

电路游乐场Express = CPLAYBOOT

ItsyBitsy M0 Express = ITSYBOOT

ItsyBitsy M4 Express = ITSYM4BOOT

羽毛M0 Express = FEATHERBOOT

羽毛M4 Express = FEATHERBOOT

地铁M0 Express = METROBOOT

地铁M4 Express = METROM4BOOT

盛大Central M4 Express = GCM4BOOT

NeoTrelis M4 Express = TRELM4BOOT

CIRCUITPY驱动器

当CircuitPython完成安装，或者将CircuitPython板插入已安装CircuitPython的计算机时，该板将作为USB驱动器显示在计算机上 CIRCUITPY 。

CIRCUITPY 驱动器是您的代码以及必需的库和文件所在的位置。您可以直接在此驱动器上编辑代码，保存时它将自动运行。创建和编辑代码时，会将代码保存在 CIRCUITPY 驱动器上的code.py文件中。如果要与“学习”指南一起关注，则可以粘贴内容教程示例中的内容放入 CIRCUITPY 驱动器上的code.py中并保存以运行示例。

CircuitPython查找code.py并运行其中的内容当板子启动，重新加载或保存对文件的更改时，文件会自动生成。这就是让您轻松开始项目并更新代码的原因！

设备

有许多与CircuitPython一起使用的板。您可能会发现自己处于同时使用多个板的情况。当您将多块板插入计算机时会发生什么？您有多个 CIRCUITPY 驱动器！您怎么知道是哪一个？您可以重命名每个 CIRCUITPY 驱动器以避免混淆。

重命名CIRCUITPY

重命名 CIRCUITPY 时，它将名称写入文件系统。这意味着更改名称将通过断开电路板连接以及重新加载CircuitPython来持续！

名称必须小于等于11个字符！这是文件系统的限制。如果您选择的名称超过11个字符，则会收到错误消息。

在Mac上重命名CIRCUITPY

在Mac上重命名 CIRCUITPY 驱动器很简单。在Finder中单击驱动器，以便查看内容。然后，右键单击Finder中的驱动器，然后选择“重命名”。

单击“重命名”后，在右键菜单中，驱动器名称将显示在一个文本框中，您可以在其中重命名驱动器。键入新名称。

在Windows上重命名CIRCUITPY

在Windows上重命名 CIRCUITPY 驱动器很容易。打开文件资源管理器，找到 CIRCUITPY 驱动器。右键单击它，然后单击“重命名”。

在Windows上重命名 CIRCUITPY 驱动器很容易。打开文件资源管理器，找到 CIRCUITPY 驱动器。右键单击它，然后单击“重命名”。

还可以通过“属性”菜单重命名驱动器，该菜单可以通过Windows File Explorer以几种不同的方式打开，包括右键单击 CIRCUITPY 驱动器，然后选择“属性”。

在Linux上重命名CIRCUITPY

在Linux上重命名 CIRCUITPY 需要几个步骤。您需要确定安装点，然后运行命令以重命名驱动器。

打开终端程序。运行以下命令找出您的电路板的安装位置：

下载：文件

复制代码

df | grep CIRCUITPY df | grep CIRCUITPY

您将在结果行的右端看到CIRCUITPY。该行左端的dev/foo（其中foo是安装点的名称）是安装点。

接下来，您可以运行以下命令卸下电路板，将foo替换为您的特定挂载点。

下载：文件

复制代码

sudo umount /dev/foo sudo umount /dev/foo

要重命名木板，请运行以下命令：

下载：文件

复制代码

sudo fatlabel /dev/foo NEW_NAME sudo fatlabel /dev/foo NEW_NAME

然后弹出板，拔下电源插头，然后重新插入，以强制使用新名称重新安装。

要检查其是否工作，请在以下位置查找驱动器您的文件管理器。或者，您可以运行以下命令：

下载：文件

复制代码

df | grep NEW_NAME df | grep NEW_NAME

通过CircuitPython重命名CIRCUITPY

您还可以使用CircuitPython重命名板。在您的 CIRCUITPY 驱动器上创建一个名为boot.py的新文件。将以下代码复制到新的boot.py文件中：

下载：文件

复制代码

import storage

storage.remount（“/”， readonly=True）

m = storage.getmount（“/”）

m.label = “NEW_NAME”

storage.remount（“/”， readonly=False） import storage

storage.remount（“/”， readonly=True）

m = storage.getmount（“/”）

m.label = “NEW_NAME”

storage.remount（“/”， readonly=False）

弹出板，然后按一次“重置”按钮或拔下板来重新启动板并重新插入。片刻之后，它应该会以您选择的NEW_NAME出现在文件浏览器中！您可以在文件浏览器中显示新命名的板后删除boot.py。

还原为CIRCUITPY

您可以按照上述相同的过程将驱动器重命名为 CIRCUITPY 。

您还将通过擦除文件系统恢复为 CIRCUITPY 。如果您需要擦除CircuitPython板上的文件系统，则驱动器名称将在完成后恢复为 CIRCUITPY 。

创建和编辑代码

CircuitPython最好的事情之一就是使代码的启动和运行变得如此简单。在本节中，我们将介绍如何创建和编辑第一个CircuitPython程序。

要创建和编辑代码，只需要一个编辑器即可。有很多选择。 我们强烈建议您使用Mu！它是为CircuitPython设计的，并且非常简单易用，带有内置的串行控制台！

如果您不使用Mu，则可以使用基本的文本编辑器进入每个操作系统，例如Windows上的记事本，Mac上的TextEdit和Linux上的gedit。但是，许多这些编辑器不会立即将更改写回到您编辑的文件中。使用CircuitPython时可能会导致问题。请参阅下面的“编辑代码”部分。如果您现在想跳过该部分，请确保在不使用Mu的情况下在写入文件后在Windows上执行“弹出”或“安全删除”，或者在Linux上执行“同步”。 （在MacOS上这不是问题。）

创建代码

打开编辑器，然后创建一个新文件。如果您使用的是Mu，请单击左上角的 New 按钮

复制并粘贴将以下代码添加到编辑器中：

下载：文件

复制代码

import board

import digitalio

import time

led = digitalio.DigitalInOut（board.D13）

led.direction = digitalio.Direction.OUTPUT

while True：

led.value = True

time.sleep（0.5）

led.value = False

time.sleep（0.5） import board

import digitalio

import time

led = digitalio.DigitalInOut（board.D13）

led.direction = digitalio.Direction.OUTPUT

while True：

led.value = True

time.sleep（0.5）

led.value = False

time.sleep（0.5）

看起来像这样-请注意，在while True：行下，接下来的四行有空格以使其缩进，但是它们的缩进量完全相同。其他所有行在文本之前都没有空格。

将此文件另存为CIRCUITPY上的 code.py

。在每个板上，您都会发现一个红色的小LED。现在它应该闪烁。每秒一次

恭喜，您已经运行了第一个CircuitPython程序！

编辑代码

要编辑代码，请打开CIRCUITPY驱动器上的 code.py 文件进入编辑器。

对代码进行所需的更改。保存文件。就是这样！

文件保存完成后，您的代码更改将立即运行。

在继续之前，我们只有一个警告……

Don单击重置或拔出！

板上的CircuitPython代码将检测何时更改或写入文件，并会自动重新启动代码。

但是，这样做可以使编码变得非常快。

但是，您必须 等到文件保存完成后才能拔出或重置主板！ 在使用某些编辑器的Windows上，有时可能会花费 90秒，在Linux上，则可能需要30秒来完成，因为文本编辑器不会保存完全归档。 Mac OS似乎没有此延迟，这很好！

要意识到这一点非常重要。如果在计算机完成将文件写入板之前拔出板或重置板，则可能损坏驱动器。如果发生这种情况，您可能会丢失编写的代码，因此定期将代码备份到计算机上很重要。

有几种方法可以避免这种情况：

1。保存时，请使用可以完全写出文件的编辑器。

推荐的编辑器：

mu 是可以安全地写入所有更改的编辑器（它也是我们推荐的编辑器！）

emacs 还是一个可以在保存时完全写入文件的编辑器

Sublime Text 安全地写入所有更改

Visual Studio代码似乎可以安全地写入所有更改

gedit 在Linux上似乎可以安全地写入所有更改

推荐仅具有特定设置或附加组件：

vim / vi 安全地写入所有更改。但是将 vim 设置为不将交换文件（.swp文件：您的编辑的临时记录）写入CIRCUITPY。使用vim -n运行vim，设置no swapfile选项，或设置directory选项以在其他位置写入交换文件。否则，交换文件writestrigger会重新启动程序。

如果在“设置”-》“系统设置”-》“同步”中启用了“安全写入”，则 PyCharm IDE 是安全的（默认情况下为true） 。

如果您使用的是 Atom ，请安装保存时fsync软件包，以便它始终将对CIRCUITPY上文件的所有更改写出。

SlickEdit 仅在您添加了宏来刷新磁盘时有效。

我们不推荐这些编辑器：

记事本（默认的Windows编辑器）和N otepad ++ 可能写起来很慢，因此我们建议使用上面的编辑器！如果您使用的是记事本，请确保弹出驱动器（见下文）

IDLE 不会立即强制更改

nano （在Linux上）不会强制更改

geany （在Linux上）不会强制更改

其他任何操作-我们尚未测试其他编辑器，因此请使用推荐的编辑器！

2。写入后弹出或同步驱动器

如果您使用的是我们不推荐的编辑器之一，则不会丢失所有信息！您仍然可以使其工作。

在Windows上，您可以弹出或安全删除 CIRCUITPY驱动器。它实际上不会弹出，但是会强制操作系统将文件保存到磁盘。在Linux上，在终端中使用 sync 命令来强制写入磁盘。

哦，我没有做错什么，现在CIRCUITPY驱动器没有显示！！！

别担心！损坏驱动器并不是世界末日（或您的董事会！）。如果发生这种情况，请按照每块主板指南的“故障排除”页面上的步骤操作，以重新启动您的主板。

返回编辑代码。..

现在！让我们尝试编辑添加到板上的程序。在编辑器中打开 code.py 文件。我们将进行简单的更改。将第一个0.5更改为0.1。代码应如下所示：

下载：文件

复制代码

import board

import digitalio

import time

led = digitalio.DigitalInOut（board.D13）

led.direction = digitalio.Direction.OUTPUT

while True：

led.value = True

time.sleep（0.1）

led.value = False

time.sleep（0.5） import board

import digitalio

import time

led = digitalio.DigitalInOut（board.D13）

led.direction = digitalio.Direction.OUTPUT

while True：

led.value = True

time.sleep（0.1）

led.value = False

time.sleep（0.5）

其余代码保持原样。保存文件。看看板上的LED会怎样？事情变了！你知道为什么吗？让我们找出答案吧！

探索您的第一个CircuitPython程序

首先，我们来看一下正在编辑的代码。

这又是原始代码：

下载：文件

复制代码

import board

import digitalio

import time

led = digitalio.DigitalInOut（board.D13）

led.direction = digitalio.Direction.OUTPUT

while True：

led.value = True

time.sleep（0.5）

led.value = False

time.sleep（0.5） import board

import digitalio

import time

led = digitalio.DigitalInOut（board.D13）

led.direction = digitalio.Direction.OUTPUT

while True：

led.value = True

time.sleep（0.5）

led.value = False

time.sleep（0.5）

导入和库

您运行的每个CircuitPython程序都需要掌握很多信息。 CircuitPython使用起来如此简单的原因是，大多数信息都存储在其他文件中并在后台运行。这些文件称为库。其中一些内置在CircuitPython中。其他文件则存储在您的CIRCUITPY驱动器上的 lib 文件夹中。

下载：文件

复制代码

import board

import digitalio

import time import board

import digitalio

import time

import语句告诉董事会您重新使用代码中的特定库。在此示例中，我们导入了三个库：board，digitalio和time。所有这三个库都内置在CircuitPython中，因此不需要单独的文件。这就是使它成为出色的第一个例子的原因之一。您不需要任何额外的东西即可使其正常工作！ board使您可以访问板上的硬件，digitalio可以使您访问该硬件作为输入/输出，而time您通过“睡眠”来打发时间

向上发光二极管

接下来的两行代码设置使用发光二极管的代码。

下载：文件

复制代码

led = digitalio.DigitalInOut（board.D13）

led.direction = digitalio.Direction.OUTPUT led = digitalio.DigitalInOut（board.D13）

led.direction = digitalio.Direction.OUTPUT

您的主板将红色LED表示为D13。因此，我们初始化该引脚，并将其设置为输出。我们将led设置为等于该信息的其余部分，因此我们以后不必在代码中再次输入所有信息。

循环去循环

第三部分以while语句开头。 while True：本质上表示“永远执行以下操作：”。 while True：创建一个循环。代码将在条件为“ true”（相对于false）时“ while”循环，并且由于True永远都不为False，因此代码将永远循环。在while True：下缩进的所有代码都在循环“内部”。

在循环内部，我们有四个项目：

下载：文件

复制代码

while True：

led.value = True

time.sleep（0.5）

led.value = False

time.sleep（0.5） while True：

led.value = True

time.sleep（0.5）

led.value = False

time.sleep（0.5）

首先，我们有led.value = True。这条线告诉LED点亮。在下一行，我们有time.sleep（0.5）。此行告诉CircuitPython将运行代码暂停0.5秒。由于这是在打开和关闭LED之间进行的操作，因此LED将持续0.5秒。

接下来的两行类似。 led.value = False告诉LED熄灭，time.sleep（0.5）告诉CircuitPython再暂停0.5秒。

然后在再次关闭LED并重新打开LED的同时发生这种情况。

然后，循环将再次开始，只要代码正在运行，循环就会继续！

p》

因此，当您将第一个0.5更改为0.1时，可以减少代码使LED点亮的时间。因此，它会在关闭之前快速闪烁！

辛苦了！您已经在CircuitPython程序中编辑了代码！

如果我没有循环怎么办？

如果没有循环，代码将运行到最后并退出。在这样的简单程序中，这可能导致某些意想不到的行为，因为“退出”还会重置硬件状态。这与通过REPL运行命令不同。因此，如果您正在编写似乎无法正常运行的简单程序，则可能需要在最后添加一个循环，以使该程序不会退出。

最简单的循环是：

while True：

pass

记住，您可以按 退出循环。

另请参阅文档中的“行为”部分。

更多更改

我们不必在此止步！我们继续吧。将第二个0.5更改为0.1，使其如下所示：

下载：文件

复制代码

while True：

led.value = True

time.sleep（0.1）

led.value = False

time.sleep（0.1） while True：

led.value = True

time.sleep（0.1）

led.value = False

time.sleep（0.1）

现在，它闪烁的很快！您减少了代码打开和关闭LED的时间！

现在尝试将两个0.1都增加到1。您的LED指示灯闪烁的速度会慢得多，因为您增加了打开和关闭LED指示灯的时间。

做得好！你做得很好！您已经准备好开始新的示例并对其进行编辑以查看会发生什么！这些是简单的更改，但是主要更改是使用相同的过程完成的。进行所需的更改，保存并获取结果。

命名程序文件

CircuitPython在板上寻找要运行的代码文件。有四个选项： code.txt ， code.py ， main.txt 和 main.py 。 CircuitPython按该顺序查找那些文件，然后运行找到的第一个文件。虽然我们建议使用 code.py 作为代码文件，但重要的是要知道其他选项的存在。如果您的程序在工作时似乎没有更新，请确保没有创建另一个正在读取的代码文件，而不是正在处理的代码文件。

连接到串行控制台

CircuitPython的主要功能之一（通常是编程！）被称为“打印语句”。这是您包含在代码中的一行，使您的代码输出文本。 CircuitPython中的打印语句如下：

print（“Hello， world！”）

此行将导致：

Hello， world！

但是，这些打印语句需要在某个地方显示。串行控制台就在这里！

串行控制台接收从CircuitPython板通过USB发送的输出并显示它，以便您查看。当您在代码中包含了一条打印语句并且想要查看打印的内容时，这是必需的。这对于解决错误也很有用，因为您的电路板会发送错误，而串行控制台也会打印错误。

串行控制台需要终端程序。终端是一个程序，为您提供一个基于文本的界面来执行各种任务。

如果您使用的是Linux，并且在连接到串行控制台时遇到数秒的延迟，或者在连接时看到“ AT”和其他乱码，则说明Modemmanager服务可能会干扰。只需将其删除；除非您仍在使用拨号调制解调器，否则它用处不大。要删除，请在外壳上键入以下命令：

下载：file

复制代码

sudo apt purge modemmanager sudo apt purge modemmanager

您在使用Mu吗？

如果是，这是个好消息！串行控制台内置在Mu 中，并且会自动检测您的电路板，使用REPL 真的非常简单。

请注意Mu尚未与基于nRF52或ESP8266的CircuitPython板一起使用时，请跳至下一部分，以了解有关使用终端程序的详细信息。

首先，确保已插入CircuitPython电路板。如果使用Windows 7，请确保已安装

在Mu中，在菜单中查找 Serial 按钮，然后单击

在Linux上

设置权限

在Linux上，如果看到错误当您按下 Serial （串行）按钮，您需要将自己添加到用户组中才能具有连接到串行控制台的权限。

在Ubuntu和Debian上，通过执行以下操作将自己添加到 dialout 组中：

sudo adduser $USER dialout

运行上述命令后，重新启动计算机即可访问该组。在其他Linux发行版上，您需要的组可能不同。有关如何将您自己添加到正确的组的详细信息，请参见Mac和Linux上的高级串行控制台。

使用其他功能吗？

如果您不使用Mu进行编辑，则使用ESP8266或nRF52 CircuitPython，或者由于某些原因您不喜欢该功能内置的串行控制台，您可以将串行控制台作为单独的程序运行。

Windows要求您下载终端程序，请查看此页面以获取更多详细信息

Mac和Linux都内置了一个，尽管可以下载其他选项，请查看此页面以获取更多详细信息

与串行控制台交互

成功连接到串行控制台后，就该开始使用它了。

您编写的代码较早版本没有输出到串行控制台。因此，我们将对其进行编辑以创建一些输出。

在编辑器中打开您的code.py文件，并包含一个print语句。您可以打印任何喜欢的东西！只需将您的词组放在括号内的引号之间即可。例如：

下载：文件

复制代码

import board

import digitalio

import time

led = digitalio.DigitalInOut（board.D13）

led.direction = digitalio.Direction.OUTPUT

while True：

print（“Hello， CircuitPython！”）

led.value = True

time.sleep（1）

led.value = False

time.sleep（1） import board

import digitalio

import time

led = digitalio.DigitalInOut（board.D13）

led.direction = digitalio.Direction.OUTPUT

while True：

print（“Hello， CircuitPython！”）

led.value = True

time.sleep（1）

led.value = False

time.sleep（1）

保存文件。

现在，让我们看一下与串行控制台连接的窗口。

优秀！我们的控制台上会显示我们的打印声明！尝试将打印的文本更改为其他内容。

将串行控制台窗口保留在可以看到的位置。保存文件。您将看到板重启时串行控制台显示的内容。然后，您将看到新的更改！

Traceback （most recent call last）：告诉您董事会在保存文件之前所做的最后一件事。这是正常现象，每次主板复位时都会发生。这对于故障排除非常方便。让我们介绍一个错误，以便我们可以看到它的用法。

从e行的True末尾删除led.value = True，使其显示为led.value = Tru

保存文件。您会注意到您的红色LED指示灯将停止闪烁，并且可能有彩色的状态LED指示灯向您闪烁。这是因为代码不再正确，也无法正常运行。我们需要修复它！

通常，当您遇到错误时，这并不是因为您故意引入它们。您可能有200行代码，并且不知道错误可能隐藏在哪里。这是串行控制台可以提供帮助的地方。让我们看一下！

Traceback （most recent call last）：告诉您它能够运行的最后一件事是代码中的第10行。下一行是您的错误：NameError： name ‘Tru’ is not defined。该错误可能对您没有多大影响，但是结合知道问题出在第10行之后，它为您提供了一个绝佳的起点！

返回您的代码，然后看一下第10行显然，您已经知道问题所在了。但是，如果您没有这样做，则希望查看第10行，看看是否可以解决。如果仍然不确定，请尝试使用该错误来获取帮助。在这种情况下，您知道要查找什么。您拼写错了。修正错字并保存文件。

解决错误的好工作！您的串行控制台正在流式传输，并且红色LED再次闪烁。

串行控制台将显示您的代码生成的所有输出。某些传感器（例如湿度传感器或热敏电阻）会接收数据，您可以使用打印语句来显示该信息。您也可以使用打印语句进行故障排除。如果您的代码无法正常工作，并且想知道失败的地方，则可以将打印语句放在各个位置，以查看停止打印的地方。

串行控制台有很多用途，这是一个了不起的成就用于学习和编程的整体工具！

REPL

串行连接的另一个功能是 R ead- E valuate - P rint- L oop或REPL。 REPL允许您输入单独的代码行并使它们立即运行。如果您遇到某个特定程序的麻烦而又不知道原因，那将非常方便。它是交互式的，因此非常适合测试新想法。

要使用REPL，您首先需要连接到串行控制台。建立连接后，您需要按 Ctrl + C 。

如果正在运行代码，它将停止并且您会看到Press any key to enter the REPL. Use CTRL-D to reload.请按照这些说明操作，然后按键盘上的任意键。

Traceback （most recent call last）：告诉您在按Ctrl + C并中断之前，董事会正在做的最后一件事。 KeyboardInterrupt是按Ctrl + C组合键。此信息在进行故障排除时会很方便，但是现在不用担心。只需注意这是预期的行为。

如果没有代码在运行，则按Ctrl + C后将立即输入REPL。由于没有代码在运行，因此在中断之前您的电路板没有任何信息。

不管哪种方式，一旦您按下一个键，您都会看到一个》》》提示符，欢迎您使用REPL！

如果无法进入》》》提示符，请尝试再按Ctrl + C几次。

从REPL获得的第一件事就是有关您的木板的信息。

此行告诉您正在使用的CircuitPython的版本以及发布的时间。接下来，它为您提供了所使用的板的类型以及该板使用的微控制器的类型。视您使用的版本而定，每个部分对于您的电路板可能会有所不同。

其后是CircuitPython提示符。

在此提示符下，您可以运行各种命令和代码。我们要做的第一件事是运行help（）。这将告诉我们从哪里开始探索REPL。要在REPL中运行代码，请在REPL提示符旁边键入它。

在REPL中的提示符旁边键入help（）。

然后按Enter。然后，您应该会看到一条消息。

消息的第一部分是对您正在使用的CircuitPython版本的另一个引用。其次，是CircuitPython相关项目指南的URL。那。..等等这是什么？ To list built-in modules， please do `help（“modules”）`。还记得您在创建代码时学到的库吗？这就是这里所说的！这是一个理想的起点。让我们看一下！

在提示旁边的REPL中键入help（“modules”），然后按Enter。

这是CircuitPython内置的所有核心库的列表。我们讨论了电路板如何包含您可以在代码中使用的电路板上的所有引脚。在REPL中，您可以看到该列表！

在REPL中键入import board，然后按Enter。它将转到新的提示。看起来好像什么都没发生，但事实并非如此！如果您还记得的话，import语句只是告诉代码期望对该模块执行某些操作。在这种情况下，它告诉REPL您打算对该模块进行操作。

下一步，在REPL中键入dir（board）并按Enter。

这是主板上所有可用引脚的列表供您在代码中使用。每个板的列表将根据可用的引脚数而略有不同。您看到D13吗？这就是您用来使红色LED闪烁的引脚！

REPL也可以用于运行代码。请注意，您输入到REPL中的任何代码都不会保存。如果要测试要保留的新内容，请确保也将其保存在计算机上！

每种编程语言中的每个程序员都以一段代码开头， “你好，世界。”我们要和别的东西打招呼。键入REPL：

print（“Hello， CircuitPython！”）

然后按Enter。

这就是在REPL中运行代码的全部！干得好！

您可以编写单行运行的代码。您也可以将整个程序写入REPL以对其进行测试。正如我们所说，请记住，键入REPL不会保存任何内容。

REPL可以为您做很多事情。如果您想看看是否有几行新的代码行得通，这对于测试新想法非常有用。通过一次输入一行代码并找出失败的地方来对代码进行故障排除，这非常了不起。它可以让您查看可用的库并浏览这些库。

尝试在REPL中输入更多内容以查看会发生什么！

返回串行控制台

当您准备离开REPL并返回串行控制台时，只需按 Ctrl + D 。这将重新加载您的电路板并重新进入串行控制台。在输入REPL之前，您将重新启动已运行的程序。在控制台窗口中，您将看到正在运行的程序的任何输出。而且，如果您的程序影响了板上的任何视觉效果，您也会看到它再次启动。

您可以随时返回REPL！

CircuitPython硬件

现在是时候根据您所学的知识做点大事了！每块CircuitPython板都非常适合项目。但是，每个人在不同领域都表现出色。我们将为您提供有关每块板的一些详细信息，并突出显示使用每块板的学习指南。您可以尝试这些方法或为自己的项目获取想法！

小饰品M0

Adafruit Trinket M0是我们随身携带的最小的CircuitPython开发板。但是，不要让那个愚弄你！这是一块功能强大的小板。我们希望设计一种微控制器板，该板足够小以适合任何项目，并且成本低廉，可以毫不犹豫地使用。计划测试概念验证并需要CircuitPython开发板投入使用？还没准备好拆卸您辛苦设计的项目以提取上次使用的电路板吗？小饰品M0已覆盖。它是目前可用的最低价的CircuitPython开发板，但可以轻松地与更大的开发板保持一致！

Trinket M0随CircuitPython一起提供，并且板上已包含演示代码。您可以打开和编辑CIRCUITPY驱动器上找到的main.py文件以开始使用，也可以创建自己的文件！ Trinket M0指南为您提供了有关板子需要了解的所有信息。请查看CircuitPython部分，以找到大量示例示例。

您可以使用Trinket M0来制作Chilled Drinkibot，该设备使用Trinket来控制饮料的热电冷却。或构建一个怪异的万圣节项目，将您的糖果桶变成尖叫的大锅！

Gemma M0

Adafruit Gemma M0是一个很小的CircuitPython板，具有足够的内置功能来构建许多简单的项目。它被设计用于您的可穿戴项目，外部有大孔用于缝制（而且它们对鳄鱼夹也很友好！）。 Gemma M0将为您的可穿戴设备充电，并且比以往更易于使用。电路板上内置电容触摸板，一个开-关开关和一个RGB DotStar LED，因此您无需添加任何东西就可以做很多事情。添加导电线和LED，您将立即拥有眨眼的可穿戴设备！

像Trinket一样，Gemma M0随CircuitPython一起提供，并且板上已经有演示代码。您可以打开和编辑CIRCUITPY驱动器上的main.py文件，也可以创建自己的文件！ Gemma M0指南向您显示了有关板子的所有信息，并提供了很多CircuitPython示例供您试用。

使用Gemma M0创建一对带有NeoPixel环上有趣光图案的Clockwork护目镜。或搭配此3D打印的Sheikah吊坠为您的下一个服装添加一点光！

Circuit Playground Express

Adafruit Circuit Playground Express是迈向完美介绍电子学和编程的下一步。它挤满了传感器，LED，按钮和开关，而且上手起来超级容易！该板超级通用。无论您是电子和编程的新手，还是经验丰富的老手，Circuit Playground Express都是一款很棒的主板。电路板内置了如此多的元件，您无需购买任何其他零件，即可了解不同类型的电子产品的工作原理并对其进行编程。您所需要的只是USB电缆和开发板！但是，这仅仅是开始。电路板外部的许多焊盘都有多种功能，可让您将其他东西连接到电路板上。例如，您可以连接伺服或电位器。可能性无穷无尽！

Circuit Playground Express指南包含有关棋盘所有出色功能的大量信息。该指南的CircuitPython部分提供了使用CircuitPython和开发板的内置功能的大量示例列表。还有一个叫做Python Playground的小节，有更多的演示和一个Drum Machine项目供您试用。

您可以使用Lime Key上的触摸板将Circuit Playground Express变成电容式按键音钢琴。董事会。使用内置的加速度计，可以在您的木板上制作带有灯光和外来声音的UFO飞碟，以及房屋周围或3D打印飞碟上的一些额外物品！

羽毛M0 Express

Adafruit Feather M0 Express是第一个专门为CircuitPython设计的Feather。它是Adafruit Feather开发板产品线的一部分，该开发板可独立工作或堆叠工作，并由USB或锂离子电池供电，因此可用于固定项目和移动项目。 Feather M0 Express带有两个用于无焊面包板的接头，或者您可以将电线直接焊接到板上的引脚上。这允许您在处理项目时进行原型制作，并在准备就绪时进行永久安装。 Feather M0 Express令人惊叹的一件事是大量的板块，称为Featherwings，其设计恰好适合Feather。

羽毛M0 Express出厂时已安装CircuitPython，并已安装UF2引导程序，并准备在您收到电路板时安装CircuitPython。创建您的第一个程序，将其保存到板上，然后就可以使用！ Feather M0 Express指南包含有关您的开发板的所有详细信息，并提供了一个CircuitPython部分以帮助您入门。

Feather M0 Express可用于为各种项目提供动力。使用3D打印的零件和DotStar条带构建CircuitPython Painter POV LED魔杖。用NeoPixels创建一个刻有边缘照明的LED丙烯酸标牌。 Featherwings提供了一些指南，这些指南解释了如何将它们与CircuitPython一起使用，例如OLED Display和Adalogger Featherwing。

Metro M0 Express

Metro M0 Express是第一款设计用于CircuitPython的Metro板。这不是初学者委员会。如果您只是入门，我们建议您使用以前的主板之一。它具有与Feather M0 Express相同的许多功能，以及一些特定于开发的功能（例如内置的SWD端口！）。 Metro M0 Express旨在与Arduino尺寸一起使用，因此，如果您已经有了Arduino扩展板，那么该板将非常适合您。已经有一些屏蔽的CircuitPython库。它有25个GPIO引脚（是所有这些主板中的大多数！），因此如果您正在寻找很多选择，那就非常好。

Metro M0 Express出厂时已安装CircuitPython且已安装UF2引导程序，并且准备好在您收到电路板时安装CircuitPython。创建您的第一个程序，将其保存到开发板中，一切顺利！ Metro M0 Express指南为您提供了有关板卡的所有详细信息，并且CircuitPython部分可帮助您入门。

所有带有CircuitPython库的传感器和分线板将与运行CircuitPython的Metro M0 Express一起使用。找到适合您的传感器的指南，然后按照指南查找如何进行接线。有很多选项。

下一步是什么？

现在，您准备跳入更多的学习指南，或者开始一个全新的项目。干得好，祝你好运！

CircuitPython库

在我们继续开发CircuitPython并创建新版本时，我们将停止支持较旧的版本。访问https://circuitpython.org/downloads为您的电路板下载最新版本的CircuitPython。您必须下载与您的CircuitPython版本匹配的CircuitPython库捆绑包。请更新CircuitPython，然后访问https://circuitpython.org/libraries下载最新的库包。

您运行的每个CircuitPython程序都需要很多工作的信息。 CircuitPython使用起来如此简单的原因是，大多数信息都存储在其他文件中并在后台运行。这些文件称为库。其中一些内置在CircuitPython中。其他的则存储在您的 CIRCUITPY 驱动器上的一个名为 lib 的文件夹中。使CircuitPython如此出色的部分原因在于它能够独立于固件本身存储代码。将代码与固件分开存储，可以更轻松地更新您编写的代码和所依赖的库。

您的开发板可能已经附带了一个 lib 文件夹，该文件夹位于基础中驱动器的目录。如果没有，只需自己创建文件夹。首次安装CircuitPython时，将为您创建一个空的 lib 目录。

CircuitPython库的工作方式与常规Python模块相同，因此Python文档为它们的工作方式提供了很好的参考。用Python术语，我们可以将库文件放置在 lib 目录中，因为默认情况下它是Python路径的一部分。

这种单独的库方法的缺点是它们是而不是内置的。要使用它们，必须先将它们复制到 CIRCUITPY 驱动器，然后才能使用它们。幸运的是，我们提供了一个完整的库捆绑包。

我们的捆绑包和发行版还具有库扩展名，带有 .mpy 。这些文件在驱动器上占用的空间更少，并且在加载时具有较小的内存占用。

安装CircuitPython库捆绑包

我们正在不断更新和改进我们的库，因此（目前）我们不这样做随我们的CircuitPython板一起提供完整的库包。相反，您可以在电路板指南中找到依赖外部库的示例代码。这些库中的某些库可以从Adafruit处获得，有些库库由社区成员编写！

无论哪种方式，当您开始探索CircuitPython时，您都想知道如何在库中使用库。

您可以通过单击下面的按钮来获取最新版本的Adafruit CircuitPython捆绑包。

注意：将捆绑包版本与您所使用的CircuitPython版本进行匹配正在运行-用于运行任何版本的CircuitPython 3的3.x库，用于运行任何版本的CircuitPython 4的4.x库，等等。如果将库与主要CircuitPython版本混合使用，则由于在运行期间库接口可能发生变化，很可能会出错主要版本更改。

单击以获取最新的Adafruit CircuitPython库捆绑软件版本

如果需要其他版本，还可以访问捆绑软件发行页面，该页面将可以让您确切选择要查找的版本以及有关更改的信息。

无论哪种方式，下载与CircuitPython固件版本匹配的版本。如果您不知道该版本，请查看CircuitPython REPL中的初始提示，其中会报告该版本。例如，如果您正在运行v4.0.1，请下载4.x库捆绑包。还有一个 py 软件包，其中包含未压缩的python文件，除非您在库上进行高级工作，否则您可能不想要。

下载zip后，解压缩其内容。这通常是通过双击拉链来完成的。在Mac OSX上，它将文件放在与zip相同的目录中。

打开包文件夹。在内部，您将找到两个信息文件和两个文件夹。一个文件夹是lib捆绑包，另一个文件夹是示例捆绑包。

现在打开lib文件夹。当您打开文件夹时，您会看到大量的 mpy 文件和文件夹

示例文件

每个库中的所有示例文件现在都包含在捆绑软件以及仅示例捆绑软件中。包含这些内容主要有两个原因：

允许快速测试设备。

提供示例代码库，可以轻松地将其用于个性化目的。

将库复制到板上

首先，您要创建 CIRCUITPY 驱动器上的 lib 文件夹。打开驱动器，右键单击，选择创建新文件夹的选项，并将其命名为 lib 。然后，打开从下载的zip提取的 lib 文件夹。在内部，您会找到许多文件夹和 .mpy 文件。找到您要使用的库，然后将其复制到 CIRCUITPY 上的lib文件夹中。

这也适用于示例文件。它们仅作为原始的 .py 文件提供，因此如果遇到以下问题，可能需要使用 mpy-cross 实用程序将它们转换为 .mpy 。 MemoryErrors。 《 CircuitPython Essentials指南》中对此进行了讨论。用法与上文“快速公告板”部分中所述的用法相同。注意：如果不将示例放在单独的文件夹中，则应从import语句中删除示例。

示例：ImportError由于缺少库

如果选择加载库根据需要，您可以编写代码尝试使用尚未加载的库。我们将演示当您尝试利用板上未加载的库时发生的情况，并介绍解决此问题所需的步骤。

此演示只会返回错误如果您没有将所需的库加载到 CIRCUITPY 驱动器上的 lib 文件夹中。

让我们使用修改后的版本示例。

下载：文件

复制代码

import board

import time

import simpleio

led = simpleio.DigitalOut（board.D13）

while True：

led.value = True

time.sleep（0.5）

led.value = False

time.sleep（0.5） import board

import time

import simpleio

led = simpleio.DigitalOut（board.D13）

while True：

led.value = True

time.sleep（0.5）

led.value = False

time.sleep（0.5）

保存此文件。董事会没有任何反应。让我们检查串行控制台以查看发生了什么。

我们有一个ImportError。它说有no module named ‘simpleio’。那就是我们刚刚包含在我们代码中的代码！

单击上面的链接下载正确的捆绑包。从下载的捆绑文件中提取lib文件夹。向下滚动以找到 simpleio.mpy 。这是我们要查找的库文件！请按照上述步骤加载单个库文件。

LED再次开始闪烁！让我们检查串行控制台。

没有错误！优秀。您已经成功解决了ImportError！

如果以后再遇到此错误，请按照上述步骤操作，然后选择与您所缺少的库匹配的库。

非Express板上的库安装

如果您有Trinket M0或Gemma M0，则需要按照上面示例中的相同步骤安装所需的库。您不必总是等待ImportError，因为您可能知道您在代码中添加了哪个库。只需打开下载的 lib 文件夹，找到所需的库，然后将其拖到 CIRCUITPY 驱动器上的 lib 文件夹中即可。

即使仅根据需要加载库，也可能最终在Trinket M0或Gemma M0上空间不足。您可以使用许多步骤来尝试解决此问题。您可以在学习板指南的“疑难解答”页面中找到它们。

更新CircuitPython库/示例

库和示例会不时更新，因此，重要的是更新 CIRCUITPY 驱动器。

要更新单个库或示例，请遵循上述相同步骤。将库文件拖到lib文件夹时，它将询问您是否要替换它。说是就是这样！

每次对库进行更新时，都会发布一个新的库捆绑包。更新内容包括错误修复和新功能。经常检查一次很重要，以查看您使用的库是否已更新。

欢迎来到社区！

CircuitPython是一种编程语言，入门非常简单，非常适合学习。它可以在微控制器上运行，并且可以直接使用。您可以将其插入并开始使用任何文本编辑器。最好的部分？ CircuitPython带有一个很棒的支持社区。

每个人都欢迎！ CircuitPython是开源的。这意味着任何人都可以使用，编辑，复制和改进它。这也意味着CircuitPython变得更好，因为您参与其中。不管这是您的第一个微控制器板还是计算机工程师，提供Adafruit CircuitPython社区都是重要的。我们将重点介绍您可以成为其中一部分的多种方式！

Adafruit Discord

Adafruit Discord服务器是最好的起点。 Discord是社区聚集在一起进行志愿活动并提供各种实时支持的地方。从一般讨论到详细的问题解决，以及介于两者之间的一切，Discord是一个数字制造商空间，来自世界各地的制造商。

有很多不同的渠道，因此您可以选择最适合自己的需求。每个通道在Discord上都显示为“ #channelname”。 #projecthelp频道可为您当前的项目提供帮助，或为下一个项目提供帮助。 #showandtell频道可用于炫耀您的最新作品。不要害怕在任何频道中提问！如果您不确定，＃general是一个不错的起点。如果另一个渠道更有可能为您提供更好的答案，那么有人会指导您。

CircuitPython渠道是您处理CircuitPython问题的地方。 #circuitpython适用于新用户和开发人员，请随时提出问题或发表评论！任何经验水平的人士都可以参加。我们很想听听您怎么说！

对社区做出贡献的最简单方法是在Discord上为他人提供帮助。支持他人并不总是意味着回答问题。一起庆祝成功！庆祝你的错误！有时，只要听到别人经过类似的斗争就足以使制造商前进。

Adafruit Discord是您可以带给孙女的24x7x365黑客空间。

访问https://adafru.it/discord以注册Discord。我们期待与您见面！

Adafruit论坛

Adafruit论坛是理想的支持场所。 Adafruit有出色的付费支持人员，可以回答您可能遇到的任何问题。无论您的硬件给您带来了问题还是代码似乎都无法正常工作，论坛总是在那里供您提问。您需要一个Adafruit帐户才能发布到论坛。您可以使用从Adafruit订购的同一帐户。

尽管Discord可能会比论坛提供更快的响应，但论坛是更可靠的信息来源。如果您确定要得到Adafruit支持的答案，那么论坛是最好的选择。

论坛类别涵盖了所有主题，包括Adafruit的所有主题。在“受支持的产品和项目”下的Adafruit CircuitPython和MicroPython类别是发布CircuitPython问题的最佳位置。

请确保包括到达目的地的步骤。如果涉及布线，请张贴图片！如果您的代码给您带来麻烦，请将您的代码包括在您的帖子中！这些是确保有足够的信息来帮助您解决问题的好方法。

您可能会认为您才刚刚开始，但您肯定知道别人没有的东西。论坛的好处是您也可以帮助其他人！欢迎并鼓励大家对任何已发布的问题提供建设性的反馈。这是为社区做出贡献并分享您的知识的绝妙方法！

Adafruit Github

无论您是刚刚起步还是想要做出贡献的终生程序员，都有许多方法可以使每个人都参与构建CircuitPython。 GitHub是为CircuitPython本身做出贡献的最佳途径。如果您需要一个帐户，请访问https://github.com/并注册。

如果您是GitHub的新手或一般编程人员，那么您将有很多机会。转到GitHub上的adafruit/circuitpython，单击“问题”，您将找到一个列表，其中包含标有“良好的第一期”的问题。这些都是我们认为具有任何经验水平的人都可以帮助的事情。这些问题包括诸如更新文档，提供反馈和修复简单错误之类的选项。

已经经验丰富，正在寻找挑战？查看其余的问题列表，您会发现很多贡献的方法。您将找到从新驱动程序请求到核心模块更新的所有内容。任何级别的每个人都有很多机会！

使用CircuitPython时，您可能会发现问题。如果发现错误，那就太好了！我们喜欢虫子！将详细的问题发布到GitHub是有助于改进CircuitPython的宝贵方法。确保包括复制问题的步骤以及您认为相关的任何其他信息。越详细，越好！

测试新软件非常容易，而且非常有用。只需将最新版本的CircuitPython或库加载到CircuitPython硬件上，然后使用它。通过将新问题发布到GitHub，让我们知道您发现的任何问题。在当前和Beta版本中进行软件测试是贡献CircuitPython的非常重要的一部分。我们自己不可能找到所有问题！我们需要您的帮助以使CircuitPython变得更好。

在GitHub上，您可以提交功能请求，提供反馈，报告问题等等。如有疑问，请记住，Discord和论坛都在这里寻求帮助！

ReadTheDocs

ReadTheDocs是深入了解CircuitPython的绝佳资源。您可以在这里找到API文档和有关核心模块的详细信息。还有一个设计指南，其中包含有关CircuitPython的贡献指南。

RTD使您可以深入了解CircuitPython。有关每个核心模块的详细信息。每个模块都列出了可用的库。每个模块库页面列出了可用的参数以及每个参数的说明。在许多情况下，您会找到快速的代码示例，以帮助您了解模块和参数的工作方式，但是其中没有像《学习指南》这样的详细说明。如果您需要帮助来了解正在编写的任何CircuitPython代码的幕后情况，ReadTheDocs可以为您提供帮助！

Windows上的高级串行控制台

Windows 7驱动程序

如果您使用的是Windows 7，请使用下面的链接下载驱动程序包。您无需在Mac，Linux或Windows 10上安装驱动程序。

下载Windows 7驱动程序

什么是COM？

首先，您需要确定您的主板正在使用哪个串行端口。当您将开发板插入计算机上的USB时，它会连接到串行端口。该端口就像一扇门，您的主板可以通过它使用USB与计算机进行通信。

我们将使用Windows设备管理器来确定主板正在使用哪个端口。确定主板正在使用哪个端口的最简单方法是首先不插入检查主板。打开设备管理器。单击端口（COM和LPT）。您应该在该列表中已经找到带有（COM＃）的内容，其中＃是数字。

现在将板子插入。设备管理器列表将刷新，并且新项目将出现在端口（COM和LPT）下。您会在列表中此项目之后找到其他（COM＃）。

有时，该项目指的是木板的名称。如上图所示，其他时候它可能被称为USB串行设备。无论哪种方式，名称后都会有一个新的（COM＃）。这是您的电路板正在使用的端口。

安装腻子

如果使用Windows，则需要下载终端程序。我们将使用PuTTY。

首先要做的是下载最新版本的PuTTY。您将要下载Windows安装程序文件。您最有可能需要64位版本。下载文件并在计算机上安装程序。如果遇到问题，可以尝试下载32位版本。但是，该64位版本适用于大多数PC。

现在您需要打开PuTTY。

在连接类型下： 串行旁边的按钮。

在串行行下的框中，输入您发现主板正在使用的串行端口。

在速度下的框中，输入115200。这称为波特率，它是通过串行连接发送数据的每秒速度（以比特为单位）。对于带有内置USB的板卡来说，没什么大不了的，但是对于ESP8266和其他带有单独芯片的板卡，板卡所需的速度为每秒115200位。因此，您最好也使用115200！

如果要保存这些设置以供以后使用，请使用加载，保存或删除存储的会话下的选项。在保存的会话下的框中输入名称，然后单击右侧的保存按钮。

输入设置后，就可以连接到串行控制台了。点击窗口底部的“打开”。一个新窗口将打开。

如果没有代码在运行，则该窗口将为空白或与上面的窗口类似。现在您可以查看代码的结果。

干得好！您已连接到串行控制台！

在Mac和Linux上的高级串行控制台

在Mac和Linux上连接到串行控制台的过程基本上相同。两种操作系统都不需要安装驱动程序。在MacOSX上，已安装终端。在Linux上，有多种，例如KDE上的gnome-terminal（称为Terminal）或Konsole。

端口是什么？

首先，您要确定主板使用的是哪个串行端口。当您将开发板插入计算机上的USB时，它会连接到串行端口。该端口就像一扇门，您的主板可以通过该门使用USB与计算机进行通信。

我们将使用终端来确定主板使用的端口。确定主板正在使用哪个端口的最简单方法是先检查是否未插入主板。在Mac上，打开“终端”并键入以下内容：

ls /dev/tty.*

每个串行连接都显示在/dev/目录中。它的名称以tty.开头。命令ls向您显示目录中的项目列表。您可以将*用作通配符，以搜索以相同字母开头但以其他字母结尾的文件。在这种情况下，我们要求查看/dev/中所有以tty.开头并以任何结尾结束的列表。这将向我们显示当前的串行连接。

对于Linux，过程相同，但是名称略有不同。如果您使用的是Linux，则将输入：

ls /dev/ttyACM*

与Linux的概念相同。我们要求查看/dev/文件夹中的列表，这些列表以ttyACM开头，以任何结尾。这将显示当前的串行连接。在下面的示例中，错误表明没有以ttyACM开头的当前串行连接。

现在，插入板子。在Mac上，键入：

ls /dev/tty.*

这将向您显示当前的串行连接，现在将包括您的主板。

使用Mac，出现了一个新列表，名为/dev/tty.usbmodem141441。此清单的tty.usbmodem141441部分是示例板所使用的名称。

使用Linux，键入：

ls /dev/ttyACM*

这将向您显示当前的串行连接，现在包括您的面板。

使用Linux，出现了一个新列表，名为/dev/ttyACM0。此清单的ttyACM0部分是示例板所使用的名称。您的名字将被称为类似。

与屏幕连接

现在，您知道板子正在使用的名称，就可以连接到串行控制台了。我们将使用名为screen的命令。 screen命令包含在MacOS中。 Linux用户可能需要使用其软件包管理器进行安装。要连接到串行控制台，请使用终端。键入以下命令，将board_name替换为您的开发板正在使用的名称：

screen /dev/tty.board_name 115200

第一部分这是使用screen命令建立的。第二部分告诉屏幕您要使用的板的名称。第三部分告诉屏幕用于串行连接的波特率。波特率是通过串行连接发送数据的速度，以每秒比特数为单位。在这种情况下，开发板所需的速度为每秒115200位。

使用示例板名的MacOS屏幕命令

按Enter键运行命令。它将在同一窗口中打开。如果没有代码在运行，则该窗口将为空白。否则，您将看到代码的输出。

干得好！您已连接到串行控制台！

Linux上的权限

如果您尝试运行screen却无法正常运行，则可能是权限问题。 Linux跟踪用户和组以及允许他们执行和不执行的操作，例如访问与串行连接关联的硬件以运行screen。因此，如果您看到以下内容：

，那么您可能需要授予自己访问权限。通常有两种方法可以执行此操作。首先是使用screen命令运行sudo，这会暂时为您提供提升的特权。

输入密码后，您应该位于：

第二种方法是将自己添加到组中与硬件相关联。要确定该组是什么，请使用命令ls -l，如下所示。群组名称以红色圈出。

然后使用命令adduser将您自己添加到该群组中。您需要提升的特权才能执行此操作，因此您需要使用sudo。在下面的示例中，组为 adm ，用户为 ackbar 。

将自己添加到论坛后，您需要注销并重新登录，或者在某些情况下，请重新启动计算机。再次登录后，请使用命令groups确认您已添加到该组。如果您仍不在该组中，请重新启动并再次检查。

现在您应该可以运行screen而不使用sudo。

而您位于：

以上示例使用screen，但是如果您愿意，也可以使用其他程序，例如putty或picocom。

PyCharm和CircuitPython

此过程无效。该插件从未设计过与CircuitPython一起使用。这里描述的过程是一种变通办法，功能有限。如果您想在Pycharm中使用REPL，请在终端和屏幕中使用内置功能。和错误突出显示。它在社区版中免费提供。

最近，他们添加了一个MicroPython插件，该插件可从编辑器内部使用REPL。官方不支持CircuitPython，但是我们有一些步骤使其能够正常工作！

在您的计算机上下载并安装PyCharm。然后，插入您的电路板并执行以下步骤！

创建新项目或打开现有项目。

打开PyCharm偏好设置/设置。点击插件，然后搜索“ micropython”。单击在存储库中搜索。

此过程无效。该插件从未设计过与CircuitPython一起使用。这里描述的过程是一种变通办法，功能有限。如果要在Pycharm中使用REPL，请在终端和屏幕中使用内置的。

点击安装。

安装完成后，单击重新启动PyCharm 。

重新启动后，打开“首选项/设置”。单击语言和框架，然后选择 MicroPython 。

此过程无效。该插件从未设计过与CircuitPython一起使用。这里描述的过程是一种变通办法，功能有限。如果要在Pycharm中使用REPL，请在终端和屏幕中使用内置的。

从列表中选择项目目录。

从“设备名称”列表中选择 ESP8266 。

现在，无论使用哪种板，您都将使用此选项。

您需要手动添加设备路径。这是您的串行连接的路径。输入后，单击确定。

如果需要帮助来查找设备的串行连接，请参阅Windows上的“高级串行控制台”。和Mac和Linux上的高级串行控制台。

i》 此过程无效。该插件从未设计过与CircuitPython一起使用。这里描述的过程是一种变通办法，功能有限。如果要在Pycharm中使用REPL，请在终端和屏幕中使用内置的。

现在，从您选择的项目目录中打开任何Python文件。

一条消息可能会弹出，提示“找不到ESP8266支持所需的软件包”，然后是软件包列表。单击此消息上的安装要求以安装所需的软件包。

现在，您可以单击工具菜单，您应该会找到一个 MicroPython 菜单。突出显示这一点，您将找到 MicroPython REPL 。

REPL将在PyCharm窗口的底部打开。现在您可以开始编码了！

如果要将内置REPL与其他电路板一起使用，则需要进入并将Device Path更改为与您要使用的电路板匹配的路径。

要更改设备路径，请按照上述步骤从手动添加设备路径开始。

PyCharm REPL不能同时在多个板上使用。在多个项目上执行上述步骤并不能始终如一地打开多个REPL连接。

“从MicroPython设备中删除所有文件”和“ Flash项目”功能不起作用，但可能会损坏您的电路板。不要尝试使用这些功能。请记住，CircuitPython不受官方支持，并且上述步骤是一种解决方法。

此过程无效。该插件从未设计过与CircuitPython一起使用。这里描述的过程是一种变通办法，功能有限。如果要在Pycharm中使用REPL，请使用内置的端子和屏幕。

用于ESP8266的CircuitPython

我们不再在ESP8266上支持CircuitPython。此页面仅用于历史目的。无法保证说明会继续有效。

为什么要放弃对ESP8266的支持？

ESP8266上的CircuitPython对于用户来说并不是一个很好的体验。由于它没有本地USB，因此很难将文件发送到设备，并且您很快就会用完RAM（添加网络堆栈后，内存会比您想象的要少）。我们决定仅将ESP用作协处理器。特别是ESP32，因为它具有良好的TLS/SSL支持，即使是最基本的交互，现在也必不可少。

如果您想使用ESP8266，请继续使用3.x版本，不支持。您还可以查看仍受支持的MicroPython for ESP8266！

如果您想添加WiFi支持，请查看有关ESP32/ESP8266作为协处理器的指南。

关于CircuitPython的ESP8266（3.x）

我们有两个CircuitPython的“应变”，主要的是具有本地USB连接的基于ATSAMD21/51的板。原生USB意味着该板可以显示为名为CIRCUITPY的磁盘驱动器并在其中保存所有文件。

还有ESP8266和nRF52832等板的CircuitPython，这些芯片确实不错分别内置WiFi和Bluetooth。但是它们没有本地USB！，这意味着该芯片无法作为磁盘驱动器出现。您仍然可以将它们与CircuitPython一起使用，但是难度要大得多，因此我们不建议初学者使用它们。这是关于将非本机芯片用于CircuitPython的一些知识：

仅 个获得REPL连接！没有HID键盘/鼠标或其他USB接口

没有用于拖放文件移动的磁盘驱动器，必须通过 ampy 这样的特殊工具来移动文件通过REPL为您输入文件

加载CircuitPython需要命令行工具

在ESP8266上安装CircuitPython

要将CircuitPython与ESP8266一起使用，您需要先使用最新固件对其进行刷新。

下载esptool

首先安装esptool.py可以在ESP8266上烧写固件的软件。安装此工具的最简单方法是使用Python的pip包管理器。如果尚未安装，则需要安装Python 2.7（在Windows上安装时，请确保选中将Python放入系统路径的框），然后在终端中运行以下命令：pip install esptool

在Mac OSX和Linux上的注意事项，您可能需要使用sudo以root身份运行命令，例如：sudo pip install esptool

如果收到的错误是esptool.py仅支持Python 2.x，请尝试使用 pip2 命令而不是pip再次运行（可能您的系统正在使用Python 3，并且pip命令对要使用的版本感到困惑）。

下载最新的CircuitPython固件

下一步下载最新的CircuitPython ESP8266固件文件：

下载最新的ESP8266 Huzzah固件（v3.1.2）

让ESP8266准备好进行引导加载

现在您需要将ESP8266设置为固件刷新模式。每个ESP8266板略有不同：

对于原始ESP8266模块，您需要将GPIO0和RESET引脚的按钮接地。按住GPIO0按钮（或将线接地），同时仍将GPIO0接地，按住并释放RESET按钮（或从地面连接并释放线），然后释放GPIO0。

对于板中内置了用于GPIO0和RESET的HUZZAHESP8266 Breakout 按钮。按住GPIO0，然后按并释放RESET（同时保持GPIO0），最后释放GPIO0。

对于Feather HUZZAH ESP8266 ，您无需执行任何特殊操作即可进入固件刷新模式。该评估板用于检测何时打开串行端口进行刷新，并自动配置ESP8266模块以接收固件。 请务必先在Windows和Mac OSX上安装SiLabs CP210x驱动程序，以使开发板的串行端口可见！ 在Windows上，您需要普通的VCP驱动程序，而不是“具有串行枚举”驱动程序。

擦除ESP8266

建议在上传固件前先擦除ESP8266开发板的整个闪存。在终端中运行以下命令以执行此擦除：

下载：文件

复制代码

esptool.py --port ESP8266_PORTNAME erase_flash esptool.py --port ESP8266_PORTNAME erase_flash

其中ESP8266_PORTNAME是连接到ESP8266的串行端口的路径或名称。设备的确切名称取决于串行到USB转换器芯片的类型，因此您可能需要查看有无设备连接的串行端口才能找到其名称。

程序ESP8266

现在将ESP8266放回固件刷新模式，然后运行以下命令来加载下载的固件文件：

下载：文件

复制代码

esptool.py --port ESP8266_PORTNAME --baud 115200 write_flash --flash_size=detect 0 firmware.bin esptool.py --port ESP8266_PORTNAME --baud 115200 write_flash --flash_size=detect 0 firmware.bin

再次将ESP8266_PORTNAME设置为连接到ESP8266的串行端口的路径或名称。另外，将 firmware.bin 设置为您要加载的固件文件的名称或路径。

i》

工具完成固件刷新后（在此过程中，您通常会看到ESP8266模块上的蓝灯闪烁），请按ESP8266板上的RESET按钮或断开连接，然后将其重新连接到计算机。应该都准备好开始使用板上的最新CircuitPython固件！

请注意，如果看到“检测不是有效的flash_size参数”错误，则可能是使用了较早版本的esptool。 py要升级到最新版本，请运行以下命令pip install --upgrade esptool

使用Ampy上载库和文件！

ESP8266的最大与众不同之处在于，您需要使用一种特殊的工具来移动文件。阅读本指南，查看ampy。它与MicroPython有关，但CircuitPython几乎相同，因此总体安装和用法相同！

了解如何使用ampy在ESP8266上移动文件

其他需要了解的东西！

REPL的工作方式与您期望的一样希望如此，因此请查看该介绍性页面。

文件存储与CircuitPython在同一芯片中，因此如果进行更新，则可能会丢失文件！保留备份。

库和API也与其他CircuitPython板相同。

请注意，ESP8266没有大量引脚，只有一个模拟输入为0 -1.0V范围。没有可用的UART端口（这是用于REPL的端口！）。

没有模拟输出。

对于SPI和I2C，您可以使用它们！但是您将需要使用bitbangio创建总线对象

卸载CircuitPython

我们的许多开发板都可以与多种编程语言一起使用。例如，Circuit Playground Express可以与MakeCode，Code.org CS Discoveries，CircuitPython和Arduino一起使用。

也许您尝试过CircuitPython并想回到MakeCode或Arduino？没问题

随时可以随时删除/重新安装CircuitPython ！哎呀，您每天都可以改变主意！

备份您的代码

在卸载CircuitPython之前，请不要忘记备份小磁盘驱动器上的代码。这意味着您的 main.py 或 code.py 任何其他文件， lib 文件夹等。删除CircuitPython时，这些文件可能会丢失，因此备份是关键！只需将文件拖到便携式计算机或台式计算机上的文件夹中，就像使用任何USB驱动器一样。

移动到MakeCode

如果您想重新使用MakeCode，这真的很容易。访问makecode.adafruit.com，找到您要上传的程序。单击下载以下载由MakeCode生成的 .uf2 文件。

现在，双击CircuitPython板，直到看到板载LED变绿并且 。.. BOOT 目录出现。

然后找到下载的MakeCode .uf2 文件，并将其拖到 。.. BOOT 驱动器上。

您的MakeCode现在正在运行，并且CircuitPython已删除。向前，您只需单击重置按钮

移至Arduino

如果要将固件更改为Arduino，这也非常简单。

首先插入板子，然后双击重置，直到获得绿色的板上LED为止-就像使用MakeCode

在Arduino IDE中一样，选择匹配的板，例如Circuit Playground Express

选择正确的匹配端口：

创建新简单的Blink草图示例：

下载：文件

复制代码

// the setup function runs once when you press reset or power the board

void setup（） {

// initialize digital pin 13 as an output.

pinMode（13， OUTPUT）;

}

// the loop function runs over and over again forever

void loop（） {

digitalWrite（13， HIGH）; // turn the LED on （HIGH is the voltage level）

delay（1000）; // wait for a second

digitalWrite（13， LOW）; // turn the LED off by making the voltage LOW

delay（1000）; // wait for a second

} // the setup function runs once when you press reset or power the board

void setup（） {

// initialize digital pin 13 as an output.

pinMode（13， OUTPUT）;

}

// the loop function runs over and over again forever

void loop（） {

digitalWrite（13， HIGH）; // turn the LED on （HIGH is the voltage level）

delay（1000）; // wait for a second

digitalWrite（13， LOW）; // turn the LED off by making the voltage LOW

delay（1000）; // wait for a second

}

确保LED仍为绿色，然后单击上传以上传闪烁。成功上传后，串行端口将更改，因此重新选择新的端口！

一旦上传了闪烁，您就不再需要双击进入引导加载程序模式，上传后Arduino将自动重置

非UF2安装

仅当您不安装此页面时才需要安装了UF2引导程序（例如boardBOOT拖放）！此页面适用于非Express Feather M0，Arduino Zero和M0以及其他自定义ATSAMD21开发板。

用Bossac闪烁-用于非Express Feather M0和Arduino Zero

我们较旧的Feather M0板没有UF2不附带，而是附带了一个更简单的名为 bossa 的引导程序。这也是安装在Arduino Zero和其他使用ATSAMDx1或nRF52840的CircuitPython兼容板上的东西。如果CircuitPython安装文件是 .bin 而不是 .uf2

命令行！

使用bossac进行闪烁需要使用计算机的命令行界面。在Windows上，这是 cmd 或 powershell 工具。在Mac和Linux上，使用终端！

下载最新的CircuitPython固件

您要做的第一件事就是下载最新版本的CircuitPython。

截至2019年4月，有两个站点可以下载适当的.bin文件。 Adafruit正在将文件迁移到CircuitPython.org。建议首先通过搜索兼容板找到.bin文件。在该站点上只会列出对适当的引脚定义文件有拉取请求的兼容板，如果开发人员希望看到列出的新CircuitPython板，则开发人员应提交要包含的材料。

单击下面的绿色按钮以搜索您的电路板以找到合适的文件。

从CircuitPython.org查找并下载电路板软件

或者，使用GitHub

目前，CircuitPython开发板文件也位于Adafruit CircuitPython GitHub存储库中，尽管它们将来可能会迁移到专用的CircuitPython存储库。如果对CircuitPython.org有问题，请使用下面的第二个绿色按钮从GitHub下载。

为CircuitPython开发板下载.bin文件

下载后，将 .bin 文件保存到桌面上，您将很快需要它！

如果您运行的是Windows 7，则必须安装驱动程序集（

下载BOSSA

一旦有了固件映像，就需要下载BOSSA工具，该工具可以在SAMD21/51板上加载固件。 Arduino IDE在对这些板进行编程时实际上在内部使用此工具，但是您可以自己使用它来加载自定义固件

请注意，必须使用 1.7。 Bossac的0或更高版本，可为SAMD21和SAMD51板编程BOSSA 1.7.0之前的版本不起作用，因为它不支持SAMD21/51芯片。 还请注意，bossac 1.9.0和更高版本已不兼容地更改了其命令行参数，并且在不受保护的情况下可以擦除您的引导加载程序。（Adafruit板随附受保护的引导加载程序。）请按照以下说明进行操作

要使用bossac（BOSSA的命令行工具）进行刷新，请先从此处下载最新版本。 ming32版本适用于Windows，apple-darwin适用于Mac OSX，而各种linux选项适用于Linux。

bossac适用于.bin文件仅，它不适用于.uf2文件！

测试bossac

打开一个终端，并使用bossac工具导航到该文件夹。然后使用--help选项运行该工具以检查其运行情况：

打开一个终端，并使用bossac工具导航到该文件夹。然后使用带有--help选项的bossac --help

来运行该工具，以检查该工具是否运行。或者，如果您使用的是Linux或Mac OSX，则需要添加 。/以指定从当前目录（例如 。/bossac --help

）运行bossac，确保您看到的是BOSSA版本1.7.0或更高版本！，请参阅以下有关1.9.0及更高版本的警告。如果看到较低的版本，则表示您不小心下载了该工具的较旧版本，并且该工具无法刷新SAMD21芯片。返回并如上所述从该BOSSA GitHub存储库中获取最新版本。

端口Mac OS的选择

如果您使用的是Mac，则需要知道要使用哪个端口。

在同一终端窗口中，运行命令ls /dev/cu.*。记下列出的端口，然后插入板子并再次运行命令。可能会列出该设备，例如/dev/cu.usbmodem14301 。记下下面bossac部分的端口名称。

进入引导加载程序

您必须手动将板“踢”入引导加载程序。双击重置按钮即可。红色的“＃13” LED指示灯应点亮和熄灭。如果您使用的是Arduino Zero，请确保您已连接到本地USB 端口，而不是调试/编程端口。

如果使用的是Arduino，请特别注意来自Arduino.org的M0，您需要将其引导程序替换为Arduino零引导程序，以便它可以与BOSSA一起使用。为此，请在Arduino IDE板管理器中安装Arduino/Genuino Zero板，然后按照以下步骤刻录Arduino Zero引导加载程序（使用板上的编程端口）。加载Arduino Zero Bootloader之后，您应该能够按照以下说明将M0与bossac一起使用。

运行thebossac命令

插入电路板并运行引导加载程序后，您就可以将CircuitPython固件刷新到电路板上了。将固件.bin文件复制到与bossac工具相同的目录中，然后在终端中导航到该位置并运行以下命令之一，具体取决于您拥有的bossac版本。

对于bossac 1.9或更高版本，必须在命令行上使用--offset参数，并且必须对您的电路板具有正确的值。

对于bossac 1.9或更高版本，您必须提供一个--offset参数此参数是在bossac 1.8.0中添加的，默认值为0x2000，但从1.9开始，默认偏移量已更改为0x0000，在大多数情况下这不是您想要的。如果您省略了bossac 1.9或更高版本的参数，则可能会看到来自bossac的“ 验证失败”错误。切记更改-p或--port的选项以匹配Mac上的端口。

将下面的文件名替换为下载的名称 .bin ：这将根据您的主板而有所不同！

使用bossac版本1.7.0、1.8

有没有可用的--offset参数。使用这样的命令行：

bossac -p /dev/cu.usbmodem14301 -e -w -v -R adafruit-circuitpython-boardname-version.bin

例如，

bossac -p /dev/cu.usbmodem14301 -e -w -v -R adafruit-circuitpython-feather_m0_express-3.0.0.bin

使用bossac 1.9或更高版本

对于具有8kB引导程序的M0板，必须指定-offset=0x2000，例如：

bossac -p /dev/cu.usbmodem14301 -e -w -v -R --offset=0x2000 adafruit-circuitpython-feather_m0_express-3.0.0.bin

对于具有16kB引导程序的M4板，必须指定-offset=0x4000，例如：

bossac -p /dev/cu.usbmodem14301 -e -w -v -R --offset=0x4000 adafruit-circuitpython-feather_m4_express-3.0.0.bin

这将e擦除芯片，w写入给定的文件，v验证写入并R设置板。在Linux或MacOS上，您可能需要使用sudo 。/bossac 。..运行此命令，或首先将自己添加到拨号组。

在BOSSA加载固件后，您应该会看到输出类似于以下内容：

重置后，CircuitPython应该正在运行，并且会出现 CIRCUITPY 驱动器。您始终可以通过单击重置按钮来手动重置板，有时需要将其“唤醒”。 Express板可能会警告USB驱动器过早弹出，但请忽略它。没什么重要的事情被写入驱动器！

故障排除

有时，在使用CircuitPython时会遇到问题。这是您可能会遇到的一些问题以及如何解决它们。

继续开发CircuitPython并创建新版本，我们将停止支持旧版本。访问https://circuitpython.org/downloads为您的电路板下载最新版本的CircuitPython。您必须下载与您的CircuitPython版本匹配的CircuitPython库捆绑包。请更新CircuitPython，然后访问https://circuitpython.org/libraries下载最新的库捆绑包。

始终运行最新版本的CircuitPython和库

在继续开发CircuitPython和创建新版本时，我们将不再支持较旧版本发布。 您需要更新到最新的CircuitPython。

您需要下载与您的CircuitPython版本匹配的CircuitPython库捆绑包。 请更新CircuitPython，然后下载最新的软件包。

当我们发布CircuitPython的新版本时，我们将停止提供以前的软件包作为Adafruit CircuitPython库软件包仓库中自动创建的下载文件。 。如果必须继续使用早期版本，则仍可以从CircuitPython存储库上特定版本的CircuitPython中下载mpy-cross的相应版本，并创建自己的兼容.mpy库文件。 但是，最好将CircuitPython和库捆绑包都更新为最新版本。

我必须继续使用CircuitPython 3.x或2.x，在哪里可以找到兼容的库？

我们是不再构建或支持CircuitPython 2.x和3.x库包。我们强烈建议您将CircuitPython更新到最新版本并使用当前版本的库。。但是，如果由于某种原因而无法更新，则可以在此处找到最后一个可用的2.x版本和最后一个可用的3版本。 .x在此处构建。

CPLAYBOOT，TRINKETBOOT ，FEATHERBOOT或GEMMABOOT驱动器不存在 ，您可能拥有其他板子。

只有Adafruit Express板子和Trinket M0和Gemma M0板子才装有UF2引导程序。 Feather M0 Basic，Feather M0 Adalogger和类似的电路板使用常规的Arduino兼容引导加载程序，该引导加载程序不显示boardnameBOOT驱动器。

MakeCode

如果您正在Circuit Playground Express上运行MakeCode程序，只需按一下重置按钮即可显示CPLAYBOOT驱动器。两次按下将不起作用。

Windows 10

您是否误安装了Adafruit Windows Drivers软件包？对于大多数Adafruit板，您不需要在Windows 10上安装此软件包。旧版本（v1.5）可能会干扰您的设备识别。转到设置-》 应用，并卸载所有“ Adafruit”驱动程序。

Windows 7

最新版本的Adafruit Windows驱动程序（2.0.0.0版或更高版本）将解决Windows 7上缺少的boardnameBOOT驱动器问题。要解决此问题，请先卸载旧版本的驱动程序：

拔下所有板子。在卸载或更改程序（控制面板-》程序-》卸载程序）中，卸载所有名为“ Windows Driver Package-Adafruit Industries LLC 。..”的内容。

现在安装新的2.3.0.0（或更高版本）的Adafruit Windows驱动程序包：

安装最新的Windows驱动程序

运行时安装程序，将显示一个可供选择的驱动程序列表。您可以选中和取消选中复选框以选择要安装的驱动程序。

现在应该完成！通过拔下并重新插入电路板进行测试。您应该看到CIRCUITPY驱动器，然后双击重置按钮（单击运行MakeCode的Circuit Playground Express一次），您应该看到相应的boardnameBOOT驱动器。

如果这不适合您，请在Adafruit支持论坛或Adafruit Discord上告诉我们！

访问boardnameBOOT驱动器时Windows资源管理器锁定

在Windows上，我们知道的一些第三方程序可能会引起问题。症状是您尝试访问boardnameBOOT驱动器，而Windows或Windows资源管理器似乎已锁定。已知这些程序会引起麻烦：

AIDA64 ：要修复，请停止该程序。此问题已报告给AIDA64。他们获得了要测试的硬件，并发布了可解决该问题的beta版本。这可能已合并到最新版本中。如果您测试此插件，请在论坛中告诉我们。

硬盘前哨

卡巴斯基反病毒软件：修复后，您可能需要完全禁用卡巴斯基。禁用卡巴斯基的某些方面并不总是能够解决问题。已经向卡巴斯基报告了此问题。

将UF2复制到boardnameBOOT驱动器时，复制已挂起0％

在Windows上，其外部USB驱动器附带的 Western Digit（WD）实用程序干扰将UF2文件复制到boardnameBOOT驱动器。卸载该实用程序以解决问题。

未显示CIRCUITPY驱动器

卡巴斯基反病毒软件会阻止CIRCUITPY驱动器的出现。我们尚未发现可以防止这种情况的设置更改。完全卸载卡巴斯基可以解决此问题。

Norton防病毒软件可能会干扰CIRCUITPY。用户已在Windows 7上报告了此问题。该用户关闭了智能防火墙和自动保护，然后出现CIRCUITPY。

Mu中的串行控制台不显示任何内容

有时，串行控制台将完全不显示任何内容，例如例如，当当前没有代码在运行，或者在打开控制台之前没有串行输出的代码已经在运行。但是，如果您发现自己应该出现类似错误的情况，请考虑以下事项。

根据屏幕或Mu窗口的大小，在打开串行控制台时，串行控制台面板可能很小。这可能是个问题。一个基本的CircuitPython错误需要10行才能显示！

下载：文件

复制代码

Auto-reload is on. Simply save files over USB to run them or enter REPL to disable.

code.py output：

Traceback （most recent call last）：

File “code.py”， line 7

SyntaxError： invalid syntax

Press any key to enter the REPL. Use CTRL-D to reload.

Auto-reload is on. Simply save files over USB to run them or enter REPL to disable.

code.py output：

Traceback （most recent call last）：

File “code.py”， line 7

SyntaxError： invalid syntax

Press any key to enter the REPL. Use CTRL-D to reload.

更复杂的错误将占用更多行！

因此，如果您的串行控制台面板是高度不超过五行，您可能只会看到空白行或空白行，后跟Press any key to enter the REPL. Use CTRL-D to reload.。在这种情况下，您需要将鼠标悬停在面板顶部以利用该选项来调整串行面板的大小，或者使用右侧的滚动条向上滚动以查找消息。

这适用于任何类型的串行输出，无论是错误消息还是打印语句。因此，在开始尝试在硬件方面调试问题之前，请确保检查是否由于串行输出面板的高度而不只是错过了串行消息。

CircuitPython RGB状态灯

Feather M0 Express，Feather M4 Express，Metro M0 Express ，Metro M4 Express，ItsyBitsy M0 Express，ItsyBitsy M4 Express，Gemma M0和Trinket M0的板上都有单个NeoPixel或DotStar RGB LED，用于指示CircuitPython的状态。

电路游乐场Express没有状态指示灯。在引导加载程序中时，LED会闪烁绿色。它们在运行CircuitPython时不会指示任何状态。

以下是颜色和闪烁的含义：

稳定的绿色：code.py（或 code.txt，main.py或main.txt）正在运行

向绿色施加脉冲：code.py（等）完成或不存在

稳定黄色 ：（ 4.0.0-alpha.5及更高版本）CircuitPython正在等待重置以表明它应该在安全模式下启动

以脉冲方式黄色：电路Python处于安全模式：崩溃并重新启动

稳定的白色： REPL正在运行

稳定运行蓝色：boot.py正在运行

以下带有多次闪烁的颜色表示Python异常，然后表示行号错误。第一次闪烁的颜色表示错误的类型：

绿色：IndentationError

CYAN ：SyntaxError

白色：NameError

橙色：OSError

紫色：ValueError

黄色：其他错误

这些错误之后会闪烁指示行号，包括位置值。 白色闪烁是数千个位置，蓝色是数百个位置，黄色是数十个位置，青色是一个人的地方。因此，例如，第32行的错误将黄色闪烁三下，然后 CYAN 闪烁两次。零表示为一个超长的暗间隙。

ValueError：不兼容的.mpy文件。

当导入以mpy二进制文件存储的模块时，会发生此错误，该二进制文件由CircuitPython的不同版本生成。它被加载到其中。特别是mpy二进制格式在CircuitPython版本2.x和3.x之间以及在1.x和2.x之间进行了更改。

例如，如果您升级了从2.x到CircuitPython 3.x，您需要下载库的更新版本，该库在import上触发了错误。它们都可以在Adafruit捆绑包中找到。

如果使用CircuitPython版本2.2.4，请确保下载文件名中具有2.0.0或更高版本的版本，以及具有3.0.0或更高版本的版本。如果使用的是CircuitPython 3.0版，则文件名应更高。

CIRCUITPY驱动器问题

您可能会发现无法再将文件保存到您的CIRCUITPY驱动器中。您可能会发现CIRCUITPY停止显示在文件资源管理器中，或显示为NO_NAME。这些是文件系统有问题的指示器。

第一次检查-您是否已使用Arduino对电路板进行编程？如果是这样，CircuitPython将不再能够提供USB服务。重置开发板，以便获得一个boardnameBOOT驱动器而不是一个CIRCUITPY驱动器，将最新版本的CircuitPython（.uf2）复制回到该板上，然后进行重置。这可能会恢复CIRCUITPY功能。

如果仍然损坏-当CIRCUITPY磁盘在通过按钮重置或与USB断开连接之前未安全弹出时，可能会损坏闪存驾驶。在Windows，Mac或Linux上都可能发生这种情况。

在这种情况下，必须完全擦除开发板，并且必须将CircuitPython重新加载到开发板上。

完成以下步骤后，您将失去董事会上的所有东西。如有可能，请复制代码，然后再继续。

最简单的方法：使用storage.erase_filesystem（）

从2.3.0版开始，CircuitPython包含一个内置函数来擦除和重新格式化文件系统。如果您的电路板上有旧版本的CircuitPython，则可以执行此操作以更新到最新版本。

使用Mu或终端程序重新连接到CircuitPython。

类型：

下载：文件

复制代码

》》》 import storage

》》》 storage.erase_filesystem（） 》》》 import storage

》》》 storage.erase_filesystem（）

CIRCUITPY将被删除并重新格式化，然后您的电路板将重新启动。就是这样！

Circuit Playground Express，Feather M0 Express和Metro M0 Express：

如果您无法使用REPL，或者您正在运行2.3.0之前的CircuitPython版本，并且不想要升级，可以执行此操作。

1.下载正确的擦除文件：

Circuit Playground Express

羽毛M0 Express

羽毛M4 Express

Metro M0 Express

Metro M4 Express QSPI橡皮擦

格子M4 Express（QSPI）

大Central M4 Express（QSPI）

PyPortal M4 Express（QSPI）

电路游乐场Bluefruit（QSPI）

Monster M4SK（QSPI）

PyBadge/PyGamer QSPI Eraser.UF2

2.双击板上的重置按钮以调出boardnameBOOT驱动器。

3.拖动擦除.uf2文件放入boardnameBOOT驱动器。

4.板载NeoPixel将变为黄色或蓝色，表示擦除已开始。

5。大约15秒钟后，主板NeoPixel将点亮绿色。在NeoTrellis M4上，这是网格上的第一个NeoPixel。

6.双击板上的重置按钮以调出boardnameBOOT驱动器。

7.拖动适当的最新版本的CircuitPython .uf2驱动器上的cc = 1》文件。

它将自动重新启动，并且您应该在文件资源管理器中再次看到boardnameBOOT。

如果LED指示灯在步骤5期间呈红色闪烁，表示擦除失败。重复从2开始的步骤。

如果尚未为电路板下载最新版本的CircuitPython，请查看安装页面。您还需要安装您的库和代码！

旧方法：对于具有UF2引导程序（Gemma M0，Trinket M0）的非Express板：

如果您无法使用REPL，或者您正在运行CircuitPython版本2.3.0之前的版本，并且您不想升级，则可以执行此操作。

1.下载擦除文件：

Gemma M0，Trinket M0

2.双击板上的重置按钮以调出CIRCUITPY驱动器。

3.将擦除的boardnameBOOT文件拖到.uf2驱动器。

4.引导LED将再次开始闪烁，并且boardnameBOOT驱动器将重新出现。

5.将适当的最新发行版CircuitPython boardnameBOOT文件拖到.uf2驱动器。

它将自动重启，并且您应该在文件浏览器中再次看到boardnameBOOT。

如果尚未下载最新版本的CircuitPython您的面板上，请查看安装页面您还需要安装天秤座ries和代码！

没有UF2引导程序（羽毛M0基本原型，羽毛Adalogger，Arduino零）的非Express板：

如果您运行的是2.3.0之前的CircuitPython版本，并且不想升级，

只需按照以下说明使用CIRCUITPY重新加载CircuitPython，这将擦除并重新创建bossac。

p》

非Express板上文件空间不足

板上的文件系统非常小。 （比古老的软盘要小。）因此，很可能您会用完空间但不要惊慌！有两种释放空间的方法。

该板还附带Windows 7串行驱动程序！如果不需要或已经安装，请随时删除。它的大小约为12KiB。

删除某些内容！

释放空间的最简单方法是从驱动器中删除文件。也许CIRCUITPY文件夹中有一些不再使用的库，或者未使用的测试代码。不过，不要完全删除lib文件夹，只需删除不需要的内容即可。

使用标签

Python的一个独特功能是缩进代码很重要。通常建议对每个缩进使用四个空格缩进代码。通常，我们也建议这样做。 但是，存储更多人类可读代码的一个技巧是使用单个制表符进行缩进。这种方法使用缩进空间的1/4，当我们计算字节数时可能很重要。

Mac OSX喜欢添加额外的文件。

幸运的是，您可以禁用Mac上的一些其他隐藏文件OSX通过运行一些命令来添加禁用搜索索引并创建零字节占位符的功能。请按照以下步骤操作，以最大程度地利用OSX上的可用空间：

防止并删除Mac OSX隐藏文件

首先找到主板的卷名。插入木板后，在终端中运行以下命令以列出所有卷：

下载：文件

复制代码

lib ls -l /Volumes

查找名称类似于ls -l /Volumes的卷（默认用于CircuitPython）。卷的完整路径是CIRCUITPY路径。

现在按照此问题的步骤运行以下终端命令，以防止在板上创建隐藏文件：

下载：文件

复制代码

/Volumes/CIRCUITPY mdutil -i off /Volumes/CIRCUITPY

cd /Volumes/CIRCUITPY

rm -rf 。{，_.}{fseventsd，Spotlight-V*，Trashes}

mkdir .fseventsd

touch .fseventsd/no_log .metadata_never_index .Trashes

cd -

替换上面的命令中的mdutil -i off /Volumes/CIRCUITPY

cd /Volumes/CIRCUITPY

rm -rf 。{，_.}{fseventsd，Spotlight-V*，Trashes}

mkdir .fseventsd

touch .fseventsd/no_log .metadata_never_index .Trashes

cd -，如果不相同，请使用完整的木板音量路径。此时，应从开发板上清除所有隐藏文件，并阻止某些隐藏文件的创建。

但是，在某些情况下，Mac OSX仍会创建隐藏文件。特别是，如果您复制从Internet下载的文件，它将具有特殊的元数据，Mac OSX将这些元数据存储为隐藏文件。幸运的是，您可以从终端运行复制命令来不复制该隐藏的元数据文件。请参阅下面的步骤。

在Mac OSX上复制文件而不创建隐藏文件

在Mac上使用上述命令禁用并删除了隐藏文件后， OSX，您需要小心使用特殊命令将文件复制到板上，以防止将来创建隐藏文件。不幸的是，您无法在Finder中使用拖放副本，因为在某些情况下（对于从Internet下载的文件，例如Adafruit的模块），它仍会创建这些隐藏的扩展属性文件。

要复制文件或文件夹，请在终端中的 cp 命令中使用 -X 选项。例如，使用以下命令将/Volumes/CIRCUITPY文件复制到板上：

下载：文件

复制代码

foo.mpy cp -X foo.mpy /Volumes/CIRCUITPY

（将 cp -X foo.mpy /Volumes/CIRCUITPY

替换为您的文件名要复制。）或复制文件夹及其所有子文件/文件夹，请使用以下命令：

下载：文件

复制代码

foo.mpy cp -rX folder_to_copy /Volumes/CIRCUITPY

如果要复制到cp -rX folder_to_copy /Volumes/CIRCUITPY文件夹或其他文件夹，请确保该文件夹在复制之前存在。

下载：文件

复制代码

lib # if lib does not exist， you‘ll create a file named lib ！

cp -X foo.mpy /Volumes/CIRCUITPY/lib

# This is safer， and will complain if a lib folder does not exist.

cp -X foo.mpy /Volumes/CIRCUITPY/lib/

其他Mac OSX节省空间的提示

如果需要查看驱动器上已使用的空间量并手动删除隐藏的文件，这里是操作方法。首先使用 df 命令列出# if lib does not exist， you’ll create a file named lib ！

cp -X foo.mpy /Volumes/CIRCUITPY/lib

# This is safer， and will complain if a lib folder does not exist.

cp -X foo.mpy /Volumes/CIRCUITPY/lib/驱动器上使用的空间量：

让我们先删除CIRCUITPY个文件。

哇！我们比以前多了13 Ki！现在可以将此空间用于库和代码！

CircuitPython Essentials

您已经阅读了“欢迎使用CircuitPython”指南。您已经完成所有设置，并已运行CircuitPython。大！怎么办？ CircuitPython Essentials！

CircuitPython内置了许多核心模块，并且提供了常用的库。 《 Essentials指南》将向您介绍这些内容，并向您展示如何使用它们的示例。

责任编辑：wv