1. 从“Hello World”到“捕光者”：行空板Python的第一次物理交互
如果你已经跟着第一课点亮了行空板的屏幕，打印出了“Hello World”，那么恭喜你，已经迈出了从虚拟代码到物理世界交互的关键一步。但仅仅让屏幕显示文字，总感觉少了点什么，对吧？毕竟，我们玩硬件开发板，最过瘾的就是让代码去“触碰”现实世界——点亮一盏灯、转动一个马达，或者，像我们这节课要做的，去“捕捉”一束光。
“小小捕光仪”这个名字听起来就很有意思，它不是一个复杂的科学仪器，而是我们用行空板内置的光敏传感器，配合Python代码，亲手搭建的一个光线强度探测器。这节课的核心，远不止是学会读取一个传感器的数值。关键在于，你将第一次理解如何将物理世界连续变化的模拟信号，通过行空板这个“翻译官”，变成我们程序里可以处理、判断的数字信息。这个过程，是嵌入式开发、物联网应用乃至任何智能硬件项目的基石。我们会从最基础的电路原理讲起，一步步拆解代码，最后让你不仅能做出一个会报数的“捕光仪”，还能让它根据光线明暗做出不同的反应，比如让屏幕变色，或者用蜂鸣器发出警报。这才是“入门”该有的样子：知其然，更知其所以然，然后举一反三。
2. 光敏电阻与ADC：捕光仪的核心硬件原理
在动手写代码之前，我们得先搞清楚行空板是怎么“看见”光的。很多教程会直接让你调用一个light.read()之类的函数，然后告诉你这就读到了光线值。但作为入门，我们得挖深一点，这样以后遇到其他传感器（比如声音、温度、压力）你才能触类旁通。
2.1 光敏电阻：如何将光线变成电阻值
行空板上集成的光线传感器，其核心元件通常是一个光敏电阻（LDR）。它的工作原理非常直观：当照射在它表面的光线越强，其内部的导电能力就越强，表现出来的就是电阻值越小；反之，光线越暗，电阻值越大。你可以把它想象成一个会根据光线自动调节“宽阔程度”的水龙头，光线强，水龙头就开大（电阻小，电流容易通过）；光线弱，水龙头就关小（电阻大，电流难通过）。
但是，我们的Python程序是数字世界的居民，它只认识0和1，不认识“1000欧姆”或者“5000欧姆”这样的模拟电阻值。因此，我们需要一个“翻译官”把电阻值的变化，翻译成数字世界能理解的信号。这个翻译官就是模数转换器（ADC）。
2.2 ADC模数转换：从模拟到数字的桥梁
行空板上的主控芯片内置了ADC模块。我们通过一个简单的分压电路将光敏电阻接入ADC引脚。这个电路通常由光敏电阻和一个固定阻值的参考电阻串联而成，ADC测量的是它们中间连接点的电压。
这里涉及一个关键的计算，我画个简图帮你理解：
VCC (3.3V) —— [参考电阻 R_ref] —— (ADC测量点) —— [光敏电阻 R_ldr] —— GNDADC测量点（也就是光敏电阻和参考电阻的连接处）的电压V_adc由公式决定：V_adc = VCC * (R_ldr / (R_ref + R_ldr))
- 当光线很强时：
R_ldr很小，假设小到接近0欧姆。那么公式就变成了V_adc ≈ 3.3V * (0 / (R_ref + 0)) = 0V。ADC读到的电压很低。 - 当光线很暗时：
R_ldr很大，大到远大于R_ref。那么公式近似为V_adc ≈ 3.3V * (R_ldr / R_ldr) = 3.3V。ADC读到的电压接近电源电压。
所以，光线强弱 → 光敏电阻阻值变化 → ADC引脚电压变化，这条链路就打通了。ADC模块的工作，就是以极高的速度对这个电压进行“采样”，并将这个连续的电压值（例如0.823V）转换成一个离散的数字值。行空板的ADC通常是12位的，这意味着它会把0V到3.3V的电压范围，划分成 2^12 = 4096 个等级。转换后的数字值范围就是0到4095（或1到4096，取决于设计）。这个0-4095（或类似范围）的数字，就是我们最终在Python程序中读到的“光线强度值”。
注意：不同版本的行空板，其光线传感器接的ADC通道和参考电压可能略有差异，最终读数的原始范围也可能不是0-4095，可能是0-1023（10位ADC）或其他。但原理完全一致。我们编程时，通常会使用行空板库封装好的函数，它已经帮我们处理好了这些底层细节，返回一个更易理解的数值（比如0-100%的亮度百分比）。理解原理是为了在函数返回的值不符合预期时，你知道该去哪里排查。
3. 搭建你的第一个捕光仪：代码逐行解析
理解了硬件原理，写代码就变成了“按图索骥”。行空板的Python库unihiker已经为我们封装好了所有复杂的底层操作。我们直接开始动手。
3.1 环境准备与库导入
首先，确保你的行空板已经开机并连接到同一Wi-Fi，在你的电脑上使用VSCode或其他支持行空板远程开发的IDE，连接到行空板的IP地址。
创建一个新的Python文件，比如命名为light_detector.py。代码的第一步永远是导入必要的库。
from unihiker import GUI # 导入GUI库，用于显示 from pinpong.board import Board # 导入pinpong库的Board类，用于初始化板子 from pinpong.extension.unihiker import * # 导入行空板扩展，其中包含了光线传感器等硬件的驱动 import time # 导入时间库，用于控制循环间隔这里重点说一下pinpong库。它是一个优秀的国产开源硬件Python库，统一了不同硬件平台（如行空板、Arduino、micro:bit等）的编程接口。对于行空板，我们通过from pinpong.extension.unihiker import *这行代码，就自动导入了光线传感器light、蜂鸣器buzzer等所有板上资源的对象，无需我们再手动定义引脚。
3.2 初始化与图形界面创建
接下来，我们需要初始化行空板，并创建一个简单的图形用户界面来显示我们的捕光结果。
# 初始化行空板 Board().begin() # 初始化pinpong库，建立与硬件的通信 # 创建GUI对象 gui = GUI() # 在屏幕上显示一个标题 title = gui.draw_text(x=120, y=30, text="小小捕光仪", font_size=20, color="blue") # 创建一个用于动态显示光线数值的文本标签 # 我们先给它一个初始文本，位置放在标题下方 light_value_text = gui.draw_text(x=120, y=80, text="光线值: --", font_size=18) # 再创建一个文本标签，用于显示光线状态的描述（如“明亮”、“昏暗”） light_status_text = gui.draw_text(x=120, y=120, text="状态: --", font_size=18) # 甚至可以画一个简单的“光强条”，用矩形填充来直观表示 # 先画一个空的边框 bar_border = gui.draw_rectangle(x=50, y=160, w=220, h=30, width=2, color="black") # 再画一个填充矩形，初始宽度为0，颜色我们用绿色 light_bar = gui.draw_rectangle(x=52, y=162, w=0, h=26, color="green", fill=True)这段代码搭建了捕光仪的“仪表盘”。gui.draw_text和gui.draw_rectangle这些函数非常直观，通过指定坐标（x, y）、大小（w, h）、颜色等参数，就能在屏幕上绘制元素。注意，行空板的屏幕坐标原点(0,0)在左上角，x轴向右增加，y轴向下增加。
3.3 核心循环：读取、判断与更新
捕光仪的核心是一个无限循环，在这个循环里，我们不断地读取传感器数据，根据数据更新显示。
# 主循环 while True: # 1. 读取光线传感器数值 # light.read() 函数返回一个代表光线强度的数值。 # 根据行空板文档，这个值通常在0-100之间，越大表示光线越强。 light_value = light.read() # 2. 在文本标签上更新数值显示 # 使用 config() 方法动态更新已创建文本对象的内容 light_value_text.config(text=f"光线值: {light_value:.1f}") # :.1f 表示保留一位小数 # 3. 根据光线值判断状态，并更新状态文本和光强条 status = "" bar_width = 0 bar_color = "green" if light_value > 70: status = "非常明亮" bar_width = 216 # 对应最大宽度 (220 - 2*2边框内偏移) bar_color = "yellow" elif light_value > 30: status = "光线充足" bar_width = int((light_value - 30) / 40 * 216) # 在30-70之间线性映射宽度 bar_color = "green" elif light_value > 10: status = "光线昏暗" bar_width = int((light_value - 10) / 20 * 216) # 在10-30之间线性映射 bar_color = "orange" else: status = "黑暗环境" bar_width = int(light_value / 10 * 216) # 在0-10之间线性映射 bar_color = "red" # 更新状态文本 light_status_text.config(text=f"状态: {status}") # 更新光强条：通过改变矩形的宽度和颜色来实现动态效果 light_bar.config(w=bar_width, color=bar_color) # 4. 添加一个简单的蜂鸣器反馈（可选） # 如果光线突然变得很暗（比如用手捂住传感器），让蜂鸣器短响一声提示 # 这里需要记录上一次的值，我们假设一个全局变量 last_value，初始为None if 'last_value' not in locals(): last_value = None if last_value is not None and light_value < 15 and last_value >= 15: # 光线从亮（>=15）突然变暗（<15），触发蜂鸣器 buzzer.on() # 打开蜂鸣器 time.sleep(0.1) # 响0.1秒 buzzer.off() # 关闭蜂鸣器 last_value = light_value # 更新上一次的值 # 5. 控制循环速度，避免刷新太快消耗资源 time.sleep(0.2) # 每0.2秒检测一次，即每秒5次让我们拆解这个循环里的几个关键点：
- 数据读取：
light_value = light.read()是唯一与硬件传感器交互的代码，库函数帮我们完成了ADC读取、数值换算等一系列复杂操作，直接返回一个易用的值。 - 状态判断逻辑：我设置了四个阈值区间（>70, 30-70, 10-30, <10）。这些阈值不是固定的，你需要根据实际环境测试调整。比如在室内台灯下，读数可能是50；用手完全捂住传感器，读数可能降到5以下。实操心得：阈值设置是这类项目的灵魂，一定要通过
print(light_value)在实际环境中多测试几次，找到符合你感知的临界点。 - 动态图形反馈：通过
light_bar.config(w=bar_width, ...)动态改变矩形宽度，将抽象的数字转化为直观的图形，用户体验立刻提升一个档次。这里的宽度计算用了简单的线性映射，确保光强条能平滑地随光线变化。 - 事件触发反馈：通过比较本次值和上次值，我们实现了“当光线突然变暗时蜂鸣”的简单事件检测。这是一个非常重要的编程模式——状态变化检测，在物联网报警、交互触发等场景中极其常用。
- 循环延迟：
time.sleep(0.2)非常重要。如果没有它，while True循环会以CPU能承受的最快速度狂奔，可能导致屏幕刷新过快看不清，更重要的是会无谓地消耗大量计算资源。0.2秒的间隔对于光线检测来说足够灵敏，也保证了程序运行流畅。
4. 功能进阶：让捕光仪更智能
一个只会显示数字和条形的捕光仪，还只是个玩具。我们可以轻松地给它添加更多实用或有趣的功能，这也是学习编程的乐趣所在。
4.1 数据记录与简单分析
我们可以让捕光仪记录一段时间内的光线变化，并计算平均值、最大值、最小值。
# 在循环外初始化一个列表用于存储数据 light_history = [] MAX_HISTORY = 100 # 最多记录100个数据点 while True: light_value = light.read() # ... 更新显示代码 ... # 记录数据 light_history.append(light_value) if len(light_history) > MAX_HISTORY: light_history.pop(0) # 移除最旧的数据，保持列表长度固定 # 每记录10个点，计算并打印一次统计信息（可以改为在屏幕上显示） if len(light_history) % 10 == 0: avg_val = sum(light_history) / len(light_history) max_val = max(light_history) min_val = min(light_history) print(f"[记录] 平均: {avg_val:.1f}, 最高: {max_val:.1f}, 最低: {min_val:.1f}")这个功能模拟了数据采集系统的基本形态。你可以进一步思考：如何将这些数据保存到文件？如何绘制成简单的实时折线图？（行空板的GUI库支持画线功能）
4.2 与环境互动：光线控制LED或屏幕主题
行空板上还有LED灯。我们可以让捕光仪根据环境光，自动调节LED的亮度或颜色，甚至改变整个屏幕的主题色，实现初步的“自适应”功能。
# 假设行空板上的LED灯接在引脚P23（请根据实际板子文档确认） from pinpong.board import Pin, PWM # 导入PWM类用于调节LED亮度 led = PWM(Pin.P23) # 将LED引脚初始化为PWM输出 # 在主循环的状态判断部分添加 if light_value > 70: status = "非常明亮" led.duty(10) # PWM占空比设为10%，LED微亮 gui.config(bg="white") # 将屏幕背景设为白色 elif light_value > 30: status = "光线充足" led.duty(50) # 中等亮度 gui.config(bg="lightgray") elif light_value > 10: status = "光线昏暗" led.duty(150) # 较高亮度 (注意：有些LED是低电平驱动，逻辑可能相反) gui.config(bg="darkgray") else: status = "黑暗环境" led.duty(1023) # 最大亮度（对于10位PWM，1023为全亮） gui.config(bg="black") # 同时可以把文字颜色改成白色，确保在黑色背景下可见 title.config(color="white") light_value_text.config(color="white")重要避坑提示：驱动LED时，务必确认你的行空板LED是高电平驱动还是低电平驱动。高电平驱动意味着给高电压（如3.3V）LED亮；低电平驱动则相反，引脚输出0V时LED亮。行空板上的用户LED通常是低电平驱动。这意味着
led.duty(1023)（占空比100%）实际上输出了3.3V，如果LED是低电平驱动，此时LED反而最暗！实操心得：遇到驱动外设没反应或效果相反，第一件事就是查数据手册或原理图，确认电平逻辑。对于行空板内置LED，可以尝试将占空比数值从大到小反向测试。
4.3 联网与远程监控
行空板连上了Wi-Fi，不让它做点联网的事就太可惜了。我们可以将光线数据定时发送到物联网平台（如阿里云IoT、ThingsBoard等），或者简单地发送到你的手机通知。
这里以一个最简单的例子——通过HTTP GET请求将数据发送到一个网络服务（如IFTTT Webhooks）来触发手机通知为例。你需要先在IFTTT上设置好Applet。
import urequests # 行空板MicroPython常用的网络请求库 # IFTTT的Webhooks触发URL，替换成你自己的key和事件名 IFTTT_URL = "https://maker.ifttt.com/trigger/light_alert/json/with/key/YOUR_KEY_HERE" # 在主循环中，可以设定一个发送间隔，比如每10秒发送一次，或者当光线低于阈值时发送 send_interval = 10 last_send_time = time.time() while True: # ... 读取和显示代码 ... current_time = time.time() # 条件触发：当光线突然变得极暗，立即发送警报 if light_value < 5 and ('last_value' in locals() and last_value >= 5): try: # 构建包含光线值的JSON数据 data = {"value1": light_value} # 发送POST请求 response = urequests.post(IFTTT_URL, json=data) print("警报已发送:", response.text) response.close() except Exception as e: print("网络发送失败:", e) # 定时发送：每隔一段时间发送当前数据 if current_time - last_send_time > send_interval: try: data = {"value1": light_value, "value2": status} response = urequests.post(IFTTT_URL, json=data) print("定时数据已发送:", response.text) response.close() last_send_time = current_time except Exception as e: print("定时发送失败:", e) last_value = light_value time.sleep(0.2)这个例子展示了如何将本地传感器数据与云端服务连接。注意事项：网络操作（urequests）可能会因为网络不稳定而失败，所以一定要用try...except包裹起来，避免程序因网络异常而崩溃。同时，网络请求比较耗时，会阻塞主循环，如果发送频率很高，可能会影响屏幕更新的流畅度。在实际项目中，可以考虑使用异步任务或者更轻量级的协议（如MQTT）。
5. 调试与优化：让捕光仪工作得更稳定
第一个版本的程序跑起来后，你可能会发现一些“小毛病”，比如数值跳动太厉害、屏幕刷新闪烁、或者在某些极端条件下程序行为异常。别担心，这都是正常的，接下来我们就来“打磨”这个捕光仪。
5.1 软件滤波：让数值不再“跳舞”
光线传感器读到的原始值可能会有微小波动，导致显示的数字和条形图不停抖动。这在模拟信号读取中非常常见。我们可以通过简单的软件滤波算法来平滑数据。
移动平均滤波是最简单有效的一种。它的原理是维护一个最近N次读数的列表，每次显示时取这个列表的平均值。
# 在循环外初始化一个滤波队列 filter_window = [] WINDOW_SIZE = 5 # 窗口大小，表示取最近5次读数的平均值 while True: raw_value = light.read() # 读取原始值 # 1. 更新滤波窗口 filter_window.append(raw_value) if len(filter_window) > WINDOW_SIZE: filter_window.pop(0) # 保持窗口大小固定 # 2. 计算滤波后的值 filtered_value = sum(filter_window) / len(filter_window) # 3. 使用滤波后的值进行后续显示和判断 light_value = filtered_value # 替换原来的 raw_value # ... 后续的显示、判断逻辑全部使用平滑后的 light_value ... light_value_text.config(text=f"光线值: {light_value:.1f}") # ...仅仅增加这短短几行代码，你的捕光仪显示就会立刻变得稳定、顺滑。窗口大小WINDOW_SIZE是一个可调参数：值越大，曲线越平滑，但对光线变化的反应也越迟钝；值越小，反应越快，但可能不够平滑。对于光线检测，5到10是一个不错的起点。
5.2 优化显示性能：避免不必要的屏幕重绘
在我们的代码中，每次循环都会调用light_value_text.config(...)和light_bar.config(...)来更新屏幕元素。即使数值没有变化，这些操作也会执行。虽然对于这个简单程序影响不大，但养成优化习惯很重要。
我们可以增加一个判断，只有当数值或状态确实发生变化时，才去更新屏幕。
# 在循环外记录上一次显示的值和状态 last_display_value = None last_display_status = "" last_display_width = 0 while True: # ... 计算 light_value, status, bar_width ... # 仅当数值变化超过一定阈值（比如0.5）时才更新数值文本 if last_display_value is None or abs(light_value - last_display_value) > 0.5: light_value_text.config(text=f"光线值: {light_value:.1f}") last_display_value = light_value # 仅当状态文字变化时才更新状态文本 if status != last_display_status: light_status_text.config(text=f"状态: {status}") last_display_status = status # 仅当光强条宽度变化超过1个像素时才更新图形（避免频繁微调） if abs(bar_width - last_display_width) > 1: light_bar.config(w=bar_width, color=bar_color) last_display_width = bar_width # ... 其他代码 ...这种优化在元素更多、更复杂的图形界面中效果尤为明显，可以显著降低CPU使用率，让程序运行更流畅。
5.3 异常处理与程序健壮性
一个健壮的程序应该能应对各种意外情况。比如，万一光线传感器硬件临时故障（虽然概率极低），light.read()会不会报错导致整个程序崩溃？我们可以提前预防。
while True: try: # 将所有与硬件交互和核心逻辑放在try块内 light_value = light.read() # ... 所有后续计算和显示代码 ... except Exception as e: # 如果发生任何异常，捕获它并在屏幕上显示错误信息，而不是让程序静默崩溃 error_msg = f"传感器读取错误: {e}" print(error_msg) # 可以在屏幕上固定位置显示一个错误提示 # 先检查错误信息文本对象是否已创建，如果没有则创建 if 'error_text' not in globals(): error_text = gui.draw_text(x=50, y=200, text="", font_size=12, color="red") error_text.config(text=error_msg) # 等待一段时间后重试，避免疯狂报错 time.sleep(2) time.sleep(0.2)此外，我们还可以增加一个“校准”功能。因为不同环境下的“黑暗”和“明亮”标准不同，我们可以让用户手动校准。思路是：在程序启动时，提示用户“请将传感器置于最暗环境并按A键”，记录下此时的读数作为dark_reference；然后提示“请置于最亮环境并按B键”，记录作为bright_reference。之后所有的读数都可以映射到0-100的百分比范围：percentage = (current - dark_ref) / (bright_ref - dark_ref) * 100。这样你的捕光仪就能适应任何安装环境了。这个功能就留给你作为课后扩展练习。
6. 项目扩展思路：从捕光仪到创意应用
掌握了捕光仪的核心原理和实现方法后，你已经拥有了一个感知环境光线的能力。这个能力可以成为许多有趣项目的起点。下面分享几个我实践过或觉得很有潜力的扩展方向，希望能激发你的创意。
6.1 自动夜灯/桌面氛围灯
这是最直接的应用。将行空板连接一个可调光的LED灯带（需通过继电器或MOS管模块控制），你的捕光仪程序稍加修改，就能变成一个智能光控开关。
核心逻辑：设定一个光线阈值（如light_value < 20）。当环境光低于阈值时，自动打开LED灯带，并根据时间或手动设置调节亮度和色温（如果是RGB灯带）；当环境光高于阈值时，自动关闭灯带以节能。你甚至可以加入人体传感器（如红外热释电传感器），实现“人来灯亮，人走灯灭，光线充足时不亮”的完全自动化场景。
实操要点：驱动大功率LED灯带务必使用外接电源和合适的驱动模块（如MOS管或固态继电器），切勿直接用行空板的GPIO引脚驱动，电流会烧毁板子。
6.2 植物生长监测仪
对于家庭种植爱好者，你可以将捕光仪放置在盆栽附近，长期监测植物接收的光照是否充足。
升级方案：
- 数据记录：将每小时的平均光照强度记录到行空板的SD卡或通过Wi-Fi上传到云端数据库。
- 可视化：在行空板屏幕上绘制过去24小时或一周的光照曲线图。
- 智能提醒：设定不同植物所需的光照时长和强度阈值。例如，多肉植物需要强光，如果连续三天日均光照不足，屏幕提示“请为多肉植物补光”；绿萝耐阴，如果光照太强则提示“避免阳光直射”。
- 联动控制：如果搭配了智能插座，甚至可以在光照不足时，自动开启补光灯一段时间。
这个项目将单一的传感器读数，升级成了一个具有数据记录、分析和决策建议的简易物联网系统。
6.3 简易相机曝光辅助器
喜欢手机摄影的朋友可能遇到过这样的问题：在复杂光线下，手机自动曝光不一定准确。你可以用行空板做一个“点测光”工具。
实现思路：将捕光仪程序读数范围精细化为更接近摄影曝光EV值的范围。在屏幕上显示当前光线强度对应的建议快门速度、ISO和光圈组合（需要你事先根据相机和测光表原理，建立一个简单的换算公式或查找表）。你甚至可以加入一个“锁定”按钮（用行空板的触摸屏或物理按键），按下后锁定当前曝光参数，方便你移动到不同构图位置进行对比。
技术深化：这个项目会促使你去学习基础的摄影曝光原理，并将物理测量值与摄影参数联系起来，是跨学科实践的好例子。
6.4 结合其他传感器：环境监测站
光线 rarely works alone。将光敏传感器与行空板集成的或外接的温湿度传感器（如DHT11）、声音传感器结合起来，你就搭建了一个多功能环境监测站。
代码架构：你可以设计一个多线程或异步任务的结构。一个线程负责循环读取所有传感器数据；另一个线程负责更新GUI显示；还可以有一个线程负责定时将数据打包上传。屏幕上可以分区域显示光照、温度、湿度、噪音等级的实时值和历史曲线。
挑战与收获：这个项目会涉及到多任务编程、数据同步、GUI布局优化等更进阶的内容。当你看到一个小小的行空板同时稳定地监控着四五种环境参数时，那种成就感是无与伦比的。
从我个人的经验来看，硬件编程项目最大的魅力就在于这种“可触摸的扩展性”。一个简单的捕光仪，就像一颗种子，理解了它的原理（ADC、分压电路、软件滤波），熟练了它的工具（pinpong库、GUI绘制、循环逻辑），你就能把它应用到无数个具体的场景中去。下次当你遇到一个需要感知光线的创意时，你不会再觉得无从下手，而是会自信地说：“这个简单，我用行空板加个光敏就能搞定。”这才是真正意义上的“入门”。