基于PyPortal与光传感器的物联网闭环控制：从单向指令到可靠状态反馈

1. 项目概述与核心价值

如果你曾经尝试过用手机远程开关家里的台灯或者风扇，大概率会接触到“物联网”这个概念。简单来说，物联网就是让物理世界的“物”（比如电器、传感器）能够接入互联网，变得可以被远程感知和控制。听起来很酷，但很多入门项目往往只做到了“单向控制”——你点一下手机App，设备执行动作，至于设备到底有没有真的打开，你其实并不知道。网络延迟、信号中断都可能导致控制指令“石沉大海”，你在App上看到开关是“开”的，但设备可能早就因为意外断电而关闭了。

今天分享的这个项目，就是为了解决这个“控制失准”的痛点。它不仅仅是一个远程开关，更是一个带“眼睛”和“嘴巴”的智能节点。我们使用Adafruit PyPortal这款自带屏幕和Wi-Fi的开发板作为大脑，通过继电器控制家电的电源，同时，我们额外增加了一个BH1750环境光传感器，用它来“看”家电电源指示灯的状态。这样一来，系统就形成了一个闭环：你发送开关指令 -> PyPortal控制继电器 -> 家电状态改变 -> 光传感器检测指示灯变化 -> 将真实状态上报回云端。你在手机或电脑的仪表盘上，看到的将不再是“指令已发送”，而是“设备已确认开启/关闭”。

这个方案的核心价值在于可靠性和状态可观测性。对于智能家居、小型自动化设备监控，甚至是需要确认关键设备状态的工业原型场景，这种带反馈的机制能极大提升系统的可信度。你不再需要亲自跑到设备跟前去确认，云端仪表盘上的状态指示灯就是最真实的反馈。

2. 系统架构与核心组件选型解析

要搭建这样一个带反馈的物联网控制系统，我们需要一个清晰的架构。整个系统可以划分为三层：云端服务层、网络通信层和本地设备层。每一层的组件选择都直接关系到系统的稳定性、易用性和开发效率。

2.1 云端服务层：为什么选择Adafruit IO？

在物联网项目中，云平台负责接收、存储设备数据，并提供用户交互界面。市面上有AWS IoT、Azure IoT、阿里云物联网平台等众多选择，但对于个人开发者、创客和教育项目，我强烈推荐从Adafruit IO开始。

Adafruit IO是一个为创客和爱好者量身定制的物联网平台，它的最大优势是上手极其简单。你不需要去理解复杂的“物模型”、“产品”、“设备”三层概念，它的核心抽象只有两个：Feed（数据流）和Dashboard（仪表盘）。一个Feed就是一个可以收发数据的时间序列通道，比如我们项目中的relay流用于接收开关指令，status流用于上报设备状态。Dashboard则是将这些数据流可视化的网页界面，通过拖拽各种“块”（Block）如开关、图表、指示灯，几分钟就能搭建出一个专业的控制面板。

从技术角度看，Adafruit IO完美支持MQTT协议，并且提供了针对MicroPython/CircuitPython的专用库，封装了连接、认证等繁琐细节。其免费套餐对于个人项目和小型原型完全够用。相比之下，大型商业云平台虽然功能强大，但配置复杂、学习曲线陡峭，容易让初学者在概念阶段就失去信心。因此，对于我们的目标——快速实现一个可靠、可视化的远程控制原型，Adafruit IO是最佳选择。

2.2 本地设备层：PyPortal与外围硬件搭配

本地设备层是系统的“手”和“眼”，负责执行命令和感知环境。

主控单元：Adafruit PyPortalPyPortal是一款基于ATSAMD51的强大开发板，它集成了ESP32 Wi-Fi协处理器、3.2英寸触摸屏、MicroSD卡槽、内置扬声器以及多个STEMMA QT/Qwiic连接器。选择它而非普通的ESP32开发板，原因有三：

1. 集成度高：Wi-Fi、屏幕、扩展接口一体，省去了复杂的接线和电平转换，让项目更整洁。
2. 开发友好：原生支持CircuitPython，这是一种基于Python的微控制器编程语言，语法简单，交互式开发体验极佳，非常适合快速原型开发。
3. 可视化调试：自带的屏幕可以实时显示连接状态、传感器读数、错误信息，这在调试网络连接和传感器校准阶段是无价之宝。

