蓝牙水控器 FOSS 完全指南：从入门到精通

深圳市常工电子"蓝牙水控器"控制程序的开源实现，专为国内高校宿舍热水器打造。本指南将帮助你快速上手并充分利用这款开源工具的全部功能。

一、入门指南

1.1 什么是蓝牙水控器 FOSS？

蓝牙水控器 FOSS 是一款基于 Web 技术的开源应用，旨在为高校学生提供便捷的宿舍热水器控制方案。它通过浏览器蓝牙 API 与常工电子蓝牙水控器通信，让你摆脱厂商专用 App 的限制，真正实现"我的设备我做主"。

图 1：蓝牙水控器 FOSS 主界面展示

1.2 系统要求

设备类型	支持平台	推荐浏览器	特殊说明
桌面设备	Windows/macOS/Linux	Chrome 90+/Edge 90+	需开启蓝牙硬件
移动设备	Android 8.0+	Chrome/Cromite/Vivaldi	需授予位置权限（Android 11以下）
移动设备	iOS 14.0+	Bluefy浏览器	系统限制，需专用浏览器
平板设备	ChromeOS	系统自带浏览器	-

⚠️ 兼容性警告：国产浏览器通常存在兼容性问题，强烈建议使用上述推荐浏览器。iOS 用户请特别注意，由于系统限制，必须使用 Bluefy 浏览器才能正常使用蓝牙功能。

1.3 安装选项

1.3.1 PWA 安装（推荐）

PWA (Progressive Web App) 安装可将应用添加到桌面或主屏幕，获得接近原生应用的体验：

✅ 步骤：

1. 使用推荐浏览器访问应用主页
2. 点击地址栏右侧的「+」图标（Chrome/Edge）
3. 选择「安装到桌面」或「添加到主屏幕」
4. 在弹出的确认框中点击「安装」

💡 小贴士：安装后应用将具备离线运行能力，即使断网也能正常使用核心功能。

1.3.2 源码安装

适合开发者或需要自定义功能的用户：

✅ 步骤：

1. 克隆仓库：git clone https://gitcode.com/gh_mirrors/wa/waterctl.git
2. 进入项目目录：cd waterctl
3. 使用浏览器打开 index.html 文件

二、核心功能

2.1 设备连接

首次使用需要完成蓝牙设备配对：

⌛ 连接流程：

1. 确保热水器已通电并处于可连接状态
2. 打开应用，点击主界面「扫描设备」按钮
3. 在设备列表中选择你的水控器（通常以"CG"开头）
4. 点击连接，等待配对完成（首次连接可能需要10-15秒）

⚠️ 安全提示：蓝牙配对过程中请确保周围没有无关人员，防止他人恶意连接你的设备。

2.2 实时监控面板

成功连接后，主界面将显示以下关键信息：

• 🔹 当前状态：在线/离线
• 🌡️ 水温监测：实时显示出水温度
• 🌊 流量统计：当前水流速度（L/min）
• ⏱️ 使用时长：本次使用时间统计
• 💰 费用估算：基于流量和当地水价的实时费用计算

2.3 基本控制操作

控制面板提供直观的设备操作界面：

• 🚿 开关控制：一键启停水流
• 🌡️ 温度调节：滑动控制目标温度（部分型号支持）
• ⏱️ 定时功能：设置自动关闭时间，防止忘记关水
• 🔔 提醒设置：水温达标提醒、超时提醒

三、高级配置

3.1 Web API 接口

蓝牙水控器 FOSS 提供 RESTful API 接口，方便开发者进行二次开发或集成到其他系统：

3.1.1 接口基础信息

• 基础路径：/api/v1/
• 支持方法：GET/POST
• 数据格式：JSON
• 认证方式：无需认证（本地使用）

3.1.2 常用接口示例

获取设备状态

GET /api/v1/status

响应示例：

{
  "status": "online",
  "temperature": 42.5,
  "flow_rate": 1.8,
  "uptime": 125
}

控制设备开关

POST /api/v1/control

请求体：

{
  "action": "toggle",
  "timeout": 300
}

响应示例：

{
  "result": "success",
  "current_state": "on",
  "message": "设备已成功切换状态"
}

📌 开发提示：所有 API 接口均支持 CORS，可直接在前端 JavaScript 中调用，无需后端代理。

3.2 自定义主题

应用支持通过修改 CSS 变量自定义界面风格：

1. 打开设置 > 外观设置
2. 调整颜色方案、字体大小等参数
3. 点击「导出配置」保存你的主题设置
4. 通过「导入配置」分享给其他用户

3.3 数据记录与导出

高级用户可启用数据记录功能：

• 自动记录每次使用的水温、流量和时长
• 生成用水统计报表（日/周/月）
• 支持 CSV 格式导出，方便进一步分析

四、开发资源

4.1 项目结构

waterctl/
├── index.html        # 主界面
├── service-worker.js # PWA服务 worker
├── manifest.json     # PWA配置文件
├── light.min.css     # 样式表
├── waterctl.jpg      # 示例图片
├── README.md         # 项目说明
└── FAQ.md            # 常见问题

4.2 贡献指南

我们欢迎社区贡献：

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add some amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 打开 Pull Request

4.3 技术栈说明

• 前端框架：原生 JavaScript (Vanilla JS)
• UI 样式：Tailwind CSS (light.min.css)
• 蓝牙通信：Web Bluetooth API
• 离线支持：Service Worker + Cache API
• 部署方式：静态网页 (支持 GitHub Pages)

五、常见问题速查

5.1 连接问题

Q: 应用无法找到设备怎么办？

A: 请按以下步骤排查：

1. 确认水控器已通电且在有效范围内（通常3米内）
2. 检查设备蓝牙是否已开启
3. 关闭并重新打开浏览器
4. 尝试清除浏览器缓存后重试

Q: Android 设备提示"需要位置权限"？

A: 这是 Android 系统限制，蓝牙扫描需要位置权限。我们承诺不会收集或使用你的位置信息，仅用于蓝牙设备发现。

5.2 功能问题

Q: 为什么无法调节温度？

A: 可能有以下原因：

1. 你的水控器型号不支持远程温度调节
2. 设备连接不稳定，尝试重新连接
3. 浏览器权限不足，检查是否授予了必要权限

Q: 应用离线时能使用哪些功能？

A: PWA安装后，所有核心控制功能均可离线使用，但用水数据统计和报表功能需要联网同步。

5.3 故障排查流程图

开始排查 → 检查蓝牙是否开启 → 是 → 检查浏览器兼容性
                          ↓ 否 → 开启蓝牙
                                          ↓
检查设备是否在范围内 → 是 → 清除缓存后重试 → 问题解决？
                  ↓ 否 → 靠近设备后重试     ↓ 否
                                          联系开发者

六、附录

6.1 开源许可信息

本项目采用 MIT 开源许可协议：

MIT License

Copyright (c) 2023 celesWuff

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
...

完整许可文本请参见项目根目录下的 LICENSE 文件。

6.2 相关资源

• 项目源码：waterctl
• 常见问题：FAQ.md
• 图标资源：logo192.png / logo512.png
• 样式文件：light.min.css

---

通过本指南，你应该已经掌握了蓝牙水控器 FOSS 的基本使用方法和高级功能。如有其他问题或建议，欢迎参与项目讨论或提交 Issue。开源的力量在于社区，让我们一起打造更好的宿舍生活体验！