CircuitPython调试指南：串口输出、自动重启与安全模式解析

1. 项目概述：CircuitPython调试中的那些“坑”与“灯”

搞嵌入式开发，尤其是用CircuitPython这类对新手友好的环境，最怕的不是代码写不出来，而是代码跑不起来，或者跑起来行为诡异，你却两眼一抹黑，不知道问题出在哪。我遇到过不少刚接触的朋友，对着一个不断重启的板子，或者一个空空如也的串口监视器窗口抓耳挠腮，最后怀疑是硬件坏了。其实很多时候，问题就出在我们对CircuitPython运行时的一些“小脾气”和状态指示机制不够了解。

CircuitPython设计得非常贴心，它通过板载的RGB状态灯（Status LED）和串口控制台（Serial Console）提供了丰富的运行时信息。但如果你不知道这些闪烁的灯光和滚动的文字在“说”什么，它们就只是一些无意义的闪烁和字符。更棘手的是，一些看似是硬件或代码底层的问题，根源可能仅仅是你的串口监视器窗口开得太小，或者电脑上某个不起眼的备份软件在“默默耕耘”。本文将深入拆解两个最常让人困惑的现象：串口输出信息丢失和程序无故自动重启，并详解终极救星——安全模式（Safe Mode）的进入方法与使用场景。理解这些，就相当于拿到了CircuitPython系统的“诊断手册”，能让你在调试时事半功倍。

2. 串口输出：为什么我的错误信息消失了？

串口输出是我们与CircuitPython板子对话的主要窗口，所有的print()语句、未捕获的异常信息（Traceback）都会从这里打印出来。但很多时候，我们打开串口监视器，可能只看到一片空白，或者只有一行“Press any key to enter the REPL”的提示，然后就武断地认为程序没跑起来或者崩溃了。这种情况，十有八九是串口面板的“显示”问题，而非代码或硬件问题。

2.1 错误信息被“截断”的典型场景

想象一下，你的code.py里有一个简单的语法错误，比如少了一个括号：

