CircuitPython Web Workflow实战：无线开发Yoto Mini与I2C硬件验证

1. 项目概述与核心价值

如果你玩过像树莓派Pico或者ESP32这类微控制器，肯定对“插拔-编程-调试”这个循环不陌生。每次改几行代码，就得拔下USB线，重新上电，然后盯着串口监视器看输出。这个过程在项目初期调试硬件时，尤其繁琐。今天要聊的CircuitPython Web Workflow，就是来打破这个循环的。它让你能通过Wi-Fi，用浏览器直接访问你的开发板，像操作一个微型服务器一样，编辑代码、管理文件、甚至运行Python命令。这听起来可能有点像那些复杂的物联网框架，但CircuitPython把它做得极其简单，几乎零配置。

这次我们拿一个特别的硬件——Yoto Mini儿童播放器——来当实验平台。这玩意儿原本是个封闭的讲故事设备，但得益于开放的硬件设计和CircuitPython的支持，它变成了一块功能强大的开发板：彩色屏幕、旋转编码器、NFC、RTC、音频DAC一应俱全。我们的目标很明确：第一，让Yoto Mini连上Wi-Fi，并通过Web Workflow在浏览器里“驯服”它；第二，利用Web Workflow上传一个I2C扫描程序，验证所有硬件是否正常通信；第三，跑一个简单的“Hello World”图形demo，证明整个软硬件链路是通的。整个过程，你不需要在电脑上安装复杂的IDE或驱动，一个支持现代Web标准的浏览器就够了。这对于快速原型验证、远程设备管理，或者仅仅是让开发过程更优雅，都大有裨益。

1.1 为什么是Web Workflow？

传统的嵌入式开发流程，代码编辑和设备运行是分离的。你需要在PC上写代码，编译，然后通过某种方式（通常是USB）烧录到设备上。CircuitPython本身通过将存储盘符（CIRCUITPY）映射到电脑，已经简化了文件传输，但调试依然依赖串口监视器。Web Workflow将“编辑”和“调试/交互”这两个环节都搬到了浏览器里。

它的核心原理并不复杂：在CircuitPython固件中，集成了一个轻量级的HTTP服务器和WebSocket服务。当开发板连接到Wi-Fi后，这个服务就在后台启动。你通过浏览器访问板子的IP地址或circuitpython.local这样的域名，服务器就会返回一个包含代码编辑器、文件浏览器和串口终端（REPL）的网页。你的所有操作，比如保存一个code.py文件，实际上是通过HTTP POST请求发送到板子，板子上的Python解释器会实时执行。这本质上是一种**远程文件系统访问和远程过程调用（RPC）**的混合体。

对于Yoto Mini这样的设备，优势更明显。它的接口丰富，调试时你可能需要同时观察屏幕输出、监听I2C设备状态、检查NFC读写。如果全靠USB线接串口，信息流会很单一。而Web Workflow允许你在一个浏览器标签页里看串口日志，另一个标签页里编辑代码，还能通过文件浏览器直接管理SD卡里的音频资源，这种一体化的体验是传统方式难以比拟的。

1.2 Yoto Mini作为开发平台的潜力

Yoto Mini拆解后，其核心是一块定制的主板，上面集成了Nordic nRF52840微控制器（运行CircuitPython）、一个彩色IPS显示屏、ES8156音频DAC、PCF8563实时时钟（RTC）、NXP NFC读卡器以及多个通过I2C总线连接的管理芯片（如电池管理）。它就像是一个“All-in-One”的嵌入式实验箱。

使用CircuitPython开发，意味着你可以用高级的Python语言直接控制这些硬件，无需关心底层的寄存器配置和复杂的C语言编译链。Adafruit为它提供了专门的adafruit_yoto库，这个库封装了所有硬件的初始化细节。例如，创建一个显示对象，在底层库中已经帮你设置好了正确的I2C地址、初始化序列和显示参数。这使得开发者可以专注于应用逻辑，比如：“当旋转编码器按下时，切换下一首歌”，而不是“如何通过I2C向某个地址发送特定字节来配置显示屏”。

