948462448/rinnai-c33-ha
GitHub: 948462448/rinnai-c33-ha
一个实验性的 Home Assistant 集成，通过透明 TCP 代理拦截和解析通信协议，实现对 Rinnai C33 锅炉的本地控制与状态监控。
Stars: 0 | Forks: 0
# Rinnai C33 Capture for Home Assistant
[中文说明](README.zh-CN.md)
这是一个用于 Rinnai C33 锅炉的实验性 Home Assistant 集成，使用
HF-LPB100 WiFi 遥控模块。
本项目将 Home Assistant 变为 Rinnai WiFi 遥控器与原厂云服务器之间的透明 TCP 代理。它可以观测原始的本地流量，在 Home Assistant 中公开有用的状态，并向已连接的遥控器发送少量经过测试的命令。
本项目与 Rinnai 没有任何隶属关系，也未获得其认可。
## 支持的功能
已在一个配备 HF-LPB100 WiFi 遥控器的 Rinnai C33 设备上进行了测试。
支持的命令：
| Home Assistant 服务 | 含义 |
| --- | --- |
| `rinnai_c33_capture.set_dhw_temperature` | 设置生活热水目标温度 |
| `rinnai_c33_capture.set_heating` | 启用或禁用供暖 |
| `rinnai_c33_capture.set_fast_hot_water` | 启用或禁用快速热水模式 |
公开的状态：
| 实体 | 含义 |
| --- | --- |
| `sensor.rinnai_c33_last_packet` | 代理状态、数据包计数器、最后数据包元数据 |
| `sensor.rinnai_c33_dhw_target_temperature` | 生活热水目标温度 |
| `switch.rinnai_c33_heating` | 底层供暖状态镜像 |
| `switch.rinnai_c33_fast_hot_water` | 底层快速热水状态镜像 |
| `sensor.rinnai_c33_temperature_42` | 候选只读温度或状态字段 |
| `sensor.rinnai_c33_temperature_43` | 候选只读温度或状态字段 |
| `binary_sensor.rinnai_c33_field_47` | 候选二进制 runtime/状态字段 |
其他 Rinnai 型号、固件版本或区域云 endpoint 的表现可能有所不同。
## 工作原理
HF-LPB100 模块通常被配置为 TCP 客户端。在观测到的设置中，它会连接到：
```
wifiboiler_s1.rinnai.com.cn:6969
```
此集成没有更改模块自身的服务器地址，而是保持该设备设置不变，并更改家庭网络内部的 DNS 解析：
```
wifiboiler_s1.rinnai.com.cn
```
此后，WiFi 遥控器将向 Home Assistant 发起其原有的 TCP 连接。
然后，Home Assistant 会向真实的上游服务器打开第二个 TCP 连接，并双向转发字节。
```
HF-LPB100 remote
-> wifiboiler_s1.rinnai.com.cn:6969
-> router DNS/hosts override
-> Home Assistant rinnai_c33_capture:6969
-> real Rinnai cloud server:6969
```
在转发流量时，集成会解析如下所示的 frame：
```
fa d4 ff ff
```
稳定观测到的字段有：
| 字段 | 含义 |
| --- | --- |
| `0x14` | 生活热水目标温度 |
| `0x18` | 启用供暖 |
| `0x13` | 快速热水 |
在控制方面，集成会向已连接的遥控器写入 cloud 风格的命令 frame。例如，将生活热水目标温度设置为 44 C 会发送：
```
fa d4 9f 37 ff ff 04 00 14 0e 01 2c
```
详细的协议说明位于 [docs/protocol.md](docs/protocol.md) 中。
## HACS 安装
是的，本仓库的结构支持作为 HACS 自定义仓库进行安装。
HACS 会将集成安装在 Home Assistant 的 `custom_components` 目录下。
1. 在 Home Assistant 中打开 HACS。
2. 进入 **Integrations**。
3. 打开右上角的三点菜单并选择 **Custom repositories**。
4. 添加此仓库 URL：
https://github.com/948462448/rinnai-c33-ha
5. 选择类别 **Integration**。
6. 下载 **Rinnai C33 Capture**。
7. 重启 Home Assistant。
HACS 安装完文件后，请继续进行下方的 YAML 和路由器 DNS 设置。
## 手动安装
将此目录复制到 Home Assistant 中：
```
custom_components/rinnai_c33_capture
```
最终路径应如下所示：
```
/custom_components/rinnai_c33_capture/manifest.json
/custom_components/rinnai_c33_capture/__init__.py
/custom_components/rinnai_c33_capture/services.yaml
```
复制文件后，请重启 Home Assistant。
## Home Assistant YAML
将以下内容添加到 `configuration.yaml`：
```
rinnai_c33_capture:
host: 0.0.0.0
port: 6969
upstream_host: wifiboiler_s1.rinnai.com.cn
upstream_ip: 123.56.82.103
upstream_port: 6969
remote_host: 192.168.1.90
log_file: rinnai_c33_capture.log
```
配置选项：
| 选项 | 必填 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `host` | 否 | `0.0.0.0` | TCP 代理的监听地址 |
| `port` | 否 | `6969` | TCP 代理的监听端口 |
| `upstream_host` | 否 | `wifiboiler_s1.rinnai.com.cn` | 原始云端主机名 |
| `upstream_ip` | 否 | 空 | 上游服务器的可选固定 IP |
| `upstream_port` | 否 | `6969` | 原始云端 TCP 端口 |
| `remote_host` | 否 | 空 | WiFi 遥控器的可选 IP；用于选择命令 socket |
| `log_file` | 否 | `rinnai_c33_capture.log` | HA 配置目录内的抓取日志文件 |
当您的路由器 DNS 覆盖将云端域名指向 Home Assistant 时，`upstream_ip` 非常有用。如果没有 `upstream_ip`，Home Assistant 可能会解析到相同的被覆盖地址，从而意外地连接回自身。
## 路由器 DNS 或 Hosts 设置
在您的路由器上添加本地 DNS 或 hosts 覆盖：
```
wifiboiler_s1.rinnai.com.cn
```
示例：
```
192.168.1.240 wifiboiler_s1.rinnai.com.cn
```
在 Xiaomi 或 Redmi 路由器上，这可以通过 Xiaomi WiFi 应用的自定义 Hosts 页面来完成。格式如下：
```
IP domain
```
请保留一条恢复途径。如果遥控器或移动应用停止工作，请移除此 hosts 覆盖并重启或重新通电 WiFi 遥控器。遥控器随后应恢复到原始的云端路径。
## 可选的 UI 控制
该集成公开了底层状态和服务。要实现常规的可点击 UI 控制，请将：
```
examples/rinnai_c33_controls.yaml
```
复制到您的 Home Assistant `packages` 目录中，或将其合并到您自己的 template YAML 中。
如果您尚未使用 packages，请将以下内容添加到 `configuration.yaml`：
```
homeassistant:
packages: !include_dir_named packages
```
然后将示例文件放置在：
```
/packages/rinnai_c33_controls.yaml
```
重启 Home Assistant。之后您应该会获得：
| 实体 | 用途 |
| --- | --- |
| `number.rinnai_dhw_target_temperature` 或本地化等效项 | 可点击的目标温度控制 |
| `switch.rinnai_heating_control` 或本地化等效项 | 可点击的供暖开关 |
| `switch.rinnai_fast_hot_water_control` 或本地化等效项 | 可点击的快速热水开关 |
Home Assistant 可能会根据显示名称生成本地化的实体 ID。如果确切的实体 ID 不同，请在开发者工具中搜索 `Rinnai`。
## 使用服务
设置生活热水目标温度：
```
service: rinnai_c33_capture.set_dhw_temperature
data:
temperature: 44
```
开启供暖：
```
service: rinnai_c33_capture.set_heating
data:
enabled: true
```
关闭供暖：
```
service: rinnai_c33_capture.set_heating
data:
enabled: false
```
开启快速热水：
```
service: rinnai_c33_capture.set_fast_hot_water
data:
enabled: true
```
关闭快速热水：
```
service: rinnai_c33_capture.set_fast_hot_water
data:
enabled: false
```
请从无害的空操作（no-op）测试开始，例如再次设置当前温度，或者关闭一个已经关闭的功能。
## 验证清单
重启 Home Assistant 后：
1. 确认 `sensor.rinnai_c33_last_packet` 存在。
2. 它的初始状态可能是 `listening`。
3. 如果未重新连接，请重启或重新通电 WiFi 遥控器。
4. 连接后，传感器属性应包含 `peer` 地址，并且 `packet_count` 应该增加。
5. 使用空操作（no-op）服务调用来验证命令注入。
需要检查的示例状态：
```
sensor.rinnai_c33_last_packet
sensor.rinnai_c33_dhw_target_temperature
switch.rinnai_c33_heating
switch.rinnai_c33_fast_hot_water
```
## 独立工具
在 Home Assistant 外部运行本地透明代理：
```
python3 tools/rinnai_c33_tcp_capture.py --host 0.0.0.0 --port 6969 \
--upstream-host 123.56.82.103 --upstream-port 6969
```
运行带有微型本地控制 API 的代理：
```
python3 tools/rinnai_c33_tcp_capture.py --host 0.0.0.0 --port 6969 \
--upstream-host 123.56.82.103 --upstream-port 6969 \
--control-host 127.0.0.1 --control-port 6970
```
控制 API 示例：
```
curl 'http://127.0.0.1:6970/dhw?temperature=44'
curl 'http://127.0.0.1:6970/heating?enabled=0'
curl 'http://127.0.0.1:6970/fast?enabled=1'
```
解码抓取的日志：
```
python3 tools/rinnai_c33_decode_capture.py captures/example.log
```
## 安全注意事项
- 本项目用于控制供暖设备。请仔细测试。
- 数据包抓取可能包含设备标识符和家庭行为数据。
- 除非您已进行审查和脱敏处理，否则请勿发布原始抓取数据。
- 确保路由器 hosts 覆盖易于撤销。
- 这是一个实验性的逆向工程集成，不是安全系统。
## 许可证
MIT
标签：Home Assistant, TCP代理, 并发处理, 智能家居, 智能锅炉, 流量拦截, 物联网, 逆向工具