小米设备错误码速查：hass-xiaomi-miot常见问题与解决方案

【免费下载链接】hass-xiaomi-miot Automatic integrate all Xiaomi devices to HomeAssistant via miot-spec, support Wi-Fi, BLE, ZigBee devices. 小米米家智能家居设备接入Hass集成 项目地址: https://gitcode.com/gh_mirrors/ha/hass-xiaomi-miot

你是否在使用hass-xiaomi-miot集成小米设备时遇到过各种错误码？连接失败、控制无响应、数据同步异常？本文汇总了该集成中最常见的错误代码及其解决方案，让你无需专业知识也能快速排查问题。

错误码解析基础

小米IoT设备通过MIOT协议与HomeAssistant通信时，任何异常都会返回特定错误码。这些代码由3位数字或带负号的4位数字组成，反映从设备离线到权限不足的各类问题。所有错误码定义均来自项目核心模块custom_components/xiaomi_miot/core/miot_spec.py，该文件维护着完整的错误码对照表。

错误码分类

根据错误来源，可分为三大类：

类别	错误码范围	示例	主要原因
设备相关	001-015	011	设备离线、不存在或操作超时
参数相关	033-059	043	属性不可读/写、值错误或格式问题
授权相关	901-999	905	Token失效、未授权或设备未绑定

设备连接类错误

011: 设备离线

现象：在HomeAssistant中显示设备离线，但米家APP可正常控制。

解决方案：

1. 检查设备Wi-Fi连接，重启路由器和设备
2. 确认设备固件为最新版本
3. 重启HomeAssistant集成：进入配置 > 集成 > Xiaomi MIoT，点击"重新加载"
4. 若使用本地连接，检查设备与HomeAssistant是否在同一网段

相关代码实现：

# [custom_components/xiaomi_miot/core/miot_spec.py](https://link.gitcode.com/i/51d0ff3bf0b18c9222761e3d609ecf7b#L51)
SPEC_ERRORS = {
    '011': 'Device offline',  # 设备离线
}

001: 设备不存在

现象：添加设备时提示"设备不存在"，但设备已在米家APP中正常使用。

解决方案：

1. 确认设备已绑定至当前小米账号
2. 检查集成中登录的小米账号与米家APP一致
3. 尝试在集成设置中重新登录小米账号
4. 对于蓝牙/ZigBee设备，确保网关已正常连接

参数操作类错误

043: 属性值错误

现象：调节设备属性（如亮度、温度）时失败，返回参数错误。

解决方案：

1. 检查属性值是否在有效范围内（如温度16-30°C）
2. 确认设备支持该属性调节功能
3. 示例：设置空调温度代码需符合设备规格

# 正确的温度设置示例
await device.async_set_property('temperature', 26)  # 而非字符串"26"或超出范围的值

错误码定义位置：custom_components/xiaomi_miot/core/miot_spec.py

023: 属性不可写

现象：尝试控制设备时提示"属性不可写"。

解决方案：

1. 确认设备该属性是否支持写入操作（部分传感器数据仅可读）
2. 检查设备是否处于特殊模式（如节能模式下某些功能被锁定）
3. 查看设备服务定义中的可写属性列表：custom_components/xiaomi_miot/core/miot_spec.py

授权与网络类错误

905: 设备未绑定

现象：集成显示"设备未绑定"，但设备已在米家APP中使用。

解决方案：

1. 确认小米账号已绑定设备：登录i.mi.com检查设备列表
2. 在集成中重新登录小米账号：custom_components/xiaomi_miot/core/xiaomi_cloud.py处理登录逻辑
3. 清除集成缓存：删除config/.storage/xiaomi_miot目录后重启

901: Token失效

现象：突然出现所有设备离线，日志显示"Token does not exist or expires"。

解决方案：

1. 集成自动尝试刷新Token，等待5-10分钟
2. 手动重新登录：进入集成设置页面输入小米账号密码
3. 若频繁失效，检查系统时间是否同步或更换网络环境

高级故障排除

错误日志查看

当遇到未列出的错误码时，可通过HomeAssistant日志获取详细信息：

1. 启用调试日志：在configuration.yaml中添加

logger:
  default: warn
  logs:
    custom_components.xiaomi_miot: debug

2. 重启HomeAssistant后查看日志：配置 > 系统 > 日志

3. 搜索包含"miot"或"xiaomi"的错误记录，特别关注类似以下格式的输出：

ERROR (MainThread) [custom_components.xiaomi_miot.core.miot_spec] MIOT error: 043 Property value error

常见问题流程图

总结与资源

通过本文介绍的错误码解析方法，90%的小米设备集成问题都能自行解决。遇到复杂问题时，可通过以下途径获取帮助：

1. 项目官方文档：README_zh.md
2. 错误码完整列表：custom_components/xiaomi_miot/core/miot_spec.py
3. 社区支持：在HomeAssistant社区论坛搜索错误码

定期更新集成组件可有效减少错误发生，建议开启HACS的自动更新功能。收藏本文以备日后遇到错误码时快速查阅！

【免费下载链接】hass-xiaomi-miot Automatic integrate all Xiaomi devices to HomeAssistant via miot-spec, support Wi-Fi, BLE, ZigBee devices. 小米米家智能家居设备接入Hass集成 项目地址: https://gitcode.com/gh_mirrors/ha/hass-xiaomi-miot