小米智能家居集成是小米官方支持的Home Assistant集成组件，允许用户在Home Assistant中使用小米IoT智能设备。

**安装方法：**

该项目提供三种安装方法：

1. 从GitHub克隆：推荐使用此方法，方便更新到特定版本。

2. 使用HACS：即将加入HACS商店。

3. 手动安装：下载并复制`custom_components/xiaomi_home`文件夹到Home Assistant的`config/custom_components`文件夹。

**配置：**

1. 登录：在Home Assistant的“设置”>“设备和服务”>“添加集成”中搜索“小米智能家居”，然后按照提示登录小米账号。

2. 添加设备：登录成功后，会弹出“选择家庭和设备”对话框，用户可以选择包含要导入Home Assistant的设备的家庭。

3. 多账户登录：用户可以添加多个小米账号。方法：在“设置”>“设备和服务”>“已配置”>“小米智能家居”>“添加网关”>“下一步”中登录其他小米账号。

4. 更新配置：用户可以在“配置选项”对话框更改配置，例如更新用户昵称和要导入的设备列表。方法：在“设置”>“设备和服务”>“已配置”>“小米智能家居”>“配置”中选择更新选项。

5. 调试模式：在调试模式下，用户可以手动向设备发送带参数的动作命令。方法：在“设置”>“设备和服务”>“已配置”>“小米智能家居”>“配置”中启用调试模式。

**安全：**

小米智能家居集成和相关的云接口由小米官方提供。用户需要使用小米账号登录以获取设备列表。集成实现了OAuth 2.0登录流程，不会将用户的账号密码存储在Home Assistant应用程序中。但是，由于Home Assistant平台的限制，用户登录成功后，小米账号的用户数据（包括设备信息、证书、令牌等）会以明文形式保存在Home Assistant配置文件中。用户需要确保配置文件安全存储，防止泄露导致他人以用户身份登录。

**常见问题：**

1. 集成是否支持所有小米智能家居设备？目前支持大多数类别，不支持蓝牙设备、红外设备和虚拟设备。

2. 集成是否支持多个小米账号？支持，并且允许不同账号的设备添加到同一区域。

3. 集成是否支持本地控制？通过小米中央网关（固件版本3.4.0_0000及以上）或内置中央网关的小米智能家居设备（软件版本0.8.0及以上）实现本地控制。如果没有中央网关，则所有控制命令都通过小米云发送。支持Home Assistant本地控制功能的小米中央网关固件尚未发布，请参考MIoT团队的通知了解升级计划。小米中央网关仅在中国大陆地区可用。集成也可以通过启用小米局域网控制功能实现部分本地控制，但功能可能存在异常，建议不要使用。

4. 集成在哪些地区可用？在中国大陆、欧洲、印度、俄罗斯、新加坡和美国可用。由于不同地区的小米云用户数据隔离，导入设备时需要选择区域。

**消息传递原理：**

1. 通过云端控制：集成订阅MIoT云中MQTT代理上的设备消息。当设备属性发生变化或设备事件发生时，设备向MIoT云发送上行消息，MQTT代理将订阅的设备消息推送到集成。集成通过MIoT云的HTTP接口向设备发送命令消息控制设备。

2. 本地控制：小米中央网关包含标准MQTT代理，实现了完整的订阅发布机制。集成通过小米中央网关订阅设备消息。当设备属性发生变化或设备事件发生时，设备向小米中央网关发送上行消息，MQTT代理将订阅的设备消息推送到集成。集成通过发布设备命令消息到MQTT代理控制设备。

**MIoT-Spec-V2与Home Assistant实体映射：**

MIoT-Spec-V2是小米IoT平台制定的IoT协议，包含功能定义（在其他IoT平台称为数据模型）、交互模型、消息格式和编码。小米智能家居集成根据MIoT-Spec-V2创建Home Assistant实体。

**多语言支持：**

配置流程语言选项中有8种语言可选，包括简体中文、繁体中文、英语、西班牙语、俄语、法语、德语和日语。简体中文和英语的配置流程页面已由开发者手动审阅，其他语言由机器翻译提供。用户可以修改`custom_components/xiaomi_home/translations/`目录下的特定语言的json文件修改配置流程页面的内容。

**目录结构：**

该项目包含以下目录：

* `miot`：核心代码。

* `miot/miot_client`：与用户登录相关的功能。

* `miot/miot_cloud`：云服务相关功能，包括OAuth登录流程、HTTP接口功能等。

* `miot/miot_device`：设备实体，包括设备信息、属性、事件和动作的处理逻辑。

* `miot/miot_mips`：订阅和发布消息的机制。

* `miot/miot_spec`：解析MIoT-Spec-V2。

* `miot/miot_lan`：设备局域网控制，包括设备发现、设备控制等。

* `miot/miot_mdns`：中央网关服务局域网发现。

* `miot/miot_network`：获取网络状态和网络信息。

* `miot/miot_storage`：集成的文件存储。

* `miot/test`：测试脚本。

* `config_flow`：配置流程。