print("Hello, World"

CircuitPython启动执行到这一行时，会抛出一个SyntaxError，并在串口生成类似下面的追踪信息：

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 2 SyntaxError: invalid syntax Press any key to enter the REPL. Use CTRL-D to reload.

这段信息大概有6行。如果你的串口监视器窗口（例如Mu编辑器、PuTTY或VS Code的串行监视器）面板高度只设置了显示5行甚至更少，那么会发生什么？你只能看到最后面的几行，也就是：

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

更复杂的错误，追踪栈可能更长，达到十几行。如果面板高度不足，你看到的可能就只是最后的那句提示，或者干脆是几行空白。这直接导致你错过了定位问题的关键信息——那个指向具体文件和行号的Traceback。

实操心得：我习惯在开始调试任何新问题前，第一件事就是把串口监视器的滚动缓冲区（Buffer Size）调大（比如10000行），并把显示区域拉高，确保能完整看到一大段输出。这能避免很多不必要的、针对硬件或电源的无效排查。

2.2 如何确保捕获完整输出

解决这个问题的方法非常简单，但必须养成习惯：

1. 调整面板尺寸：鼠标悬停在串口输出面板的上边缘，当光标变成双箭头时，拖动以增加面板的高度。
2. 使用滚动条：检查并利用右侧的滚动条，向上滚动，查看是否历史输出中有被“顶上去”的错误信息。
3. 检查工具设置：不同的串口工具设置不同。在Mu编辑器中，确保没有勾选“清除输出”之类的选项。在命令行工具如screen或picocom中，记得检查其回滚（scrollback）设置是否足够。

这个原则适用于所有串口输出，无论是错误信息还是你主动打印的调试日志。所以，下次当你觉得程序“毫无反应”时，别急着拔线，先向上滚动看看，或者把窗口拉大一点。

3. 自动重启（Auto-Reload）的烦恼与应对

CircuitPython有一个非常方便的功能叫自动重载（Auto-reload）。当你通过USB把修改后的code.py或boot.py文件保存到CIRCUITPY磁盘时，CircuitPython会自动检测到文件变化，并软重启来运行新代码。这极大地简化了开发流程，实现了“保存即运行”。

3.1 是什么导致了意外的“无限重启”？

这个便利的特性有时会变成噩梦：你的板子在没有进行任何文件保存操作的情况下，也开始不停地重启。现象就是板载LED频繁闪烁（通常是先熄灭再亮起），CIRCUITPY盘符在电脑上时而出现时而消失，程序根本无法稳定运行。

根源在于：任何对CIRCUITPY驱动器的写入操作，都会触发自动重载。除了你手动保存文件，电脑上一些后台程序也会默默地写入这个“可移动磁盘”。

• 杀毒/安全软件：这是最常见的“凶手”。许多杀毒软件、系统清理工具或备份软件（如Acronis True Image）会定期扫描新插入的可移动设备，并可能写入一些元数据或索引文件。在Windows平台上，Acronis的“Managed Machine Service Mini”服务就因此“臭名昭著”。
• 磁盘工具：磁盘查错（如chkdsk）、索引服务（Windows Search）或云盘同步客户端（如Dropbox、OneDrive）如果将其同步文件夹设置在CIRCUITPY，也会导致频繁写入。
• 操作系统行为：某些操作系统可能会为磁盘创建缩略图缓存（Thumbs.db）、资源索引（.Spotlight-V100）或回收站元数据。

这些后台写入可能每秒发生多次，导致CircuitPython陷入“写入 -> 重启 -> 初始化 -> 被写入 -> 再重启”的循环。

3.2 诊断与根治方案

遇到无故重启，可以按以下步骤排查：

1. 观察与隔离：拔掉板子，观察电脑上是否有其他外置存储设备。重新插入板子，打开任务管理器（Windows）或活动监视器（macOS），在CIRCUITPY盘符出现后，观察磁盘活动情况。同时，暂时关闭所有非必要的后台应用，特别是杀毒、备份和云同步软件。
2. 针对性禁用服务：如果怀疑是特定软件（如Acronis），可以尝试在服务管理器中找到并禁用对应的服务。这不是长久之计，但能用于验证问题源头。
3. 终极方案：禁用自动重载：如果无法彻底阻止后台写入，或者你希望获得一个绝对稳定的运行环境（比如在部署最终项目时），可以永久关闭自动重载功能。这需要你在boot.py或code.py文件中添加两行代码：

   import supervisor supervisor.runtime.autoreload = False

   强烈建议将这段代码放在boot.py中。因为boot.py在code.py之前运行，且不受自动重载影响（修改boot.py后需要硬复位才能生效）。这样一来，任何对CIRCUITPY的写入都不会再触发重启，你的程序会一直运行，直到你手动复位。

注意事项：关闭自动重载后，你修改code.py后需要手动按一下板子的复位键（RESET）才能让新代码生效。这虽然多了一步操作，但换来了运行时环境的绝对稳定，在项目调试后期或演示时非常有用。

4. 读懂状态灯：CircuitPython的“摩尔斯电码”

状态灯是板子与你无声交流的窗口。不同颜色、不同闪烁模式代表了CircuitPython内核的不同状态。从7.0.0版本开始，闪烁模式经过了简化以省电，但传达的信息依然清晰。

4.1 CircuitPython 7.0.0 及之后版本

• 启动阶段（黄色闪烁）：上电或复位后，LED会快速闪烁黄色约1秒。这是一个进入安全模式的关键窗口期！在这1秒内按下复位键，板子将重启并进入安全模式。
• 启动后（常规闪烁）：如果没有用户代码运行，板子会每5秒闪烁一次，报告状态：
  • 1次绿色闪烁：code.py成功执行完毕，正常退出（无错误）。
  • 2次红色闪烁：用户代码因未捕获的异常（Exception）而崩溃。此时必须查看串口输出，那里有详细的错误信息。
  • 3次黄色闪烁：板子运行在安全模式。没有执行任何用户代码。同样需要查看串口确认进入安全模式的原因。
• REPL模式（常亮白色）：当你按下任意键进入交互式REPL环境时，LED会变为常亮白色。

4.2 CircuitPython 6.3.0 及更早版本

早期版本的指示灯逻辑更复杂一些：

• 常亮绿色：code.py正在运行。
• 呼吸绿色：code.py已执行完毕或不存在。
• 常亮黄色（启动时）：等待复位以进入安全模式。
• 呼吸黄色：已处于安全模式（因崩溃而重启后）。
• 常亮白色：REPL正在运行。
• 常亮蓝色：boot.py正在运行。
• 彩色闪烁+计数闪烁：当发生Python异常时，会先通过一种颜色闪烁指示错误类型（如青色代表SyntaxError），然后通过多组闪烁指示错误发生的行号（千位、百位、十位、个位分别用不同颜色表示）。这套“密码”功能强大但解读稍显繁琐，这也是7.0.0版本简化它的原因。

理解这些灯光信号，你就能在不连接电脑的情况下，对板子的状态有个基本判断。看到红灯两闪，就知道该去连串口看错误了；看到黄灯三闪，就明白它进了安全模式。

5. 安全模式：系统恢复的“安全屋”

安全模式是CircuitPython的一个特殊启动状态，可以理解为嵌入式系统的“安全模式”。它的核心特点是：不自动运行boot.py和code.py，并禁用自动重载。这使它成为系统恢复的利器。

5.1 什么情况下需要安全模式？

1. 文件系统只读或丢失：你的CIRCUITPY驱动器突然变成只读，甚至完全从文件管理器里消失，显示为NO_NAME。
2. 代码导致死锁或启动循环：code.py或boot.py中的代码有严重错误（如死循环、硬件初始化冲突），导致板子一启动就卡死或不断重启，你根本没有机会通过正常方式修改文件。
3. 误操作锁死系统：例如，在boot.py中写入了将CIRCUITPY设为只读或完全卸载的代码，导致下次启动后无法再写入任何文件。

5.2 如何进入安全模式？

进入方法因主版本不同而略有差异，但核心都是在启动初期的特定时间窗口内按下复位键。

• CircuitPython 7.x 及以后：板子上电或复位后，会有1秒钟的等待时间，此时状态灯会闪烁黄色。在这1秒内再次按下复位键，即可进入安全模式。你可以把它想象成一个“慢速的双击复位”（快速双击是进入UF2引导加载程序）。
• CircuitPython 6.x：上电或复位后，有0.7秒的等待时间，状态灯会常亮黄色。在此时间内按下复位键进入安全模式。

这个操作需要一点手速和时机把握。如果失败，只需重新上电再试即可。

5.3 安全模式下能做什么？

成功进入后，状态灯会以特定模式闪烁（7.x为间歇性黄灯三闪，6.x为呼吸黄灯）。连接串口控制台，你会看到明确的提示信息：

Auto-reload is off. Running in safe mode! Not running saved code. CircuitPython is in safe mode because you pressed the reset button during boot. Press again to exit safe mode. Press any key to enter the REPL. Use CTRL-D to reload.

此时，CIRCUITPY驱动器应该会以可读写的方式重新出现在你的电脑上。你现在可以：

1. 删除或修复问题文件：直接找到导致问题的code.py或boot.py，进行删除或修改。
2. 检查文件系统：浏览CIRCUITPY，看看是否有异常文件。
3. 通过REPL修复：如果需要更高级的操作（如修复文件系统），可以按任意键进入REPL。

完成修复后，再次按下复位键，或者拔插USB线，即可让板子正常重启，退出安全模式。

避坑技巧：如果你不确定是哪个文件导致问题，最安全的方法是先将code.py和boot.py都重命名（如code.py.bak）或移动到电脑备份，然后让板子空载启动。如果能正常启动，再逐一排查文件内容。

6. 文件系统损坏与彻底修复

如果安全模式都无法解决CIRCUITPY驱动器的问题（例如，在安全模式下依然无法识别或写入），那很可能文件系统已经损坏。这通常是由于未安全弹出就断开USB连接，或者在写入过程中突然断电/复位导致的。

6.1 首选方案：通过REPL擦除文件系统（CircuitPython 2.3.0+）

这是最干净、最推荐的方法，但前提是你能进入REPL（可以在安全模式下进入）。

1. 连接串口，按任意键进入REPL（>>>提示符）。
2. 依次输入以下命令：

   >>> import storage >>> storage.erase_filesystem()

3. 板子会自动重启，CIRCUITPY会被格式化并恢复为一个全新的空驱动器。

6.2 备用方案：使用UF2擦除文件（针对特定板型）

对于无法进入REPL，或版本过旧不支持storage模块的情况，Adafruit为许多Express板型和RP2040板型提供了特殊的.uf2擦除文件。

1. 双击复位键，让板子进入UF2引导加载程序模式（此时电脑上会出现一个名为XXXBOOT的驱动器，而非CIRCUITPY）。
2. 根据你的板型，从Adafruit的指南页面下载对应的擦除文件（例如，flash_nuke.uf2用于RP2040板）。
3. 将该.uf2文件拖入XXXBOOT驱动器。
4. 板子会自动执行擦除，状态灯通常会变黄或蓝，完成后变绿。
5. 再次双击复位进入引导模式，拖入最新的CircuitPython固件（.uf2文件）进行重刷。

6.3 针对非Express板型（如Trinket M0, GEMMA M0）

这些板子没有外部闪存，存储空间小，且可能没有UF2引导程序。对于有UF2引导程序的，方法同上。对于没有的（如Feather M0 Basic），则需要使用bossac命令行工具通过Arduino IDE等方式重新刷写固件，这个过程会同时擦除并重建文件系统。

严重警告：无论是通过REPL还是UF2文件擦除，都会永久清除CIRCUITPY上的所有数据，包括你的代码和库文件。操作前务必确认已备份重要文件。

7. 空间不足与非Express板型的优化

对于SAMD21非Express板型（如Trinket M0、QT Py M0），其内置的Flash空间非常有限（可能只有几百KB），除去固件占用的，留给文件系统的空间往往比一张老式软盘还小。很容易出现“No space left on device”的错误。

7.1 常规清理方法

• 删除无用文件：检查lib文件夹，移除未使用的库。库文件通常很大。也可以删除板子自带的、你可能用不上的驱动文件（如旧的Windows串口驱动）。
• 使用制表符（Tab）缩进：Python代码中，用单个Tab字符代替四个空格进行缩进，可以节省大量空间。这对于空间以字节计的小容量板子来说效果显著。

7.2 macOS用户的特殊困扰与解决

macOS系统会为外接磁盘创建一系列隐藏文件（如._.DS_Store,._.Trashes,._.fseventsd），这些文件会悄无声息地占用宝贵空间。

1. 一次性清理与预防：在终端中执行一系列命令，可以停止索引并清理现有隐藏文件。核心步骤是定位你的CIRCUITPY卷，然后禁用Spotlight索引并删除相关文件。具体命令在Adafruit的指南中有详细说明，其原理是操作系统的mdutil和rm命令。
2. 安全的文件拷贝方式：即使做了预防，从网上下载的文件（比如从GitHub下载的库）被拷贝时，macOS仍可能生成隐藏的扩展属性文件。绝对不能使用Finder直接拖拽拷贝。必须使用终端命令cp -X（用于文件）或cp -rX（用于目录）来拷贝，-X参数可以阻止这些属性文件的生成。

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

养成这些习惯，能为你非Express板子上的项目腾出至关重要的几KB到几十KB空间，往往就是这点空间决定了你的项目能否塞下所有必需的代码和库。

8. 从CircuitPython切换到其他开发环境

CircuitPython只是你板子众多可能性中的一种。如果你需要更高的性能、更底层的控制，或者想尝试图形化编程，完全可以轻松切换。

8.1 切换至MakeCode（仅限Circuit Playground Express）

1. 访问makecode.adafruit.com，创建或打开一个项目，点击“下载”获取.uf2文件。
2. 双击板子复位键，进入引导模式（出现CPLAYBOOT驱动器）。
3. 将下载的.uf2文件拖入CPLAYBOOT驱动器。
4. 完成后，板子将运行MakeCode程序。之后只需单击复位键即可再次进入引导模式。

8.2 切换至Arduino IDE

1. 在Arduino IDE中安装对应板型的支持包（如Adafruit SAMD Boards）。
2. 双击板子复位键进入引导模式。
3. 在IDE中选择正确的板型和端口。
4. 编写或打开一个示例程序（如Blink），点击“上传”。
5. Arduino IDE会自动完成擦除、烧录和复位的过程。上传成功后，CircuitPython就被Arduino程序替代了。

关键点：切换环境本质上是用新的程序（UF2或二进制）覆盖掉Flash中原来的CircuitPython固件。所以“卸载”CircuitPython就是“安装”另一个程序。在覆盖前，千万记得备份CIRCUITPY盘里你自己的代码和库，因为这个过程会格式化整个用户存储区。

调试的本质是沟通，是与你的硬件和运行环境进行有效的信息交换。CircuitPython通过串口和状态灯提供了丰富的诊断信息，而自动重载、安全模式等机制则是它设计的容错与恢复路径。掌握从“信息被截断”的排查，到应对“无限重启”的镇定，再到利用“安全模式”力挽狂澜，最后到在极端情况下进行系统修复甚至环境切换，这一整套流程，你就能从被问题牵着鼻子走，转变为从容不迫的系统诊断者。记住，当板子行为异常时，第一反应不应该是怀疑硬件，而是系统地检查输出信息、理解状态指示、并善用系统内置的恢复工具。