内容
# 泳池水位监测器
无线泳池水位监测器，适用于住宅泳池，具有自动补水控制功能。采用Particle Photon 2 + VL53L1X 激光测距传感器 + SHT41 环境传感器。可与Particle Cloud、MQTT/Home Assistant以及任何支持Webhook的平台集成。
## 功能特点
- **±1毫米精度**，通过VL53L1X激光测距传感器，透过密封玻璃窗口
- **非接触式测量** — 不需要在氯化水中安装电极或浮标
- **自动补水控制**，具有多重安全联锁：
- 最大补水时长超时（10分钟）
- 每日补水次数限制（漏水检测）
- 补水速率检查（卡住阀门检测）
- 低电池电压锁定
- **5个月电池寿命**，使用18650锂离子电池（使用2W太阳能板可无限使用）
- **多平台集成**：Particle Cloud、MQTT、Home Assistant、REST
- **凝结水监测**，通过SHT41环境传感器，在外壳内
## 硬件
参见`hardware/BOM.md`获取完整的物料清单。
总成本：约85加元。
## 编译和烧录
该项目使用Particle Workbench + DeviceOS 5.x。
```bash
# 安装Particle CLI
npm install -g particle-cli
particle login
# 依赖项已在project.properties中锁定，由云编译器解析
# （SparkFun_VL53L1X_Arduino_Library 1.2.9，adafruit-sht31 1.0.5，MQTT 0.5.6）
# 编译和烧录
particle compile photon2 . --saveTo firmware.bin
particle flash <device-name> firmware.bin
```
或使用Particle Workbench（VS Code扩展）— 推荐用于开发。
## 配置
在烧录前编辑`src/config.h`。关键参数：
| 参数 | 默认值 | 描述 |
|-----------|---------|-------------|
| `SKIMMER_DEPTH_MM` | 250 | 传感器到水池底部距离 |
| `LOW_WATER_TRIGGER_MM` | 80 | 自动补水激活级别 |
| `FILL_TARGET_MM` | 150 | 自动补水截止级别 |
| `MAX_FILL_DURATION_MS` | 600000 | 硬性安全超时（10分钟） |
| `SLEEP_DURATION_S` | 300 | 报告间隔（5分钟） |
| `MQTT_BROKER` | 192.168.1.10 | Mosquitto/HA代理IP |
## 校准
安装外壳和玻璃窗口后：
1. 完全排空水池
2. 调用校准函数：`particle call <device> calibrate`
3. 记录返回的基准距离
4. 更新`SKIMMER_DEPTH_MM`在`config.h`中
5. 重新烧录
`WINDOW_OFFSET_MM`考虑了ToF通过玻璃的折射误差 — 通常为1毫米硼硅酸盐玻璃的0-2毫米。
## 集成
### Particle Cloud
- REST：`GET https://api.particle.io/v1/devices/{id}/level_mm`
- 函数：`fill`、`stop`、`reset`、`calibrate`
- 事件：`skimmer/reading`、`skimmer/fill`、`skimmer/alert`
### MQTT主题
- `pool/skimmer/level` — 水位（毫米）
- `pool/skimmer/temperature` — 外壳温度（摄氏度）
- `pool/skimmer/humidity` — 外壳湿度（百分比）
- `pool/skimmer/battery` — 电池电压
- `pool/skimmer/fills_today` — 每日补水次数
- `pool/skimmer/total_fills` — 生命周期补水次数
### Home Assistant
参见`docs/home-assistant.yaml`获取完整的HA配置。
### Postgres + Claude（MCP）
`integration/`包将MQTT读取数据导入Postgres，并通过MCP服务器（`get_skimmer_level`、`get_fill_history`、`force_fill`、`get_evaporation_rate`）向Claude公开监测器。参见`integration/README.md`和`docs/SETUP.md`。
## 文档
- **[docs/SETUP.md](docs/SETUP.md)** — 端到端设置：固件 → 代理 → Postgres → Home Assistant → Claude
- **[docs/README.md](docs/README.md)** — 架构、数据流、完整API参考
- [docs/calibration.md](docs/calibration.md) — 窗口偏移校准程序
- [docs/mqtt-schema.md](docs/mqtt-schema.md) — MQTT主题和负载参考
## 安全注意事项
该设备控制水阀。需要的安全措施：
1. 设备垫上的硬件关闭 — 永远不要仅依赖固件
2. 填充管线上的压力释放
3. 大多数地区要求安装防回流阀
4. 在断开阀门的情况下测试升速安全功能
5. 在信任夜间操作之前测试最大持续时间超时
## 文件
```
skimmer-monitor/
├── src/
│ ├── skimmer-monitor.ino 主固件
│ └── config.h 可调参数
├── integration/
│ ├── src/ingest.ts MQTT → Postgres桥接
│ ├── src/mcp-server.ts MCP服务器向Claude公开水位监测工具
│ └── schema.sql Postgres模式
├── hardware/
│ ├── BOM.md 物料清单，含加拿大供应商
│ ├── wiring.md 引脚分配和接线图
│ └── enclosure.md 安装和防水指南
├── docs/
│ ├── SETUP.md 端到端设置指南
│ ├── README.md 架构和API参考
│ ├── home-assistant.yaml HA配置
│ ├── calibration.md 逐步校准程序
│ └── mqtt-schema.md MQTT主题参考
├── scripts/
│ └── monitor.sh 测试CLI订阅者
├── test/
│ └── bench-test.md 部署前测试清单
├── project.properties Particle CLI清单
└── README.md
```
## 许可证
MIT
## 作者
EcoWorks Web Architecture Inc.
