enapt/haismart-local
GitHub: enapt/haismart-local
为 Home Assistant 提供海尔空调完全本地化控制的集成组件，免去云端依赖。
Stars: 3 | Forks: 1
# Haismart Local — 在 Home Assistant 中完全脱离云端控制海尔空调
[](https://github.com/hacs/integration)
[](https://github.com/enapt/haismart-local/releases/latest)
[](https://github.com/enapt/haismart-local/actions/workflows/validate.yml)
[](LICENSE)
_完全通过你自己的网络在 Home Assistant 中控制你的海尔空调。你只需登录一次，以便集成获取设备的密钥（key）——之后它只会通过你的局域网（LAN）与空调通信。_
## 我的空调支持吗？
**关键在于你使用的 App，而不是你所在的国家。** 如果你的空调配对的是 **Haier / Haismart** App（也称为 *Haier U+* 或 *uHome*），那么你来对地方了。尽管该平台内部带有“东南亚”标签，但在该地区之外注册的账户也能正常使用——本项目每天都在一个于东南亚以外地区注册的账户上使用。
| 你的 App | 这里支持吗？ | 推荐使用的替代项目 |
|---|---|---|
| **Haier / Haismart / Haier U+ / uHome** | ✅ **支持** | — |
| hOn（主要在欧洲） | ❌ 不支持 — 这些模块根本不开放 56800 端口 | [Andre0512/hon](https://github.com/Andre0512/hon) |
| Haier 智家（中国大陆） | ❌ 不支持 — 使用不同的云端 | [banto6/haier](https://github.com/banto6/haier) |
| SmartHQ（美国 / GE 家电） | ❌ 不支持 — 完全是不同的平台 | — |
| SmartAir2 / Smart Clima（老型号） | ❌ 不支持 — 端口相同，但是较旧且未加密的协议 | [oxystin/homebridge-haier-air-conditioner](https://github.com/oxystin/homebridge-haier-air-conditioner) |
**已确认支持的设备型号**列在 [`DEVICES.md`](DEVICES.md) 中。你的设备不在里面？它大概率仍然可以使用——该集成是根据你的空调云端配置文件提供的型号描述动态构建的，而不是依赖硬编码的设备型号表。如果有什么解码异常的情况，非常[欢迎提交 Issue](#before-you-open-an-issue)，这通常很容易修复。
**快速检查：** 如果 `nc -z <你的空调IP> 56800` 命令执行成功，说明本地协议正在监听。
## 功能特性
每台空调对应一个设备，包含：
| 实体 | 功能说明 |
|---|---|
| **Climate** | 温度设定值、模式（制冷 / 制热 / 除湿 / 仅送风 / 自动）、风速、扫风、开关机 |
| **Indoor temperature** | 空调自身的室温读数 |
| **Outdoor temperature** | 室外温度探头（仅限带有该探头的设备） |
| **Switches** | 强劲、静音、健康、睡眠、显示屏灯光 |
| **Eco** | Eco 等级（仅限已确认支持的型号） |
| **Local key** *(诊断实体，默认关闭)* | 你的设备密钥，会随 HA 备份一起保存 |
具体会出现哪些实体取决于你的设备型号——集成只会暴露它能在你的设备上实际驱动的控制功能，而不是显示那些没有任何作用的按钮。
## 安装前须知
提前了解以下几点，以免遇到意外情况：
- Home Assistant 和空调必须在**同一个子网**内。没有云端中继可以作为备用。
- 空调一次只接受**一个本地会话**，且每个会话的上限约为 17 秒。如果对同一台设备运行另一个海尔本地集成，将导致两者都无法正常工作。
- 安装此集成**不会阻止你的空调与海尔云端通信**。除非你设置防火墙拦截，否则它将保持自身的云端连接——请参阅[实现完全脱离云端](#going-fully-cloud-independent)。
- 为空调设置**静态 DHCP 分配**。如果其 IP 地址发生变化，Home Assistant 必须重新查找。
- 社交账号登录（Google / Facebook）没有可用于登录的密码。请创建一个一次性的邮箱/密码海尔账号，在 App 中**将空调共享给该账号**，然后在这里使用该账号——共享授予的本地访问权限与设备所有者相同。
## 安装说明
### 方式 1 — HACS（推荐）
1. 确保已安装 [HACS](https://hacs.xyz/)。
2. 在 HACS 中打开此仓库：\
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=enapt&repository=haismart-local&category=integration)
3. 点击 **Download**，然后在版本对话框中再次点击 **Download**。
4. **重启 Home Assistant。** 自定义集成的代码只会在启动时加载——仅仅重新加载集成条目是不够的。
## 设置你的空调
[](https://my.home-assistant.io/redirect/config_flow_start/?domain=haismart)
或者：**设置 → 设备与服务 → + 添加集成 → Haismart**。如果列表中没有显示，请强制刷新浏览器（Ctrl+Shift+R）。
然后选择以下两种方式之一：
**登录（推荐）。** 输入你的海尔账号邮箱（或手机号）和密码，以及你的**账号**注册所在的国家。集成会列出你的空调，自动获取所选设备的密钥，并在你的网络中找到它——你无需粘贴任何内容。
**手动。** 直接输入 Host + 设备 ID + 本地密钥。完全离线——无需账号。如果你已经拥有密钥（来自 *Local key* 诊断传感器或备份），请使用此方式。
## 自动化示例
```
# 在你到家前预冷客厅
automation:
- alias: "Pre-cool before arrival"
triggers:
- trigger: zone
entity_id: person.me
zone: zone.home
event: enter
actions:
- action: climate.set_temperature
target: { entity_id: climate.living_room_ac }
data: { temperature: 23, hvac_mode: cool }
```
```
# 夜间 Quiet mode
automation:
- alias: "AC quiet at night"
triggers:
- trigger: time
at: "22:30:00"
actions:
- action: switch.turn_on
target: { entity_id: switch.living_room_ac_quiet }
```
## 实现完全脱离云端
设置完成后，一切都在本地运行。目前仅存的云端依赖是，海尔的服务器可能会**轮换**（rotate）你设备的本地密钥，届时集成会重新获取该密钥。
如果你希望你的空调完全不与云端通信：
1. **首先备份密钥。** 在设备页面上启用 *Local key* 诊断传感器——其状态值就是密钥，其属性包含 Host、设备 ID 和版本。这样它就会自动随你的 Home Assistant 备份一起保存。
2. 在路由器上**阻止该空调的互联网访问**（保持局域网畅通——Home Assistant 仍然需要 56800 端口）。通过 MAC 地址进行针对特定设备的 WAN 拦截是最可靠的方法；DNS 拦截可能会被硬编码的地址绕过。
3. 密钥将无法再轮换，因此你存储的密钥将无限期保持有效。以后你随时可以通过**手动**方式重新添加设备，完全不需要涉及云端。
详细信息（包括域名列表）请参阅：[`INSTALL.md`](INSTALL.md)。
## 故障排除
56800` 命令是否仍然能够成功执行。
## 提交 Issue 前
这是一个逆向工程的本地协议，因此一份详尽的反馈报告非常有价值：
1. 查看[日志页面](https://my.home-assistant.io/redirect/logs/)上是否有来自 `haismart` 的警告。
2. 开启调试日志（如上所述）并重现该问题。
3. 搜索[现有 Issues](https://github.com/enapt/haismart-local/issues?q=is%3Aissue)（包括已关闭的）。
4. 下载诊断信息：**设置 → [设备与服务](https://my.home-assistant.io/redirect/integrations/) → Haismart → ⋮ → 下载诊断信息**。敏感信息已被脱敏；其中包含的原始状态字节正是诊断解码问题所需的内容。
5. 附上你的**空调型号**、已知的 Wi-Fi 模块信息以及你配对使用的 App。
**为新型号添加支持**是这里最有价值的贡献，并且它不需要编写任何代码——请参阅 [`docs/new-model.md`](docs/new-model.md) 了解简短的抓包流程。
## 登录原理
设置过程使用的是**该 App 自身的登录流程和你的账号**：你输入你的海尔凭据后，集成会使用应用程序级别的标识符（一个对于每个安装 Haismart App 的设备都相同的 `appId`/`appKey` 对）为普通的 API 请求进行签名，海尔随后会返回你空调的本地密钥。这里没有绕过身份验证，没有突破保护机制，也没有涉及任何其他人的用户级私密信息——这与 [`banto6/haier`](https://github.com/banto6/haier) 用于海尔大陆版 App 以及 [pyhOn](https://github.com/Andre0512/pyhOn) / [`hon`](https://github.com/Andre0512/hon) 用于 hOn 平台所采用的互操作性模型完全相同。
那些应用程序级别的标识符作为默认值内置在程序中，以确保开箱即用的登录体验。如果你希望自己提供，所有的标识符都可以通过环境变量进行覆盖——`HAISMART_APP_ID`, `HAISMART_APP_KEY`, `HAISMART_CLIENT_ID`, `HAISMART_APP_VERSION`。
设置完成后的所有操作都在本地进行：空调在 56800 端口上通信使用的协议是专门为本项目破译的，目的是让你能够通过自己的网络驱动你拥有的设备。这正是本项目的核心意义所在——实现与你自有硬件的互操作性，而不是去访问任何不属于自己的东西。
## 免责声明
这是一个独立的社区项目，**与海尔没有任何附属关系、授权或认可**。“Haier”、“Haismart”和“Haier U+”是其各自所有者的商标，此处仅用于标识本软件与之互操作的硬件。
在设置过程中，会使用**你自己的**凭据登录海尔的账号 API；没有任何安全机制被绕过。将设备共享给辅助账号可能会受到相关 App 服务条款的约束，遵守条款是你的责任。本项目按“原样”提供，不含任何担保，仅供你在自己拥有的硬件和网络上使用。
采用 [MIT](LICENSE) 授权许可。
目录
- [我的空调支持吗？](#is-my-air-conditioner-supported) - [功能特性](#what-you-get) - [安装前须知](#before-you-install) - [安装说明](#installation) - [设置你的空调](#set-up-your-air-conditioner) - [自动化示例](#automation-examples) - [实现完全脱离云端](#going-fully-cloud-independent) - [故障排除](#troubleshooting) - [提交 Issue 前](#before-you-open-an-issue) - [贡献指南](#contributing) - [致谢](#credits) - [登录原理](#how-sign-in-works) - [免责声明](#disclaimer)如果按钮无效——手动添加
1. 从侧边栏打开 **HACS**。 2. 点击右上角的三点菜单 → **Custom repositories**。 3. 仓库填写：`https://github.com/enapt/haismart-local`，类型选择 **Integration** → 点击 **Add**。 4. 在 HACS 中搜索 **Haismart** → **Download**。 5. 重启 Home Assistant。方式 2 — 手动安装
1. 下载[最新版本](https://github.com/enapt/haismart-local/releases/latest)的源码。 2. 将 `custom_components/haismart/` 文件夹复制到你的 Home Assistant 的 `config/custom_components/` 目录下。 3. 重启 Home Assistant。 该集成完全独立——无需执行 `pip install` 步骤，相关的辅助库已经打包在内。“登录失败” / “账号未注册”
这几乎总是**国家代码**的问题。它是你的海尔**账号**注册国家的电话区号，这个国家可能不是你现在居住的国家，也不一定是空调所在的国家。如果你确信输入无误，请检查你的账号是否真的是 Haier / Haismart 账号——hOn 和海尔智家（中国）的账号存在于完全不同的服务器上，任何国家代码对它们都不起作用。“无法从 <IP> 解码状态”
空调已经响应且连接正常，但 Home Assistant 无法读取回复。原因有两种： - **本地密钥已过期** —— 密钥会在服务器端进行轮换。如果你使用账号登录，它会自动重新获取；否则，系统会提示你重新进行身份验证。 - **未知的报告数据结构** —— 你的型号在打包状态数据时略有不同。最新版本会尽可能解码其内容，并明确指出问题所在，而不是直接报错失败。请带上诊断信息[提交一个 Issue](#before-you-open-an-issue)；这通常只需要修改一行代码就能修复。实体不可用，或者空调掉线
请检查空调的 IP 是否发生变化（设置 DHCP 静态分配），确认没有其他程序在占用同一台设备的本地会话，以及 `nc -z开启调试日志
``` # configuration.yaml logger: default: info logs: custom_components.haismart: debug haismart_hrdp: debug haismart_extractor: debug ```标签：HACS, Home Assistant, 局域网控制, 智能家居, 海尔空调, 物联网, 逆向工具