安装Mu代码编辑器
Mu是一个简单的代码编辑器，适用于Adafruit Circuit Python开发板。它是用Python编写的，可在Windows、MacOS、Linux和树莓派上运行。串行控制台已经内置在其中，因此可以立即从开发板的串口输出获得反馈。
Mu是我们推荐的编辑器——请尽可能使用它（除非你是有经验的码农，或者已经有喜欢的编辑器）。
下载并安装Mu编辑器
单击“Download”按钮以获取下载和安装说明。
单击“Start Here”以查找其他信息，包括扩展教程和操作指南。
对于Windows用户：由于MSI安装程序的特性，请在安装最新版本之前删除旧版本的Mu。
启动Mu编辑器
第一次启动Mu时，会提示你选择“模式”—可以随时更改选择。现在请选择Circuit Python选项。可以点击右下角齿轮图标更改界面语言。
当前模式显示在窗口右下角，靠近“齿轮”图标。如果模式显示为“Microbit”或其他内容，请单击左上角的“模式”按钮，然后在弹出的对话框中选择“Circuit Python”。
Mu在启动时会尝试自动检测你连接的开发板，因此如果没有连接CIRCUITPY驱动器的Circuit Python开发板，Mu将会提示在何处保存代码，直到你连接开发板为止。
为了避免这个警告，请插入一块开发板，并确保在启动Mu之前已经挂载了CIRCUITPY驱动器。
开始使用Mu
现在你可以开始探索Mu了！窗口的三个主要部分如下所示：按钮栏、文本编辑器和串口控制台/REPL。
现在你已经准备好码代码了！让我们继续...
安装Circuit Python
随着Circuit Python的不断发展，Adafruit将停止对旧版本的支持。如果你正在运行早期版本的Circuit Python，你需要更新到最新版本。通常情况下，Adafruit会支持最近的两个主要版本。
一些兼容Circuit Python的开发板已经预装了Circuit Python，其他一些Circuit Python兼容的开发板需要安装Circuit Python，此外要更新已经安装在开发板上的Circuit Python的版本。安装和更新的步骤是相同的。本节将介绍如何在开发板上安装或更新Circuit Python。
你只需要安装Circuit Python一次。之后就可以自由地进行编程，而无需再次进行此过程，直到下次更新大版本时为止。
下载最新版本
首先，你需要做的是下载最新版本的Circuit Python。
如果你已经在运行Circuit Python，请确保正在运行最新版本！如果不确定，可以按照以下步骤确保安装了最新版本。
在安装或更新Circuit Python之前，一定要备份代码！
在安装或更新Circuit Python之前，一定要备份代码！
在安装或更新Circuit Python之前，一定要备份代码！
大多数情况下，更新过程中不会从开发板上删除任何内容，但也有可能发生意外。如果你的开发板上已经有代码，请务必在进行下面的步骤之前将其备份到计算机上。
通过前往circuitpython.org下载您的开发板的最新固件。
接下来，需要使用USB数据线连接开发板与电脑。确保USB线是数据线！有些USB线只能充电，可能会导致很多问题。
对于Windows 7和8.1的用户
如果你使用的是Windows 7或8.1，您需要在插入开发板之前安装驱动程序。
如果你使用的是Windows 7或8.1，请查看Windows 7和8.1驱动程序页面以获取详细信息。
强烈建议你升级到Windows 10。
启动UF2引导程序
几乎所有的Circuit Python开发板都配备了一个名为UF2（USB Flash）的引导程序，它使安装和更新Circuit Python变得简单易上手。开发板必须处于BOOTLOADER模式下才可以烧录.uf2文件。如果你下载的.uf2文件与你的开发板名称匹配，那么可以继续阅读本节内容。然而，如果文件以.bin结尾，你需要进行更复杂的安装 - 请前往下面的连接获取详细信息。
https://learn.adafruit.com/welcome-to-circuitpython/non-uf2-installation
对于大多数开发板：
在开发板上可以找到复位按钮，通常在板上标有RESET或RST。（在Circuit Playground Express和Bluefruit上，它是位于板中心的较小按钮。）
连续按两次复位按钮进入BOOTLOADER模式，如果寄了没进去，没啥大问题，再来一次。如果您有一个Circuit Playground Express（不用查，这个很贵），而且是刚刚拿出袋子的，可以尝试按一次按钮。
对于RP2040开发板：
在RP2040开发板上，有可能有两个按钮（合宙家的只有一个，偷工减料了）：复位按钮和BOOTSEL/BOOT按钮。这两个按钮大小相同，都是小黑色按钮。要注意复位按钮通常在板上标有RESET或RST，而启动按钮在板上标有BOOTSEL或BOOT。
要进入RP2040开发板的BOOTLOADER模式，必须按住BOOTSEL按钮，并在继续按住的同时，按下并释放RESET按钮。继续按住BOOTSEL按钮，直到引导程序驱动器出现（好麻烦，不过也就弄一次）。
BOOTLOADER模式
一旦成功，开发板上的RGB状态LED灯将闪烁红色，然后变为绿色。计算机上将出现一个新的驱动器。
对于大多数开发板：
驱动器的名称是“开发板名称+BOOT”，其中开发板名称是特定开发板的引用。例如，基本的Feather开发板将具有FEATHERBOOT，而Trinket开发板将具有TRINKETBOOT等。
对于RP2040开发板：
所有RP2040开发板的驱动器名称都为RPI-RP2。
开发板现在处于引导模式，现在就可以安装或更新Circuit Python了！
安装Circuit Python
现在找到您下载的.uf2文件。将该文件拖到电脑上刚才文件管理器中显示的磁盘内。
开发板上的灯光再次闪烁，电脑上的磁盘消失，然后计算机上将显示一个名为CIRCUITPY的新磁盘。
Bang！已成功安装了CircuitPython！
CIRCUITPY和“开发板名称+BOOT”或RPI-RP2之间有什么区别？
当你将Circuit Python开发板连接到计算机时，计算机将将开发板的闪存视为USB闪存驱动器，可以存储文件。成功安装Circuit Python后，你将看到CIRCUITPY驱动器。当你在大多数开发板上双击复位按钮时，将看到“开发板名称+BOOT”的磁盘驱动器，或者在RP2040开发板上保持引导选择并点击复位时，将看到RPI-RP2磁盘驱动器。你可以将文件拖到引导驱动器和CIRCUITPY驱动器，但只有CIRCUITPY才能运行Circuit Python代码。
通常情况下，将文件拖到挂载的USB驱动器时，文件会复制到驱动器中，然后可以在文件资源管理器中看到。然而，将.uf2文件拖到引导驱动器时，它似乎会消失，驱动器会断开连接。这是正常的，不要大惊小怪哈。UF2本质上是一个安装程序文件（类似.exe），并不仅仅停留在驱动器上，而是在开发板处于bootloader模式（即引导驱动器）时安装Circuit Python。
可以试试将其他文件复制到引导驱动器，但它们不会倍开发板执行或对Circuit Python可用。因此，在安装Circuit Python完成后，请确保将文件拖到并在CIRCUITPY驱动器上进行编辑！
引导程序驱动器名称
此列表并非最详细版本，但应该足够了解引导程序驱动器名称中要查找的内容。
- Feather RP2040 = RPI-RP2
- QT Py RP2040 = RPI-RP2
- ItsyBitsy RP2040 = RPI-RP2
- Trinket M0 = TRINKETBOOT
- Gemma M0 = GEMMABOOT
- Circuit Playground Express = CPLAYBOOT
- ItsyBitsy M0 Express = ITSYBOOT
- ItsyBitsy M4 Express = ITSYM4BOOT
- Feather M0 Express = FEATHERBOOT
- Feather M4 Express = FEATHERBOOT
- Metro M0 Express = METROBOOT
- Metro M4 Express = METROM4BOOT
- Grand Central M4 Express = GCM4BOOT
- NeoTrelis M4 Express = TRELM4BOOT
- PyPortal, Pynt and Titano = PORTALBOOT
CIRCUITPY U盘
当 Circuit Python 完成安装，或者你将一个已经安装了 Circuit Python 的开发板连接到计算机时，计算机上弹出一个名为 CIRCUITPY 的 U盘。
你要把写的代码以及所需的库和文件放到CIRCUITPY U盘里，而且你可以直接在这个U盘上编辑代码，当你保存以后，代码就会自动运行。在创建和编辑代码时，你需要把代码保存在 CIRCUITPY U盘上的一个名为 code.py 的文件中。如果你正在按照指南学习，你可以将教程示例的内容粘贴到 CIRCUITPY U盘上的 code.py 文件中，并保存来运行示例。
在安装了最新的 Circuit Python 固件后，在 CIRCUITPY U盘上，你会看到一个包含 print(&[color=var(--text_link)]#34;Hello World!") 的 code.py 文件以及一个空的 lib 文件夹。如果 CIRCUITPY U盘中没有 code.py 文件，你可以随便创建一个并保存到U盘中。当开发板启动或复位时，Circuit Python 会自动寻找 code.py 文件，并自动执行文件中的代码。在对 CIRCUITPY U盘中的文件进行更改后（例如更改了 code.py 文件），开发板会进行复位，并自动运行代码。完全无需手动运行代码。这正是circuit python如此简单的原因。 注意：对 CIRCUITPY 内容的所有更改，如保存新文件、重命名当前文件或删除现有文件，都会触发开发板的复位。
如果没有 CIRCUITPY 的开发板怎么办？
Circuit Python对于一些不支持原生 USB 的单片机也是可以刷写的。这些开发板无法在电脑上显示为CIRCUITPY U盘。包括使用 ESP32 或 ESP32-C3 微控制器的开发板。（其实现在已经支持了，ESP32_S3和S2都能直接刷了）
在这些开发板上，有其他的方法来传输和编辑文件。你可以使用 Thonny (https://thonny.org/)编辑器，它使用发送到 REPL 的隐藏命令来读写文件。或者可以使用引入于 Circuit Python 8 中的 Circuit Python Web 工作流。Web 工作流提供了基于浏览器的 WiFi 访问 Circuit Python 文件系统的方式。这些网站可以了解 Web 工作流： https://learn.adafruit.com/circuitpython-with-esp32-quick-start
https://learn.adafruit.com/getting-started-with-web-workflow-using-the-code-editorCIRCUITPY U盘
当 Circuit Python 完成安装，或者你将一个已经安装了 Circuit Python 的开发板连接到计算机时，计算机上弹出一个名为 CIRCUITPY 的 U盘。
你要把写的代码以及所需的库和文件放到CIRCUITPY U盘里，而且你可以直接在这个U盘上编辑代码，当你保存以后，代码就会自动运行。在创建和编辑代码时，你需要把代码保存在 CIRCUITPY U盘上的一个名为 code.py 的文件中。如果你正在按照指南学习，你可以将教程示例的内容粘贴到 CIRCUITPY U盘上的 code.py 文件中，并保存来运行示例。
在安装了最新的 Circuit Python 固件后，在 CIRCUITPY U盘上，你会看到一个包含 print(&[color=var(--text_link)]#34;Hello World!") 的 code.py 文件以及一个空的 lib 文件夹。如果 CIRCUITPY U盘中没有 code.py 文件，你可以随便创建一个并保存到U盘中。当开发板启动或复位时，Circuit Python 会自动寻找 code.py 文件，并自动执行文件中的代码。在对 CIRCUITPY U盘中的文件进行更改后（例如更改了 code.py 文件），开发板会进行复位，并自动运行代码。完全无需手动运行代码。这正是circuit python如此简单的原因。 注意：对 CIRCUITPY 内容的所有更改，如保存新文件、重命名当前文件或删除现有文件，都会触发开发板的复位。
如果没有 CIRCUITPY 的开发板怎么办？
Circuit Python对于一些不支持原生 USB 的单片机也是可以刷写的。这些开发板无法在电脑上显示为CIRCUITPY U盘。包括使用 ESP32 或 ESP32-C3 微控制器的开发板。（其实现在已经支持了，ESP32_S3和S2都能直接刷了）
在这些开发板上，有其他的方法来传输和编辑文件。你可以使用 Thonny (https://thonny.org/)编辑器，它使用发送到 REPL 的隐藏命令来读写文件。或者可以使用引入于 Circuit Python 8 中的 Circuit Python Web 工作流。Web 工作流提供了基于浏览器的 WiFi 访问 Circuit Python 文件系统的方式。这些网站可以了解 Web 工作流： https://learn.adafruit.com/circuitpython-with-esp32-quick-start
https://learn.adafruit.com/getting-started-with-web-workflow-using-the-code-editor
创建和编辑你的代码
Circuit Python 最大的优点之一是启动和运行代码非常简单。本节介绍如何创建和编辑你的第一个 Circuit Python 程序。
要创建和编辑代码，只需要一个代码编辑器，而代码编辑器有很多很多选择。Adafruit 强烈推荐使用 Mu，它专为 Circuit Python 设计，非常简单易用，并带有内置的串口控制台。
创建代码
安装 Circuit Python 会在CIRCUITPY U盘上生成一个 code.py 文件。如果要开始写自己的代码，需要打开代码编辑器，从 CIRCUITPY U盘加载 code.py 文件。
如果你正在使用 Mu，点击按钮栏中的 &[color=var(--text_link)]#34;Load" 按钮，导航到 CIRCUITPY U盘，并选择 code.py进行加载就可以了。 将以下代码复制并粘贴到编辑器中：
//******************分割线******************//
import board
import digitalio
import time
led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT
while True:
led.value = True
time.sleep(0.5)
led.value = False
time.sleep(0.5)
//******************分割线******************//
KB2040、QT Py 和 Trinkeys 没有板载的红色 LED，它们有一个 WS2812 LED。上述示例在 KB2040、QT Py 或 Trinkeys 开发板上将无法运行！
//******************分割线******************//
Blink example for boards with ONLY a NeoPixel LED (e.g. without a built-in red LED).
Includes QT Py and various Trinkeys.
Requires two libraries from the Adafruit CircuitPython Library Bundle.
Download the bundle from circuitpython.org/libraries and copy the
following files to your CIRCUITPY/lib folder:
* neopixel.mpy
* adafruit_pixelbuf.mpy
Once the libraries are copied, save this file as code.py to your CIRCUITPY
drive to run it.
&[color=var(--text_link)]#34;"" import time
import board
import neopixel
pixels = neopixel.NeoPixel(board.NEOPIXEL, 1)
while True:
pixels.fill((255, 0, 0))
time.sleep(0.5)
pixels.fill((0, 0, 0))
time.sleep(0.5)
//******************分割线******************//
WS2812 闪烁示例使用内置的WS2812，但时间代码是相同的。可以使用链接内的WS2812 闪烁示例来继续学习本指南。（就上面那一大串，不用再点开网站了，都复制过来了）
代码复制进去以后效果如图所示。要注意在 &[color=var(--text_link)]#34;while True:" 行下面，接下来的四行以四个空格开头，且缩进的量完全相同。在此之前的所有行都没有前面的空格缩进。
将 code.py 文件保存到 CIRCUITPY U盘上。
板载 LED 现在应该在每半秒钟闪烁一次。
恭喜，你刚刚运行了你的第一个 Circuit Python 程序！
在大多数开发板上，都板载了微小的红色 LED，在 ItsyBitsy nRF52840 开发板上，板载了一个微小的蓝色 LED，而在 QT Py M0、QT Py RP2040 和 Trinkey 系列开发板上，只会找到一个 WS2812 LED。
编辑代码
要编辑代码，需要在编辑器中打开 CIRCUITPY U盘上的 code.py 文件。对代码进行所需的更改然后保存文件。就这么简单！只要文件保存完毕，代码更改就会生效。
在继续之前，有一个警告...
不要在保存文件和更改代码的时候点击复位按钮或拔下开发板！
开发板上的 Circuit Python 固件会检测到文件发生更改或写入，并自动重新启动代码。如果在计算机将文件写入开发板之前拔下或复位开发板，可能会损坏驱动器。如果发生这种情况，可能会丢失已经写好的代码，因此定期备份代码备份非常重要。
有几种避免文件系统损坏的方法。
如果将文件从主机计算机拖放到 CIRCUITPY U盘上，仍然需要执行第二步，即在保存完文件后执行 &[color=var(--text_link)]#34;Eject" 或 &[color=var(--text_link)]#34;Sync"（下一步）以确保文件完全写入。 2. 写入后弹出或同步驱动器
如果使用的是我们不推荐的编辑器，仍然有办法让它工作。
在 Windows 上，可以弹出或安全移除 CIRCUITPY U盘。它实际上不会弹出（物理），但它会强制操作系统将文件保存到磁盘。在 Linux 上，可以在终端中使用 sync 命令强制写入磁盘。
如果使用 Windows 资源管理器或 Linux 图形文件管理器将文件拖放到 CIRCUITPY 上，也需要执行此操作。
哦，不，我做错了什么，现在 CIRCUITPY U盘不显示了！！！
不要担心！破坏驱动器并不是世界末日（也不会是开发板的末日！）。如果发生这种情况，请按照每个开发板指南上的故障排除页面上的步骤来重新启动你的开发板。
回到代码编辑...
现在！让我们尝试编辑你添加到开发板上的程序。在编辑器中打开 code.py 文件并进行一个简单的更改。将第一个 0.5 更改为 0.1。代码应该如下所示：
//******************分割线******************//
import board
import digitalio
import time
led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT
while True:
led.value = True
time.sleep(0.1)
led.value = False
time.sleep(0.5)
//******************分割线******************//
其余的代码保持不变，保存文件。看看板载LED 会发生什么变化？有些东西发生了变化！知道为什么吗？
不必止步于此！让我们继续前进。将第二个 0.5 更改为 0.1，使其如下所示：
//******************分割线******************//
while True:
led.value = True
time.sleep(0.1)
led.value = False
time.sleep(0.1)
//******************分割线******************//
现在它闪烁得非常快！
现在尝试将这两个 0.1 都改为 1。由于增加了 LED 保持亮和灭的时间，LED 闪烁速度会慢得多。
做得好！做得很棒！现在你已经准备好开始尝试新的示例并对其进行编辑，看看会发生什么！这些只是简单的更改，但是不积跬步无以至千里。进行所需的更改，保存它，然后查看结果。实际上，就是这么简单so easy！
程序文件的命名
Circuit Python 在开发板上寻找一个要运行的代码文件有四个文件选项：code.txt、code.py、main.txt 和 main.py。Circuit Python 按照这个顺序寻找这些文件，然后运行它找到的第一个文件。尽管 code.py 是建议的代码文件名，但重要的是要知道还有其他选项存在。如果你写的程序似乎在工作时没有更新，请确保没有创建另一个同名但无用的代码文件。
连接到串口控制台
Circuit Python（以及其他编程语言）的基础之一是所谓的“输出语句”，可以使代码输出文本。在Circuit Python（以及Python）中，输出语句看起来像这样：
在code.py中，运行这行代码将会产生：
Hello, world!
然而，这些输出语句需要一个地方来显示输出。这就是串口控制台的作用。
开发板通过USB发送信号，串口控制台接收并将其显示出来，以便你可以看到它。它还有助于故障排除，如果开发板发送错误的信息，串口控制台也会显示这些错误信息。
为了读取串口数据，需要一个具有内置控制台的编辑器，或者一个单独的控制台程序。
你是否在使用Mu？
如果是这样，那太好了！串口控制台内置在Mu中，并且将自动检测你的开发板，使用串口控制台会非常非常容易。
首先，确保Circuit Python开发板已连接电脑。
如果你在没有插入开发板的情况下打开了Mu，可能会遇到上图所见的错误，这是提醒你Mu没有找到Circuit Python开发板，并指示你代码在插入开发板之前会存储在哪里。
如果你使用的是Windows 7，请确保你已安装驱动程序。
在插入开发板并打开Mu后，寻找按钮栏中的“Serial”按钮，然后单击它。
Mu窗口将水平分为两半，并在底部显示串口控制台。
如果串口控制台中没有显示任何内容，可能意味着你的代码已运行完毕或其中没有输出语句。点击Mu中的串口控制台部分，并按下CTRL+D重新加载。
Linux上的串口控制台问题或延迟
如果你在Linux上连接到串口控制台时遇到多秒的延迟，或者在连接时看到“AT”和其他乱码，则可能是modemmanager服务在干扰，只需将其删除即可，除非你仍在使用拨号调制解调器，否则它没有太多用途。
要删除modemmanager，请在shell中键入以下命令：
sudo apt purge modemmanager
在Linux上设置权限
在Linux上，如果在按下“Serial”按钮时看到类似以下内容的错误框，则需要将自己添加到一个用户组中，以便获得连接到串口控制台的权限。
在Ubuntu和Debian上，通过执行以下操作将自己添加到“dialout”组中：
sudo adduser $USER dialout
在运行上述命令后，重新启动你的计算机以获取对该组的访问权限。在其他Linux发行版上，你可能需要不同的组。有关如何将自己添加到正确组的详细信息，请参阅有关Linux上高级串口控制台的说明。
使用其他工具？
如果你没有使用Mu进行编辑代码，或者由于某种原因不喜欢其内置的串口控制台，你可以从单独的程序中运行串口控制台。
一旦连接成功，你将会看到类似以下内容的信息。
与串口控制台交互
一旦成功连接到串口控制台，就可以开始使用它了。
打开你的code.py文件并将输出语句包含在其中。你可以输出任何你喜欢的内容！只需在括号内的引号之间包含你的短语。例如：
//******************分割线******************//
import board
import digitalio
import time
led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT
while True:
led.value = True
time.sleep(1)
led.value = False
time.sleep(1)
//******************分割线******************//
保存你的文件。
现在，让我们去看看我们连接到串口控制台的窗口。
太棒了！我们的输出语句显示在控制台中！尝试将打印的文本更改为其他内容。
//******************分割线******************//
import board
import digitalio
import time
led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT
while True:
led.value = True
time.sleep(1)
led.value = False
time.sleep(1)
//******************分割线******************//
将串口控制台窗口保持在你可以看到的位置。保存你的文件。在开发板重新启动时，你将看到串口控制台显示的内容。然后你将看到你的新更改！
"Traceback (most recent call last):"告诉你在保存文件之前，开发板正在执行的最后一项操作。这是正常的，每次开发板重置时都会发生。这对于故障排除非常有用。让我们引入一个错误，以便你可以看到如何使用它。
在 led.value = True 中删除 True 末尾的 e ，使其变成 led.value = Tru 。
//******************分割线******************//
import board
import digitalio
import time
led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT
while True:
led.value = Tru
time.sleep(1)
led.value = False
time.sleep(1)
//******************分割线******************//
保存你的文件。你会注意到红色LED停止闪烁，同时你可能会看到一个彩色的状态LED在闪烁。这是因为代码不再正确，无法正确运行，需要修复它！
通常，当遇到错误时，不是因为你故意引入了错误。你可能有200行代码，不知道错误可能藏在哪里。这就是串口控制台可以帮助的地方。让我们来看看！
"Traceback (most recent call last):"告诉你它能够运行的最后一项操作是你代码中的第10行。下一行是你的错误：NameError: name &[color=var(--text_link)]#39;Tru' is not defined。这个错误对你来说可能意义不大，但结合知道问题在第10行，你就有了一个很好的起点！ 回到你的代码，看看第10行。显然，你已经知道问题是什么。但是，如果你不知道，你会想要查看第10行，看看是否能找出问题所在。如果你还不确定，可以尝试在Google上搜索错误以获得一些帮助。在这种情况下，你知道要查找什么。
很好，成功修复错误！你的串口控制台正在接收信号，红色LED正在闪烁。
串口控制台将显示由你的代码生成的任何输出。一些传感器，例如湿度传感器或热敏电阻，会接收数据，你可以使用输出语句来显示这些信息。你还可以使用输出语句进行故障排除，这称为“打印调试”。基本上，如果你的代码不起作用，并且想知道出了什么问题，你可以在不同的位置放置打印语句，以查看在哪里停止打印。
串口控制台具有许多用途，是学习和编程的绝佳工具。
REPL交互
串口连接的另一个功能是Read-Evaluate-Print-Loop（REPL），即读取-求值-打印-循环。REPL允许你输入单独的代码并立即运行它们。如果你在特定程序中遇到问题，并且无法弄清楚原因，它非常有用。它是交互式的，因此非常适合测试新的idea。
进入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的时间点。这些信息在故障排除时非常有用，但现在不用担心。只需记住这是你操作后会发生的事。
如果你的code.py文件是空的或不包含循环，它将显示一个空输出和“Code done running.”。控制台不会告诉你打断它之前开发板正在做什么，因为没有代码在运行。
如果在你的CIRCUITPY驱动器上没有code.py，你将在按下CTRL+C后立即进入REPL。同样，控制台不会告诉你打断它之前开发板正在做什么，因为没有代码在运行。
无论如何，一旦按下键，你将会看到一个 >>> 提示你已经进入REPL！
如果你在进入>>>提示时遇到问题，请尝试多按几次Ctrl + C。
从REPL获得的第一条信息是关于你的开发板的信息。
这一行告诉你你正在使用的Circuit Python版本以及发布日期。接下来，它会给出你正在使用的开发板类型和开发板所使用的主控类型。对于不同的开发板内部分的信息都不一样，这取决于你正在使用的版本。
然后是Circuit Python提示。
与REPL交互
在这个提示符下，你可以运行各种命令和代码。首先要做的事情是运行help()。这将告诉你从哪里开始探索REPL。要在REPL中运行代码，请将其输入到REPL提示旁边。
在REPL提示旁边键入help()。
然后按下回车。然后你应该会看到一条消息。
第一部分是关于你正在使用的Circuit Python的版本。接下来是与Circuit Python相关的项目指南的URL。然后...等等。这是什么？要列出内置模块，请键入`help(&[color=var(--text_link)]#34;modules")`。还记得你在创建代码时学到的模块吗？说的就是这个！这是一个完美的起点。让我们来看看！ 在REPL提示旁边键入help(&[color=var(--text_link)]#34;modules")，然后按回车。
这是内置在Circuit Python中的所有核心模块的列表，包括board。记住，board包含你可以在代码中使用的开发板上的所有引脚。从REPL中，你可以看到该列表！
在REPL中键入import board，然后按回车。它会进入新的提示符。它可能看起来好像没有发生任何事情，但情况并非如此！如果你还记得，import语句只是告诉代码期望对该模块执行某些操作。在这种情况下，它告诉REPL你计划对该模块执行某些操作。
接下来，键入dir(board)进入REPL，然后按回车。
这是你的开发板上所有可用于在代码中使用的引脚的列表。每个开发板的列表可能会略有不同，这取决于可用的引脚数。你看到LED了吗？那就是你用来闪烁红色LED的引脚！
REPL也可以用于运行代码。请注意，你在REPL中输入的任何代码都不会被保存在任何地方。如果你要测试新的内容并希望保留它，请确保将其也保存在计算机的其他地方！
然后按回车。
在REPL中运行代码就是这么简单！做得好！
你可以编写独立运行的单行代码。你还可以将整个程序写入REPL以进行测试。请记住，任何键入到REPL中的内容都不会被保存。
REPL可以为你做很多事情。如果你想要查看几行新代码是否有效，它非常适用于测试新想法。通过逐行输入代码并找出出错位置，它非常适用于排查代码。它还允许你查看可用的模块并探索这些模块。
尝试在 REPL 中输入更多内容，以查看会发生什么！
在 REPL 中键入的所有内容都是临时的。一旦重新加载 REPL 或返回串口控制台，你输入的任何内容都不会保留在任何内存空间中。因此，请务必将你编写的任何所需代码保存在其他地方，否则在离开当前 REPL 实例时会丢失它！
返回串口控制台
当你准备离开 REPL 并返回串口控制台时，只需按下 CTRL+D。这将重新加载你的开发板并重新进入串口控制台。你将重新启动之前在进入 REPL 之前运行的程序。在控制台窗口中，你将看到来自你运行的程序的任何输出。如果你的程序影响了板上的任何可视内容，则你还将看到该内容重新启动。
你随时可以返回 REPL！
Circuit Python库
你运行的每个Circuit Python程序都需要有许多附加信息才能正常工作。Circuit Python之所以如此简单易用，是因为大部分底层运行代码都存储在其他文件中，并在后台运行。这些文件被称为库。其中一些库内置在Circuit Python中。其他库存储在你的CIRCUITPY驱动器上的一个名为&[color=var(--text_link)]#34;lib"的文件夹中。Circuit Python的一个优点是能够将代码与固件本身分开存储。将代码与固件分开存储使得更容易同时更新你编写的代码和你依赖的库。 你的开发板可能已经附带了一个名为&[color=var(--text_link)]#34;lib"的文件夹，它位于驱动器的基本目录中。如果没有，只需自行创建该文件夹。当你首次安装Circuit Python时，将为你创建一个空的&[color=var(--text_link)]#34;lib"目录。
这种把库文件分开存放的方法的一个缺点是它们不是内置的。要使用它们，需要在使用之前将它们复制到CIRCUITPY驱动器上。不过幸运的是，我i们准备了一个库文件的捆绑包。
捆绑包和GitHub上发布的库文件还包含了优化版本的库，具有&[color=var(--text_link)]#34;.mpy"文件扩展名。这些文件在驱动器上占用更少的空间，并且占用更小的内存空间，因为它们加载时的内存占用更小。 由于定期的更新和空间限制，Adafruit不会随附整个捆绑包。因此，当你开始使用开发板时，你需要加载所需的库。你可以在你的开发板指南中找到依赖于外部库的示例代码。
无论用上面的哪种方式，当你开始学习Circuit Python时，你都会想知道如何将库文件加载到开发板上。
Adafruit学习指南项目捆绑包
从Adafruit学习系统中获得项目最快、最简单的方法是使用项目捆绑包。现在，大多数指南的完整代码示例顶部都有一个“下载项目捆绑包”按钮。点击此按钮将下载所有必要的文件，包括图像等，以使项目指南能够运行起来。只需点击按钮，打开生成的zip文件，复制正确的文件，即可开始使用！
第一步是在你正在使用的指南中找到“下载项目捆绑包”按钮。
在学习指南中，仅完整的GitHub演示代码才会有“下载项目捆绑包”按钮。代码片段将不会有该按钮。
当你将项目捆绑包的内容复制到CIRCUITPY驱动器上时，它将替换所有现有内容！如果你不想丢失任何内容，请确保在复制新的项目捆绑包内容之前将当前代码复制到计算机上！
“下载项目捆绑包”按钮会下载一个zip文件。此zip文件包含一系列目录，其中包含code.py、图像或音频等相关资产，以及包含所有必要库的lib/文件夹。下面的zip文件是从&[color=var(--text_link)]#34;Lime钢琴按键"指南中下载的。
在这里选择了&[color=var(--text_link)]#34;Lime钢琴按键"指南作为示例。该指南专为Circuit Playground Express设计，不能用于所有开发板。不要指望下载该捆绑包后，它能在非CPX开发板上正常工作。 当你打开zip文件时，你会找到一些嵌套的目录。浏览这些目录，直到找到所需内容。最终，你会找到一个适用于你的Circuit Python版本（在本例中为7.x）的目录。在版本目录中，你会找到所需的文件和目录：code.py和lib/。一旦找到所需的内容，你可以将所有内容复制到CIRCUITPY驱动器上，用刚刚下载的zip文件中的文件替换驱动器上已有的文件。
在某些情况下，与code.py和lib/相同目录中可能还会有其他文件，例如音频或图像。确保在复制文件时包括所有文件！
一旦复制了所有相关文件，项目就应该开始运行了！如果发现项目运行不如预期，请确保你已将所有项目文件都复制到了开发板上。
这就是使用项目捆绑包的全部内容！
Adafruit Circuit Python库捆绑包
Adafruit为其提供的大部分硬件（包括传感器、拓展板等）提供了Circuit Python库。为了不再需要逐个搜索每个库，这些库都集中在Adafruit Circuit Python库捆绑包中。捆绑包包含使用每个库所需的所有文件。
下载Adafruit Circuit Python库捆绑包
你可以通过单击下面的按钮来下载最新的Adafruit Circuit Python库捆绑包版本。由于库经常更新和改进，你应该下载最新的捆绑包。
将捆绑包版本与你正在运行的Circuit Python版本匹配。例如，如果你正在运行Circuit Python 6的任何版本，你将下载6.x库捆绑包，或者如果你正在运行Circuit Python 7的任何版本，你将下载7.x库捆绑包，依此类推。如果你在不同的Circuit Python主要版本中混合使用库，由于主要版本更改可能会导致库接口变化，你将会遇到不兼容的mpy错误。
https://circuitpython.org/libraries
下载与你的Circuit Python固件版本相匹配的捆绑包版本。如果你不知道版本，请在CIRCUITPY驱动器上的boot_out.txt文件中查看版本信息，或者在Circuit Python REPL中的初始提示中查看版本信息。例如，如果你正在运行v7.0.0版本，那么请下载7.x库捆绑包。
还有一个名为&[color=var(--text_link)]#34;py"的捆绑包，其中包含未压缩的Python文件，除非你在库上进行高级工作，否则你可能不需要它。 Circuit Python社区库捆绑包
Circuit Python社区库捆绑包由Circuit Python社区的成员编写和提供。这些库通常是在社区成员遇到Adafruit捆绑包中不支持的硬件，或者为了支持个人项目而编写的。这些作者选择将这些库提交给社区，使其可供社区使用。
这些库由其作者维护，不受Adafruit支持。与任何库一样，如果你遇到问题，请随时在库的GitHub上提出问题。但是要记住，这些库通常由单个人支持，你可能需要耐心等待回应。请记住，这些人是在用爱发电，他们在可能的情况下会自愿投入个人时间来提供支持。
下载Circuit Python社区库捆绑包
你可以通过单击下面的按钮来下载最新的Circuit Python社区库捆绑包版本。由于库经常更新和改进，所以你应该下载最新的捆绑包。
https://github.com/adafruit/CircuitPython_Community_Bundle/releases
该链接会带你到GitHub上Circuit Python社区库捆绑包的最新版本。捆绑包有多个版本可供选择。下载与你的Circuit Python固件版本相匹配的捆绑包版本。如果你不知道版本，请在CIRCUITPY驱动器上的boot_out.txt文件中查看版本信息，或者在CircuitPython REPL中的初始提示中查看版本信息。例如，如果你正在运行v7.0.0版本，那么请下载7.x库捆绑包。
了解捆绑包
下载zip文件后，解压。
打开捆绑包文件夹。在里面，你会找到两个文件和两个文件夹。其中一个文件夹是库捆绑包，另一个文件夹是示例捆绑包。
现在打开库文件夹。打开文件夹后，你会看到许多.mpy文件和文件夹。
示例文件
每个库的所有示例文件现在都包含在捆绑包中的一个示例目录中（如上图所示），以及一个仅包含示例的捆绑包。它们包括两个主要原因：
1. 快速测试设备。
2. 提供一个示例代码基础，以便进行个性化的构建。
复制库到你的开发板
首先，在你的CIRCUITPY驱动器上打开&[color=var(--text_link)]#34;lib"文件夹。然后，打开从下载的zip文件中提取的&[color=var(--text_link)]#34;lib"文件夹。在里面，你会找到许多文件夹和.mpy文件。找到你想要使用的库，将其复制到CIRCUITPY上的&[color=var(--text_link)]#34;lib"文件夹中。
如果库是包含多个.mpy文件的文件夹，请确保将整个文件夹复制到CIRCUITPY/lib中。
上述步骤这也适用于示例文件。打开从下载的zip文件中提取的示例文件夹，将适用的文件复制到CIRCUITPY驱动器上。然后，将其重命名为code.py以运行它。
如果一个库包含多个.mpy文件，应确保将整个文件夹复制到CIRCUITPY/lib中。
了解要安装哪些库
你现在知道如何将库加载到与Circuit Python兼容的开发板上了。你可能会想知道，你需要安装哪些库呢？坏消息是没有直接的办法能让你弄清楚。不过一般有一个过程，以及一个相对简单的方法来弄清剩下的部分。首先，让我们看看一般下手的地方。
当你查看大多数Circuit Python示例时，你会看到它们以一个或多个import语句开头。通常如下所示：
//******************分割线******************//
import library_or_module
//******************分割线******************//
但是，import语句有时也可能如下所示：
//******************分割线******************//
from library_or_module import name
from library_or_module.subpackage import name
from library_or_module import name as local_name
//******************分割线******************//
它们还可以具有更复杂的格式，例如包含try / except块等。
重要的是要知道import语句包含你正在导入的模块或库的名称。
因此，最好一开始先看看import语句。
以下是一个供你在本节中使用的示例导入列表。这里没有显示设置或其他代码，因为本节的目的只涉及导入列表。
//******************分割线******************//
import time
import board
import neopixel
import adafruit_lis3dh
import usb_hid
from adafruit_hid.consumer_control import ConsumerControl
from adafruit_hid.consumer_control_code import ConsumerControlCode
//******************分割线******************//
请注意，并非所有导入的项目都是库。其中一些是内置的Circuit Python模块。如何区分它们？现在是访问REPL的时候了。
在本指南的“与REPL互动”部分，讨论了help(&[color=var(--text_link)]#34;modules")命令。这个命令提供了你的开发板上所有内置模块的列表。因此，如果你连接到开发板上的串行控制台，并进入REPL，你可以运行help(&[color=var(--text_link)]#34;modules")来查看可用于你的开发板的所有内置模块。然后，当你阅读导入语句时，你可以根据模块来排除导入模块。 https://learn.adafruit.com/welcome-to-circuitpython/the-repl#interacting-with-the-repl-2977486-14
以下是内置于Feather RP2040的Circuit Python模块列表。你的列表可能看起来相似，或者是较小板的重要子集。
既然你知道在寻找什么，现在是时候阅读导入语句了。前两个导入项，time和board，位于上面的模块列表中，因此它们是内置的模块。
接下来是一个neopixel，不在模块列表中。这意味着它是你的第一个库！因此，你需要前往下载的捆绑包zip文件，然后搜索neopixel。在捆绑包zip文件中有一个neopixel.mpy文件。将其复制到CIRCUITPY驱动器上的&[color=var(--text_link)]#34;lib"文件夹中。接下来一个adafruit_lis3dh，也不在模块列表中。对于adafruit_lis3dh，你可以按照同样的过程进行操作，找到adafruit_lis3dh.mpy并复制它。 第五个是usb_hid，它在模块列表中，因此它是内置的。通常，所有内置模块都会首先出现在导入列表中，但有时不会！不要假设第一个库之后的所有内容都是库，要根据模块列表验证每个导入是否正确。否则，你会搜索捆绑包，却找不到任何内容！
最后两个导入项不太清楚。请记住，当导入语句格式如下时，从关键字‘from
’后的第一个是库名。在这种情况下，库名是adafruit_hid。在捆绑包中搜索adafruit_hid，你会找到一个adafruit_hid文件夹。当一个库是一个文件夹时，你必须将整个文件夹及其内容复制到CIRCUITPY驱动器上的&[color=var(--text_link)]#34;lib"文件夹中。在这种情况下，你将整个adafruit_hid文件夹复制到CIRCUITPY/lib文件夹中。 请注意，有两个以adafruit_hid开头的导入项。有时你需要从同一个库中导入多个内容。无论你从同一个库中导入多少次，只需要复制一次adafruit_hid文件夹以加载库。
这就是你可以使用示例代码来确定要在Circuit Python兼容的开发板上加载哪些库的方法！
但是，有些情况下，库在内部需要其他库。在库存在依赖关系的情况下，最简单的方法是连接到串行控制台，并根据打印的ImportError进行操作。下面是一个缺少库时出现ImportError的非常简单的示例，但是对于任何缺少库的情况，其概念是相同的。
示例：由于缺少库而引发的ImportError
如果你选择按需加载库文件，或者使用现有示例开始，你可能会遇到尝试使用尚未加载到开发板上的库的代码。此部分将演示当你尝试使用尚未加载到开发板上的库时会发生什么，并介绍解决此问题所需的步骤。
只有当你尚未将所需的库加载到CIRCUITPY驱动器上的&[color=var(--text_link)]#34;lib"文件夹中时，此演示才会返回错误。 让我们使用修改过的闪烁示例。
//******************分割线******************//
import board
import time
import simpleio
led = simpleio.DigitalOut(board.LED)
while True:
led.value = True
time.sleep(0.5)
led.value = False
time.sleep(0.5)
//******************分割线******************//
保存此文件。你的开发板上什么都没有发生。让我们检查串行控制台，看看发生了什么。
出现了ImportError。它说没有名为&[color=var(--text_link)]#39;simpleio'的模块。这就是你刚刚在代码中包含的库！ 点击上面的链接以下载正确的包。从下载的包文件中提取lib文件夹。滚动查找simpleio.mpy。这是你要找的库文件！按照上面的步骤加载单个库文件。
LED再次开始闪烁！让我们检查串行控制台。
没有错误！太棒了。你已成功解决了ImportError！
如果将来遇到此错误，请按照上述步骤进行操作，并选择与你缺少的库相匹配的库。
非Express板上的库安装
如果你有M0非Express的开发板，如Trinket M0、Gemma M0、QT Py M0或M0 Trinkeys中的一种，你将希望按照上面的示例中的相同步骤安装所需的库。请记住，如果你知道将哪个库添加到了你的代码中，你不需要等待ImportError。打开你下载的库包，找到你需要的库，并将其拖放到CIRCUITPY驱动器上的lib文件夹中。
即使你只在需要时加载库，你的M0非Express板仍可能出现空间不足的情况。你可以尝试一些方法来解决此问题。你可以在故障排除页面上找到建议。
https://learn.adafruit.com/welcome-to-circuitpython/troubleshooting
更新Circuit Python库和示例
库和示例会不时更新，重要的是更新你在CIRCUITPY驱动器上的文件。
要更新单个库或示例，请按照上面的相同步骤进行操作。将库文件拖放到lib文件夹时，它会询问是否要替换它。选择是。就这样！
每次库更新时都会发布新的库包。更新包括错误修复和新功能等内容。定期查看你使用的库是否已更新非常重要。
CircUp CLI工具
有一个名为CircUp的命令行界面（CLI）实用程序，可用于轻松安装和更新设备上的库。请按照CircUp学习指南中的安装页面上的说明进行操作。一旦安装完成，你可以在终端中运行命令circup update以交互方式更新连接的Circuit Python设备上的所有库。有关完整功能列表，请参阅CircUp指南中的使用页面。
欢迎来到社区！
Circuit Python是一种非常简单入门且非常适合学习的编程语言。它可以在微控制器上运行，并且开箱即用。你可以将其连接并使用任何文本编辑器开始使用。最好的部分是，Circuit Python拥有一个令人惊叹且支持广泛的社区。
Circuit Python是开源的。这意味着任何人都可以使用、编辑、复制和改进它。这也意味着Circuit Python因为有你的参与而变得更好。无论这是你的第一个微控制器板还是你是一名经验丰富的软件工程师，你都可以为Adafruit Circuit Python社区做出重要贡献。本页面突出显示了你可以参与其中的许多方式！
Adafruit Discord（老外的QQ群）
Adafruit Discord服务器是开始的最佳地方。Discord是社区志愿者提供各种实时支持的地方。从一般讨论到详细问题解决，以及各种各样的主题，Discord是一个数字创客空间，汇聚了来自世界各地的创客。
有许多不同的频道，因此你可以选择最适合你需求的一个。每个频道在Discord上显示为“[color=var(--text_link)]#channelname”。有一个#help-with-projects频道，用于协助你解决当前项目的问题或帮助你想出下一个项目的主意。有一个#show-and-tell频道，用于展示你的最新创作。不要害怕在任何频道中提问！如果你不确定，#general是一个很好的起点。如果另一个频道更可能为你提供更好的答案，会有人指导你。 有关Circuit Python问题，请前往Circuit Python问题帮助频道。#help-with-circuitpython专为新用户和开发人员提供，因此请随时提出问题或发表评论！任何经验水平的人都可以加入对话。你的贡献非常重要！#circuitpython-dev频道也可用于开发讨论。
为社区做出贡献的最简单方式是在Discord上帮助其他人。支持他人并不总是意味着回答问题。参与庆祝成功！庆祝你的错误！有时，只是听到别人经历了类似的困难足以使一个创客继续前进。
Adafruit Discord是一个24x7x365（996都不敢想，全年无休）的黑客空间，你可以带你的孙女来参观（老外的茬不懂）。
CircuitPython.org
Circuit Python本身是用C语言编写的。但是，所有Adafruit Circuit Python库都是用Python编写的。如果你有兴趣为Circuit Python的Python方面做出贡献，请查看circuitpython.org/contributing。你将找到与每个Adafruit Circuit Python库GitHub存储库相关的信息，从而有机会通过找到适合你的贡献选项加入社区。
请注意页面上“Current Status”旁边的日期：
如果你向库提交了任何贡献，但在Contributing页面上没有看到它们的反映，那可能是检查新更新的作业尚未运行。只需明天再来查看！
现在，让我们看看不同的选项。
Pull Requests
你将找到的第一个选项卡是一个打开的拉取请求列表。
GitHub拉取请求，或PR，是在某人向Adafruit Circuit Python库GitHub存储库添加了内容并要求Adafruit将其更改合并到主要库代码中时打开的。要合并PR，必须首先进行审查。审查是一种很好的贡献方式！查看打开的拉取请求列表，并选择一个你感兴趣的请求。如果你有硬件，可以测试代码更改。如果没有，你仍然可以检查代码更新的语法。对于文档更新，你可以验证信息或检查拼写和语法。一旦你检查了更新，你可以留下评论，让我们知道你已经查看了。一旦你做了一段时间，并且感到更加自在，你可以考虑加入Circuit Python Librarians审查团队。我们拥有的审查员越多，我们就可以支持的作者越多。审查是开源生态系统的关键组成部分，包括Circuit Python在内。
Open Issues
你将找到的第二个选项卡是一个打开的问题列表。
GitHub问题是由许多原因而创建的，包括库或示例代码中存在错误或故障时，或者当有人想提出功能请求时。问题是通过更新代码或文档来直接为库做出贡献的绝佳方式。如果你有兴趣贡献代码或文档，请查看打开的问题，并找到一个你感兴趣的问题。
如果不确定从何开始，可以按标签搜索问题。标签被应用于问题上，以使目标在第一次看时更容易识别，或者表示问题的难度级别。单击“按问题标签排序”旁边的下拉菜单以查看可用标签列表，然后单击其中一个以选择它。
如果你对一切都不熟悉，不熟悉对参与开源贡献，或者不熟悉对Circuit Python项目的贡献，你可以选择“Good first issue”。带有该标签的问题定义明确，范围有限，适合新手解决。
如果你想要更复杂一些的东西，可以考虑“Bug”或“Enhancement”。Bug标签适用于与库中的问题或故障有关的问题。Enhancement标签适用于功能请求。
Library Infrastructure Issues
你将找到的第三个选项卡是一个库基础结构问题列表。
此部分由运行库的检查的脚本生成，然后报告可能存在问题的地方。它由包含指向正在经历特定问题的存储库的链接的子部分列表组成。这一页主要供内部使用，但你可能会发现一些贡献机会。如果有列出的问题听起来是你可以帮助解决的问题，请在Discord上提及它，或在GitHub上提交问题，指出你正在努力解决该问题。其他人可以通过任何方式回复，以让你知道问题的范围可能是什么，并在必要时帮助你解决它。
CircuitPython本地化
你将找到的第四个选项卡是CircuitPython本地化选项卡。
如果你会说其他语言，你可以帮助翻译Circuit Python！翻译适用于Circuit Python核心中包含的信息性和错误消息。这意味着不会说英语的人在使用Circuit Python时有机会以其自己的语言看到这些消息。这对于为所有用户提供最佳体验非常重要。Circuit Python使用Weblate进行翻译，这使得贡献翻译变得更加简单。你仍然需要了解一些关于Circuit Python特定实践和一些有关编写字符串的基础知识，但与任何Circuit Python贡献一样，人们会提供帮助。
无论你的技能水平如何，或者你想如何为Circuit Python项目做出贡献，都有机会可用。Contributing页面是一个很好的起点！
Adafruit GitHub
无论你是初学者还是一生的程序员，都有适合每个人参与Circuit Python项目的方式。Circuit Python核心是用C编写的。库是用Python编写的。GitHub是为Circuit Python核心和Circuit Python库提供贡献的最佳来源。如果你需要帐户，请访问https://github.com/并注册。 如果你对GitHub或编程总体都不熟悉，那么对你来说有很好的机会。对于Circuit Python核心，前往GitHub上的Circuit Python存储库，单击“Issues”，你会找到一个包含标记为“good first issue”的问题的列表。对于库，前往Contributing页面的问题列表，并使用下拉菜单搜索“good first issue”。这些问题被确定为任何经验水平的人都可以帮助解决的问题。这些问题包括更新文档、提供反馈和修复简单的错误。如果你需要帮助开始使用GitHub，Contributing to Circuit Python with Git and GitHub上有一份出色的指南。
已经有经验并寻找挑战吗？查看其他问题列表，你会找到许多贡献的方式。你会发现各种各样的东西，从新的驱动程序请求到库错误，再到核心模块更新。对于任何水平的每个人都有大量的机会！
当使用Circuit Python或Circuit Python库时，你可能会遇到问题。如果发现错误，那太好了！团队喜欢错误！向GitHub提交详细的问题是改进CircuitPython的宝贵方式。对于Circuit Python本身，请在这里提交问题。对于库，请在GitHub上的特定库存储库上提交问题。请确保包括复制问题的步骤以及你认为相关的任何其他信息。细节越多越好！
测试新软件非常简单且非常有帮助。只需将CircuitPython的最新版本或库加载到你的Circuit Python硬件上并使用它。通过将新问题发布到GitHub来告诉我们你发现的任何问题。在稳定和不稳定版本上进行软件测试是贡献Circuit Python的非常重要的一部分。开发人员无法自己找到所有问题！他们需要你的帮助来使Circuit Python变得更好。
在GitHub上，你可以提交功能请求、提供反馈、报告问题等等。如果有问题，请记住Discord和论坛都可以提供帮助！
Adafruit论坛
Adafruit论坛是支持的最佳地方。Adafruit拥有出色的付费支持人员，可以回答你可能遇到的任何问题。无论你的硬件是否出现问题还是你的代码似乎无法正常工作，论坛始终都在等待你提问。你需要一个Adafruit帐户才能在论坛上发布。你可以使用在Adafruit订购时使用的同一个帐户。
尽管Discord可能会为你提供比论坛更快的响应，但论坛是更可靠的信息来源。如果你想确保获得由Adafruit支持的答案，论坛是最好的地方。
有涵盖各种主题的论坛类别，包括Adafruit的一切。在“Supported Products & Projects”下的Adafruit Circuit Python类别是发布Circuit Python问题的最佳地点。
确保包括你采取的步骤以到达你所在的位置。如果涉及布线，请发布一张图片！如果你的代码给你带来麻烦，请在你的帖子中包含代码！这是确保有足够信息帮助你解决问题的绝佳方法。
你可能认为你刚刚开始，但你绝对知道有些事情是其他人不知道的。论坛的好处在于你也可以帮助其他人！欢迎并鼓励每个人向发布的问题提供建设性的反馈。这是为社区做出贡献并分享你的知识的绝佳方式！
Read the Docs
Circuit Python 文档
前面已经介绍了 Circuit Python 的内置模块和外部函数库。但是有时这些指南未必能展示出所有功能，而且通常还有更多关于模块或库的内容需要学习。那么，你在哪里可以找到更详细的信息呢？这就是你需要查看 API 文档的时候了。
整个 Circuit Python 项目都有详尽的文档，可在 Read the Docs 上找到。
Circuit Python 核心文档
Circuit Python 核心文档涵盖了你可能想了解的关于 Circuit Python 核心和相关主题的许多详细信息。它包括 API 和使用信息、设计指南以及有关将 Circuit Python 移植到新板上、与 Circuit Python 相关的 Micro Python 信息，以及有关项目的一般信息。
主页涵盖了基本信息，包括从哪里下载 CircuitPython、如何贡献你的力量、与 MicroPython 的区别、有关项目结构的信息，以及整个文档的完整目录。
使用左侧的列表导航到更多关于特定主题的信息。
第一部分是 API 和使用指南。你可以找到有关如何使用各个内置核心模块的信息，例如时间和数字 I/O，有关支持的端口的详细信息，故障排除建议，以及关于库捆绑包的基本信息和链接。核心模块部分还包括支持矩阵，其中还有一个表格列出了哪些核心模块在哪些板上可用。
第二部分是设计和移植参考。它包括设计指南、架构信息、移植细节和在其他端口中添加模块支持的详细信息。
第三部分是关于 Micro Python 的特变注意事项。它包括与 Micro Python 及相关库有关的信息，以及术语表。
第四部分是关于项目的信息。它包括有关构建、测试和调试 Circuit Python 的详细信息，以及 Adafruit 社区行为准则等各种有用的链接。
无论你是经验丰富的专业人士还是电子和编程的新手，你都可以在文档中找到丰富的信息，以帮助你在 Circuit Python 的旅程中前进！
Circuit Python 库文档
除此以外，要查看特定库的文档，你可以访问该库的 GitHub ，并在 README 中找到链接。
本页的目的是介绍 LED 动画库的文档。每个库的 GitHub 中都有两个文档链接。第一个是 README 顶部附近的文档徽章。
https://github.com/adafruit/Adafruit_CircuitPython_LED_Animation
第二个位置是 README 的“文档”部分。向下滚动可以找到它，然后单击“Read the Docs”以访问文档。
现在你知道如何查找文档了，是时候看看里面的内容了。
并非所有库文档都看起来完全相同，但这将为你提供一些你想知道的信息。
介绍页面是从 README 自动生成的，因此它包含了所有相同的信息，例如 PyPI 安装说明、快速演示和一些构建细节。它还包含了完整的目录，用于剩余文档（这不是 GitHub README 的一部分）。页面应该看起来类似于下面的样子。
左侧包含链接到文档其余部分的链接，分为三个不同的部分：示例、API 参考和其他链接。
示例
示例部分是一个库示例列表。此列表包含库的示例的从少数几个到全部示例的不等数量。
https://circuitpython.readthedocs.io/projects/led-animation/en/latest/examples.html
这个部分至少包含一个示例 - 简单的测试示例。
简单测试示例通常是一个基本示例，旨在显示你的设置是否正常工作。它可能需要其他库来运行。请注意，它很简单 - 它不会展示库的所有功能的全面使用。
简单测试 Blink 动画
在某些情况下，你会发现一个更长的列表，其中可能包括库中其他功能的示例。LED 动画文档包括一系列示例，所有这些示例都在库中可用。这些示例包括基本功能和更复杂功能的演示。只需单击你感兴趣的示例，即可查看相关的代码。
当示例部分中存在多个链接时，实际上所有的示例内容都位于同一页上。第一个链接之后的每个链接都是指向页面指定部分的锚链接。因此，你也可以通过向下滚动页面来查看所有可用的示例。
要查看示例的其余部分，只需单击列表中的链接或向下滚动页面即可。这些示例是完全可用的代码。也就是说，虽然它们可能依赖于其他库以及你正在查看文档的库，但它们不应需要修改才能正常工作。
API 参考
API 参考部分包括库函数和类的列表。库的 API（应用程序编程接口）是库提供的函数和类的集合。实际上，API 定义了你的程序如何与你在代码中调用的函数和类进行交互，以使用该库。
https://circuitpython.readthedocs.io/projects/led-animation/en/latest/api.html
在这个栏目下始终至少一个列表项。对于将代码包含在单个 Python（.py）文件中的库，只会有一个项目。对于代码位于目录中的多个 Python 文件（称为子包）的库，此列表中将有多个项目。LED 动画库具有一系列子包，因此此列表中有多个项目。
单击列表中的第一个项目以开始查看 API 参考部分。
与示例部分一样，API 参考内容都在单个页面上，并且 API 参考下的链接都是指向页面指定部分的锚链接。
点开API 参考部分中的项目后，你将找到有关库中的类和函数的详细信息。在此部分只有一个项目的情况下，库的所有可用功能都将包含在该部分的第一个子部分中。但是，在具有子包的库的情况下，每个项目都包含与链接指示的特定子包的功能。文档将覆盖库的所有可用功能，包括可能不会引起你兴趣的更复杂功能。
第一个列表项是动画子包。如果向下滚动，你将开始看到动画的可用功能。它们按字母顺序列出。你可以在代码中调用这些内容中的任何内容。它包括你将调用的特定函数的名称和描述，以及如果需要任何参数，则列出参数以及其描述。
你可以通过单击左侧的链接或向下滚动页面来查看其他子包。你可能对更实际的东西感兴趣。这里有一个示例。要使用 LED 动画库的彗星动画，你可以运行以下示例。
//******************分割线******************//
# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries
# SPDX-License-Identifier: MIT
&[color=var(--text_link)]#34;"" This example animates a jade comet that bounces from end to end of the strip.
For QT Py Haxpress and a NeoPixel strip. Update pixel_pin and pixel_num to match your wiring if
using a different board or form of NeoPixels.
This example will run on SAMD21 (M0) Express boards (such as Circuit Playground Express or QT Py
Haxpress), but not on SAMD21 non-Express boards (such as QT Py or Trinket).
&[color=var(--text_link)]#34;"" import board
import neopixel
from adafruit_led_animation.animation.comet import Comet
from adafruit_led_animation.color import JADE
# Update to match the pin connected to your NeoPixels
pixel_pin = board.A3
# Update to match the number of NeoPixels you have connected
pixel_num = 30
pixels = neopixel.NeoPixel(pixel_pin, pixel_num, brightness=0.5, auto_write=False)
comet = Comet(pixels, speed=0.02, color=JADE, tail_length=10, bounce=True)
while True:
comet.animate()
//******************分割线******************//
请注意，在创建comet对象的一行中。括号内有许多项。在这种情况下，你提供了一个完全可用的示例。但是，如果你想更改comet的工作方式怎么办？代码本身并没有解释这些选项的含义。
因此，在 API 参考文档列表中，单击adafruit_led_animation.animation.comet链接，向下滚动一点，直到看到以下内容。
这是设置comet对象的文档。它解释了代码中提供的comet设置中的每个参数的含义，以及其他可用的功能。例如，代码speed=0.02。文档说明这是“以秒为单位的动画速度”。代码不包括ring。文档指出这是一个可用的设置，可启用“环模式”。
这种类型的信息对于你在代码中设置的任何函数都是可用的。如果你需要对某些事情有更多的解释，想知道是否有更多的选项可用，或者只是对你编写的代码中涉及的详细信息感兴趣，请查看 Circuit Python 库的文档！
其他链接
这个部分对于每个库都是相同的。它包括指向外部站点的链接列表，你可以访问这些站点以获取有关 Circuit Python 项目和 Adafruit 的更多信息。
这涵盖了 Circuit Python 库文档！当你准备超越指南中介绍的基本库功能，或者你有兴趣更好地理解这些功能时，Read the Docs 上的库文档可以帮助你！
高级设置
Circuit Python旨在降低编程和电子学的入门门槛，这使它非常适合初学者。它也非常可扩展，适用于更复杂的项目，这意味着对于有更多经验的人来说也非常适用。如果你已经有一段时间的编程经验，或者准备探索与Circuit Python一起使用的更高级选项，那么本节非常适合你！
推荐的编辑器
你的开发板上的Circuit Python代码会在检测到文件更改或写入时自动重新启动你的代码。这使得编程非常快速，因为你保存后它会重新运行。
但是，在拔掉或重置开发板之前，你必须等待文件保存完成！在Windows上使用某些编辑器，这有时可能需要长达90秒，在Linux上可能需要30秒，因为文本编辑器未完全保存文件。Mac OS似乎没有这种延迟。
这是非常重要的，请注意。如果在计算机完成将文件写入开发板之前拔掉或重置开发板，可能会损坏驱动器。如果发生这种情况，你可能会丢失已编写的代码，因此定期将代码备份到计算机非常重要。
为了避免文件系统损坏的可能性，请使用在保存时完全写出文件的编辑器。请查看下面推荐的编辑器列表。
- mu是一个安全写入所有更改的编辑器（也是我们推荐的编辑器）
- emacs也是一个编辑器，在保存文件时会完全写入
- Sublime Text能安全写入所有的更改
- Visual Studio Code似乎能安全写入所有的更改
- 在Linux上，gedit似乎能安全写入所有的更改
- Python 3.8.1或更高版本中的IDLE已修复，会立即写入所有更改
- Thonny在保存时会完全写出文件
只推荐在特定设置或附加组件下使用
- vim/vi能安全写入所有的更改。但要设置vim不要no swapfile（.swp文件：记录编辑的临时文件）到CIRCUITPY。使用vim -n运行vim，设置不写入交换文件选项，或设置directory选项以将交换文件写入其他位置。否则，交换文件的写入会触发程序重新启动。
- 如果在设置->系统设置->同步（默认为true）中打开了“安全写入”，PyCharm IDE是安全的。
- 如果你使用Atom，请安装fsync-on-save包或language-circuitpython包，以确保它始终将所有更改写入CIRCUITPY中的文件。
- SlickEdit仅在添加宏以刷新磁盘的情况下才有效。
不推荐使用以下编辑器！
- notepad（默认的Windows编辑器）和Notepad++可能写入速度较慢，因此建议使用上述推荐的编辑器！如果使用notepad，请确保将驱动器弹出。
- Python 3.8.0或更早版本中的IDLE不会立即强制执行更改。
- Linux上的nano不会强制执行更改。
- Linux上的geany不会强制执行更改。
- 其他编辑器未经测试，因此请使用推荐的编辑器！
库文件类型和冻结库
前面已经介绍了Circuit Python库的基本使用方法。将库复制到CIRCUITPY驱动器上，它就可以在你的代码中使用了。
但是，你可能已经注意到有两个可供下载的捆绑包，或者在某些板上，不必复制库即可使用它。这是怎么回事？本页将详细介绍库文件的更深层次的细节，如何使用它们，为什么选择其中一个而不是另一个，以及更多相关的内容。
库文件有两种不同的文件格式：.mpy和.py。每种文件类型都有单独的库捆绑包。Circuit Python可以以三种不同的方式访问库：.mpy文件、.py文件或冻结模块。接下来的几节详细介绍了这些文件类型之间的区别，以及访问库的不同方式。
RAM vs文件系统空间
文中所指的“内存”指的是RAM（随机存取内存），它是微控制器中的读/写内存。RAM和内存在本文中是一个意思。
有一个部分涉及到文件系统空间。文件系统空间不是RAM；它是存储文件的地方。
.mpy库文件
最常用的库文件类型是.mpy文件。你可以直接从其GitHub存储库下载库的.mpy版本，但获取它们的最简单、最方便的方式是从circuitpython.org上的“Libraries”页面(https://circuitpython.org/libraries)下载适当的捆绑包。库页面上的第一个捆绑包是.mpy捆绑包。该捆绑包提供了Adafruit Circuit Python捆绑包中的所有库，都以.mpy格式提供。
“Community Bundle”由社区提供和维护的库组成，也以.mpy格式提供，位于Libraries页面的下方。
什么是.mpy文件？
.mpy文件是通过在.py文件上运行mpy-cross工具生成的文件，该工具将.py文件编译为字节码。这个过程会删除文档字符串并进行一些小的优化。此外，注释、空格和类型提示不会转化为字节码，因此在编译后也不会存在。编译的结果是一个体积较小，占用的RAM内存较少的文件。mpy-cross使得一些库可以作为.mpy文件提供给Circuit Python，否则它们无法作为.py文件导入到较小的板上，因为它们占用的RAM太多，无法在板上编译。
基本上，你可以为Circuit Python提供一个.mpy文件，它会加载到RAM中，但由于它已经编译，所以不需要即时编译。考虑到这一点以及.mpy格式带来的小型优化，它使用的内存比.py文件少。但需要注意的是，.mpy文件是不可读的。如果你想直接查看代码，你需要使用.py文件。
要使用.mpy格式的库，你只需将.mpy库文件复制到CIRCUITPY驱动器上的/lib文件夹中。例如，如果你正在使用需要NeoPixel库的演示程序，你将把neopixel.mpy文件复制到/lib文件夹中。
如果你想要修改库，你会发现你无法编辑.mpy文件。为此，你需要切换到.py文件。
创建一个.mpy文件
使用mpy-cross，你可以将自己的.py文件快速简单地转换为.mpy文件。
从这里下载你操作系统的最新mpy-cross，确保选择与你的Circuit Python版本匹配的mpy-cross版本。可以在Windows、macOS、x64 Linux和树莓派Linux上找到编译版本。例如，如果你使用的是Circuit Python 7.3.0和MacOS Big Sur，你可以下载mpy-cross-macos-bigsur-7.3.0-arm64。为了方便使用，将下载的文件重命名为mpy-cross。
要创建.mpy文件，你首先需要一个.py文件。打开终端程序或命令行，cd进入包含mpy-cross的目录，并运行以下命令：
./mpy-cross path/to/your-library-file.py
这将在与原始.py文件相同的目录中创建your-library-file.mpy文件。
然后，将your-library-file.mpy文件复制到CIRCUITPY驱动器上以使用它。就这么简单！
.py库文件
每个Circuit Python库都可以作为.py文件使用。你可以从各自的GitHub存储库中单独下载.py库文件。更快、更方便的方法是从circuitpython.org上的“Libraries”页面下载捆绑包，然后使用库的.py文件。
捆绑包中的第二个文件是.py文件捆绑包。它包含了Adafruit Circuit Python捆绑包中的所有库的.py版本。
.py文件是什么？
.py文件是一个你可以在你最喜欢的Python编辑器中打开并修改的Python文件。然而，除非你计划修改一个库并测试你的修改，一般来说最好还是使用.mpy文件。基本上，.py文件需要更多的内存，在较小的微控制器上，比如SAMD21（M0），尝试在你的代码中导入库时可能会导致内存分配失败。
冻结库
冻结库是将库文件的内容嵌入到Circuit Python固件中的特殊类型的库。这意味着，当你在使用这种库时，不需要在CIRCUITPY驱动器上复制或加载任何库文件。它们已经包含在Circuit Python固件中。
冻结库是什么？
一些微控制器板，比如Circuit Playground Express，没有足够的内存来运行某些库文件中的代码，即使它们是.mpy格式。在这些情况下，适用的库以及可能的依赖项会被包含在特定板上的Circuit Python构建中。冻结库是指在各种板上的Circuit Python构建中包含的任何库。这样做有两个优点：如果存在内存问题，它也能确保代码的运行，但更实际的是，这意味着你可以在你的代码中访问这些库，而无需将文件复制到CIRCUITPY/lib目录中。
有一个绝佳的例子：Circuit Playground Express。CPX最容易使用Adafruit Circuit Playground库。Adafruit Learn System中的许多指南都使用Circuit Playground库。问题是，如果你复制Circuit Playground库以及其依赖项（Adafruit Circuit Python HID、LIS3DH、Thermistor和NeoPixel）到CPX上，你的代码会因可用内存不足而很快运行失败。Circuit Playground库导入所有的依赖项，所以当你在你的代码中导入它时，你也导入了列表中的其他部分。那么，你可以怎么做呢，那就是将所有这些库都冻结到CPX的Circuit Python固件中！
如果你想知道你的微控制器板的Circuit Python构建中是否包含冻结库，你可以在circuitpython.org的Downloads页面上查看你特定板的信息。搜索你的板，并单击它以打开其特定的下载页面。在当前适用于你的板的每个Circuit Python版本下，你会找到一个&[color=var(--text_link)]#34;内置模块可用："的列表，以及（如果你的构建包含冻结库的话）一个&[color=var(--text_link)]#34;包含的冻结模块："的列表。冻结模块列表包括所有冻结到你的板的Circuit Python中的库。下面显示了circuitpython.org上的PyPortal页面，包括其冻结模块列表，位于下图右下角的洋红色突出显示的部分。
Project Bundle和冻结库
Project Bundle的基础知识在Circuit Python Libraries页面上有介绍。然而，了解Project Bundle与冻结库一起使用时的工作原理非常重要。Project Bundle不知道冻结库的存在。因此，单击&[color=var(--text_link)]#34;下载Project Bundle"按钮会下载一个zip文件，其中包含了一个示例所需的所有库文件，无论这些库是否被冻结到特定板构建中。这不会导致运行库时出现问题（继续阅读本页面以获取详细信息），但这意味着库占用了文件系统空间。如果这对你造成问题，你可以从CIRCUITPY/lib目录中删除任何被冻结到你的板的Circuit Python构建中的库文件。
注意，adafruit_bus_device是一个特例。它作为一个真正的模块内置到大多数板的Circuit Python中（你可以在&[color=var(--text_link)]#34;内置模块可用："列表中看到）。Project Bundle也不知道它，因此它也包含在下载中。只要你在Downloads页面上看到它，你也可以从你的微控制器上删除它。 正如你所看到的，所有的&[color=var(--text_link)]#34;包含的冻结模块："也都包含在从Project Bundle下载的/lib目录中。因此，如果你开始在Circuit Playground Express上的文件系统空间不足，你可以从CIRCUITPY/目录中删除与Downloads页面上的列表匹配的文件，以释放更多空间。这适用于任何包含冻结库的微控制器的项目包。 库文件优先级
Circuit Python在微控制器上寻找特定的库文件类型，以特定的顺序在特定的位置。当你尝试使用更新或修改过的库时，你可以利用这一点。
如果你想测试你对一个以.mpy文件或冻结到Circuit Python中的库文件所做的修改或更新，有几种方法可以做到这一点。要测试你的更新，你可以将更新的.py库文件复制到CIRCUITPY驱动器的适当位置。特定于冻结库，你可以创建一个包含更改的Circuit Python固件。
Circuit Python会寻找哪些库文件？
库文件的开发需要在微控制器上实时测试库的更改，以确保它们正常工作。这意味着要更新.py文件，将其复制到CIRCUITPY，并运行使用你的更新的示例。然而，一旦你进入开发环节，你可能会在不同格式的库文件上拥有多个副本。你如何确定Circuit Python是否运行了更新的文件？——>检查格式。
Circuit Python将首先尝试运行一个.py文件。这意味着如果你有一个.py库文件和同一个库的.mpy文件在同一个目录中，Circuit Python将运行.py文件。
例如，如果你在CIRCUITPY的/lib文件夹中有neopixel.py和neopixel.mpy，那么neopixel.py文件将优先于neopixel.mpy文件。因此，在你的code.py文件中导入neopixel来测试你的更新时，它将导入你的更新库。如果你在CIRCUITPY驱动器的根目录中有相同的.py和.mpy文件，结果将是相同的。
CIRCUITPY上各种库文件的位置也影响Circuit Python在选择文件时的工作方式。在下一节中了解具体情况。
Circuit Python在哪里查找库文件？
测试你的库修改在微控制器上非常重要。冻结库对此可能造成一些困难，因为你不能从板上删除它们。因此，Circuit Python以特定的顺序在不同的位置查找库文件，以允许你&[color=var(--text_link)]#34;覆盖"其他位置的库文件。你知道这个顺序是什么吗？这就是sys.path的作用。 在Circuit Python（和Python）中，sys.path是sys模块中的一个变量，返回一个字符串列表，指定模块或库文件的搜索路径。更简单地说，它允许你告诉Circuit Python确切地在哪里以及以什么顺序查找CIRCUITPY驱动器上的库文件。
要了解具体情况，你可以在code.py中运行以下两行代码，或在你当前使用的板的REPL中运行它们。如果特定板的Circuit Python构建中包含冻结模块，结果将如下所示：
//******************分割线******************//
>>> import sys
>>> print(sys.path)
//******************分割线******************//
如果特定板的Circuit Python构建中没有冻结模块，结果将如下所示：
//******************分割线******************//
>>> import sys
>>> print(sys.path)
//******************分割线******************//
这实际上意味着什么呢？你可以将结果分解如下。
如果特定板的Circuit Python固件中内置了冻结库，Circuit Python将按照以下顺序在以下位置查找库文件：
1. 当前目录（CIRCUITPY/）
2. 根目录（CIRCUITPY/）
3. 冻结库（.frozen在这个目的上是一个虚假的目录，因为冻结模块不在文件系统中）
4. 库文件夹（CIRCUITPY/lib）
如果特定板的Circuit Python构建中没有冻结库，Circuit Python将按照以下确切顺序在以下位置查找库文件：
1. 当前目录（CIRCUITPY/）
2. 根目录（CIRCUITPY/）
3. 库文件夹（CIRCUITPY/lib）
从实际角度来看，这意味着什么呢？以下是一些示例。
1. 如果你将一个库的.mpy版本放入/lib文件夹中，然后发现问题。然后你获取了该库文件的.py版本，进行了更改，并准备测试。你可以将修改后的.py文件复制到CIRCUITPY/的根目录中，这将“覆盖”.mpy文件，因为Circuit Python首先找到你的修改的.py文件并运行它。
2. 如果你正在使用一个冻结到Circuit Python中的特定库的微控制器板，并且你发现问题。你可以将修改后的.py文件放在CIRCUITPY/的根目录中，这将“覆盖”冻结模块，因为Circuit Python首先找到你的修改的.py文件并运行它。
你还可以在修改的.py文件上运行mpy-cross，并将.mpy文件放在CIRCUITPY/的根目录中，这将“覆盖”冻结模块和lib/文件夹中的所有文件。如果你发现使用.py文件导致代码由于内存问题而运行失败，这是必需的。
从本质上讲，这也意味着你可以将库文件放在CIRCUITPY/驱动器的根目录上，它们将像在/lib文件夹中一样运行。然而，如果你总是将库文件复制到/lib文件夹中，那么在测试之前，这种测试技巧始终可用，而无需在测试之前删除文件。
使用更新的冻结库构建Circuit Python
对于一些板，例如Circuit Playground Express，你会发现使用冻结模块覆盖将导致代码运行失败，因为内存分配失败。在某些情况下，即使在.py文件上运行了mpy-cross，你的代码仍然会失败。这意味着你可能需要创建一个包含你的修改库的Circuit Python版本。
测试冻结库的更困难但更现实的方法是构建Circuit Python固件，并在其中包含你的修改库。这是最现实的测试方法，因为它确保更改仍适用于特定的Circuit Python构建。它还允许你在即使作为.mpy文件的情况下，由于内存限制而无法运行的情况下测试库。但是，对于某些人来说，这是一个令人生畏的前景，当他们想测试他们对库的简单更改时。
在这之前，你需要按照此处的步骤复制要修改的库的副本到你的计算机上。在本地库目录内进行修改。当你准备测试时，你将整个库目录，例如Adafruit_CircuitPython_CircuitPlayground/目录，复制到Circuit Python存储库的本地副本的根目录中的frozen/目录中。这将替换现有版本并使用你的更新版本。
一旦在frozen/目录中用你的修改版本的库目录更新了，你就可以开始构建了。继续按照&[color=var(--text_link)]#34;构建Circuit Python"指南中的说明完成Circuit Python的构建。请记住，如果与示例中的板不同，要更改你要构建的板。构建完成后，将固件.uf2文件复制到*BOOT驱动器中。
这个构建是为Circuit Playground Express准备的。
现在，你可以测试你的更改了！
实际区别是什么？
你现在了解了Circuit Python库以不同方式使用、访问和测试修改的方式。但是，你如何知道这些不同的选项实际上在内存使用方面有什么差异呢？有一种通过数字来查看实际差异的简单方法。
.mpy和.py之间的内存使用情况
导入Python文件有两部分会使用额外的内存。代码编译过程以及在编译过程中和之后需要在内存中存储的生成的字节码。请记住，.mpy文件已经编译过了，不需要在导入时进行编译。
本质上，导入.mpy会加载已编译的代码，而导入.py必须在导入时编译代码。在这两种情况下，已编译的代码都存储在RAM中，生成的编译代码基本上大小相同。但是，编译过程在编译期间需要额外的RAM，如果可用的RAM不足，这个过程将会失败。编译也可能导致一些碎片，但在Circuit Python中大多数情况下都可以避免这种情况。
可以这样来看待。你可以将一个已经做好的蛋糕带到朋友家，也可以带上在朋友家烘烤相同蛋糕的材料。完成的蛋糕将占用相同数量的空间。但是，在做蛋糕之前，为了将成分组合在一起、烘烤它并撒上糖霜，你将需要更多的空间和资源。如果事实证明你的朋友没有足够的空间，或者缺少重要的成分，你将无法完成蛋糕。基本上，如果你不确定朋友家是否有足够的空间和资源来烘烤蛋糕，最好带上一个已经做好的蛋糕，以确保有蛋糕可供享用！
如果你不确定你的微控制器板是否具有运行.py库版本所需的内存资源，最简单的解决方法是选择.mpy文件。
使用gc.mem_free()来检查你的字节
Circuit Python具有内置的gc（garbage collector）模块，其中包括gc.mem_free()。其中mem_free()功能专门适用于Circuit Python（和Micro Python），因此在CPython的gc模块中不可用。
当你在REPL中运行gc.mem_free()或在code.py中运行print(gc.mem_free())时，它会返回可用的RAM的字节数。这是剩余的RAM量，用于导入更多库和执行代码。对于我们的目的来说，它将告诉我们导入.mpy文件、.py文件和冻结模块时使用了多少内存。
为了进行这个示例，你将使用Circuit Playground Express上的NeoPixel库。NeoPixel库被冻结到CPX的Circuit Python固件中，并且可以在两个包中找到：neopixel.mpy和neopixel.py。为了准备进行测试，你需要连接到串行控制台并进入REPL。
对于这些示例中的每一个，你首先要从REPL中运行以下命令：
//******************分割线******************//
>>> import gc
>>> gc.mem_free()
//******************分割线******************//
这将为你提供在导入任何其他库之前的可用内存基准。
首先，你将测试导入NeoPixel库的冻结版本时使用了多少内存。确保CIRCUITPY驱动器上没有复制到任何地方的库文件，包括/lib中！
一旦你确定了基准，如上面所述，运行以下命令：
//******************分割线******************//
>>> import neopixel
>>> gc.mem_free()
//******************分割线******************//
正如你所看到的，基准可用内存为17840字节。一旦导入冻结版本的NeoPixel库，你的可用内存就会减少到16432字节。导入冻结版本需要占用1408字节内存。
现在，你将测试导入NeoPixel库的未冻结.py版本时使用了多少内存。在CIRCUITPY的根目录中将neopixel.py文件复制到CIRCUITPY中。确保在此之前删除/neopixel.mpy文件，否则CircuitPython将首先运行冻结版本。
按照上述步骤进行相同的操作，获取基线并显示导入后的可用内存。
基准相同，但导入后的可用内存现在为13984字节。导入neopixel.mpy需要3856字节。
接下来，从CIRCUITPY驱动器中删除neopixel.mpy文件。将neopixel.py文件复制到CIRCUITPY/驱动器的根目录。
按照上述步骤进行相同的操作，获取基准并显示导入后的可用内存。
基准相同，但导入后的可用内存现在为11680字节。导入neopixel.py需要6160字节。
通过查看基准和导入后的内存使用情况，你可以确定使用.mpy或.py版本的库文件时需要多少内存。在大多数情况下，使用.mpy版本可以帮助你节省内存，因为它在导入时使用的内存较少，从而为你的应用程序留出更多的空间。
常见问题和解决方法
本页已经讲解了获取、访问和测试Circuit Python库修改的不同方法。以下是你在操作过程中可能遇到的一些问题以及处理建议。
.mpy以前正常工作，但现在不能运行
你需要确定你下载了库的.mpy版本，并且以前使用.mpy文件运行代码，但现在由于内存使用而失败。最常见的原因是在同一目录中留下了相同库的.py版本（例如，.py和.mpy都在/lib中），或者.py文件位于“覆盖”目录中（例如.py位于/中，.mpy位于/lib中）。在这两个示例中，Circuit Python都将加载.py文件。
如果遇到此问题，请查看CIRCUITPY驱动器的内容，并确保在/或/lib中没有剩余的.py文件。往往情况下，删除.py文件将解决此问题。
内存分配
Circuit Playground Express是一款内存受限的微控制器板。在字节检查示例中，将Circuit Playground库替换为NeoPixel库会导致冻结模块和.mpy文件的行为相似。但是，如果你尝试将Circuit Playground库导入为.py包，它将无法导入，并显示类似下面的错误。
Circuit Playground库是一个很好的例子，因为该库非常大，导入了大量的依赖项，绝对不能作为.py文件在CPX上运行。这不适用于所有嵌入到Circuit Python各种版本中的库（如NeoPixel所示），因此在尝试测试修改或更新时，你不会始终得到此结果。
内存碎片化
内存分配失败并不一定意味着你完全没有内存。Circuit Python内存会随着操作的增加而变得碎片化，整个内存上会有较小的内存块可用，这些内存块加起来足够使用，但没有足够大的块可用于分配给特定任务所需的内存。碎片化可能阻止分配需要连续内存块的任何内存块，例如大型缓冲区。在导入库文件的上下文中，它具体指的是没有足够大的内存块来分配所请求的内存。
在导入.mpy文件的情况下，编译的字节码跨越多个块进行导入。在导入.py文件的情况下，编译所需的内存可能超过了可用块的大小，在这种情况下，在导入任何字节码之前，内存都可能会耗尽。
Circuit Python确实会进行一些优化以避免内存碎片化。一旦成功导入库，它将被移动到可用内存的末尾，从而减少了碎片化。随着时间的推移，一些碎片化是无法避免的，但导入优化确实有助于减少初始碎片化。
导入顺序可能很重要
如果你的代码在导入时失败，你可能会发现更改导入顺序可以使代码运行。在导入任何内容之前，会有较大的内存块可用。因此，在仍然有较大内存块可用的情况下，首先导入较大的库可能会使你的代码成功运行，即使最初失败了。这不是一个保证的结果，但在某些情况下可能有所帮助。
库结构不完整或不在正确的目录中
请记住，库文件有两种结构 - 单个文件和包含多个文件的目录。这些结构必须保持完整，以便Circuit Python能够使用库。对于单个文件，将该独立文件复制到CIRCUITPY驱动器上。对于目录，将整个目录及其内容复制到CIRCUITPY驱动器上。
此外，库文件不能放在另一个目录中。例如，如果你在CIRCUITPY上创建了一个neopixel/目录，并在其中放置了neopixel.mpy，你的代码将失败。Circuit Python不会检查多余的目录以寻找库文件或包。
在上述任何情况下，当你尝试在代码中使用库时，你的代码将失败。当Circuit Python无法找到库文件中使用的模块时，它会抛出错误。错误通常会类似于以下内容。（此错误特定于尝试在一个neopixel/目录中的neopixel.mpy中的code.py中创建像素对象的尝试。）
不要将测试代码命名为与库相同
在你的Circuit Python体验中，你将编写各种不同的演示。显然，你需要为文件命名其他名称，而不是code.py，以便在多个演示中进行工作，这样你知道文件是什么，并且Circuit Python知道你当前要运行哪个文件。但是，在这样做的过程中，有一个严重的注意事项，可能会导致各种问题并使故障排除变得困难。你必须避免将文件命名为与库文件相同的名称。
假设你编写了一个NeoPixel示例。然后，你准备好进行其他示例。因此，你将当前的code.py重命名为neopixel.py，并继续下一个演示。下次需要在代码中使用NeoPixel库时，你将发现你的代码将失败。这是因为它尝试导入先前重命名为neopixel.py的代码，当然不包含库内容。
避免这种情况的最佳方法是在文件名中保持创意性。例如，始终在名称中包含代码（即neopixel_code.py），或者更详细地进行命名，称其为neopixel_all_pixels_red.py。这是两个简单的建议。还有很多其他创意命名文件的方法。
PyCharm 和 Circuit Python
PyCharm是一款功能齐全的Python编辑器，包括诸如代码自动完成和错误突出显示等非常实用的功能。它在Community Edition中提供免费下载。
通过以下步骤利用PyCharm IDE编译Circuit Python：
1. 禁用PyCharm的自动保存功能
2. 在本地系统驱动器上创建项目并将CIRCUITPY添加为内容根
3. 安装circuitpython-stubs
4. 安装你正在使用的任何库
5. 在终端窗格内连接到串行控制台（可选）
禁用自动保存功能
默认情况下，PyCharm会非常频繁地自动保存你正在工作的代码文件。这通常很好，但对于CIRCUITPY驱动器来说可能不理想，因为它会导致设备更频繁地重置和重新运行代码。当你使用PyCharm直接编辑CIRCUITPY驱动器上的文件时，最好禁用自动保存功能，并在准备运行新版本的code.py时手动保存（使用CTRL+S）。
要禁用自动保存，请按照以下步骤操作：
1. 使用CTRL+ALT+S打开设置，或点击文件->设置。
2. 打开外观和行为->系统设置。
3. 取消选中“如果IDE空闲X秒，则保存文件”框。
4. 取消选中“切换到其他应用程序时保存文件”框。
在计算机文件系统上创建项目
PyCharm喜欢创建一个名为“.idea”的文件夹，其中保存项目的配置设置和元信息。此文件夹在你正在工作的项目的根目录中创建。理想情况下，我们不希望它最终出现在CIRCUITPY驱动器上，因为它会占用宝贵的存储空间并在其中的文件被更改时导致设备重置。我们通过在计算机硬盘上创建项目，然后将CIRCUITPY或包含它的目录添加为“内容根”来避免这种情况，这样PyCharm将显示CIRCUITPY驱动器上的文件作为项目的一部分。
1. 点击文件->新建项目。
2. 为项目输入名称。可以使用`DEVICE_WORKSPACE`，但你可以选择任何你喜欢的名称。
3. 输入或浏览到你计算机硬盘上存储项目目录的位置。
4. 点击“创建”按钮。
5. 在打开的新项目中，点击文件->设置，或按CTRL+ALT+S打开设置窗口。
6. 打开“项目 [YOUR_PROJECT_NAME]”，然后点击“项目结构”。
7. 点击窗口右侧的“+添加内容根”按钮。
下一步取决于你的操作系统。
- 如果你使用的是Linux，请键入或导航到`/media/[username]/`，其中[username]是计算机上的实际用户名。点击“确定”将此目录添加为内容根。
- 如果你使用的是Mac，请键入或导航到`/Volumes/`，然后点击“确定”将此目录添加为内容根。
- 如果你使用的是Windows，请键入或导航到与你的CIRCUITPY驱动器匹配的驱动器号，例如D:，然后点击“确定”将此目录添加为内容根。
在Windows上，如果在连接Circuit Python设备时打开项目，添加的内容根可能最终为空，或者如果由于插入其他可移动存储设备而导致设备的驱动器号更改，则可能显示为空。重复上述说明以重新添加具有当前驱动器号的设备。你还可以在同一设置窗口中点击旧的/不起作用的内容根上的“X”将它们从列表中删除。
完成这些步骤后，你将在计算机硬盘上拥有一个项目，其中将存储`.idea`目录。你还将可以访问连接到计算机的CIRCUITPY驱动器。
安装circuitpython-stubs
circuitpython-stubs将让PyCharm获取有关Circuit Python中内置核心模块的更多信息，以便提供相关的代码提示和类型信息。这些存根在PyPi上发布，可以通过PyCharm的设置窗口安装。
1. 点击文件->设置，或按CTRL+ALT+S打开设置窗口。
2. 打开“项目：[YOUR_PROJECT_NAME]”，然后点击“Python解释器”。
3. 在窗口右侧点击“+安装”按钮。
4. 在搜索栏中键入“circuitpython-stubs”。
5. 选择`circuitpython-stubs`软件包，然后按左下角的“安装软件包”按钮。
安装库
如果你的项目使用Circuit Python Library Bundle中的库，你可以在计算机上安装它们（如果它们已发布到PyPi）。这样做将为PyCharm提供有关库的信息，以提供更相关的代码提示和类型信息。
使用上述说明打开“可用软件包”窗口，然后在搜索框中输入“adafruit-circuitpython-”以查看所有已部署到PyPi的库。
在终端窗格中的串行控制台
要打开终端窗格，请点击“视图”->“工具窗口”->“终端”。
使用screen或tio连接到你的设备。然后，你可以查看输出并与设备和REPL进行交互。
京公网安备 11010502049360号 ) | 网站地图
| 2012- WGPro.CoM |