因此，这个项目不仅仅是学习Web Workflow，更是探索如何将一个消费电子产品转化为一个极具创造力的开发平台。我们将从最基础的网络连接开始，逐步深入到硬件交互，最终让你能自由地在这个平台上实现自己的想法。

2. 环境准备与初始连接

要让Web Workflow跑起来，第一步是确保你的Yoto Mini（或其他支持Wi-Fi的CircuitPython板）有一个正确的网络配置。这通常是通过一个名为settings.toml的配置文件完成的。这个文件的作用，类似于给设备颁发一张“网络身份证”和“家门钥匙”。

2.1 配置settings.toml文件

在你电脑上看到的CIRCUITPY磁盘根目录下，创建一个新文件，命名为settings.toml（注意全小写，扩展名是.toml）。用任何文本编辑器打开它，输入以下内容：

CIRCUITPY_WIFI_SSID = "你的Wi-Fi名称" CIRCUITPY_WIFI_PASSWORD = "你的Wi-Fi密码" CIRCUITPY_WEB_API_PASSWORD = "你设定的Web访问密码"

参数详解与避坑指南：

1. Wi-Fi名称与密码：CIRCUITPY_WIFI_SSID和CIRCUITPY_WIFI_PASSWORD是必须的。请确保你的Wi-Fi是2.4GHz频段。绝大多数支持CircuitPython的微控制器（包括nRF52840）目前只支持2.4GHz网络。如果你的路由器开启了双频合一，可能会导致连接失败，建议在路由器后台暂时为2.4GHz网络设置一个独立的SSID。
2. Web API密码：CIRCUITPY_WEB_API_PASSWORD是Web Workflow的访问密码。强烈建议设置一个强密码，不要留空。因为一旦设备连入网络，理论上同一局域网内的任何设备都可以尝试访问它。设置密码是基本的安全措施。这个密码之后在浏览器登录时会用到。
3. 文件格式：TOML文件对格式非常敏感。等号=两边需要有空格，字符串值需要用双引号"括起来。一个常见的错误是写成SSID=你的WiFi（缺少空格和引号），这会导致配置被忽略。
4. 保存与重启：保存settings.toml文件后，需要按一下Yoto Mini上的复位（Reset）按钮，或者重新拔插USB电源。CircuitPython会在每次启动时读取这个文件。仅仅保存文件不会触发重新连接网络。

注意：settings.toml文件中的密码是以明文形式存储的。因此，请避免在公开场合分享你的CIRCUITPY磁盘内容，或者在使用后清除敏感信息。对于需要分发的项目，可以考虑在代码中首次运行时通过REPL交互式地输入密码，但这会牺牲一些便利性。

2.2 获取设备IP地址的三种方法

设备重启并成功连接Wi-Fi后，你需要知道它的IP地址才能用浏览器访问。这里有三种可靠的方法，推荐按顺序尝试：

方法一：观察串口终端标题栏（最优雅）如果你使用像screen（macOS/Linux）或PuTTY（Windows）这样的终端程序通过串口连接板子，当Web Workflow服务启动后，它会通过特殊的ANSI转义序列，将IP地址直接更新到终端窗口的标题栏。这是一个非常贴心的设计，让你一目了然。在Thonny IDE的Shell窗口底部，有时也能直接看到类似Web workflow available at: http://192.168.0.121的提示。

方法二：通过REPL命令行查询（最直接）通过串口连接到板子的REPL（交互式Python环境），依次输入以下命令：

>>> import wifi >>> wifi.radio.ipv4_address IPv4Address('192.168.0.121')

wifi.radio.ipv4_address会返回一个IPv4Address对象，显示的内容就是板子的本地IP地址。这是最万无一失的方法。

