用 USB-RS485 转换器（或 RS232 串口 / 局域网 TCP、UDP 透传模块）直连 VRF 中央空调室外机， Home Assistant 自动发现每一台内机，并为每台内机生成一个可控制的空调实体。
- 无需 ESPHome、无需中间网关固件，Home Assistant 主机直连 485 总线
- 支持 中弘 / 德姆瑞 / 硕创 三套协议，可「自动探测」
- 一台网关 = 一个配置项 = 一台 VRF；可同时添加多台、多品牌
- 每台内机一个独立实体，唯一 ID 稳定，不会重复生成
- 支持重新配置、删除/恢复不需要的内机实体
- 总线通信在工作线程完成，不阻塞 Home Assistant 事件循环，长期运行不占 CPU、不写硬盘
| 能力 | 说明 |
|---|---|
| 串口连接 | USB-RS485 转换器、主板 RS232（/dev/ttyUSB*、/dev/ttyS*） |
| 网络连接 | 局域网 TCP / UDP 串口透传模块 |
| 自动发现 | 上电后自动扫描内机列表，新接入的内机也会自动出现 |
| 实体 | 每台内机一个 climate 实体，含模式 / 风速 / 目标温度 / 室温 |
| 多网关 | 可同时添加任意数量的 VRF 网关，互不干扰 |
| 实体管理 | 可禁用、删除、恢复单个内机实体；可自动清理掉线内机 |
| 稳定性 | 通信在独立工作线程；断线自动重连；不做任何本地磁盘写入 |
| 品牌（协议） | 帧格式 | 校验 | 备注 |
|---|---|---|---|
| 中弘 | [地址][功能码][功能值][数量][记录…][校验和] |
字节和低 8 位 | 使用「外机地址 + 内机地址」复合地址 |
| 德姆瑞 | 固定 10 字节 | 字节和低 8 位 | 内机列表为 32 位位图 |
| 硕创 | 固定 12 字节 | Modbus CRC16 | 查询内机数量 + 单台参数 |
配置向导里选择「自动探测」即可：集成会依次尝试三种协议的发现报文，识别成功后锁定该协议。 也可以手工指定品牌，跳过探测过程。
VRF 室外机 / 网关 USB-RS485 转换器 Home Assistant 主机
A ──────────────────────── A
B ──────────────────────── B
GND ─────────────────────── GND
USB ────────────────── USB 口
- 选一个自动收发方向的 USB-RS485 转换器（推荐带光耦隔离、5V 供电）；
- 转换器插入 Home Assistant 主机（HA OS 用 USB 扩展口，Docker 需映射
/dev/ttyUSB0）； - A/B 两根线接室外机的 485 端子，A/B 接反只会不通讯，不会损坏设备；
- 确认主机上出现
/dev/ttyUSB0（Linux）或/dev/tty.usbserial-*（macOS）。
部分 VRF 网关提供 RS232 接口，按网关手册接线即可，配置时把串口设备改成 /dev/ttyS0 等。
实测要点（现场踩坑）
- 串口必须是 8N1（1 个停止位）。改成 2 个停止位后，设备会完全不应答，表现为「添加成功但一台内机都没有」。配置向导里已提供「停止位」选项，默认 1。
- 这类网关连续收帧会锁死：短时间内密集发几帧后，它就不再回包，需要断电重启网关恢复。因此集成每轮只查一台内机，并在连续失败时自动冷却 15 秒。
- 485 线路偶发丢字节，回包可能被截断；集成会丢弃残帧并重试，不会把半截数据当成状态。
- 中弘网关执行指令后约 2 秒才更新状态，期间不做回读，避免界面被旧值覆盖。
把「串口转网络模块」接在 485 总线上（模块的 RS485 端接 A/B，模块网口接交换机）， 然后在配置向导里选择 TCP 或 UDP 并填写模块 IP 与端口。
Linux 下串口通常属于 dialout 组：
sudo usermod -aG dialout homeassistant
# 重新登录或重启 HA 生效Docker 部署时记得把设备映射进去：
services:
- name: homeassistant
image: ghcr.io/home-assistant/home-assistant:stable
devices:
- /dev/ttyUSB0:/dev/ttyUSB0
volumes:
- ./config:/config- HACS → 右上角菜单 → 自定义仓库；
- 仓库地址填
https://github.com/symi-daguo/ha-vrf-bridge，类别选 集成； - 下载 VRF 中央空调网关；
- 重启 Home Assistant。
把 custom_components/vrf_bridge 整个目录复制到 Home Assistant 的 config/custom_components/ 下，然后重启。
设置 → 设备与服务 → 添加集成 → 搜索「VRF 中央空调网关」，按向导操作：
- 选择连接方式
串口（USB / RS232）：转换器直插主机TCP（局域网）/UDP（局域网）：串口转网络模块
- 填写参数
- 品牌：不确定就选「自动探测」
- 串口设备：
/dev/ttyUSB0等（下拉框里是本机实际检测到的串口，也可手动输入） - 波特率：与网关通讯参数一致，中弘/德姆瑞/硕创常见 9600
- 从机地址：网关在总线上的地址，多数为 1
- TCP/UDP 还需填写 主机地址 与 端口
- 集成会立即发一条发现报文验证链路。能连通但暂时没有内机也不会报错，网关稍后通电或 线路接好后会自己出现内机实体。
添加成功后，集成会自动扫描内机，每台内机生成一个实体，例如：
climate.vrf_zhong_hong_dev_ttyusb0_nei_ji_1 内机 1（制冷 24℃）
climate.vrf_zhong_hong_dev_ttyusb0_nei_ji_2 内机 2
（实体 ID 由「设备名 + 实体名」生成，实际以 Home Assistant 中显示的为准。）
| 方式 | 适用场景 | 填写内容 | 说明 |
|---|---|---|---|
| 串口 | USB-RS485 / RS232 直连主机 | 串口路径、波特率 | 最稳定，推荐 |
| TCP | 串口转网络模块 | 主机 IP、端口 | 长连接，延迟略高 |
| UDP | 串口转网络模块 | 主机 IP、端口 | 无连接，丢包时自动重试下一轮 |
三种方式的协议层完全一致，切换连接方式只需在「重新配置」里改一次。
每个内机对应一个 climate 实体：
| 属性 | 说明 |
|---|---|
| 状态 | 关机 / 制冷 / 制热 / 除湿 / 送风 |
| 当前温度 | 内机室温（协议不上报时留空） |
| 目标温度 | 16 – 30 ℃，步长 1 ℃ |
| 风速 | 自动 / 低 / 中 / 高 |
| 开关机 | 支持 climate.turn_on / climate.turn_off；开机自动恢复上次使用的模式 |
不会出现重复实体：实体唯一 ID 由「配置项 ID + 外机地址 + 内机地址」组成， 同一台内机重复扫描只更新状态，不会新建实体。
实体管理（三种方式，按需选择）：
- 禁用/删除单个实体：在实体卡片上点「⋯」→「禁用」或「删除」，Home Assistant 原生能力；
- 服务移除：
vrf_bridge.remove_unit会删除实体并把该内机加入忽略列表，之后不会再自动生成； - 服务恢复：
vrf_bridge.restore_unit取消忽略，下次扫描重新生成实体。
在「设备与服务 → VRF 中央空调网关 → 配置」中可调整：
| 选项 | 默认 | 说明 |
|---|---|---|
| 轮询间隔 | 2 秒 | 每轮读取一台内机状态的间隔。VRF 网关连续收帧会锁死（彻底不应答），所以刻意放慢、每轮只查一台 |
| 重新发现内机的间隔 | 60 秒 | 扫描内机列表的间隔，新接入的内机最多等这么久就会出现 |
| 允许制热 | 是 | 关闭后不提供制热模式，制热请求会被降级为制冷（部分工程机只支持制冷） |
| 自动清理已下线的内机 | 否 | 开启后，内机连续两次扫描不再上报时自动移除其实体 |
| 服务 | 参数 | 作用 |
|---|---|---|
vrf_bridge.rescan |
可选 device_id |
立即重新扫描内机（不等待下一个发现周期） |
vrf_bridge.remove_unit |
必填 address，可选 device_id |
移除指定地址内机的实体，并加入忽略列表 |
vrf_bridge.restore_unit |
必填 address，可选 device_id |
恢复被移除的内机实体 |
在「开发者工具 → 动作」里可以直接调用，例如：
action: vrf_bridge.rescan
target:
device_id: <VRF 网关设备 ID>action: vrf_bridge.remove_unit
data:
address: 3- 每台 VRF 对应一个配置项，在「设备与服务」里可以重复添加多台；
- 不同网关的实体唯一 ID 含各自的配置项 ID，不会互相覆盖或重复；
- 不同品牌可以共存：中弘走串口、德姆瑞走 TCP、硕创走 UDP 都可以，各自独立轮询；
- 每条总线各自占用一个连接，互不干扰。
添加时提示「无法打开该链路」
- 串口路径不对：用
ls /dev/ttyUSB* /dev/ttyS*或dmesg | tail确认设备名； - 权限不足：把 HA 用户加入
dialout组； - 端口被占用：其它程序（串口助手、Modbus 工具）占用了同一端口；
- Docker 部署未映射设备。
能添加但一直没有内机
- A/B 是否接反（接反只会不通讯）；
- 波特率、从机地址是否与网关一致；
- 485 总线是否需要终端电阻（长线两端各一个 120Ω）；
- 部分中弘机型需要在网关 Web 后台把「RS485 校验」改为「无校验」；
- 用「自动探测」再试一次，或手工指定品牌。
内机状态不刷新
- 检查轮询间隔是否过大；
- 总线冲突：同一总线上不能有两个主站同时发报文，集成已保证单线程串行发送；
- 部分机型在内机控制后 2 秒内不响应查询，属于设备特性，状态会在下一轮补齐。
日志里出现「VRF 总线异常，将重连」
- 链路被拔断或设备重启，集成会自动重连；
- 若持续出现，检查接线与供电。
# 单元测试（协议编解码 + 总线收发，使用内置模拟器）
python -m pytest tests -v
# 代码检查
ruff check .
ruff format --check .
mypy custom_components/vrf_bridge测试不需要真实设备：tests/support/simulator/ 内置了三套设备端模拟器，
用伪终端（PTY）与总线通信做端到端对拍，覆盖发现、查询、控制、噪声与分片报文。
- 只支持 VRF 室外机/网关的 485 透传协议，不支持厂家云端或私有 App 协议；
- 室温依赖设备上报，未上报时该属性为空；
- 目标温度范围按设备常用区间限制为 16–30 ℃；
- 中弘协议的「外机地址 + 内机地址」复合地址已支持，同一内机地址挂多台外机不会冲突；
- 内机掉线后实体不会自动变为「不可用」，可通过开启「自动清理已下线的内机」让其消失。