XiaomiGateway3项目中Aqara人体传感器超时设置优化指南

在智能家居系统中，人体传感器的状态保持时间（occupancy_timeout）是一个关键参数，它决定了传感器在检测到人体活动后保持"有人"状态的持续时间。本文将详细介绍如何在XiaomiGateway3项目中正确配置Aqara人体传感器的超时参数。

问题背景

许多用户在使用XiaomiGateway3集成时发现，Aqara人体传感器（型号RTCGQ11LM）的检测状态会在大约90秒到2分钟后自动清除，即使他们已经在configuration.yaml文件中设置了更长的超时时间（如30分钟）。这种情况通常是由于设备ID格式不正确导致的配置未生效。

解决方案

正确的配置方法是在configuration.yaml文件中使用以下格式：

xiaomi_gateway3:
  devices:
    "0x00158d00054b9038":
      occupancy_timeout: 1800

关键点说明：

1. 设备ID必须使用十六进制格式（以0x开头）
2. 超时时间以秒为单位（1800秒=30分钟）
3. 设备ID可以从网关日志中获取，格式为'uid'字段的值

技术原理

XiaomiGateway3集成在解析设备配置时，会严格匹配设备ID的格式。当使用MAC地址格式（00:15:8d...）时，系统无法正确识别设备，导致自定义配置被忽略。而使用十六进制格式（0x00158d...）则能确保配置被正确应用。

最佳实践建议

1. 始终从网关日志中获取设备ID，而不是手动转换格式
2. 修改配置后，建议重启HomeAssistant以确保更改生效
3. 对于多个传感器，可以为每个设备单独设置不同的超时时间
4. 超时时间应根据实际使用场景调整，卫生间等区域可设置较长超时，走廊等区域可设置较短超时

故障排除

如果配置后仍未生效，可以检查以下方面：

1. 确认设备ID完全匹配日志中的'uid'字段
2. 检查yaml文件格式是否正确，特别是缩进和引号
3. 查看HomeAssistant日志是否有配置错误提示
4. 确保使用的是最新版本的XiaomiGateway3集成

通过正确配置occupancy_timeout参数，用户可以更灵活地控制人体传感器的行为，从而打造更符合实际需求的智能家居自动化场景。