ChristopherJacob/ha-countrymod-ac

# CountryMod RV 空调 — Home Assistant 集成 对市售 CountryMod 12 V / 24 V 房车空调进行本地 Bluetooth 控制， 随附于 *Bluetooth Control Panel Upgrade Kit*，其手机应用为 **AeroLink Core** (`com.kingcontech.btac`)。 无需云端，无需账户，无需配对。Home Assistant 通过 BLE 直接与显示 板进行通信。 ## 状态 通信协议是通过反编译厂商应用提取，并针对实体设备进行验证得出的。 此集成暴露的每一项控制均已在真实硬件上确认，并且集成本身已完全通过 Home Assistant UI 进行端到端驱动。唯一的例外是 **HEAT**，测试 设备未实现此功能 — 请参阅 [验证状态](#validation-status)。 ## 要求 - 安装了 Home Assistant，且在空调范围内有可用的 Bluetooth 适配器 （ESPHome Bluetooth proxy 同样适用）。 - 空调已通电。只有在设备 通电时，显示板才会响应。 ## 安装 将 `custom_components/countrymod_ac` 复制到你的 Home Assistant `config` 目录中： ``` /custom_components/countrymod_ac/ ``` 重启 Home Assistant。控制器会被自动发现 — 请在 **Settings → Devices & services** 下查看 通知，或通过 **Add integration → CountryMod RV Air Conditioner** 手动添加。 控制器广播名称以 `KT` 开头，后接序列号，例如 `KT2000000000000`，且不广播任何 service UUID — 因此发现机制是基于 名称进行匹配的。 一旦有设备连接到控制器，主机就会将模块的 GAP 名称 （`LS Dis Server`）缓存以替代序列号。发现功能接受这两种名称，但 自动发现仅在序列号匹配时触发。如果你的控制器曾与 AeroLink Core 应用配对过且 未自动出现，请手动添加它，或者 先清除过期的名称： ``` bluetoothctl remove AA:BB:CC:DD:EE:FF ``` ## 实体 | 实体 | 类型 | 备注 | | --- | --- | --- | | 空调 | `climate` | 电源、模式、目标温度、风速、扫风、预设 | | 进风口温度 | `sensor` | 回风温度，采用控制器报告的单位 | | 盘管温度 | `sensor` | 诊断信息；推断为摄氏度 | | 输入电压 | `sensor` | 控制器测量的电池电压 | | 故障 / 故障代码 | `binary_sensor`, `sensor` | 非零故障代码会触发问题标志 | | 面板显示 | `switch` | 控制器自带的屏幕 | | 灯光 | `switch` | 氛围灯；控制器仅暴露开关状态 | | 进气 | `select` | 内循环或外循环（新鲜空气） | | 低压切断 | `number` | 电池保护设定值 | | 压缩机/风机电流 | `sensor` | 默认禁用；比例换算未经确认 | | 剩余定时时间 | `sensor` | 分钟；默认禁用 | climate 实体以控制器自身设置的温标报告温度，其允许的设定范围也 随之变化（16–30 °C 或 61–86 °F）。 `preset_mode` 包含了设备叠加在基础模式之上的修饰符： `auto`、`eco`、`sleep`、`turbo` 或 `none`。 ## 工作原理 显示板暴露了一个 serial-bridge GATT service：向 `FFE2` 写入命令，在 `FFE1` 接收状态通知。每次交互都是一个固定的 9 字节 命令帧；写入值 `0` 即为读取。 控制器从不主动上报状态 — 它对一个查询回复一个状态 帧 — 因此 coordinator 会进行轮询，并且每条命令后都会紧跟一个新的查询， 这样 Home Assistant 就能显示设备实际执行的操作，而不仅仅是发送的请求。 通知以碎片化形式到达，并在解码前进行重组。 包括字节布局及各字段证据在内的完整细节，请参阅 [`docs/protocol-discovery/protocol-contract.md`](docs/protocol-discovery/protocol-contract.md)。 ## 验证状态 已针对实体设备确认，每一项均通过返回的状态帧进行了验证： - 状态刷新及完整状态解码 - 开机和关机 - 目标温度、风机转速 - 工作模式 COOL、FAN 和 DRY - 预设模式 ECO、SLEEP、TURBO 和 AUTO - 扫风、面板显示、灯光、进气 - 低压切断、温度单位、定时器启用/值/禁用 上述每一项操作也都通过 Home Assistant UI 在 真实设备上进行了实际测试，因此整个调用链路 — service call、coordinator、GATT 写入、 确认查询、状态解码 — 均被确认有效，而不仅仅是帧格式。 **尚未**确认的： - **HEAT。** 测试设备完全忽略了模式命令 — 它似乎是 一款纯制冷型号。其他 CountryMod 设备可能会接受该命令。当 设备拒绝某种模式时，集成会报错，而不是静默无响应，因此 你会收到明确的失败提示，而不是遇到一个毫无作用的 控制操作。 - **负离子。** 状态标志可以解码，但厂商应用没有对应的命令 代码，因此无内容可发送。 如果你需要自行与这些设备通信，以下三个陷阱值得注意： - 命令模式枚举与状态模式枚举**并不**相同。下发 FAN 命令使用 值 `2`，而随后控制器上报的模式为 `3`。 - **ECO 会将基础模式字段清零**（设为 `0`），这 不属于控制器自身的模式值之一。 - **改变温度单位会对控制器本身重新换算设定值** — 75 °F 会变成 23 °C。请勿在本地进行转换。 仍未确认的：压缩机和风机电流字段的比例换算（在所有的 抓包数据中读取值均为零，包括在主动制冷期间），以及盘管 温度是否确实为摄氏度。 ## 关于手机应用的说明 显示板同一时间只能维持一个 BLE 连接。当 Home Assistant 处于 连接状态时，AeroLink Core 将无法连接到该设备，反之亦然。 如果你需要重新使用手机应用，请移除或禁用本集成。 ## 开发 ``` python3 -m venv .venv .venv/bin/pip install homeassistant pytest-homeassistant-custom-component ruff .venv/bin/python -m pytest .venv/bin/ruff check custom_components tests ``` `custom_components/countrymod_ac/protocol.py` 中的编解码器不依赖于 Home Assistant 或 Bluetooth，并且已针对从真实控制器中原样提取的数据帧进行了测试。 ## 鸣谢 协议通过对 AeroLink Core 1.0.0 的静态分析还原，并针对 实体设备进行了验证。与 CountryMod 或 Kingcontech 无任何隶属关系。 CountryMod 名称和徽标归 CountryMod 所有，仅用于 标识受支持的设备。请参阅 [`assets/README.md`](assets/README.md)。

标签：Home Assistant, 房车空调, 智能家居, 本地控制, 物联网, 蓝牙低功耗, 逆向工具