3分钟定位小米智能家居异常：Home Assistant日志查询完全指南

【免费下载链接】ha_xiaomi_home Xiaomi Home Integration for Home Assistant 项目地址: https://gitcode.com/gh_mirrors/ha/ha_xiaomi_home

你是否遇到过小米智能灯突然离线却找不到原因？空调明明设置26℃却自动跳到30℃？这些"灵异事件"往往藏在设备的属性事件日志里。本文将带你用最简单的方式，3分钟内从Home Assistant日志中揪出问题根源，无需编程基础，只需跟着图文步骤操作。

日志查询前的准备工作

在开始查询前，请确认你的Home Assistant已安装Xiaomi Home Integration组件。该组件会自动记录设备的属性变化和事件触发，相关逻辑实现可见custom_components/xiaomi_home/miot/miot_device.py中的sub_device_state方法，它负责订阅设备状态变化并记录日志。

你需要准备：

• 已联网的Home Assistant系统
• 安装好的Xiaomi Home Integration（hacs.json中定义了组件元数据）
• 文本编辑器（用于查看日志文件）

两种查询方式：简单vs进阶

方法一：Home Assistant界面查询（推荐新手）

1. 打开Home Assistant网页界面，点击左侧菜单栏的"设置"→"系统"→"日志"
2. 在搜索框输入设备名称或实体ID（格式类似sensor.xiaomi_airconditioner_temperature）
3. 查看"属性变更"和"事件触发"类型的日志条目

这种方式适合快速定位最近发生的问题，但只能查看最近24小时的日志。日志记录逻辑由custom_components/xiaomi_home/event.py中的on_event_occurred方法实现，代码片段如下：

def on_event_occurred(self, name: str, arguments: dict[str, Any] | None = None) -> None:
    """An event is occurred."""
    _LOGGER.debug('%s, attributes: %s', name, str(arguments))
    self._trigger_event(event_type=name, event_attributes=arguments)

方法二：直接查看日志文件（适合进阶用户）

1. 通过SSH或Samba访问Home Assistant的配置目录
2. 打开config/home-assistant.log文件（建议使用文本编辑器或VS Code等支持大文件的编辑器）
3. 搜索设备的DID（设备唯一标识符），格式类似did=1234567890

日志文件中每条小米设备相关记录包含：

• 时间戳（精确到毫秒）
• 设备DID（可在custom_components/xiaomi_home/miot/miot_spec.py中查看DID生成逻辑）
• 属性ID（如温度对应piid=2）
• 旧值与新值
• 事件类型（如property_changed或event_triggered）

实战案例：解决空调温度异常跳变

问题描述

用户报告：小米互联网空调在设置26℃后，半小时内自动升至30℃，无任何操作。

日志查询步骤：

1. 在Home Assistant日志中搜索空调实体ID（如sensor.mi_ac_temperature）
2. 找到异常时间点的日志条目：

2023-09-30 14:30:22.123 DEBUG (MainThread) [custom_components.xiaomi_home.miot.miot_device] 属性变更: 温度, 旧值:26, 新值:30, piid=2, siid=3

3. 查看前后5分钟的日志，发现前1分钟有"模式变更"事件：

2023-09-30 14:29:15.456 DEBUG (MainThread) [custom_components.xiaomi_home.miot.miot_device] 事件触发: mode_changed, 参数:{"mode":"heat"}, eiid=1, siid=3

问题分析

根据custom_components/xiaomi_home/climate.py中的空调控制逻辑，当模式从"制冷"切换到"制热"时，温度会自动重置为默认值30℃。这解释了为何温度会突然跳变。

解决方案

在空调模式切换后重新设置目标温度，或在自动化中添加"模式变更后设置温度"的动作。

日志文件详解：你需要关注的3种条目

1. 属性变更日志

记录设备属性值的变化，格式如下：

DEBUG (MainThread) [custom_components.xiaomi_home.miot.miot_device] 属性变更: 亮度, 旧值:50, 新值:100, piid=5, siid=2

其中piid=5对应亮度属性，定义在custom_components/xiaomi_home/miot/specs/specv2entity.py的SPEC_PROP_TRANS_MAP映射表中。

2. 事件触发日志

记录设备主动上报的事件，如按键按下、传感器检测到移动等：

DEBUG (MainThread) [custom_components.xiaomi_home.event] 事件触发: button_pressed, 参数:{"button":"left", "click_type":"double"}

3. 连接状态日志

记录设备上线、离线状态变化，对于网络问题排查至关重要：

DEBUG (MainThread) [custom_components.xiaomi_home.miot.miot_network] 设备状态变更: online=True, did=1234567890

高级技巧：设置日志级别

默认情况下，Xiaomi Home Integration只记录关键信息。如果需要更详细的调试日志，可以在configuration.yaml中添加：

logger:
  default: warning
  logs:
    custom_components.xiaomi_home: debug
    custom_components.xiaomi_home.miot: debug

这会启用详细日志模式，记录包括通信数据包在内的所有信息，帮助诊断复杂问题。但注意，详细日志会占用较多磁盘空间，问题解决后建议改回默认设置。

常见问题Q&A

Q: 日志中找不到我的设备怎么办？
A: 首先确认设备是否在线（查看Home Assistant的设备页面），然后检查custom_components/xiaomi_home/config_flow.py中的配置流程是否完成，设备只有在成功配置后才会记录日志。

Q: 日志显示"认证失败"是什么原因？
A: 这通常是小米账号令牌过期导致，可在集成设置中重新登录小米账号解决，相关代码在custom_components/xiaomi_home/config_flow.py的async_step_user方法中处理。

Q: 如何导出日志供开发者分析？
A: 使用"日志"页面右上角的"下载"按钮，会生成包含所有小米设备日志的JSON文件，可附带在CONTRIBUTING.md中描述的issue报告中。

总结与下一步

通过本文介绍的方法，你已经能够：

• 在Home Assistant中查询小米设备的属性事件日志
• 识别常见的日志条目类型
• 利用日志解决简单的设备异常问题

下一步，你可以：

• 学习使用test/test_cloud.py中的测试用例验证设备通信
• 探索custom_components/xiaomi_home/miot/miot_spec.py了解设备属性定义
• 在GitHub项目提交issue或贡献代码

如果你觉得这篇指南有帮助，请点赞收藏，关注我们获取更多Home Assistant使用技巧！下期我们将介绍如何利用日志数据创建自动化场景，敬请期待。

【免费下载链接】ha_xiaomi_home Xiaomi Home Integration for Home Assistant 项目地址: https://gitcode.com/gh_mirrors/ha/ha_xiaomi_home