AquaSentinel 鱼缸守护助手

项目摘要

AquaSentinel 是一套基于 GD32F505VGT7 的开源鱼缸状态监测与本地提醒设计。它把水温、低水位、柜内漏水和光照信息集中到一块低压主板，帮助养鱼者及时发现异常，同时明确区分“测量正常”“测量异常”和“传感器不可用”。

项目面向家庭淡水缸、小型水草缸以及希望自行扩展设备的电子爱好者。它采用外接探头与模块，主板保持干燥，避免将普通空气传感器当成水下传感器。当前交付为可审查的硬件与固件工程，尚未完成打样和实物运行验证。

为什么做这个项目

养鱼时，单独看一眼温度并不能覆盖所有问题：水位下降、柜内积水、探头断线和灯光变化，往往需要分别观察。AquaSentinel 将这些分散的信息集中起来，让异常及其原因更容易被看见。

设计优先考虑日常可理解、可维护的功能：探头接错或失联时不显示成正常读数，水位线断开时给出提醒，声光告警与静音操作相互独立。它不直接控制加热棒、补水泵或市电设备，避免未经验证的执行控制给鱼缸带来额外风险。

主要设计亮点

把异常和失联分开呈现

水温采用外供电 DS18B20 探头接口，温度信息需要经过协议与数据有效性处理。无效读数不能被当成正常温度，陈旧数据也不能冒充本次测量结果。

低水位采用正常闭合的无源浮子接点。水位异常或电缆断开都会使输入变为开路，从而进入提醒路径。这种设计覆盖了断线场景，但不能区分水位异常与断线，也不能识别接线短路。

漏水接口采用检测到水时闭合的隔离干接点。它只接收开关状态，不让裸电极直接接入主板。常开接口不能识别断线，需要定期人工测试。

本地可用的低压设计

监测与声光提醒由本地主控承担，不以联网、云服务或手机在线为前提。输入为稳压 5 V，主板工作电压为 3.3 V。接口按用途分开，配合串联电阻、上拉与滤波，便于检查和逐项调试；这些措施不能替代长线防浪涌或安全认证。

可追溯的开源工程

项目提供 KiCad 原理图、PCB、BOM、制造文件、应用与板级源码、构建及检查记录。PCB 使用活动指定的 GD32F505VGT7，并在顶层丝印加入活动要求的两家官方标识。

代码验证、EDA 规则检查和未来的实物测试分别列出。这样，后续复现者可以知道哪些结论来自工具，哪些仍需在真实电路上确认，而不是只看到一张效果图。

系统组成

• 主控板：GD32F505VGT7，LQFP100，120 × 80 mm 双层 PCB。

• 水温：单只外部 3.3 V 供电、适合水浸封装的 DS18B20。

• 水位：正常水位闭合接地的无源浮子开关。

• 漏水：检测到水时闭合的隔离干接点探测器。

• 光照：外接 BH1750 模块，用于观察鱼缸周边照度变化，不等同于水下 PAR 测量。

• 交互：OLED 模块接口、报警 LED、有源蜂鸣器与按键。

• 调试与数据：SWD 和 3.3 V TTL UART。

外接探头、显示模块、电源、调试器和蜂鸣器需另外准备。接口的实际引脚顺序须按信号核对，不能直接假设不同厂家的模块兼容。

已实现的交互与提醒逻辑

• 水温约每秒采集一次，DS18B20 采用异步转换与 scratchpad CRC 校验；连续异常样本进入提醒，恢复使用迟滞，避免阈值附近频繁切换。

• 固件演示阈值为 ≤22°C 低温、≥28°C 高温，连续 3 次触发；分别回到 ≥23°C、≤27°C 后恢复。这些数值仅用于演示，不是特定鱼种的饲养建议。

• 低水位、漏水和温度探头故障有各自状态。探头失联不会自动解除已经存在的高低温告警。

• SSD1306 OLED 显示水温、水位、漏水、提醒倒计时、可选光照及告警状态。屏幕模块需另配，目前未做实屏验证。

• 投喂检查提醒从开机或上次到期确认开始，按经过 8 小时计时；不是每天固定时刻，也不是自动投喂。断电后重新计时。

• 短按按键静音 60 秒；投喂提醒已经到期时，同一按键同时确认该提醒。静音不抹除屏幕和 LED 上的异常状态。

• 串口输出 CSV，并保留最近 60 条 RAM 样本；没有断电存储、联网通知或手机应用。

GD32F505 在项目中的作用

GD32F505 统一承担采样调度、协议交互、有效性判断、提醒状态和本地输出。当前版本围绕可靠、可解释的采集与交互展开，没有为展示芯片指标而加入不必要的高速功能，也不声称已经达到芯片性能上限。剩余资源可供后续加入更完整的交互、长期日志和经过验证的扩展。

展示场景与后续实物验证

以下为打样后应执行的演示流程，不是已经拍摄或完成的实测：

1. 接入全部传感器，展示水温和环境状态。

2. 改变水温，观察阈值判定、恢复过程和提醒信息。

3. 断开浮子接线，展示异常输入不会被判为正常水位。

4. 用隔离接点模拟漏水，展示声光提醒，并验证静音后异常信息仍可见。

5. 拔掉水温探头，确认故障与当前有效测量明确区分。

6. 检查投喂提醒、按键交互与断电重启行为，避免把提醒确认描述为自动投喂完成。

实际展示时必须说明使用的是合成输入、模拟接点还是真实探头，不能用电脑模拟画面代替硬件运行证据。

当前验证与限制

新主板已通过 KiCad ERC 与 DRC 检查；独立复核确认原理图、PCB 和设计数据中的引脚网络一致。EDA 检查通过不代表电源完整性、通信时序、探头线缆兼容性、EMC 或长期可靠性已经验证。

固件的最终功能、目标构建结果和测试范围见 firmware/README_zh.md 及 tests/。待完成的实物工作包括限流上电、探头协议波形检查、参考仪器比对、故障注入、声光告警、断电重启和连续运行测试。

本设备不测量溶氧、pH、氨氮、亚硝酸盐或完整水质，不宣称能判断鱼只健康；温度阈值也必须根据实际饲养对象配置。主板与普通模块不得入水。不控制市电、加热棒、补水泵或投喂执行器，不应作为鱼缸唯一安全保障。

开源与第三方素材

原创硬件采用 CERN-OHL-P 2.0（宽松型）许可，原创固件采用 MIT 许可，完整条款随工程提供。兆易创新 SDK、数据手册、工具及标识遵循各自条款；第三方商标不因随工程分发而变为本项目原创或自由授权素材。设计源码和代码公开时需一并保留适用许可与来源说明。

提交材料索引

• 原理图与 PCB：hardware/ 中的 KiCad 工程。

• 原理图预览：outputs/schematic.pdf 与 schematic_preview.png。

• PCB 与丝印截图：outputs/pcb_layout.png、top_silkscreen.png。

• 物料与接口：hardware/BOM.csv、docs/HARDWARE.md。

• 固件与构建：firmware/、tests/。

• 官方标识来源：sources/LOGO_PROVENANCE.md。