执行单元：继电器模块继电器是一个电磁开关，我们用PyPortal的一个GPIO口（如D3）控制其线圈的通断，从而控制其常开/常闭触点的连接状态，进而控制接入的家电电源。选择继电器时，务必关注其负载能力（电压和电流）。对于控制台灯、风扇等小家电，一个支持250VAC/10A的继电器模块绰绰有余。同时，要选择带光耦隔离的继电器模块，这能将控制电路（低压直流）与被控电路（高压交流）完全电气隔离，保护你的主控板免受高压浪涌冲击，这是安全性的底线。

感知单元：BH1750光传感器为了实现状态反馈，我们需要感知家电电源指示灯的状态。为什么不直接用继电器本身的反馈或测量家电电流？因为前者需要特殊继电器，后者涉及高压测量，危险且复杂。用光传感器检测电源指示灯的亮灭，是一种非接触、安全、低成本的巧妙方案。 BH1750是一款数字环境光传感器，通过I2C接口通信，直接输出光照度值（单位：勒克斯Lux）。相比光敏电阻，它无需额外的模拟读取和分压电路，精度更高，受环境光干扰小，且内置了数字滤波。我们将它用黑色胶带紧密贴在家电的电源指示灯上，就能准确区分指示灯亮（高Lux值）和灭（低Lux值）的状态。

通信协议：MQTTMQTT是一种基于发布/订阅模式的轻量级消息协议，专为带宽有限、网络不稳定的物联网环境设计。在项目中，PyPortal作为客户端，订阅（Subscribe）云端relay主题以接收控制指令，同时向云端status主题发布（Publish）传感器读取的状态。Adafruit IO的MQTT代理服务器负责中转这些消息。这种异步、解耦的通信模式，使得设备与云端、设备与设备之间可以灵活通信，是物联网架构的基石。

3. 环境准备与硬件连接实操

在开始写代码之前，我们需要把硬件正确地组装起来，并配置好开发环境。这一步的细致程度直接决定了后续开发过程是否顺利。

3.1 硬件清单与连接指南

请确保你手头有以下部件：

1. Adafruit PyPortal开发板 x1
2. 5V继电器模块（带光耦隔离） x1
3. BH1750环境光传感器（STEMMA QT/Qwiic接口） x1
4. STEMMA QT/Qwiic 4芯连接线（公对公） x1
5. 杜邦线（母对母）若干
6. 家用电器（如台灯）及配套电源线
7. 黑色电工胶带或遮光胶带

连接步骤与原理：

1. PyPortal供电：使用USB-C数据线为PyPortal供电。此时，板载的NeoPixel指示灯会亮起。

2. 连接继电器：

   • 控制端：找到PyPortal上的D3引脚（或其他任何标注为数字IO的引脚）。用一根杜邦线连接D3到继电器模块的IN或SIG（信号）引脚。
   • 电源端：用杜邦线连接PyPortal的3.3V引脚到继电器模块的VCC引脚，连接PyPortal的GND引脚到继电器模块的GND引脚。这里特别注意：有些继电器模块需要5V驱动，请查阅你的继电器模块说明书。如果标明需要5V，则必须连接PyPortal的5V输出引脚到继电器的VCC，否则继电器可能无法可靠吸合。
   • 负载端：操作前务必断开所有电源！将家电的电源线剪断（或使用中间接插头），将其中一根线（通常是火线）断开，两端分别接入继电器模块的COM（公共端）和NO（常开端）螺丝端子。这样，当继电器线圈通电时，COM与NO接通，电路闭合，家电得电。

3. 连接BH1750传感器：这一步最简单。使用STEMMA QT连接线，一端插入BH1750传感器，另一端插入PyPortal上任意一个标有I2C或STEMMA QT的端口。这种防反插接口确保了电源（3.3V）、地（GND）和数据线（SDA, SCL）的正确连接。

