注意内容 重要内容
Circuit Python库
随着Circuit Python开发的持续进行和新版本的发布，Adafruit将停止支持旧版本。请访问https://circuitpython.org/downloads以下载适用于你的开发板的最新版本的Circuit Python。你必须下载与你的Circuit Python版本匹配的Circuit Python库捆绑包。请更新Circuit Python，然后访问https://circuitpython.org/libraries以下载最新的库捆绑包。
你运行的每个Circuit Python程序都需要有许多附加信息才能正常工作。Circuit Python之所以如此简单易用，是因为大部分底层运行代码都存储在其他文件中，并在后台运行。这些文件被称为库。其中一些库内置在Circuit Python中。其他库存储在你的CIRCUITPY驱动器上的一个名为"lib"的文件夹中。Circuit Python的一个优点是能够将代码与固件本身分开存储。将代码与固件分开存储使得更容易同时更新你编写的代码和你依赖的库。
你的开发板可能已经附带了一个名为"lib"的文件夹，它位于驱动器的基本目录中。如果没有，只需自行创建该文件夹。当你首次安装Circuit Python时，将为你创建一个空的"lib"目录。
Circuit Python库与常规Python模块的工作方式相同，因此Python参考文档(https://docs.python.org/3/tutorial/modules.html)是如何工作的极好参考。在Python术语中，你可以将我们的库文件放在"lib"目录中，因为它默认是Python路径的一部分。
这种把库文件分开存放的方法的一个缺点是它们不是内置的。要使用它们，需要在使用之前将它们复制到CIRCUITPY驱动器上。不过幸运的是，我i们准备了一个库文件的捆绑包。
捆绑包和GitHub上发布的库文件还包含了优化版本的库，具有".mpy"文件扩展名。这些文件在驱动器上占用更少的空间，并且占用更小的内存空间，因为它们加载时的内存占用更小。
由于定期的更新和空间限制，Adafruit不会随附整个捆绑包。因此，当你开始使用开发板时，你需要加载所需的库。你可以在你的开发板指南中找到依赖于外部库的示例代码。
无论用上面的哪种方式，当你开始学习Circuit Python时，你都会想知道如何将库文件加载到开发板上。
Adafruit学习指南项目捆绑包
从Adafruit学习系统中获得项目最快、最简单的方法是使用项目捆绑包。现在，大多数指南的完整代码示例顶部都有一个“下载项目捆绑包”按钮。点击此按钮将下载所有必要的文件，包括图像等，以使项目指南能够运行起来。只需点击按钮，打开生成的zip文件，复制正确的文件，即可开始使用！
第一步是在你正在使用的指南中找到“下载项目捆绑包”按钮。
在学习指南中，仅完整的GitHub演示代码才会有“下载项目捆绑包”按钮。代码片段将不会有该按钮。
当你将项目捆绑包的内容复制到CIRCUITPY驱动器上时，它将替换所有现有内容！如果你不想丢失任何内容，请确保在复制新的项目捆绑包内容之前将当前代码复制到计算机上！
“下载项目捆绑包”按钮会下载一个zip文件。此zip文件包含一系列目录，其中包含code.py、图像或音频等相关资产，以及包含所有必要库的lib/文件夹。下面的zip文件是从"Lime钢琴按键"指南中下载的。
在这里选择了"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库捆绑包。
还有一个名为"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驱动器上打开"lib"文件夹。然后，打开从下载的zip文件中提取的"lib"文件夹。在里面，你会找到许多文件夹和.mpy文件。找到你想要使用的库，将其复制到CIRCUITPY上的"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("modules")命令。这个命令提供了你的开发板上所有内置模块的列表。因此，如果你连接到开发板上的串行控制台，并进入REPL，你可以运行help("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驱动器上的"lib"文件夹中。接下来一个adafruit_lis3dh，也不在模块列表中。对于adafruit_lis3dh，你可以按照同样的过程进行操作，找到adafruit_lis3dh.mpy并复制它。
第五个是usb_hid，它在模块列表中，因此它是内置的。通常，所有内置模块都会首先出现在导入列表中，但有时不会！不要假设第一个库之后的所有内容都是库，要根据模块列表验证每个导入是否正确。否则，你会搜索捆绑包，却找不到任何内容！
最后两个导入项不太清楚。请记住，当导入语句格式如下时，从关键字‘from
’后的第一个是库名。在这种情况下，库名是adafruit_hid。在捆绑包中搜索adafruit_hid，你会找到一个adafruit_hid文件夹。当一个库是一个文件夹时，你必须将整个文件夹及其内容复制到CIRCUITPY驱动器上的"lib"文件夹中。在这种情况下，你将整个adafruit_hid文件夹复制到CIRCUITPY/lib文件夹中。
请注意，有两个以adafruit_hid开头的导入项。有时你需要从同一个库中导入多个内容。无论你从同一个库中导入多少次，只需要复制一次adafruit_hid文件夹以加载库。
这就是你可以使用示例代码来确定要在Circuit Python兼容的开发板上加载哪些库的方法！
但是，有些情况下，库在内部需要其他库。在库存在依赖关系的情况下，最简单的方法是连接到串行控制台，并根据打印的ImportError进行操作。下面是一个缺少库时出现ImportError的非常简单的示例，但是对于任何缺少库的情况，其概念是相同的。
示例：由于缺少库而引发的ImportError
如果你选择按需加载库文件，或者使用现有示例开始，你可能会遇到尝试使用尚未加载到开发板上的库的代码。此部分将演示当你尝试使用尚未加载到开发板上的库时会发生什么，并介绍解决此问题所需的步骤。
只有当你尚未将所需的库加载到CIRCUITPY驱动器上的"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。它说没有名为'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指南中的使用页面。