方法三：使用mDNS域名（最方便，但依赖网络支持）CircuitPython支持mDNS（多播DNS）服务。这意味着，在大多数现代操作系统（macOS, Linux, 部分配置正确的Windows网络）和浏览器中，你可以直接访问http://circuitpython.local这个地址，而无需知道IP。其原理是设备在网络上广播自己的名称，你的电脑通过本地域名解析将其转换为IP。如果circuitpython.local无法访问，通常是因为你的路由器或电脑的网络配置禁用了mDNS（也称为Bonjour或Zeroconf）。这时，回退到使用IP地址是标准做法。

2.3 首次登录Web Workflow界面

拿到IP地址（例如192.168.0.121）后，在你的电脑或手机浏览器地址栏输入http://192.168.0.121并访问。你会看到CircuitPython Web Workflow的欢迎页面。

首次访问任何功能（如文件浏览器、编辑器或终端）时，会弹出一个登录框。用户名（Username）留空，在密码（Password）框中填入你在settings.toml里设置的CIRCUITPY_WEB_API_PASSWORD。勾选“记住密码”可以避免每次操作都输入。

登录成功后，欢迎页面会展示几个核心功能入口：

• Serial Terminal（串口终端）：等同于一个网页版的串口监视器，可以看到code.py运行时的print输出，并且底部有一个输入框，可以输入Python命令与REPL交互。
• File Browser（文件浏览器）：网页版的文件管理器。可以查看、上传、下载、删除CIRCUITPY磁盘上的文件和文件夹。这对于上传库文件或资源文件（如图片、音频）至关重要。
• Editor（代码编辑器）：一个简易的代码编辑器，主要用于编辑code.py文件。它支持语法高亮和直接运行。

至此，你的远程开发环境已经搭建完成。接下来，我们将利用这个环境，对Yoto Mini的硬件进行一次“体检”。

3. I2C总线扫描与硬件验证

在嵌入式开发中，I2C（Inter-Integrated Circuit）总线是最常用的芯片间通信协议之一。Yoto Mini的主控芯片通过I2C与显示屏、RTC、音频DAC、电池管理芯片等多个外设通信。运行一个I2C扫描程序，就像给所有连接在总线上的设备“点名”，是验证硬件焊接是否良好、地址配置是否正确的最快方法。

3.1 I2C扫描原理与代码解读

I2C总线有两条线：SCL（时钟线）和SDA（数据线）。每个从设备都有一个7位或10位的唯一地址。主设备（这里是nRF52840）通过发送地址来发起通信。扫描的原理很简单：主设备依次尝试向所有可能的地址（通常7位地址范围是0x08到0x77）发送一个信号（例如尝试启动通信），如果某个地址有设备响应，就说明该地址被占用。

下面是我们将使用的扫描代码的核心逻辑分析：

import board import busio import time # 1. 定义所有可能的I2C总线实例化方式 ALL_I2C = ("board.I2C()", "board.STEMMA_I2C()", "busio.I2C(board.GP1, board.GP0)")

board.I2C()是CircuitPython的标准I2C对象，它会根据板子的默认定义自动选择正确的引脚。board.STEMMA_I2C()是针对Adafruit的STEMMA QT连接器定义的。busio.I2C(board.GP1, board.GP0)是手动指定SCL和SDA引脚。对于Yoto Mini，通常使用默认的board.I2C()即可，但这段代码提供了兼容性。

# 2. 探测有效的总线 found_i2c = [] for name in ALL_I2C: try: bus = eval(name) # 动态执行字符串形式的代码，创建总线对象 bus.unlock() # 确保总线处于未锁定状态 found_i2c.append((name, bus)) except Exception as e: pass # 如果创建失败，跳过该总线

这里用try...except来捕获异常。如果指定的引脚不存在或配置冲突，实例化I2C对象会抛出异常，代码会跳过这条总线。bus.unlock()是一个好习惯，确保总线可以正常访问。

# 3. 扫描并打印地址 for bus_info in found_i2c: name, bus = bus_info while not bus.try_lock(): pass # 尝试获取总线锁，确保独占访问 addresses = bus.scan() # 核心扫描函数 print(name, "found devices at:", [hex(addr) for addr in addresses]) bus.unlock() # 释放总线锁 time.sleep(2)