4. 传感器安装：找到你家电源指示灯（通常是红色或蓝色LED）。用一小块黑色电工胶带，将BH1750传感器的感光窗口紧密地粘贴在指示灯上方，确保完全覆盖并隔绝外部环境光。这是保证测量准确性的关键，环境光泄漏会导致误判。

安全警告：涉及220V市电接线的部分，务必谨慎。如果你不熟悉强电操作，建议使用现成的、带插头的智能插座进行改装，或者在有经验的人员指导下进行。安全永远是第一位的。

3.2 软件环境配置详解

PyPortal运行CircuitPython，我们需要准备两样东西：固件和库文件。

1. 刷写CircuitPython固件：

   • 访问CircuitPython官网，找到PyPortal的专用页面，下载最新的.uf2固件文件。
   • 用USB线连接PyPortal到电脑，并快速双击板子上的RESET按钮。此时，电脑上会出现一个名为PORTALBOOT的U盘。
   • 将下载的.uf2文件拖入这个U盘。U盘会自动弹出，然后以CIRCUITPY的新名称重新出现。这表明固件刷写成功。

2. 安装必要的库文件：

   • 前往Adafruit的CircuitPython库包发布页面，下载最新版本的库包（是一个.zip文件）。
   • 解压该库包，我们需要将其中几个特定的库文件或文件夹复制到PyPortal的CIRCUITPYU盘里的lib文件夹中。如果lib文件夹不存在，就新建一个。
   • 必须复制的库：
     • adafruit_bh1750.mpy：BH1750光传感器驱动。
     • adafruit_bus_device文件夹：I2C等总线设备支持。
     • adafruit_esp32spi文件夹：ESP32 Wi-Fi协处理器驱动。
     • adafruit_minimqtt文件夹：MQTT客户端库。
     • adafruit_connection_manager文件夹：网络连接管理。
     • neopixel.mpy：控制板载RGB LED（状态指示用）。
     • adafruit_requests.mpy（可选，用于HTTP请求，本项目MQTT为主）。

3. 配置网络和Adafruit IO密钥：

   • 在CIRCUITPY盘的根目录下，找到或创建一个名为settings.toml的文本文件。这是CircuitPython存储敏感配置的标准方式。
   • 用文本编辑器打开settings.toml，填入你的Wi-Fi和Adafruit IO信息：

     CIRCUITPY_WIFI_SSID = "你的Wi-Fi名称" CIRCUITPY_WIFI_PASSWORD = "你的Wi-Fi密码" ADAFRUIT_AIO_USERNAME = "你的Adafruit IO用户名" ADAFRUIT_AIO_KEY = "你的Adafruit IO Active Key"

   • 保存文件。PyPortal会在启动时自动读取这些配置。

4. 云端配置：Adafruit IO仪表盘搭建

设备端准备就绪后，我们需要在云端创建数据通道和控制界面。Adafruit IO的界面非常直观，跟着步骤走，十分钟就能搞定。

4.1 创建数据流（Feeds）

数据流是数据的管道。我们需要创建两条流。

1. 登录Adafruit IO，点击顶部导航栏的Feeds。
2. 点击Create New Feed。
   • 第一个Feed：命名为relay。这个流将用于接收从Dashboard发送的开关指令（ON/OFF）。
   • 第二个Feed：命名为status。这个流将用于接收从PyPortal上报的设备真实状态（我们用1表示开，2表示关）。
3. 创建完成后，你会在Feeds列表里看到它们。记住它们的完整主题名，格式是<你的用户名>/feeds/relay和<你的用户名>/feeds/status。这个主题名将在代码中用到。

4.2 构建控制仪表盘（Dashboard）

仪表盘是用户交互的界面。

1. 点击顶部导航栏的Dashboards，然后点击Create New Dashboard。给它起个名字，比如Appliance Controller。
2. 进入新建的Dashboard，点击右上角的Create New Block（+图标）。
3. 添加开关控制块：
   • 在Block类型中选择Toggle（开关）。
   • 在Connect a Feed步骤，选择我们之前创建的relay流。
   • 你可以自定义开关的标签（如“客厅台灯”）、颜色等，然后点击Create Block。
