[蓝牙水控器 FOSS]使用指南：打造校园热水自由（含离线控制+跨平台安装）

1. 项目概述

深圳市常工电子"蓝牙水控器"控制程序是一款专为国内高校宿舍热水系统设计的开源解决方案。该程序基于Web技术栈构建，实现了与宿舍蓝牙水控器的直接通信，让学生能够摆脱商业应用限制，自由控制热水供应。作为一款真正意义上的离线应用，它无需互联网连接即可运行，并且完全独立于微信等第三方平台，为校园生活带来真正的技术自主。

1.1 核心功能清单

• 🌐 纯离线操作模式（首次加载后无需网络）
• 📱 跨平台支持（Windows/macOS/Linux/Android/iOS/ChromeOS）
• 📲 PWA安装功能（可安装的网页应用，像原生App一样使用）
• 🔒 隐私保护设计，无数据上传
• ⚡ 轻量化架构，启动速度快

💡 小贴士

PWA（Progressive Web App）是一种特殊的网页应用，它可以像手机App一样安装在主屏幕，同时具备离线工作能力，是介于网页和原生应用之间的创新形态。

2. 核心优势

2.1 技术架构亮点

本项目采用TypeScript为主编程语言，辅以WebAssembly提升性能，通过HTML/CSS构建响应式界面。核心技术栈确保了：

• 代码可维护性和扩展性
• 跨设备兼容性
• 蓝牙通信的稳定性
• 用户界面的流畅响应

2.2 项目价值：重新定义校园热水系统

传统校园热水控制方案普遍存在以下问题：

• 依赖商业App或微信小程序，存在隐私风险
• 强制要求联网，增加使用门槛
• 界面复杂，操作流程繁琐
• 缺乏透明度和定制化可能

开源方案通过以下改进解决这些痛点：

1. 技术自主：用户掌握系统控制权，无需依赖第三方
2. 隐私保护：本地数据处理，无用户信息上传
3. 使用自由：离线可用，不受网络状况影响
4. 持续优化：开源社区共同维护，快速响应用户需求

💡 小贴士

项目采用MIT开源许可证，允许自由使用、修改和分发，确保技术方案的开放性和可持续性。

3. 实战指南

3.1 零基础部署流程

3.1.1 开发环境准备

✅ 安装Node.js和包管理器

# 检查Node.js版本（需v14.0.0以上）
node -v

# 检查npm版本
npm -v

# 或检查yarn版本
yarn -v

✅ 获取项目代码

git clone https://gitcode.com/gh_mirrors/wa/waterctl
cd waterctl

✅ 安装项目依赖

# 使用npm安装
npm install

# 或使用yarn安装
yarn install

⚠️ 注意：如果npm install失败，尝试清除npm缓存后重试：

npm cache clean --force
npm install

3.1.2 本地运行与构建

✅ 启动开发服务器

npm run dev
# 或
yarn dev

✅ 构建生产版本

npm run build
# 或
yarn build

✅ 本地预览构建结果

npm run serve
# 或
yarn serve

💡 小贴士

npm和yarn是JavaScript生态系统中最常用的两个包管理器。npm是Node.js默认内置的，而yarn通常提供更快的安装速度和更可靠的依赖解析。两者命令基本兼容，选择其一即可。

3.2 蓝牙连接全攻略

3.2.1 设备兼容性列表

设备类型	支持情况	推荐浏览器	特殊说明
Windows PC	✅ 完全支持	Chrome/Edge	需开启系统蓝牙
macOS	✅ 完全支持	Chrome/Safari	需授予蓝牙权限
Linux	✅ 完全支持	Chrome/Chromium	可能需要安装额外蓝牙库
Android手机	✅ 完全支持	Chrome/Edge/Cromite	Android 11+需位置权限
iPhone/iPad	⚠️ 有限支持	Bluefy浏览器	需专用浏览器，系统限制
ChromeOS	✅ 完全支持	系统自带浏览器	原生支持蓝牙API

3.2.2 连接步骤

✅ 启用设备蓝牙功能

• 桌面端：通过系统设置或任务栏图标开启蓝牙
• 移动端：在系统设置中开启蓝牙和位置服务（如需要）

✅ 启动应用并授权

• 打开应用后，在弹出的权限请求中选择"允许"
• 如未弹出请求，需在浏览器设置中手动开启蓝牙权限

✅ 搜索并连接设备

1. 点击应用主界面的"搜索设备"按钮
2. 在设备列表中选择您的蓝牙水控器（通常名称包含"WaterCtrl"或类似标识）
3. 点击"连接"并等待配对完成（可能需要几秒钟）
4. 连接成功后，界面将显示水控器状态和控制选项