bus.try_lock()和bus.unlock()是线程安全（或协程安全）的保障，防止多个任务同时访问总线导致数据错乱。bus.scan()返回一个包含所有响应设备地址的列表。我们将其转换为十六进制格式打印出来，这是查看I2C设备的行业惯例。

3.2 通过Web Workflow上传与运行扫描程序

现在，我们不需要用USB线复制文件，直接通过Web Workflow来完成。

1. 准备代码文件：在你的电脑上，将上述完整的I2C扫描代码（包含版权声明和导入）保存为一个名为code.py的文本文件。或者，你可以直接从Adafruit的教程页面下载项目包（Project Bundle），其中通常就包含这个文件。

2. 登录Web Workflow：在浏览器中打开你的Yoto Mini的IP地址，并登录。

3. 使用文件浏览器上传：

   • 点击“File Browser”。
   • 在文件浏览器界面，找到并点击Upload按钮。
   • 选择Upload Files（上传单个文件）或Upload Folders（上传整个文件夹，如果你下载的是项目包）。这里我们上传单个code.py文件。
   • 在弹出的系统文件选择框中，找到你电脑上的code.py文件，点击打开。文件会上传到CIRCUITPY磁盘的根目录，并覆盖现有的code.py。

   重要提示：上传操作会直接覆盖目标文件。如果你之前有重要的代码，建议先通过文件浏览器下载备份。另外，上传库文件（位于/lib文件夹）时，务必使用Upload Folders选项，并选择本地的lib文件夹，这样可以保持库的目录结构。

4. 运行与观察结果：

   • 上传完成后，code.py文件会自动运行（因为CircuitPython设备启动时会自动执行根目录下的code.py）。
   • 点击“Serial Terminal”，你就能看到扫描结果的实时输出。对于Yoto Mini，你可能会看到一串类似下面的地址：

     board.I2C() found devices at: ['0x3c', '0x51', '0x68', '0x76']

   • 这些十六进制地址对应着不同的硬件：
     • 0x3C：通常是OLED/SSD1306显示屏的I2C地址，Yoto Mini的屏幕控制器可能使用这个地址。
     • 0x51：可能是PCF8563 RTC（实时时钟）的地址。
     • 0x68：另一个常见的RTC（如DS3231）地址，也可能是其他芯片。
     • 0x76：可能是气压传感器（如BMP280）或环境光传感器的地址，具体取决于板载芯片。

   如果扫描结果为空，或者预期的设备地址没有出现，就需要排查硬件连接（对于Yoto Mini这类一体化板子，通常是焊接问题）或I2C引脚定义是否正确。

通过这一步，我们不仅验证了Web Workflow的文件管理功能是有效的，也确认了Yoto Mini的核心硬件在CircuitPython下是“活着”的，并且通信正常。这为后续使用高级库奠定了基础。

4. 集成YotoPlayer库与高级应用

I2C扫描确认了硬件底层是通的，但要方便地驱动屏幕、读取编码器、播放音频，我们还需要更高级的抽象——这就是adafruit_yoto库存在的意义。它把各个零散的硬件驱动封装成一个统一的、易于使用的接口。

4.1 库的安装与项目包管理

Adafruit为许多硬件产品提供了“项目包”（Project Bundle）。这通常是一个ZIP文件，里面包含了运行示例所需的所有库文件（放在/lib目录下）和主程序code.py。使用项目包是避免手动寻找和下载依赖库的最佳实践。

1. 下载项目包：从Adafruit的Yoto Mini学习指南页面，找到“Hello World”或“Simple Demo”示例，点击“Download Project Bundle”按钮。这将下载一个ZIP文件到你的电脑。

2. 解压并查看内容：解压ZIP文件。你会看到一个文件夹，里面至少包含一个code.py和一个lib文件夹。lib文件夹里就是所有必需的CircuitPython库文件，例如adafruit_yoto、adafruit_displayio_*、adafruit_bus_device等。