4. 添加状态指示块：
   • 再次点击Create New Block，这次选择Indicator（指示灯）。
   • 在Connect a Feed步骤，选择status流。
   • 在配置页面，我们需要设置指示灯颜色与数值的映射关系。这是关键步骤：
     • 点击+ ADD VALUE。
     • 在VALUE输入框填1，在COLOR选择绿色（表示设备开启）。点击对勾确认。
     • 再次点击+ ADD VALUE。
     • 在VALUE输入框填2，在COLOR选择红色（表示设备关闭）。点击对勾确认。
     • 其他值（Default）可以设置为灰色。
   • 点击Create Block。
5. 调整两个块的位置，一个用于控制，一个用于显示状态。现在，你的云端控制面板就准备好了。点击Toggle开关，它会向relay流发送ON或OFF；当status流收到1或2时，指示灯会相应地变绿或变红。

5. CircuitPython代码深度解析与编写

有了硬件和云端配置，最核心的部分就是让PyPortal“活”起来的代码。我们将代码分解为几个功能模块，逐行理解其背后的逻辑。

5.1 导入库与初始化配置

代码开头是导入所有必需的库，并读取配置文件。

from os import getenv import time import board import busio from digitalio import DigitalInOut import neopixel import adafruit_bh1750 import adafruit_connection_manager from adafruit_esp32spi import adafruit_esp32spi from adafruit_esp32spi import adafruit_esp32spi_wifimanager import adafruit_minimqtt.adafruit_minimqtt as MQTT # 从 settings.toml 读取敏感信息 ssid = getenv("CIRCUITPY_WIFI_SSID") password = getenv("CIRCUITPY_WIFI_PASSWORD") aio_username = getenv("ADAFRUIT_AIO_USERNAME") aio_key = getenv("ADAFRUIT_AIO_KEY") if None in [ssid, password, aio_username, aio_key]: raise RuntimeError("请确保已在 settings.toml 中配置 WiFi 和 Adafruit IO 信息。")

这里使用getenv函数从settings.toml安全地获取凭证，避免了将密码硬编码在代码中的风险。RuntimeError检查确保了配置的完整性。

5.2 硬件引脚与传感器初始化

接下来，我们初始化所有连接到PyPortal的硬件。

### 传感器校准参数 ### APPLIANCE_ON_LUX = 30.0 # 家电指示灯亮起时的光照度阈值（单位：勒克斯） SENSOR_READ_TIME = 10.0 # 传感器读取间隔（单位：秒） ### WiFi 初始化 ### esp32_cs = DigitalInOut(board.ESP_CS) esp32_ready = DigitalInOut(board.ESP_BUSY) esp32_reset = DigitalInOut(board.ESP_RESET) spi = busio.SPI(board.SCK, board.MOSI, board.MISO) esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset) status_pixel = neopixel.NeoPixel(board.NEOPIXEL, 1, brightness=0.2) wifi = adafruit_esp32spi_wifimanager.WiFiManager(esp, ssid, password, status_pixel=status_pixel) ### 继电器控制引脚初始化 ### power_pin = DigitalInOut(board.D3) power_pin.switch_to_output() # 设置为输出模式 ### 光传感器初始化 ### i2c = board.I2C() # 使用板载I2C总线 sensor = adafruit_bh1750.BH1750(i2c)

• 校准参数：APPLIANCE_ON_LUX是判断设备是否开启的阈值。你需要根据实际测量值调整这个数。SENSOR_READ_TIME决定了状态上报的频率，10秒是一个兼顾实时性和功耗的折中选择。
• WiFiManager：这个类封装了连接Wi-Fi、处理重连的逻辑，并用板载NeoPixel LED提供视觉状态反馈（如连接中闪烁蓝色，连接成功常亮绿色）。
• 继电器引脚：将D3设置为数字输出。True（高电平）吸合继电器，False（低电平）释放。
• I2C与传感器：board.I2C()自动使用PyPortal的默认I2C引脚。adafruit_bh1750.BH1750(i2c)创建了传感器对象，之后调用sensor.lux即可读取光照度。

5.3 MQTT回调函数：事件驱动的核心

MQTT是异步通信，我们通过回调函数来响应不同事件。

