小米智能家居集成升级与配置指南：解决连接问题实战方案

典型问题修复案例：三段式代码解决方案

案例 1：吸尘器回充指令失效

问题场景：执行 return_to_base 服务后，石头 G20 无响应，日志显示"service unavailable"

错误代码（miot/miot_mips.py）：

# 原代码缺少回充动作的 fallback 处理
if action == "start-charge":
    if not device.supports_action(action):
        return False # 直接返回失败

修复代码：

# 新增 fallback 机制，尝试兼容模式
if action == "start-charge":
    if not device.supports_action(action):
        # 尝试通过基础属性控制实现回充
        return device.set_property("battery", "charge-state", 1)

验证方法：在开发者工具中执行服务调用：

service: vacuum.return_to_base
target:
  entity_id: vacuum.xiaomi_vacuum

设备应在 10 秒内开始返航，状态变化可在日志中查看。

案例 2：实体 ID 变更导致自动化失效

问题场景：升级到 v0.3.0 后，所有自动化规则提示"实体未找到"

错误代码（自动化配置）：

# 旧 ID 格式：设备类型_位置_随机数
trigger:
  entity_id: light.livingroom_xiaomi_1234

修复代码：

# 新 ID 格式：品牌_型号_设备类型_随机数
trigger:
  entity_id: light.xiaomi_light_mb3_1234

批量迁移技巧：使用 Home Assistant 的"更新实体转换规则"功能（路径：设置 > 设备与服务 > Xiaomi Home > 配置）可自动更新大部分实体引用。

深度优化：从可用到好用的进阶技巧

规格文件定制指南

高级用户可通过修改设备规格文件实现个性化适配，就像给设备安装专用驱动程序。三个核心配置文件位于 custom_components/xiaomi_home/miot/specs/目录：

1. spec_filter.yaml：过滤冗余实体

# 示例：隐藏电视的冗余服务
urn:miot-spec-v2:device:television:0000A010:xiaomi-rmi1:
  services:
    - '*' # 完全忽略该设备

2. spec_modify.yaml：调整属性定义

# 示例：修正空调湿度单位
urn:miot-spec-v2:device:aircondition:0000A004:xiaomi-c17:
  properties:
    1.5: # siid=1, piid=5
      unit: "%" # 将单位从"none"改为"%"

3. multi_lang.json：补充设备翻译

{
  "urn:miot-spec-v2:device:humidifier:0000A00E:zhimi-ca4": {
    "zh-Hans": {
      "service:002:property:007": "水箱水位"
    }
  }
}

修改后需在集成配置页面点击"更新实体转换规则"使变更生效。

网络环境优化方案

网络质量直接影响设备响应速度，就像高速公路的路况决定行车速度：

1. 分段网络隔离：为 IoT 设备创建独立 VLAN，避免广播风暴干扰
2. 连接数限制：在 configuration.yaml 中设置合理的并发连接数

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

3. DNS 优化：将网关 DNS 设置为 114.114.114.114，加速云服务解析

自动化测试矩阵：版本兼容性验证方法

升级前的兼容性测试就像旅行前检查车辆，可避免途中抛锚。以下矩阵帮你系统验证新版本是否适合你的设备组合：

测试工具推荐：

• 网络诊断：tools/common.py 中的网络测试函数
• 日志分析：设置日志级别为 DEBUG（配置文件 logger 部分）
• 性能监控：Home Assistant 内置的系统监控面板

资源索引

通过本指南的系统化方法，你已掌握小米智能家居集成从问题诊断到深度优化的全流程解决方案。记住，稳定的设备连接不仅依赖软件配置，还需要合理的网络规划和定期的系统维护，就像汽车需要定期保养才能保持最佳性能。