3. 通过Web Workflow批量上传库：

   • 在Web Workflow的文件浏览器中，导航到CIRCUITPY磁盘的根目录。
   • 点击Upload按钮，然后选择Upload Folders。
   • 在你的电脑文件选择器中，选中解压后得到的那个lib文件夹本身，然后上传。
   • 系统会提示你确认上传整个文件夹，点击确认。Web Workflow会将这个lib文件夹及其所有子文件和子目录，完整地复制到设备的/lib目录下。如果存在同名文件，会被覆盖。

   实操心得：上传库文件夹时，务必确保设备上的/lib目录有足够的存储空间。Yoto Mini的CIRCUITPY磁盘空间可能有限。如果上传失败，可以尝试先删除设备上/lib目录中一些不用的旧库。另外，网络上传大文件夹需要时间，请耐心等待进度条完成，不要中途关闭浏览器。

4. 上传并运行主程序：用同样的“Upload Files”方法，将项目包里的code.py上传到设备根目录，覆盖旧文件。上传成功后，代码会自动运行。

4.2 解析“Hello World”示例代码

让我们看看一个最简单的adafruit_yoto库示例是如何工作的：

from adafruit_yoto import Yoto import time # 初始化Yoto对象，这是所有功能的起点 yoto = Yoto( default_bg=0x000000, # 设置默认背景色为黑色（RGB565格式，0x000000是黑色） rotation=0, # 屏幕旋转角度（0度） debug=False, # 关闭调试信息，减少串口输出 auto_refresh=True, # 启用自动刷新，图像更改后自动更新到屏幕 ) # 在屏幕上添加一段文本 title_index = yoto.add_text( text="Hello World!", # 要显示的文本 text_position=(yoto.display.width // 2, yoto.display.height // 2), # 位置居中 text_color=0xFFFFFF, # 文本颜色为白色 text_scale=3, # 字体缩放倍数 text_anchor_point=(0.5, 0.5), # 锚点居中（以文本的中心点作为定位基准） is_data=False, # 这不是动态数据（如果是动态变化的数据，如传感器读数，可设为True） ) # 打印外设信息到串口，用于调试 if yoto.peripherals.nfc: print(f"NFC芯片型号: {yoto.peripherals.nfc.device_name}") if yoto.peripherals.dac: print(f"音频DAC芯片ID: {yoto.peripherals.dac.chip_id:04X}") if yoto.peripherals.battery: part = yoto.peripherals.battery.part_info print(f"电池管理芯片: {part['part_number']}") if yoto.peripherals.rtc: print(f"RTC状态: {'时间已设置' if yoto.peripherals.rtc_valid else '需要设置时间'}") # 主循环，保持程序运行 while True: # 在这里可以添加其他逻辑，比如检查按钮、更新显示等 time.sleep(0.1)

代码关键点解析：

• 一站式初始化：Yoto()这个构造函数完成了所有脏活累活：初始化显示屏（通过I2C）、设置背光、配置旋转编码器（作为输入设备）、检查NFC、DAC、RTC、电池等外设。你不需要分别导入displayio、adafruit_ssd1306、rotaryio等一堆库并逐个初始化，这大大简化了代码。
• 图形系统：add_text方法展示了库的图形抽象层。它处理了字体加载、位图转换和屏幕缓冲。text_anchor_point是个很实用的参数，它决定了文本的哪个点对齐你提供的text_position坐标。(0.5, 0.5)代表中心对齐，(0, 0)代表左上角对齐。
• 外设统一访问：所有外设都通过yoto.peripherals这个对象来访问。例如yoto.peripherals.rtc就是一个RTC对象，你可以用它读取或设置时间。这种设计让代码非常整洁。
• 自动刷新：auto_refresh=True时，任何对显示内容的修改（比如改变文本）都会自动同步到硬件屏幕。如果设置为False，则需要手动调用yoto.display.refresh()来更新，这在制作动画或需要精确控制刷新时机时有用。

运行这个代码后，你应该能在Yoto Mini的屏幕上看到居中的“Hello World!”字样，同时在Web Workflow的串口终端里看到各个外设的识别信息。这标志着从底层硬件到高层应用库的整个软件栈都已成功运行。

