1. 项目概述与CircuitPython核心价值如果你对硬件编程感兴趣但又觉得C/C的编译、烧录过程过于繁琐或者对Arduino的语法感到有些束手束脚那么CircuitPython很可能就是你一直在寻找的“捷径”。它本质上是一个基于Python 3的轻量级解释器被设计成可以直接运行在微控制器上比如Adafruit的QT Py ESP32-S3。这意味着你写好的.py文件可以直接拖拽到设备上名为CIRCUITPY的U盘里代码就会自动运行。这种“所见即所得”的开发体验极大地模糊了软件开发和硬件交互之间的界限。它的核心价值在于“降本增效”。对于教育者、创客、产品原型开发者而言CircuitPython将开发重心从复杂的底层驱动和编译环境配置转移到了业务逻辑和交互设计本身。你不需要理解中断向量表也不用担心内存对齐更不用在Makefile里挣扎。你只需要关注“按下按钮时灯要变红”或者“温度超过30度就发送一个网络请求”这样的高层逻辑。Python庞大的生态系统包括其清晰的语法、丰富的内置库和活跃的社区都成为了嵌入式开发的助力。这使得快速验证一个物联网点子、制作一个交互式艺术装置或者教授编程与硬件的结合变得前所未有的简单和直观。2. 环境搭建与核心概念解析2.1 硬件准备与固件刷写要开始CircuitPython之旅你首先需要一块支持它的开发板。本文以Adafruit QT Py ESP32-S3为例这是一款集成了WiFi/蓝牙功能的紧凑型板卡性能足够应对大多数物联网项目。第一步是刷入CircuitPython固件。这个过程比传统单片机开发友好得多访问官方下载页前往CircuitPython官网找到QT Py ESP32-S3的专用页面下载最新的.uf2固件文件。进入下载模式用USB数据线连接开发板和电脑。先按住板载的Boot按钮通常标有“BOOT”或位于USB口旁边然后短暂按一下Reset按钮最后松开Boot按钮。此时电脑上会出现一个名为UF2BOOT或类似的可移动磁盘。拖拽刷写将下载好的.uf2文件直接拖入这个磁盘。完成后开发板会自动重启一个名为CIRCUITPY的新磁盘就会出现。这不仅是你的代码存储盘也是串行控制台的入口。注意务必使用质量可靠的USB数据线。有些充电线只有电源线没有数据线会导致电脑无法识别设备这是新手最常见的“坑”。2.2 理解CIRCUITPY磁盘与核心工作流成功刷写后你的工作流将完全围绕CIRCUITPY磁盘展开。这个磁盘里有几个关键文件和文件夹code.py这是主程序入口。设备上电或复位后会自动执行这个文件里的代码。你可以用任何文本编辑器推荐VS Code、Mu Editor或Thonny直接编辑它保存后代码立即生效。lib/文件夹用于存放第三方库文件通常是.mpy格式。当你需要控制特定传感器或模块时就需要从CircuitPython库捆绑包中下载对应的库文件并放入此文件夹。boot.py这是一个特殊的启动脚本在code.py之前运行。通常用于一些底层配置比如我们后面会讲到的存储模式切换。这种“文件系统即编程接口”的模式使得调试和迭代变得极其快速。你可以一边在串行监视器REPL里查看打印信息一边在编辑器里修改代码保存后立刻看到效果无需漫长的编译和烧录等待。2.3 串行REPL交互式调试利器REPLRead-Eval-Print Loop是CircuitPython的交互式命令行环境是调试和探索的绝佳工具。连接方法如下使用Mu Editor、Thonny或Putty、screen等串口工具。选择正确的串行端口在Windows设备管理器中查看COM口在macOS/Linux上通常是/dev/tty.usbmodemXX或/dev/ttyACM0。连接后按一下板子的复位键你会看到CircuitPython的版本信息和提示符。在这里你可以直接输入Python命令并立即执行比如import board查看所有引脚定义或者import digitalio测试一个LED。当你的code.py因为错误而停止时REPL会显示详细的错误追踪信息帮助你快速定位问题所在。3. 从“Hello World”到硬件交互Blink与数字输入3.1 NeoPixel Blink你的第一个硬件程序在软件世界“Hello World”是打印一行文字在硬件世界它就是让一个LED闪烁。QT Py ESP32-S3板载了一个RGB NeoPixel LED我们用它来开始。首先你需要neopixel库。从Adafruit的CircuitPython库捆绑包中找到neopixel.mpy和其依赖的adafruit_pixelbuf.mpy将它们复制到CIRCUITPY磁盘的lib文件夹内。然后在code.py中写入以下代码import time import board import neopixel # 初始化板载NeoPixel。参数1控制引脚board.NEOPIXEL是板载LED的专用引脚名。 # 参数2LED的数量我们只有1个。 pixel neopixel.NeoPixel(board.NEOPIXEL, 1) while True: # 填充红色 (R, G, B) 每个值范围0-255 pixel.fill((255, 0, 0)) time.sleep(0.5) # 等待0.5秒 # 关闭LED (R, G, B) (0, 0, 0) pixel.fill((0, 0, 0)) time.sleep(0.5)保存文件板载的彩色LED应该开始以0.5秒的间隔闪烁红光。这段代码揭示了几个核心概念硬件抽象board.NEOPIXEL是一个预定义的常量它隐藏了具体的物理引脚号。这使得代码在不同型号的Adafruit板卡间具有更好的可移植性。库导入neopixel库封装了与WS2812系列LED通信的底层时序协议你只需要关心颜色和亮度。主循环while True:是嵌入式程序的标准模式让代码持续运行。实操心得如果你发现LED没亮首先检查lib文件夹里是否有正确的库文件。其次有些板子的NeoPixel默认亮度可能被设置为0可以尝试pixel.brightness 0.3来调亮。最后确保你没有意外地初始化了多个NeoPixel对象去控制同一个引脚这会导致冲突。3.2 引入交互用按钮控制NeoPixel让灯自己闪没什么意思加上交互才有灵魂。我们利用板载的Boot按钮在代码中通常映射为board.BUTTON来控制LED。更新你的code.pyimport board import digitalio import neopixel # 初始化NeoPixel pixel neopixel.NeoPixel(board.NEOPIXEL, 1) # 初始化按钮引脚为输入模式并启用内部上拉电阻 button digitalio.DigitalInOut(board.BUTTON) button.switch_to_input(pulldigitalio.Pull.UP) while True: # 按钮按下时值为False因为上拉到高电平按下接地 if not button.value: pixel.fill((255, 0, 0)) # 按下亮红灯 else: pixel.fill((0, 0, 0)) # 松开灯灭这里引入了digitalio模块它是处理数字输入输出的核心。pulldigitalio.Pull.UP启用了内部上拉电阻这是一个关键细节。在没有按下按钮时引脚通过电阻连接到3.3V高电平value为True按下按钮时引脚直接接地低电平value为False。这样可以确保引脚有一个明确的状态避免因悬空而产生随机抖动信号。注意事项机械按钮在按下和弹起时会产生“抖动”即电平在短时间内快速变化多次。对于简单的开关控制这里的代码足够用。但如果要检测“单击”、“双击”则需要加入“消抖”逻辑通常通过延时采样来实现。4. 感知模拟世界ADC与电位器应用4.1 模拟信号与ADC原理数字世界只有0和1但真实世界是连续的。温度、光线强度、声音音量都是模拟量。微控制器通过模数转换器ADC来读取这些连续变化的电压。QT Py ESP32-S3的ADC分辨率是12位这意味着它可以将0到3.3V的参考电压划分为2^12 4096个等级。但CircuitPython的analogio库为了统一接口将读数映射到了0-6553516位的范围。你需要了解你所用板卡的ADC上限值对于ESP32-S3最大值大约是61285对应约3.09V。4.2 读取电位器电压值电位器是一个经典的模拟输入器件。我们将其连接为分压电路一端接3.3V一端接地中间抽头滑动端接模拟输入引脚A0。硬件连接如下表所示电位器引脚连接至 QT Py ESP32-S3线缆颜色参考左/外侧引脚1GND黑色中间抽头引脚A0红色右/外侧引脚23.3V白色代码实现如下import time import board import analogio # 初始化A0引脚为模拟输入 analog_pin analogio.AnalogIn(board.A0) def get_voltage(pin): 将ADC原始值转换为电压值单位伏特 # ESP32-S3的ADC参考电压约为3.09V最大读数约为61285 return (pin.value * 3.09) / 61285 while True: raw_value analog_pin.value voltage get_voltage(analog_pin) print(fRaw: {raw_value:6d} | Voltage: {voltage:.2f}V) time.sleep(0.1) # 降低打印频率便于观察打开串行监视器旋转电位器你会看到原始数值和计算出的电压值在同步变化。这个get_voltage函数是一个实用的工具函数它将抽象的ADC数值转换回了我们熟悉的电压单位这对于连接其他模拟传感器如光敏电阻、模拟温度传感器至关重要。排查技巧如果读数始终为0或接近最大值且不变化首先检查接线是否正确特别是电位器的两端是否分别接在了电源和地上。其次ESP32-S3的某些引脚在启动时可能有默认功能确保你使用的A0引脚在CircuitPython中是可用的普通模拟输入引脚。最后ADC读数可能存在轻微噪声在需要稳定读数的场合可以尝试连续采样多次然后取平均值。5. 连接网络世界WiFi测试与配置5.1 从secrets.py到settings.toml早期CircuitPython使用secrets.py文件存储WiFi密码等敏感信息。从CircuitPython 8开始官方推荐使用settings.toml文件。TOML格式更清晰且支持注释。在CIRCUITPY磁盘的根目录下创建一个名为settings.toml的文本文件内容如下# 你的WiFi网络名称和密码 CIRCUITPY_WIFI_SSID 你的WiFi名称 CIRCUITPY_WIFI_PASSWORD 你的WiFi密码 # 可以添加其他自定义配置例如API密钥 # MY_API_KEY abc123重要请务必用你的实际WiFi信息替换引号内的内容并确保文件以.toml扩展名保存且使用UTF-8编码无BOM。这个文件应该直接放在CIRCUITPY根目录而不是任何文件夹里。5.2 实现网络连接测试有了配置文件我们就可以编写连接测试代码。将以下代码保存为code.pyimport ipaddress import wifi import socketpool from os import getenv # 从settings.toml中读取WiFi配置 ssid getenv(CIRCUITPY_WIFI_SSID) password getenv(CIRCUITPY_WIFI_PASSWORD) # 安全检查确保配置已填写 if ssid is None or password is None: raise RuntimeError( WiFi配置信息缺失请检查CIRCUITPY根目录下的settings.toml文件 确保已设置CIRCUITPY_WIFI_SSID和CIRCUITPY_WIFI_PASSWORD。 ) print(正在连接WiFi...) try: wifi.radio.connect(ssid, password) except Exception as e: print(f连接失败: {e}) # 可能是密码错误、信号弱或SSID隐藏 raise print(WiFi连接成功) print(- * 30) # 创建网络套接字池为后续高级网络操作做准备 pool socketpool.SocketPool(wifi.radio) # 打印本机网络信息 print(fMAC地址: {[hex(i) for i in wifi.radio.mac_address]}) print(fIP地址: {wifi.radio.ipv4_address}) print(f子网掩码: {wifi.radio.ipv4_subnet}) print(f网关: {wifi.radio.ipv4_gateway}) print(fDNS服务器: {wifi.radio.ipv4_dns}) # 测试网络连通性ping一个公共DNS服务器 print(- * 30) print(正在测试网络连通性...) try: # 使用Google的公共DNS服务器IP ping_target ipaddress.ip_address(8.8.8.8) ping_time_ms wifi.radio.ping(ping_target) * 1000 # 转换为毫秒 if ping_time_ms is not None: print(fPing {ping_target} 成功延迟: {ping_time_ms:.2f} ms) else: print(fPing {ping_target} 超时。) except Exception as e: print(fPing测试出错: {e})保存代码后打开串行监视器。如果一切顺利你将看到连接成功的消息、获取到的IP地址以及ping测试的结果。这个脚本不仅测试连接还输出了完整的网络配置信息对于调试网络问题非常有帮助。常见问题与排查连接超时或失败首先检查settings.toml中的SSID和密码是否正确注意大小写。其次检查路由器是否设置了MAC地址过滤。你可以尝试将手机热点作为测试网络排除复杂路由器设置的影响。能连接但无法Ping通可能是开发板获取到了IP地址但无法访问外网。检查路由器的防火墙设置或尝试Ping路由器本身的IP地址通常是网关地址如192.168.1.1。反复断开重连可能是WiFi信号太弱。ESP32-S3的PCB天线性能在复杂环境中可能一般尽量让设备靠近路由器。6. 数据记录与存储打造简易温度监测器6.1 理解CircuitPython的文件系统与读写权限CIRCUITPY磁盘默认由你的电脑挂载为可读写状态方便你编辑代码。但CircuitPython运行时也想往这个磁盘写数据比如记录日志就会产生冲突。为了解决这个问题CircuitPython设计了一个精巧的“单写者”模式同一时间只能由电脑或CircuitPython程序其中之一进行写入操作。boot.py文件正是在这个环节发挥作用。它在CircuitPython启动时硬复位或重新上电运行比code.py更早。我们可以在boot.py里通过检测一个按钮的状态来决定将文件系统的写入权限分配给谁。6.2 实现双模式启动与温度记录这个项目将实现一个功能通过按住按钮启动让板子进入“数据记录模式”每隔10秒将CPU温度写入文件正常启动则为“编程模式”电脑可以自由编辑文件。第一步创建boot.py在CIRCUITPY根目录创建boot.py内容如下import time import board import digitalio import storage import neopixel # 初始化硬件 pixel neopixel.NeoPixel(board.NEOPIXEL, 1) button digitalio.DigitalInOut(board.BUTTON) button.switch_to_input(pulldigitalio.Pull.UP) # 提示用户NeoPixel亮起白色时按下按钮进入记录模式 pixel.fill((255, 255, 255)) # 白色 time.sleep(1) pixel.fill((0, 0, 0)) # 熄灭 # 关键操作根据按钮状态重新挂载文件系统 # button.value 为 True按钮未按下时readonlyTrueCircuitPython只读电脑可写 # button.value 为 False按钮按下时readonlyFalseCircuitPython可写电脑只读 storage.remount(/, readonlybutton.value) # 根据模式给出灯光提示 if button.value: # 未按下编程模式 pixel.fill((0, 255, 0)) # 绿色 time.sleep(0.5) pixel.fill((0, 0, 0)) else: # 按下记录模式 pixel.fill((0, 0, 255)) # 蓝色 time.sleep(0.5) pixel.fill((0, 0, 0))第二步创建code.py这是主数据记录程序import time import board import microcontroller import neopixel pixel neopixel.NeoPixel(board.NEOPIXEL, 1) LOG_FILE /temperature_log.txt LOG_INTERVAL 10 # 记录间隔单位秒 try: # 尝试以追加模式打开日志文件。如果文件系统对CircuitPython可写则进入此分支。 with open(LOG_FILE, a) as log_file: print(进入数据记录模式。开始记录温度...) while True: # 读取微控制器内部温度传感器数值单位摄氏度 temp_c microcontroller.cpu.temperature # 转换为华氏度可选 # temp_f temp_c * 9 / 5 32 # 构建日志行时间戳 温度 timestamp time.monotonic() # 自开机以来的秒数单调递增 log_line f{timestamp:.1f}, {temp_c:.2f}\n # 写入文件并立即刷新缓冲区确保数据落盘 log_file.write(log_line) log_file.flush() print(f已记录: {log_line.strip()}) # 视觉反馈记录时红灯亮1秒 pixel.fill((255, 0, 0)) time.sleep(1) pixel.fill((0, 0, 0)) # 等待剩余间隔时间 time.sleep(LOG_INTERVAL - 1) except OSError as e: # 如果发生OSError说明文件系统对CircuitPython是只读的编程模式或者已满。 print(f无法写入文件系统或发生错误: {e}) blink_delay 0.5 # 默认慢闪0.5秒表示只读模式 if e.args[0] 28: # 错误码28: 文件系统已满 print(警告文件系统已满) blink_delay 0.15 # 快闪0.15秒表示空间不足 # 进入错误指示循环根据blink_delay闪烁红灯 while True: pixel.fill((255, 0, 0)) time.sleep(blink_delay) pixel.fill((0, 0, 0)) time.sleep(blink_delay)第三步操作流程正常启动编程模式直接给板子上电或按复位键。NeoPixel会闪一下绿色然后熄灭。此时电脑可以读写CIRCUITPY磁盘你可以自由修改code.py等文件。板子上的程序不会记录数据红灯不会周期性闪烁。进入记录模式 a.按住板子上的Boot按钮不放。 b. 在按住按钮的同时按一下Reset复位键或者拔插USB线。 c. 你会看到NeoPixel先亮白色1秒提示窗口然后闪一下蓝色。此时松开按钮。 d. 现在CIRCUITPY磁盘在电脑上会显示为“只读”。板子开始每10秒闪一次红灯表示正在记录温度数据到temperature_log.txt文件。读取数据要读取记录的数据你需要先退出记录模式。方法是在不按按钮的情况下按一下Reset键或重新上电。板子会进入编程模式闪绿光此时电脑可以访问CIRCUITPY磁盘打开temperature_log.txt文件就能看到按时间戳和温度值排列的数据。深度解析与避坑指南storage.remount()的机制这个函数改变了CircuitPython内核对待CIRCUITPY文件系统的方式。当设置为readonlyFalseCircuitPython可写时它会卸载当前文件系统并以一种防止电脑写入的方式重新挂载。这就是为什么电脑端会看到磁盘变成“只读”。数据安全与flush()在嵌入式系统中突然断电可能导致正在写入的数据丢失。file.flush()方法强制将Python缓冲区中的数据写入到存储介质中虽然会降低一些写入速度但极大地提高了数据可靠性对于数据记录应用至关重要。温度数据的意义microcontroller.cpu.temperature读取的是芯片内核的温度通常比环境温度高。它不适合做高精度的室温测量但非常适合监测设备自身的运行状态比如判断是否过热。其变化趋势也能反映环境温度的变化。文件系统满的处理代码中特意处理了OSError: [Errno 28] No space left on device错误。当磁盘空间耗尽时程序会进入快闪红灯状态提醒用户。此时需要在编程模式下连接电脑删除或备份temperature_log.txt文件以释放空间。时间戳的选择这里使用了time.monotonic()它返回一个从开机开始持续递增的秒数不受系统时间设置影响适合用于计算时间间隔。如果你需要真实的日历时间则需要通过网络协议NTP从互联网获取这涉及更复杂的网络编程。7. 项目整合与扩展思路至此我们已经完成了从控制一个LED到读取模拟传感器再到连接网络最后实现本地数据记录的完整闭环。你可以将这些模块组合起来构建更复杂的应用。例如一个简单的物联网气象站原型可以这样设计感知将电位器替换为真正的数字温湿度传感器如DHT22或AHT20使用I2C或单总线协议。记录沿用本章的存储方案定期将温湿度数据记录到本地文件。上报在记录数据的同时通过WiFi模块每隔一段时间如每5分钟将数据打包发送到云服务器如Adafruit IO、Thingspeak或自建的MQTT服务器。交互保留按钮和NeoPixel。按钮可以切换工作模式如“仅记录”、“记录并上传”NeoPixel用不同颜色指示当前状态绿色正常蓝色发送中红色错误。这种模块化、渐进式的开发方式正是CircuitPython的魅力所在。它让你能够快速搭建起一个可工作的原型验证想法的可行性然后再逐步优化和增加功能。相比于传统嵌入式开发你节省了大量在底层驱动和调试上的时间可以将更多精力专注于产品逻辑和用户体验本身。
CircuitPython入门：从零开始构建物联网原型，简化嵌入式开发
1. 项目概述与CircuitPython核心价值如果你对硬件编程感兴趣但又觉得C/C的编译、烧录过程过于繁琐或者对Arduino的语法感到有些束手束脚那么CircuitPython很可能就是你一直在寻找的“捷径”。它本质上是一个基于Python 3的轻量级解释器被设计成可以直接运行在微控制器上比如Adafruit的QT Py ESP32-S3。这意味着你写好的.py文件可以直接拖拽到设备上名为CIRCUITPY的U盘里代码就会自动运行。这种“所见即所得”的开发体验极大地模糊了软件开发和硬件交互之间的界限。它的核心价值在于“降本增效”。对于教育者、创客、产品原型开发者而言CircuitPython将开发重心从复杂的底层驱动和编译环境配置转移到了业务逻辑和交互设计本身。你不需要理解中断向量表也不用担心内存对齐更不用在Makefile里挣扎。你只需要关注“按下按钮时灯要变红”或者“温度超过30度就发送一个网络请求”这样的高层逻辑。Python庞大的生态系统包括其清晰的语法、丰富的内置库和活跃的社区都成为了嵌入式开发的助力。这使得快速验证一个物联网点子、制作一个交互式艺术装置或者教授编程与硬件的结合变得前所未有的简单和直观。2. 环境搭建与核心概念解析2.1 硬件准备与固件刷写要开始CircuitPython之旅你首先需要一块支持它的开发板。本文以Adafruit QT Py ESP32-S3为例这是一款集成了WiFi/蓝牙功能的紧凑型板卡性能足够应对大多数物联网项目。第一步是刷入CircuitPython固件。这个过程比传统单片机开发友好得多访问官方下载页前往CircuitPython官网找到QT Py ESP32-S3的专用页面下载最新的.uf2固件文件。进入下载模式用USB数据线连接开发板和电脑。先按住板载的Boot按钮通常标有“BOOT”或位于USB口旁边然后短暂按一下Reset按钮最后松开Boot按钮。此时电脑上会出现一个名为UF2BOOT或类似的可移动磁盘。拖拽刷写将下载好的.uf2文件直接拖入这个磁盘。完成后开发板会自动重启一个名为CIRCUITPY的新磁盘就会出现。这不仅是你的代码存储盘也是串行控制台的入口。注意务必使用质量可靠的USB数据线。有些充电线只有电源线没有数据线会导致电脑无法识别设备这是新手最常见的“坑”。2.2 理解CIRCUITPY磁盘与核心工作流成功刷写后你的工作流将完全围绕CIRCUITPY磁盘展开。这个磁盘里有几个关键文件和文件夹code.py这是主程序入口。设备上电或复位后会自动执行这个文件里的代码。你可以用任何文本编辑器推荐VS Code、Mu Editor或Thonny直接编辑它保存后代码立即生效。lib/文件夹用于存放第三方库文件通常是.mpy格式。当你需要控制特定传感器或模块时就需要从CircuitPython库捆绑包中下载对应的库文件并放入此文件夹。boot.py这是一个特殊的启动脚本在code.py之前运行。通常用于一些底层配置比如我们后面会讲到的存储模式切换。这种“文件系统即编程接口”的模式使得调试和迭代变得极其快速。你可以一边在串行监视器REPL里查看打印信息一边在编辑器里修改代码保存后立刻看到效果无需漫长的编译和烧录等待。2.3 串行REPL交互式调试利器REPLRead-Eval-Print Loop是CircuitPython的交互式命令行环境是调试和探索的绝佳工具。连接方法如下使用Mu Editor、Thonny或Putty、screen等串口工具。选择正确的串行端口在Windows设备管理器中查看COM口在macOS/Linux上通常是/dev/tty.usbmodemXX或/dev/ttyACM0。连接后按一下板子的复位键你会看到CircuitPython的版本信息和提示符。在这里你可以直接输入Python命令并立即执行比如import board查看所有引脚定义或者import digitalio测试一个LED。当你的code.py因为错误而停止时REPL会显示详细的错误追踪信息帮助你快速定位问题所在。3. 从“Hello World”到硬件交互Blink与数字输入3.1 NeoPixel Blink你的第一个硬件程序在软件世界“Hello World”是打印一行文字在硬件世界它就是让一个LED闪烁。QT Py ESP32-S3板载了一个RGB NeoPixel LED我们用它来开始。首先你需要neopixel库。从Adafruit的CircuitPython库捆绑包中找到neopixel.mpy和其依赖的adafruit_pixelbuf.mpy将它们复制到CIRCUITPY磁盘的lib文件夹内。然后在code.py中写入以下代码import time import board import neopixel # 初始化板载NeoPixel。参数1控制引脚board.NEOPIXEL是板载LED的专用引脚名。 # 参数2LED的数量我们只有1个。 pixel neopixel.NeoPixel(board.NEOPIXEL, 1) while True: # 填充红色 (R, G, B) 每个值范围0-255 pixel.fill((255, 0, 0)) time.sleep(0.5) # 等待0.5秒 # 关闭LED (R, G, B) (0, 0, 0) pixel.fill((0, 0, 0)) time.sleep(0.5)保存文件板载的彩色LED应该开始以0.5秒的间隔闪烁红光。这段代码揭示了几个核心概念硬件抽象board.NEOPIXEL是一个预定义的常量它隐藏了具体的物理引脚号。这使得代码在不同型号的Adafruit板卡间具有更好的可移植性。库导入neopixel库封装了与WS2812系列LED通信的底层时序协议你只需要关心颜色和亮度。主循环while True:是嵌入式程序的标准模式让代码持续运行。实操心得如果你发现LED没亮首先检查lib文件夹里是否有正确的库文件。其次有些板子的NeoPixel默认亮度可能被设置为0可以尝试pixel.brightness 0.3来调亮。最后确保你没有意外地初始化了多个NeoPixel对象去控制同一个引脚这会导致冲突。3.2 引入交互用按钮控制NeoPixel让灯自己闪没什么意思加上交互才有灵魂。我们利用板载的Boot按钮在代码中通常映射为board.BUTTON来控制LED。更新你的code.pyimport board import digitalio import neopixel # 初始化NeoPixel pixel neopixel.NeoPixel(board.NEOPIXEL, 1) # 初始化按钮引脚为输入模式并启用内部上拉电阻 button digitalio.DigitalInOut(board.BUTTON) button.switch_to_input(pulldigitalio.Pull.UP) while True: # 按钮按下时值为False因为上拉到高电平按下接地 if not button.value: pixel.fill((255, 0, 0)) # 按下亮红灯 else: pixel.fill((0, 0, 0)) # 松开灯灭这里引入了digitalio模块它是处理数字输入输出的核心。pulldigitalio.Pull.UP启用了内部上拉电阻这是一个关键细节。在没有按下按钮时引脚通过电阻连接到3.3V高电平value为True按下按钮时引脚直接接地低电平value为False。这样可以确保引脚有一个明确的状态避免因悬空而产生随机抖动信号。注意事项机械按钮在按下和弹起时会产生“抖动”即电平在短时间内快速变化多次。对于简单的开关控制这里的代码足够用。但如果要检测“单击”、“双击”则需要加入“消抖”逻辑通常通过延时采样来实现。4. 感知模拟世界ADC与电位器应用4.1 模拟信号与ADC原理数字世界只有0和1但真实世界是连续的。温度、光线强度、声音音量都是模拟量。微控制器通过模数转换器ADC来读取这些连续变化的电压。QT Py ESP32-S3的ADC分辨率是12位这意味着它可以将0到3.3V的参考电压划分为2^12 4096个等级。但CircuitPython的analogio库为了统一接口将读数映射到了0-6553516位的范围。你需要了解你所用板卡的ADC上限值对于ESP32-S3最大值大约是61285对应约3.09V。4.2 读取电位器电压值电位器是一个经典的模拟输入器件。我们将其连接为分压电路一端接3.3V一端接地中间抽头滑动端接模拟输入引脚A0。硬件连接如下表所示电位器引脚连接至 QT Py ESP32-S3线缆颜色参考左/外侧引脚1GND黑色中间抽头引脚A0红色右/外侧引脚23.3V白色代码实现如下import time import board import analogio # 初始化A0引脚为模拟输入 analog_pin analogio.AnalogIn(board.A0) def get_voltage(pin): 将ADC原始值转换为电压值单位伏特 # ESP32-S3的ADC参考电压约为3.09V最大读数约为61285 return (pin.value * 3.09) / 61285 while True: raw_value analog_pin.value voltage get_voltage(analog_pin) print(fRaw: {raw_value:6d} | Voltage: {voltage:.2f}V) time.sleep(0.1) # 降低打印频率便于观察打开串行监视器旋转电位器你会看到原始数值和计算出的电压值在同步变化。这个get_voltage函数是一个实用的工具函数它将抽象的ADC数值转换回了我们熟悉的电压单位这对于连接其他模拟传感器如光敏电阻、模拟温度传感器至关重要。排查技巧如果读数始终为0或接近最大值且不变化首先检查接线是否正确特别是电位器的两端是否分别接在了电源和地上。其次ESP32-S3的某些引脚在启动时可能有默认功能确保你使用的A0引脚在CircuitPython中是可用的普通模拟输入引脚。最后ADC读数可能存在轻微噪声在需要稳定读数的场合可以尝试连续采样多次然后取平均值。5. 连接网络世界WiFi测试与配置5.1 从secrets.py到settings.toml早期CircuitPython使用secrets.py文件存储WiFi密码等敏感信息。从CircuitPython 8开始官方推荐使用settings.toml文件。TOML格式更清晰且支持注释。在CIRCUITPY磁盘的根目录下创建一个名为settings.toml的文本文件内容如下# 你的WiFi网络名称和密码 CIRCUITPY_WIFI_SSID 你的WiFi名称 CIRCUITPY_WIFI_PASSWORD 你的WiFi密码 # 可以添加其他自定义配置例如API密钥 # MY_API_KEY abc123重要请务必用你的实际WiFi信息替换引号内的内容并确保文件以.toml扩展名保存且使用UTF-8编码无BOM。这个文件应该直接放在CIRCUITPY根目录而不是任何文件夹里。5.2 实现网络连接测试有了配置文件我们就可以编写连接测试代码。将以下代码保存为code.pyimport ipaddress import wifi import socketpool from os import getenv # 从settings.toml中读取WiFi配置 ssid getenv(CIRCUITPY_WIFI_SSID) password getenv(CIRCUITPY_WIFI_PASSWORD) # 安全检查确保配置已填写 if ssid is None or password is None: raise RuntimeError( WiFi配置信息缺失请检查CIRCUITPY根目录下的settings.toml文件 确保已设置CIRCUITPY_WIFI_SSID和CIRCUITPY_WIFI_PASSWORD。 ) print(正在连接WiFi...) try: wifi.radio.connect(ssid, password) except Exception as e: print(f连接失败: {e}) # 可能是密码错误、信号弱或SSID隐藏 raise print(WiFi连接成功) print(- * 30) # 创建网络套接字池为后续高级网络操作做准备 pool socketpool.SocketPool(wifi.radio) # 打印本机网络信息 print(fMAC地址: {[hex(i) for i in wifi.radio.mac_address]}) print(fIP地址: {wifi.radio.ipv4_address}) print(f子网掩码: {wifi.radio.ipv4_subnet}) print(f网关: {wifi.radio.ipv4_gateway}) print(fDNS服务器: {wifi.radio.ipv4_dns}) # 测试网络连通性ping一个公共DNS服务器 print(- * 30) print(正在测试网络连通性...) try: # 使用Google的公共DNS服务器IP ping_target ipaddress.ip_address(8.8.8.8) ping_time_ms wifi.radio.ping(ping_target) * 1000 # 转换为毫秒 if ping_time_ms is not None: print(fPing {ping_target} 成功延迟: {ping_time_ms:.2f} ms) else: print(fPing {ping_target} 超时。) except Exception as e: print(fPing测试出错: {e})保存代码后打开串行监视器。如果一切顺利你将看到连接成功的消息、获取到的IP地址以及ping测试的结果。这个脚本不仅测试连接还输出了完整的网络配置信息对于调试网络问题非常有帮助。常见问题与排查连接超时或失败首先检查settings.toml中的SSID和密码是否正确注意大小写。其次检查路由器是否设置了MAC地址过滤。你可以尝试将手机热点作为测试网络排除复杂路由器设置的影响。能连接但无法Ping通可能是开发板获取到了IP地址但无法访问外网。检查路由器的防火墙设置或尝试Ping路由器本身的IP地址通常是网关地址如192.168.1.1。反复断开重连可能是WiFi信号太弱。ESP32-S3的PCB天线性能在复杂环境中可能一般尽量让设备靠近路由器。6. 数据记录与存储打造简易温度监测器6.1 理解CircuitPython的文件系统与读写权限CIRCUITPY磁盘默认由你的电脑挂载为可读写状态方便你编辑代码。但CircuitPython运行时也想往这个磁盘写数据比如记录日志就会产生冲突。为了解决这个问题CircuitPython设计了一个精巧的“单写者”模式同一时间只能由电脑或CircuitPython程序其中之一进行写入操作。boot.py文件正是在这个环节发挥作用。它在CircuitPython启动时硬复位或重新上电运行比code.py更早。我们可以在boot.py里通过检测一个按钮的状态来决定将文件系统的写入权限分配给谁。6.2 实现双模式启动与温度记录这个项目将实现一个功能通过按住按钮启动让板子进入“数据记录模式”每隔10秒将CPU温度写入文件正常启动则为“编程模式”电脑可以自由编辑文件。第一步创建boot.py在CIRCUITPY根目录创建boot.py内容如下import time import board import digitalio import storage import neopixel # 初始化硬件 pixel neopixel.NeoPixel(board.NEOPIXEL, 1) button digitalio.DigitalInOut(board.BUTTON) button.switch_to_input(pulldigitalio.Pull.UP) # 提示用户NeoPixel亮起白色时按下按钮进入记录模式 pixel.fill((255, 255, 255)) # 白色 time.sleep(1) pixel.fill((0, 0, 0)) # 熄灭 # 关键操作根据按钮状态重新挂载文件系统 # button.value 为 True按钮未按下时readonlyTrueCircuitPython只读电脑可写 # button.value 为 False按钮按下时readonlyFalseCircuitPython可写电脑只读 storage.remount(/, readonlybutton.value) # 根据模式给出灯光提示 if button.value: # 未按下编程模式 pixel.fill((0, 255, 0)) # 绿色 time.sleep(0.5) pixel.fill((0, 0, 0)) else: # 按下记录模式 pixel.fill((0, 0, 255)) # 蓝色 time.sleep(0.5) pixel.fill((0, 0, 0))第二步创建code.py这是主数据记录程序import time import board import microcontroller import neopixel pixel neopixel.NeoPixel(board.NEOPIXEL, 1) LOG_FILE /temperature_log.txt LOG_INTERVAL 10 # 记录间隔单位秒 try: # 尝试以追加模式打开日志文件。如果文件系统对CircuitPython可写则进入此分支。 with open(LOG_FILE, a) as log_file: print(进入数据记录模式。开始记录温度...) while True: # 读取微控制器内部温度传感器数值单位摄氏度 temp_c microcontroller.cpu.temperature # 转换为华氏度可选 # temp_f temp_c * 9 / 5 32 # 构建日志行时间戳 温度 timestamp time.monotonic() # 自开机以来的秒数单调递增 log_line f{timestamp:.1f}, {temp_c:.2f}\n # 写入文件并立即刷新缓冲区确保数据落盘 log_file.write(log_line) log_file.flush() print(f已记录: {log_line.strip()}) # 视觉反馈记录时红灯亮1秒 pixel.fill((255, 0, 0)) time.sleep(1) pixel.fill((0, 0, 0)) # 等待剩余间隔时间 time.sleep(LOG_INTERVAL - 1) except OSError as e: # 如果发生OSError说明文件系统对CircuitPython是只读的编程模式或者已满。 print(f无法写入文件系统或发生错误: {e}) blink_delay 0.5 # 默认慢闪0.5秒表示只读模式 if e.args[0] 28: # 错误码28: 文件系统已满 print(警告文件系统已满) blink_delay 0.15 # 快闪0.15秒表示空间不足 # 进入错误指示循环根据blink_delay闪烁红灯 while True: pixel.fill((255, 0, 0)) time.sleep(blink_delay) pixel.fill((0, 0, 0)) time.sleep(blink_delay)第三步操作流程正常启动编程模式直接给板子上电或按复位键。NeoPixel会闪一下绿色然后熄灭。此时电脑可以读写CIRCUITPY磁盘你可以自由修改code.py等文件。板子上的程序不会记录数据红灯不会周期性闪烁。进入记录模式 a.按住板子上的Boot按钮不放。 b. 在按住按钮的同时按一下Reset复位键或者拔插USB线。 c. 你会看到NeoPixel先亮白色1秒提示窗口然后闪一下蓝色。此时松开按钮。 d. 现在CIRCUITPY磁盘在电脑上会显示为“只读”。板子开始每10秒闪一次红灯表示正在记录温度数据到temperature_log.txt文件。读取数据要读取记录的数据你需要先退出记录模式。方法是在不按按钮的情况下按一下Reset键或重新上电。板子会进入编程模式闪绿光此时电脑可以访问CIRCUITPY磁盘打开temperature_log.txt文件就能看到按时间戳和温度值排列的数据。深度解析与避坑指南storage.remount()的机制这个函数改变了CircuitPython内核对待CIRCUITPY文件系统的方式。当设置为readonlyFalseCircuitPython可写时它会卸载当前文件系统并以一种防止电脑写入的方式重新挂载。这就是为什么电脑端会看到磁盘变成“只读”。数据安全与flush()在嵌入式系统中突然断电可能导致正在写入的数据丢失。file.flush()方法强制将Python缓冲区中的数据写入到存储介质中虽然会降低一些写入速度但极大地提高了数据可靠性对于数据记录应用至关重要。温度数据的意义microcontroller.cpu.temperature读取的是芯片内核的温度通常比环境温度高。它不适合做高精度的室温测量但非常适合监测设备自身的运行状态比如判断是否过热。其变化趋势也能反映环境温度的变化。文件系统满的处理代码中特意处理了OSError: [Errno 28] No space left on device错误。当磁盘空间耗尽时程序会进入快闪红灯状态提醒用户。此时需要在编程模式下连接电脑删除或备份temperature_log.txt文件以释放空间。时间戳的选择这里使用了time.monotonic()它返回一个从开机开始持续递增的秒数不受系统时间设置影响适合用于计算时间间隔。如果你需要真实的日历时间则需要通过网络协议NTP从互联网获取这涉及更复杂的网络编程。7. 项目整合与扩展思路至此我们已经完成了从控制一个LED到读取模拟传感器再到连接网络最后实现本地数据记录的完整闭环。你可以将这些模块组合起来构建更复杂的应用。例如一个简单的物联网气象站原型可以这样设计感知将电位器替换为真正的数字温湿度传感器如DHT22或AHT20使用I2C或单总线协议。记录沿用本章的存储方案定期将温湿度数据记录到本地文件。上报在记录数据的同时通过WiFi模块每隔一段时间如每5分钟将数据打包发送到云服务器如Adafruit IO、Thingspeak或自建的MQTT服务器。交互保留按钮和NeoPixel。按钮可以切换工作模式如“仅记录”、“记录并上传”NeoPixel用不同颜色指示当前状态绿色正常蓝色发送中红色错误。这种模块化、渐进式的开发方式正是CircuitPython的魅力所在。它让你能够快速搭建起一个可工作的原型验证想法的可行性然后再逐步优化和增加功能。相比于传统嵌入式开发你节省了大量在底层驱动和调试上的时间可以将更多精力专注于产品逻辑和用户体验本身。
