1. 项目缘起从“看”到“测”的硬件思维转变做开源硬件项目尤其是面向物联网和传感器应用很多朋友都是从点亮一个LED灯开始的。这当然没错但当我们想解决一个实际问题时比如监测一个鱼缸的水位、一个花盆的土壤湿度或者像我们这节课要做的——模拟监测湖水液位就会发现仅仅“看”是不够的我们需要“测”。这个“测”就是从数字世界感知物理世界的关键一步也是开源硬件从玩具走向工具的核心。“湖水液位监测仪”这个项目听起来有点宏大但我们用行空板和Python可以把它做得既小巧又实用。它的核心目标很简单利用一个模拟量传感器持续获取水位高度信息并通过行空板自带的屏幕实时显示出来当水位超过或低于某个安全阈值时还能发出警报。这背后涉及几个关键的技术点模拟信号的采集与处理、阈值的判断逻辑、以及人机交互界面的设计。对于初学者来说这是理解物联网数据流感知-处理-反馈的一个绝佳范例。我之所以选择行空板来做这个项目是因为它集成了Python运行环境、丰富的GPIO接口和一块高清屏幕省去了额外连接显示屏和配置复杂开发环境的麻烦让我们可以专注于逻辑本身。这节课我会带你从零开始手把手完成硬件连接、程序编写和调试优化让你不仅知道怎么做更明白为什么这么做。你会发现用Python玩转硬件远没有想象中那么难。2. 核心硬件选型与连接为什么是模拟量传感器在开始写代码之前我们必须先搞清楚要用什么硬件以及为什么要这么选。这是硬件项目成败的第一步选型错误后面代码写得再漂亮也是徒劳。2.1 传感器选型数字量与模拟量的本质区别监测水位市面上常见的传感器有两种工作方式数字式和模拟式。数字式水位传感器比如一些简单的浮球开关或导电式探头通常只有两个状态有水高电平或无水低电平。它就像一个开关只能告诉你“水位到了某个点”或者“没到”无法得知具体的水位高度。这种传感器成本低、电路简单适合只需要警戒水位如防止溢出的场景。模拟式水位传感器如我们本次要使用的则完全不同。它的输出是一个连续变化的电压信号。以常见的“水位压力传感器”或“液位变送器”为例其原理通常是测量水压静压而水压与水深成正比。传感器内部将这个压力信号转换成一个线性的电压信号例如0-3.3V或0-5V。行空板的ADC模数转换器引脚可以读取这个电压值并将其转换为一个数字量比如0-4095。通过校准我们就能将这个数字量映射为具体的水位高度厘米或米。对于“湖水液位监测”这种需要知道精确水位变化趋势的场景模拟量传感器是唯一的选择。它让我们能从“是否”的二元判断升级到“多少”的定量分析。注意市面上还有一种“电容式水位传感器”它通过检测电容变化来感知水位输出也可能是模拟量。但其线性度和稳定性可能不如压力式且容易受水质影响。对于学习项目我们常用一种更简单、低成本的“水位检测模块”它利用一排暴露的平行导线通过水的导电性来改变输出电阻从而引起输出电压变化。这种模块严格来说不是标准的模拟传感器其线性度较差但用于原理演示和定性观察完全足够且价格极具优势。本次教程为了普及性将以此类模块为例进行讲解但原理和代码与使用标准模拟传感器完全一致。2.2 硬件清单与连接图我们需要准备以下硬件行空板主控核心。模拟水位传感器模块建议选用工作电压为3.3V-5V的型号输出信号为模拟电压。杜邦线若干公对母。一杯水用于测试。连接步骤非常简单但每个引脚的选择都有其道理传感器VCC引脚-行空板的5V或3.3V引脚。我推荐先接3.3V因为行空板的ADC参考电压是3.3V传感器供电电压与参考电压一致时读数最稳定。如果传感器需要5V驱动再改用5V引脚。传感器GND引脚-行空板的任意GND引脚。形成共地这是电路正常工作的基础。传感器AO模拟输出引脚-行空板的Pin21。这是关键行空板上有多个ADC引脚但最常用且方便的是Pin21。为什么是Pin21因为在行空板的Python库pinpong库的默认映射中Pin21对应了一个易于使用的ADC通道。查看行空板官方文档可以确认这一点。连接完成后硬件部分就准备好了。这里有一个新手常犯的错误把传感器的DO数字输出引脚接到了ADC引脚上。DO引脚只有在水位超过模块上电位器设定的阈值时才会跳变它无法提供连续的模拟量务必确认你连接的是AO引脚。3. 代码实战从读取数据到构建监测界面硬件连接妥当后我们进入核心的编程环节。整个过程我们将分步实现确保每一步都理解透彻。3.1 环境准备与基础读数首先我们需要在行空板上创建一个Python脚本。行空板开机后通过局域网访问其IP地址在Web界面中的“文件”应用里新建一个.py文件例如water_level_monitor.py。# 导入必要的库 import time from pinpong.board import Board, Pin from pinpong.extension.unihiker import * # 初始化行空板 Board().begin() # 初始化ADC引脚Pin21对应行空板上的ADC0通道 adc Pin(Pin.P21, Pin.ANALOG) print(湖水液位监测仪启动...) print(当前ADC原始值 | 计算电压值) try: while True: # 读取ADC原始值范围通常为0-4095 adc_value adc.read_analog() # 将ADC值转换为电压值假设参考电压为3.3V voltage (adc_value / 4095) * 3.3 # 打印读数 print(f{adc_value:15} | {voltage:.2f} V) # 每秒读取一次 time.sleep(1) except KeyboardInterrupt: print(\n程序停止。)代码解析与原理Board().begin()这是pinpong库初始化板子的标准语句必须放在最前面。Pin(Pin.P21, Pin.ANALOG)这行代码声明我们使用Pin21引脚并将其模式设置为模拟输入ANALOG。此时行空板内部的ADC模块会开始对这个引脚上的电压进行采样。adc.read_analog()这个方法触发一次ADC转换并返回一个0-4095之间的整数。为什么是4095因为行空板使用的ADC通常是12位精度2^12 4096个等级从0到4095对应0V到参考电压通常是3.3V。电压转换公式voltage (adc_value / 4095) * 3.3是ADC计算的基础。它建立了数字量ADC值与模拟量电压之间的线性关系。运行这段代码将传感器的感应部分放入水中你会看到ADC值和电压值随着水位升降而变化。这就是我们监测的“源头数据”。3.2 标定与换算将电压转换为水位高度原始的电压值对我们来说没有直观意义我们需要将其转换为以厘米为单位的水位高度。这就需要“标定”。标定是一个简单的两步过程获取零点值将传感器完全脱离水面干燥状态记录此时的ADC值或电压值。这个值对应水位为0厘米。假设读数为adc_dry 120。获取满量程值将传感器浸入一个已知深度的水中例如10.0厘米确保感应部分完全被淹没记录此时的ADC值。假设读数为adc_wet 2500。有了这两个点我们就可以建立一个线性方程。原理是假设传感器的输出与水位深度成线性关系对于教学模块在大部分区间内近似成立。# 标定参数请根据你的实测值修改 ADC_DRY 120 # 干燥时的ADC值 ADC_WET 2500 # 浸入10.0厘米水深的ADC值 WATER_DEPTH_CALIBRATION 10.0 # 标定时用的水深单位厘米 def adc_to_cm(adc_val): 将ADC值转换为水位高度厘米 # 防止读数超出标定范围 if adc_val ADC_DRY: return 0.0 elif adc_val ADC_WET: return WATER_DEPTH_CALIBRATION # 线性插值公式 # 比例系数 (当前ADC值 - 干燥ADC值) / (湿润ADC值 - 干燥ADC值) ratio (adc_val - ADC_DRY) / (ADC_WET - ADC_DRY) # 水位 比例系数 * 标定水深 water_level ratio * WATER_DEPTH_CALIBRATION return round(water_level, 1) # 保留一位小数 # 在主循环中使用 while True: adc_value adc.read_analog() current_level adc_to_cm(adc_value) print(fADC: {adc_value}, 水位: {current_level} cm) time.sleep(1)实操心得标定是硬件项目中最容易出错也最关键的环节。务必保证标定环境稳定传感器静止、水面平静。对于要求不高的项目进行一次标定即可。但如果追求精度可以进行多次标定取平均值甚至在不同深度取多个点进行非线性拟合。另外传感器的特性可能会随时间、温度、水质导电率发生变化定期重新标定能保证长期准确性。3.3 阈值判断与报警逻辑监测仪不仅要显示还要能预警。我们设定两个阈值高水位警报线和低水位警报线。# 报警阈值单位厘米 HIGH_LEVEL_ALARM 8.0 LOW_LEVEL_ALARM 2.0 # 报警状态变量 alarm_status 正常 # 可以是“正常”、“过高”、“过低” def check_alarm(level): 检查水位并更新报警状态 global alarm_status if level HIGH_LEVEL_ALARM: alarm_status 过高 elif level LOW_LEVEL_ALARM: alarm_status 过低 else: alarm_status 正常 return alarm_status # 在主循环中整合 while True: adc_value adc.read_analog() current_level adc_to_cm(adc_value) status check_alarm(current_level) # 根据状态决定输出信息 if status 过高: print(f[警报] 水位过高: {current_level} cm) elif status 过低: print(f[警报] 水位过低: {current_level} cm) else: print(f[正常] 当前水位: {current_level} cm) time.sleep(1)现在你的监测仪已经具备了核心的“大脑”。但它还缺少一个友好的“面孔”我们接下来用行空板的屏幕来打造它。4. 打造图形化监测界面UI设计与优化行空板最大的优势之一就是其内置的屏幕和简化的GUI库unihiker。我们可以轻松地创建一个包含数字、文字和图形的实时显示界面。4.1 初始化GUI与绘制静态元素首先我们需要导入GUI库并创建画布。from unihiker import GUI # 创建GUI对象 gui GUI() # 设置背景色浅蓝色像湖水 gui.draw_rectangle(x00, y00, x1240, y1320, width0, fill#e0f7fa) # 绘制标题 title gui.draw_text(x120, y30, text湖水液位监测仪, font_size18, color#006064) # 绘制水位显示框 gui.draw_rectangle(x040, y080, x1200, y1140, width2, fill#ffffff) level_text gui.draw_text(x120, y110, text--.- cm, font_size24, color#00796b) # 绘制状态显示框 status_bg gui.draw_rectangle(x040, y0160, x1200, y1200, width2, fill#ffffff) status_text gui.draw_text(x120, y180, text状态: 初始化, font_size16, color#000000) # 绘制简单的液位指示条背景 gui.draw_rectangle(x060, y0220, x1180, y1280, width2, fill#e0e0e0) level_bar gui.draw_rectangle(x060, y0280, x160, y1280, width0, fill#0288d1) # 初始高度为0 # 绘制阈值刻度线 # 高水位线 (8cm对应在条状图中的位置假设条总高60像素对应10cm) high_line_y 280 - int((HIGH_LEVEL_ALARM / 10.0) * 60) gui.draw_line(x055, y0high_line_y, x165, y1high_line_y, width2, color#d32f2f) gui.draw_text(x70, yhigh_line_y-5, textf高:{HIGH_LEVEL_ALARM}cm, font_size10, color#d32f2f) # 低水位线 low_line_y 280 - int((LOW_LEVEL_ALARM / 10.0) * 60) gui.draw_line(x055, y0low_line_y, x165, y1low_line_y, width2, color#ff9800) gui.draw_text(x70, ylow_line_y-5, textf低:{LOW_LEVEL_ALARM}cm, font_size10, color#ff9800)这段代码绘制了所有不会频繁变化的界面元素标题、边框、刻度线、标签。draw_rectangle、draw_text、draw_line等方法返回的都是一个对象我们可以通过修改这些对象的属性来动态更新内容。4.2 实现动态数据更新与报警反馈接下来我们要修改主循环在每次读取传感器数据后更新屏幕上的动态元素水位数值、状态文字和液位指示条。import math def update_display(level_cm, status): 更新屏幕上的所有动态元素 # 1. 更新水位数字 level_text.config(textf{level_cm:.1f} cm) # 2. 更新状态文字和背景色 status_text.config(textf状态: {status}) if status 过高: status_bg.config(fill#ffcdd2) # 红色背景 status_text.config(color#c62828) elif status 过低: status_bg.config(fill#fff3e0) # 橙色背景 status_text.config(color#ef6c00) else: status_bg.config(fill#c8e6c9) # 绿色背景 status_text.config(color#2e7d32) # 3. 更新液位指示条 # 计算条的高度 (0-10cm 映射到 0-60像素) bar_height int((level_cm / 10.0) * 60) bar_height max(0, min(60, bar_height)) # 限制在0-60像素之间 bar_top_y 280 - bar_height # 通过重新配置矩形的位置和大小来“移动”它 level_bar.config(x060, y0bar_top_y, x1180, y1280) # 主循环整合 print(图形界面初始化完成开始监测...) try: while True: adc_value adc.read_analog() current_level adc_to_cm(adc_value) status check_alarm(current_level) # 更新屏幕显示 update_display(current_level, status) # 控制台也输出方便调试 print(f水位: {current_level:.1f} cm, 状态: {status}) time.sleep(0.5) # 更新频率提高到0.5秒一次使界面更流畅 except KeyboardInterrupt: gui.clear() # 程序退出时清屏 print(监测程序已停止。)现在一个功能完整、界面直观的湖水液位监测仪就诞生了屏幕会实时显示水位高度、用颜色区分的状态以及一个动态升降的液位条条上还有你设定的高低水位警戒线。5. 深度优化与实战避坑指南一个能跑通的Demo和一个健壮、可用的项目之间往往隔着无数个“坑”。下面分享几个我从实际项目中总结的优化点和避坑经验。5.1 数据滤波让读数更稳定传感器读数尤其是模拟量难免会有随机波动或噪声。直接使用原始数据会导致显示数值跳动影响观感和阈值判断的准确性。常用的简单滤波方法是移动平均滤波。class MovingAverageFilter: 一个简单的移动平均滤波器 def __init__(self, window_size5): self.window_size window_size self.data_queue [] def update(self, new_value): self.data_queue.append(new_value) if len(self.data_queue) self.window_size: self.data_queue.pop(0) # 移除最旧的数据 return sum(self.data_queue) / len(self.data_queue) # 在程序初始化部分创建滤波器 level_filter MovingAverageFilter(window_size5) # 窗口大小为5 # 在主循环中应用滤波 while True: adc_value adc.read_analog() # 先对ADC原始值进行滤波再转换为水位 filtered_adc level_filter.update(adc_value) current_level adc_to_cm(filtered_adc) # ... 后续逻辑不变窗口大小选择窗口越大曲线越平滑但对水位变化的响应也越迟钝。对于缓慢变化的湖水水位窗口设为5-10比较合适。你可以根据实际传感器的噪声情况调整。5.2 报警防抖避免临界状态频繁切换当水位在阈值线附近轻微波动时程序可能会在“正常”和“报警”状态之间高速切换导致屏幕闪烁和误报警。我们需要引入一个“死区”或“迟滞”逻辑。# 修改报警检查函数加入迟滞 ALARM_HYSTERESIS 0.2 # 迟滞范围0.2厘米 def check_alarm_with_hysteresis(level, previous_status): 带迟滞的报警检查 if previous_status 过高: # 如果之前是过高报警只有当水位降到低于 (高阈值 - 迟滞) 时才恢复正常 if level (HIGH_LEVEL_ALARM - ALARM_HYSTERESIS): new_status 正常 else: new_status 过高 elif previous_status 过低: # 如果之前是过低报警只有当水位升到高于 (低阈值 迟滞) 时才恢复正常 if level (LOW_LEVEL_ALARM ALARM_HYSTERESIS): new_status 正常 else: new_status 过低 else: # 之前状态是正常 if level HIGH_LEVEL_ALARM: new_status 过高 elif level LOW_LEVEL_ALARM: new_status 过低 else: new_status 正常 return new_status # 在主循环中需要记录上一次的状态 previous_alarm_status 正常 while True: # ... 获取当前水位 current_level ... current_status check_alarm_with_hysteresis(current_level, previous_alarm_status) previous_alarm_status current_status # 更新状态记录 # ... 更新显示 ...这个逻辑确保了水位必须越过阈值线并“离开”一小段距离后报警状态才会改变有效避免了抖动。5.3 传感器维护与常见问题排查读数漂移/不准原因A供电不稳。确保行空板供电充足连接充电宝或电源适配器传感器供电引脚连接牢固。可以尝试在传感器VCC和GND之间并联一个10uF-100uF的电解电容用于滤波。原因B导线接触不良或过长。模拟信号易受干扰尽量使用较短的杜邦线并确保插接紧密。避免信号线与电源线平行捆扎。原因C传感器氧化或污染。对于导电式水位模块探针长期使用可能氧化导致电阻变化。定期清洁探针表面。对于更精密的项目考虑使用光学或超声波水位传感器。屏幕刷新卡顿行空板的GUI刷新需要一定资源。如果主循环中time.sleep时间太短如小于0.1秒且进行了复杂的绘图操作可能会导致界面卡顿。将刷新频率控制在0.2-0.5秒通常是一个平衡点。优化update_display函数只更新真正需要变化的元素属性而不是每次都重绘整个界面。项目扩展思路数据记录使用Python的csv或sqlite3库将时间戳和水位数据记录到文件中用于后续分析趋势。网络上报利用行空板的Wi-Fi功能通过MQTT协议将数据发送到物联网平台如阿里云IoT、ThingsBoard等实现远程监控。多级报警除了屏幕变色可以连接一个蜂鸣器或LED在报警时发出声音或闪光实现声光报警。校准界面可以在屏幕上增加按钮引导用户进行一键校准提升产品的易用性。这个项目虽然以“湖水”为名但其内核——模拟量采集、数据处理、阈值判断和本地显示——是无数物联网监测应用的通用模板。无论是监测花盆土壤湿度、鱼缸水温还是仓库的温湿度只需更换传感器和调整标定参数整套代码框架都可以复用。