4.3 探索更多演示与项目创意

成功运行基础Demo后，Adafruit通常还提供更多有趣的演示程序，这些同样是极佳的学习材料：

• 手动显示刷新与编码器交互Demo：这个Demo会教你如何加载BMP或PNG图片到屏幕上，并响应旋转编码器的按压和旋转事件。你可以学习到displayio图块网格（TileGrid）的使用、如何将编码器旋转值映射为图片切换索引。这是构建用户界面的基础。
• MP3播放器Demo：这个Demo将Yoto Mini变成一个真正的音乐播放器。它需要你将MP3文件和专辑封面图片存放在SD卡中。代码会读取SD卡目录结构，在屏幕上显示专辑封面，并通过耳机插孔播放音乐。旋转编码器用于控制音量和切歌。这个Demo涉及文件系统操作、音频解码（通过DAC）、以及更复杂的事件循环处理。

要尝试这些Demo，步骤是一样的：下载对应的项目包，通过Web Workflow上传lib文件夹和code.py。由于涉及SD卡和音频文件，你可能还需要准备一张格式化为FAT32的MicroSD卡，并按Demo要求存放好资源文件。

项目创意延伸： 掌握了这些基础，你就可以把Yoto Mini改造成各种有趣的东西：

• 网络天气站：利用Wi-Fi从网络API获取天气信息，显示在屏幕上。
• NFC智能标签触发器：编写不同的NFC卡片，当刷卡时执行不同任务，比如播放特定故事、显示一张图片、或者发送一条网络请求。
• 简易游戏机：利用旋转编码器和屏幕，制作一个简单的贪吃蛇或Flappy Bird游戏。
• 蓝牙遥控器：利用nRF52840的蓝牙功能，将其配置为HID设备，控制电脑的演示文稿播放。

Web Workflow使得迭代这些创意变得异常快捷。你可以在任何能连接同一Wi-Fi的设备上修改代码、上传资源，并实时看到效果。

5. 常见问题排查与实战技巧

即使按照步骤操作，也可能会遇到一些问题。这里汇总了一些常见坑点及其解决方案。

5.1 网络连接相关问题

5.2 硬件与代码执行问题

5.3 Web Workflow使用技巧

• 并行操作：你可以同时打开多个浏览器标签页，一个用于文件管理，一个用于串口终端，一个用于代码编辑。这比传统单一串口工具高效得多。
• 代码编辑器的局限：Web Workflow的内置编辑器适合快速修改和小型项目。对于大型项目，建议仍在本地电脑上用VS Code、Thonny等专业编辑器编写，然后通过文件浏览器的“上传”功能同步到设备。这样可以利用本地编辑器的代码补全、语法检查等功能。
• REPL的威力：Web Workflow的串口终端就是一个完整的REPL。除了看日志，你可以在这里直接输入Python命令与设备交互。例如，设备运行中，你可以输入import wifi; print(wifi.radio.ipv4_address)重新获取IP，或者import board; dir(board)查看所有引脚定义。这是动态调试的利器。
• 存储空间管理：定期清理CIRCUITPY磁盘上的__pycache__文件夹（如果存在）和旧的.py文件。可以通过文件浏览器直接删除。如果空间实在紧张，可以考虑将库文件移到SD卡（如果设备支持），并在代码中通过sys.path添加SD卡路径。
• 复位与软重启：如果设备无响应或代码陷入死循环，可以通过Web Workflow页面上的“软重启”按钮（如果有）或物理复位键来重启设备。软重启会重新执行code.py，而不断电。

通过这套Web Workflow，CircuitPython开发的体验从“单片机编程”无限接近“Web开发”或“服务器管理”。它降低了远程调试和管理的门槛，让开发者能更专注于创意和逻辑本身。对于Yoto Mini这样一个硬件丰富的平台，这种便捷性使得快速迭代和实现复杂交互成为可能。从连接设备到运行一个图形化Demo，整个过程完全在无线环境下完成，这本身就是嵌入式开发体验的一次显著提升。