⚠️ 注意：iOS设备必须使用Bluefy浏览器（App Store下载）才能支持蓝牙功能，这是由于Apple的系统限制。

💡 小贴士

蓝牙连接距离通常为10米以内，建议保持手机与水控器的距离在3米内以获得最佳连接稳定性。

3.3 无硬件开发方案

3.3.1 本地模拟器方案

✅ 获取水控器模拟器

git clone https://gitcode.com/gh_mirrors/wa/wateremu
cd wateremu

✅ 启动模拟器

npm install
npm run start

✅ 连接模拟器

1. 确保模拟器正在运行
2. 在本项目应用中搜索蓝牙设备
3. 选择名称为"WaterEmu"的模拟设备
4. 连接后即可进行模拟操作测试

3.3.2 在线沙箱测试

对于不便搭建本地环境的用户，可使用以下在线方式测试核心功能：

✅ 访问在线演示版

• 打开浏览器访问项目提供的在线演示页面
• 无需安装，直接体验UI界面和交互流程

✅ 使用浏览器开发者工具

1. 打开浏览器开发者工具（F12或Ctrl+Shift+I）
2. 切换到"控制台"(Console)选项卡
3. 输入测试命令模拟蓝牙操作：

// 模拟连接成功
window.simulateConnect(true);

// 模拟热水开启
window.simulateWaterOn();

// 模拟流量数据
window.simulateFlow(0.5); // 升/分钟

💡 小贴士

开发过程中，可结合模拟器和浏览器调试工具，使用console.log()输出关键变量，帮助追踪蓝牙通信流程和数据处理过程。

4. 常见问题

4.1 连接故障排查流程

1. 检查基础条件

   • [ ] 设备蓝牙是否开启
   • [ ] 应用是否获得蓝牙权限
   • [ ] 设备是否在有效范围内

2. 浏览器兼容性检查

   • [ ] 是否使用推荐浏览器
   • [ ] 浏览器版本是否最新
   • [ ] 如使用iOS，是否安装Bluefy

3. 连接重试步骤

   • [ ] 关闭并重新开启蓝牙
   • [ ] 刷新应用页面
   • [ ] 清除浏览器缓存
   • [ ] 重启浏览器后重试

4. 深度排查

   • [ ] 检查系统蓝牙服务是否正常运行
   • [ ] 尝试连接其他蓝牙设备验证功能
   • [ ] 查看浏览器开发者工具中的错误信息

4.2 典型问题解决方案

4.2.1 "不支持的浏览器"提示

问题表现：打开应用后显示浏览器不支持提示
解决步骤：

1. 确认使用推荐浏览器（Chrome/Edge等）
2. 更新浏览器至最新版本
3. iOS用户需下载Bluefy浏览器
4. 国产浏览器用户建议更换为Chrome

4.2.2 蓝牙权限问题

问题表现：无法获取蓝牙权限或权限遭拒
解决步骤：

1. 检查浏览器权限设置，确保蓝牙权限已启用
2. Android用户可能需要授予位置权限（系统限制）
3. 尝试在浏览器设置中重置网站权限
4. 重启浏览器后重新请求权限

⚠️ 注意：Android 11及更低版本中，蓝牙扫描权限被归类在"位置信息"权限中，这是系统设计限制，应用本身不会收集位置信息。

💡 小贴士

遇到问题时，首先查看应用的"疑难解答"页面，那里汇总了大多数常见问题的解决方案。如仍无法解决，可在项目issue区寻求帮助。

5. 贡献者参与路径

5.1 贡献方式

项目欢迎以下形式的贡献：

• 代码改进：修复bug、添加新功能
• 文档完善：补充使用说明、翻译内容
• 测试反馈：报告问题、提供使用体验建议
• 社区支持：帮助其他用户解决问题

5.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

5.3 社区交流

虽然我们不提供外部链接，但您可以通过项目内提供的联系方式参与社区讨论，获取开发帮助和最新动态。

💡 小贴士

首次贡献者可以从"good first issue"标签的任务开始，这些任务通常难度较低，适合新手熟悉项目流程。

---

通过本指南，您应该已经掌握了蓝牙水控器开源项目的核心使用方法和开发流程。无论您是普通用户还是开发者，都可以通过这个开源方案获得更好的校园热水控制体验，同时参与到项目的持续优化中。开源的力量在于集体智慧，期待您的加入，共同打造更完善的校园生活工具！