### Feeds ### feed_relay = f"{aio_username}/feeds/relay" feed_status = f"{aio_username}/feeds/status" ### MQTT 回调函数 ### def connected(client, userdata, flags, rc): print("成功连接到 Adafruit IO！") # 可以在这里让状态灯显示特定颜色 def disconnected(client, userdata, rc): print("从 Adafruit IO 断开连接。") def on_relay_msg(client, topic, message): """处理继电器控制指令""" print(f"收到继电器指令: {message}") value = message.decode('utf-8') # 消息是字节流，需解码为字符串 if value == "ON": power_pin.value = True print("继电器已开启。") elif value == "OFF": power_pin.value = False print("继电器已关闭。") else: print(f"无法识别的指令: {value}")

• Feed定义：使用f-string动态生成完整的MQTT主题路径。
• on_relay_msg函数：这是整个控制逻辑的核心。当Adafruit IO的relay主题有新消息时，此函数被自动调用。它解析消息内容（ON/OFF），并直接控制power_pin的电平。这里有一个关键细节：从MQTT接收到的message是字节类型（bytes），必须用.decode('utf-8')将其转换为字符串再进行判断，否则if value == "ON"的比较会永远失败。

5.4 主循环逻辑：状态监控与发布

主循环负责维持MQTT连接、处理消息，并定期读取传感器状态、发布反馈。

# ... (MQTT客户端 setup 和 connect 代码之后) prv_sensor_value = 0 # 保存上一次的传感器读数 start_time = time.monotonic() # 获取单调时间，用于定时 while True: try: # 必须调用 loop() 来处理网络消息和保持连接 client.loop() now = time.monotonic() if now - start_time > SENSOR_READ_TIME: # 读取光传感器 sensor_value = sensor.lux print(f"光照度: {sensor_value:.2f} Lux") # 仅在读数发生变化时发布，避免网络流量浪费 if abs(sensor_value - prv_sensor_value) > 1.0: # 加入一个微小阈值防止抖动 if sensor_value > APPLIANCE_ON_LUX: print("检测到设备开启，发布状态 1") client.publish(feed_status, 1) else: print("检测到设备关闭，发布状态 2") client.publish(feed_status, 2) prv_sensor_value = sensor_value # 更新前值 start_time = now # 重置定时器 except (ValueError, RuntimeError, ConnectionError, OSError) as e: print(f"网络错误: {e}，尝试重连...") wifi.reset() client.reconnect() continue time.sleep(0.05) # 短暂延时，避免CPU占用率过高

• client.loop()：这是MQTT客户端的“心跳”，必须频繁调用（在主循环中）以处理传入消息、发送心跳包维持连接。
• 定时读取：使用time.monotonic()计算经过的时间，实现非阻塞的定时功能。每SENSOR_READ_TIME秒读取一次传感器。
• 变化检测：我们只在传感器读数发生显著变化（这里设定差值大于1.0 Lux）时才发布状态到云端。这被称为“变化上报”，能极大减少不必要的网络通信和数据存储，是物联网设备编程中的一个重要优化技巧。
• 异常处理：网络环境不稳定。try-except块捕获可能发生的各种网络异常（如断开连接、解析错误）。一旦出错，先重置Wi-Fi，然后尝试重连MQTT客户端。continue语句跳过后面的代码，直接开始下一次循环，尝试恢复。

6. 传感器校准与阈值确定实战

代码中的APPLIANCE_ON_LUX = 30.0只是一个示例值。你的家电指示灯亮度可能完全不同，因此校准是必须的步骤。不准确的阈值会导致状态反馈完全错误。

6.1 校准步骤详解

1. 编写并运行校准程序：将下面这段简单的代码保存为code.py并上传到PyPortal。它会每秒打印一次BH1750读取的光照度值。

   import time import board import adafruit_bh1750 i2c = board.I2C() sensor = adafruit_bh1750.BH1750(i2c) while True: print(f"{sensor.lux:.2f} Lux") time.sleep(1)

