Home Assistant 接入小米智能家居设备本地化部署指南

{
  "cloud_control": {
    "enable": true,
    "mqtt_server": "mqtt://iot.mi.com:1883",
    "api_endpoint": "https://api.io.mi.com"
  }
}

本地控制模式

适用场景：

• 拥有小米多模网关（固件≥v3.3.0_0023）
• 设备支持 MIoT-Spec-V2 协议
• 对控制延迟有较高要求

工作原理：通过本地局域网内的 MQTT Broker 直连设备，支持 WiFi/以太网设备的实时状态同步和命令下发。延迟稳定在 50-150ms，不受公网影响。

配置要点：

{
  "local_control": {
    "enable": true,
    "gateway_ip": "192.168.1.100",
    "mqtt_port": 1883,
    "timeout": 30
  }
}

🔍 风险提示：本地控制模式依赖网关固件版本，升级前请备份网关配置，避免配置丢失。

设备接入与验证

完成基础配置后，按以下步骤接入设备并验证功能：

1. 添加设备：
   • 在 Home Assistant 集成页面点击"配置"
   • 选择设备发现方式（自动/手动）
   • 输入小米账号信息（仅首次配置需要）

功能测试：以吸尘器回充功能为例，执行以下测试命令：

{
  "service": "vacuum.return_to_base",
  "target": {
    "entity_id": "vacuum.xiaomi_vacuum"
  }
}

正常情况下，设备应在 10 秒内开始返航。

验证设备状态：在开发者工具中执行以下命令检查设备连接状态：

{
  "service": "xiaomi_home.get_device_status",
  "data": {
    "entity_id": "vacuum.xiaomi_vacuum"
  }
}

优化阶段：性能调优与问题解决

性能优化策略

针对不同场景，可采用以下优化措施提升系统性能：

1. 网络优化：
   • 为 IoT 设备分配固定 IP 地址
   • 优化 WiFi 信道，减少同频干扰
   • 网关与 Home Assistant 之间使用有线连接

日志管理：调整日志级别平衡调试需求与系统资源消耗：

logger:
  default: warn
  logs:
    custom_components.xiaomi_home: info # 仅记录关键操作

连接数优化：在 configuration.yaml 中限制并发连接数：

xiaomi_home:
  max_connections: 50 # 默认 100，根据设备数量调整

常见问题排查

故障排查流程图

1. 设备无响应
   • 检查设备是否在线
   • 验证网络连接
   • 检查认证状态
   • 重启设备与网关
2. 状态不同步
   • 检查 MQTT 连接状态
   • 验证实体 ID 是否正确
   • 清除缓存并重载集成
   • 检查防火墙设置
3. 控制延迟高
   • 确认控制模式（本地/云端）
   • 测试网络延迟
   • 检查设备负载
   • 优化 Home Assistant 资源占用

典型问题解决方案

问题：吸尘器执行回充命令无响应 分析：电池服务的"start-charge"动作映射错误 解决方案：

1. 升级至 v0.4.2 及以上版本

手动修改 miot_spec.py 中的服务映射：

# 定位到 ServiceManager 类的 get_fallback_action 方法
if service_id == "battery" and action == "start-charge":
    return "charge" # 修改动作映射

问题：实体 ID 变更导致自动化规则失效 分析：v0.3.0 版本重构了实体 unique_id 生成规则 解决方案：

1. 执行后验证所有自动化规则

使用自动化规则转换工具批量更新：

python tools/convert_entity_ids.py --old-pattern "light.livingroom_xiaomi_*" --new-pattern "light.xiaomi_light_*"

版本选择决策树

选择适合的版本需要考虑设备类型、功能需求和稳定性要求，以下决策树可帮助您做出选择：

1. 您的设备类型是？
   • 空调/新风 → 选择≥v0.4.1（湿度范围单位修正）
   • 扫地机器人 → 选择≥v0.4.2（回充逻辑优化）
   • 智能开关 → 选择≥v0.3.4（功率统计精度提升）
   • 加湿器 → 选择≥v0.4.1（水位检测修正）
2. 您的主要需求是？
   • 稳定性优先 → 选择最新稳定版
   • 新功能尝鲜 → 选择测试版
   • 特定问题修复 → 选择包含修复的版本
3. 您的技术能力水平？
   • 初级用户 → 通过 HACS 安装最新稳定版
   • 中级用户 → 使用 Git 指定版本安装
   • 高级用户 → 手动编译最新源码

总结与下一步行动

通过本文介绍的'准备 - 实施 - 优化'三阶段方案，您已掌握小米智能家居本地化部署的核心技术和最佳实践。以下是建议的后续步骤：

1. 完成兼容性检查并选择适合的控制模式
2. 按照部署指南完成基础配置
3. 使用提供的测试命令验证设备功能
4. 根据性能优化建议调整系统配置
5. 将常用场景自动化，提升智能家居体验

智能家居本地化部署是一个持续优化的过程，建议定期关注版本更新和社区动态，及时获取新功能和问题修复。通过合理配置和持续优化，您的智能家居系统将更加稳定、响应迅速，为您带来更优质的智能生活体验。