corekill/poolcomfort-galaxywind
GitHub: corekill/poolcomfort-galaxywind
通过逆向Android应用实现的Pool Comfort/Galaxywind泳池热泵本地Home Assistant集成，完全离线运行于局域网UDP通信之上，无需云账户。
Stars: 0 | Forks: 0
# Pool Comfort / Galaxywind — 本地 Home Assistant 集成 (HACS)
[](https://github.com/hacs/integration)
[
[](LICENSE)
[](https://www.python.org/)
**Pool Comfort** / **Galaxywind** / **GWCD** 泳池热泵的本地 UDP 客户端和 Home Assistant 集成。通过逆向 `com.gwcd.htc_en_oem` Android 应用实现——可通过 UDP `1194` 端口完全离线对抗热泵运行。**无需云端，无需厂商账号。**
已在 Pool Comfort 设备上测试；欢迎提供使用相同协议的其他 Galaxywind / GWCD 热泵的抓包数据。如果您使用的泳池热泵配备了 **Pool Comfort** 或 **Galaxywind** 移动应用，此集成应该可以使用。
## 安装
### 通过 HACS 安装（推荐）
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=corekill&repository=poolcomfort-galaxywind&category=integration)
1. 点击上方按钮（或在 HACS 中进入 *⋮ → Custom repositories*，粘贴
`https://github.com/corekill/poolcomfort-galaxywind`，类别选择
*Integration*）。
2. 在 HACS 中找到 **Pool Comfort / Galaxywind heat pump** 并点击 *Download*。
3. 重启 Home Assistant。
4. 添加集成：
[](https://my.home-assistant.io/redirect/config_flow_start/?domain=poolcomfort)
系统会要求输入热泵的 IP 和设备密码（默认为
`123456`）。序列号会自动检测。
### 手动安装
1. 将 `custom_components/poolcomfort/` 复制到您的 Home Assistant
`config/custom_components/` 目录中。
2. 重启 Home Assistant。
3. 使用上方的 *Add integration* 按钮。
## 功能特性
- **Climate 实体** — 目标温度，HVAC 模式（关闭 / 自动 / 制热 /
制冷），当前水温。
- **传感器** — 进水温度，出水温度，序列号（诊断信息）。
- **纯本地化** — 所有流量都通过 UDP `1194` 保留在您的局域网 (LAN) 内。无云账户，无互联网依赖。
- **轮询** — 默认 30 秒。集成每次轮询使用新的 UDP 会话，从而避免了固件短暂的空闲会话超时问题。
## 支持的硬件
任何可与 Pool Comfort / Galaxywind / GWCD
`com.gwcd.htc_en_oem` Android 应用配对的热泵*应该*都可以使用——这包括 OEM 贴牌设备（Pool Comfort, Galaxywind, GWCD 以及多个中国泳池热泵品牌）。
已确认：
- Pool Comfort（一台设备，固件大约发布于 2023 年）
如果您的设备可以使用（或不能使用），请提供一小份 PCAP 文件和设备型号并开启一个 issue——参见 [`docs/capture-mikrotik.md`](docs/capture-mikrotik.md)。
## 仓库结构
| 路径 | 内容说明 |
|---|---|
| [`poolcomfort_local/`](poolcomfort_local/) | 纯 Python 库：发现、登录、查询、设置命令 |
| [`custom_components/poolcomfort/`](custom_components/poolcomfort/) | Home Assistant 自定义组件 |
| [`scripts/`](scripts/) | PCAP 分析：转储数据帧，提取认证质询-响应对 |
| [`docs/`](docs/) | 逆向工程笔记（[协议](docs/protocol.md)，[抓包指南](docs/capture-mikrotik.md)） |
| [`tests/`](tests/) | 基于真实抓包数据的 `pytest` 测试向量 |
## 库 / CLI
Home Assistant 组件基于一个独立的库构建，您可以直接使用它：
```
python -m venv .venv
. .venv/bin/activate
pip install -e .
# 按 serial 发现，查询 state
python -m poolcomfort_local.cli --serial --password 123456 status
# 或按 IP
python -m poolcomfort_local.cli --host --password 123456 status
# Control
python -m poolcomfort_local.cli --host --password 123456 power on
python -m poolcomfort_local.cli --host --password 123456 set-temp 28
python -m poolcomfort_local.cli --host --password 123456 set-mode 2
```
设置温度和设置模式要求热泵处于开机状态；除非传递了 `--assume-on`，否则 CLI 会首先检查热泵状态。
PCAP 分析（需要 `scapy`）：
```
pip install -e '.[pcap]'
python scripts/pcap_dump.py capture.pcap --pump
python scripts/pcap_auth_pairs.py capture.pcap --pump
```
## 协议 — 已知信息
- UDP `8818` — 局域网发现
- UDP `1194` — 控制会话
- 设备类型 `0x000d` — 泳池热泵
- 登录：`MD5(nonce + challenge + MD5(password))`，两步握手
- 每个属性的字节序很重要：目标温度是 **BE u16**，模式和电源
是 **首字节 / LE u16**——参见 [`docs/protocol.md`](docs/protocol.md)。
- 每次执行 SET 后，热泵期望立即对其 `0b0a` 通知进行查询和 ACK，否则会话会在约 2 秒内失效。
完整说明参见 [`docs/protocol.md`](docs/protocol.md)。
## 状态 / 已知限制
- **工作详情位域**（压缩机、风扇、压力开关……）已在状态块 `0x0015` 中
部分解码，但位到标志的映射尚未最终确定。正在处理中。
- **长期持久会话** — 固件会在约 2 秒内杀死空闲会话，
除非重现被抓包应用的精确 ping 节奏。集成通过每次轮询重新连接来规避此问题。
- 仅测试了一台物理设备。更多设备的抓包数据将有所帮助。
## 致谢
本项目通过逆向工程 `com.gwcd.htc_en_oem` Android 应用及
MikroTik LAN 抓包构建。Galaxywind / GWCD / Pool Comfort 是其
各自所有者的商标；本项目不隶属于或受其任何一方认可。
## 许可证
MIT — 参见 [`LICENSE`](LICENSE)。
标签：DNS解析, Galaxywind, GWCD, HACS, Home Assistant, HVAC控制, IoT集成, MIT许可, Pool Comfort, Python, T1046, T1059, T1125, T1210, UDP通信, XXE攻击, 云资产清单, 局域网控制, 开源项目, 插件系统, 无云服务, 无后门, 智能家居, 智能家居集成, 暖通空调, 本地控制, 泳池热泵, 物联网, 离线控制, 设备集成, 逆向工具, 逆向工程