2. 采集数据：
   • 确保传感器已用黑胶带紧贴家电电源指示灯。
   • 打开串口监视器（如Mu编辑器、Thonny或VS Code的串口插件）。
   • 先关闭家电电源，观察并记录串口输出的Lux值。这通常是环境背景光，可能很低，比如0.5 Lux。
   • 再打开家电电源，观察并记录指示灯亮起时的Lux值。这个值会显著升高，可能是45.8 Lux。
3. 确定阈值：取“开”状态值和“关”状态值的中间值是一个稳健的策略。例如，(0.5 + 45.8) / 2 ≈ 23.15。我们可以将阈值设为25.0，留出一些余量。更严谨的做法是多次开关，记录多组数据，取一个稳定的中间范围。

6.2 集成阈值到主程序

将计算好的阈值更新到主程序的变量中：

APPLIANCE_ON_LUX = 25.0 # 根据你的实测校准值修改此处

然后重新上传完整的主程序代码。现在，你的状态反馈系统就针对你的特定设备校准好了。

7. 部署、测试与故障排查实录

将完整的code.py和配置好的settings.toml、库文件都放入PyPortal的CIRCUITPY盘后，系统会自动重启运行。以下是部署后的测试流程和常见问题排查。

7.1 系统测试流程

1. 观察启动状态：PyPortal启动后，板载NeoPixel LED会开始闪烁（颜色因库版本而异，常为蓝色），表示正在连接Wi-Fi。连接成功后，LED应变为常亮绿色（或你代码中设置的颜色）。同时，串口监视器会打印连接过程日志。
2. 测试远程控制：
   • 打开Adafruit IO的Dashboard页面。
   • 点击你创建的Toggle开关，将其拨到“ON”位置。
   • 观察：串口监视器应立即打印“收到继电器指令: ON”和“继电器已开启”。同时，你应该能听到继电器模块发出“咔嗒”一声，并且受控家电（如台灯）亮起。
   • 将开关拨到“OFF”，家电应关闭，串口有相应日志。
3. 验证状态反馈：
   • 在手动控制开关的同时，观察Dashboard上的Indicator（指示灯）块。
   • 当家电打开时，Indicator应在几秒内（由SENSOR_READ_TIME决定）变为绿色。
   • 当家电关闭时，Indicator应变为红色。
   • 关键测试：在Dashboard开关为“ON”时，手动拔掉家电的电源。此时继电器虽然闭合，但家电实际已断电。观察Indicator是否会在下一个检测周期变为红色？这正是我们增加反馈机制要解决的问题！

7.2 常见问题与解决方案速查表

在实际操作中，你可能会遇到以下问题。这里是我踩过坑后总结的排查清单：

7.3 进阶优化与扩展思路

这个项目是一个坚实的基础，你可以在此基础上进行多种扩展：

1. 增加本地控制：利用PyPortal的触摸屏，在本地绘制一个开关按钮，点击时同时控制继电器和向Adafruit IO发布状态，实现“本地-云端”双控。
2. 历史数据记录：Adafruit IO的Feed天然存储历史数据。你可以在Dashboard上添加一个Chart块，连接status流，可视化设备开关的历史时间线。
3. 设置自动化规则：利用Adafruit IO的Actions功能，可以创建简单的自动化。例如，当status流的值变为2（设备关闭）超过1小时，自动向你的邮箱或IFTTT发送一个提醒通知。
4. 多设备与分组控制：创建多个relay和status流（如relay_living_room,status_living_room），复制代码逻辑，修改引脚和Feed名称，即可控制多个设备。在Dashboard上为它们创建独立的控制块。
5. 降低功耗：如果使用电池供电，可以优化代码，在非检测时段让ESP32进入深度睡眠，仅由定时器唤醒进行状态检测和上报，大幅延长续航。

这个项目从单向控制到双向反馈的演进，正是物联网系统从“能用”到“可靠”的关键一步。通过亲自动手解决硬件连接、传感器校准、网络通信和状态同步中的每一个具体问题，你对物联网系统底层细节的理解会远比只看理论深刻得多。最重要的是，当你看到Dashboard上的指示灯真实地反映出远方设备的状况时，那种“一切尽在掌握”的成就感，正是驱动我们不断折腾下去的最大乐趣。