HomeAssistant Xiaomi Miot 集成终极指南：深度解析小米智能家居接入实战技巧
项目地址: https://gitcode.com/gh_mirrors/ha/hass-xiaomi-miot 相关服务：台湾VPS服务器
Xiaomi Miot For HomeAssistant 是一个基于 MIoT-Spec 协议的强大集成插件，能够自动将小米米家智能设备接入 HomeAssistant 平台。作为目前最全面、最稳定的小米设备集成方案，它支持 Wi-Fi、蓝牙和 ZigBee 等多种连接方式的设备，为智能家居爱好者提供了无缝的小米设备接入体验。
架构设计与技术原理深度解析
MIoT-Spec 协议核心机制
MIoT-Spec 是小米 IoT 平台设计的硬件产品功能定义标准规范，该插件通过解析设备的功能定义，实现自动化实体创建和设备控制。其核心技术架构包含以下关键组件：
核心模块架构
custom_components/xiaomi_miot/
├── core/ # 核心功能模块
│ ├── device.py # 设备管理核心
│ ├── miot_spec.py # MIoT 协议解析
│ ├── xiaomi_cloud.py # 小米云服务交互
│ └── converters.py # 数据格式转换
├── 实体类型模块/
│ ├── sensor.py # 传感器实体
│ ├── switch.py # 开关实体
│ ├── light.py # 灯光实体
│ └── camera.py # 摄像头实体
└── 系统集成模块/
├── config_flow.py # 配置流程
├── __init__.py # 插件初始化
└── services.yaml # 服务定义
设备发现与连接模式
插件支持三种设备连接模式，每种模式都有其特定的应用场景：
| 连接模式 | 适用场景 | 优势 | 局限性 |
|---|---|---|---|
| 自动模式 | 混合设备环境 | 智能选择最优连接方式 | 需要网络配置优化 |
| 本地模式 | 局域网设备 | 响应速度快，不依赖云端 | 仅支持 MIoT 协议设备 |
| 云端模式 | 蓝牙/ZigBee 设备 | 支持更多设备类型 | 依赖网络稳定性 |
小贴士：对于 Wi-Fi 设备，建议优先使用自动模式；对于蓝牙和 ZigBee 设备，必须使用云端模式。
安装配置全流程详解
多途径安装方法对比
HACS 安装（推荐）
# 通过 HACS 商店安装
1. 进入 HACS > 集成
2. 点击右下角 "+" 按钮
3. 搜索 "Xiaomi Miot"
4. 点击下载并重启 HomeAssistant
手动安装方法
# 通过 SSH 一键安装
wget -O - https://get.hacs.vip | DOMAIN=xiaomi_miot bash -
# 或使用原始安装脚本
wget -O - https://raw.githubusercontent.com/al-one/hass-xiaomi-miot/master/install.sh | ARCHIVE_TAG=latest bash -
注意事项：手动安装后需要重启 HomeAssistant 两次才能完全生效。
小米账号配置优化
配置小米云服务是实现设备自动发现的关键步骤：
# configuration.yaml 配置示例
xiaomi_miot:
username: "您的米家账号"
password: "您的米家密码"
server_country: "cn" # 服务器地区：cn, tw, de, i2, ru, sg, us
http_timeout: 15 # API 请求超时时间（秒）
服务器地区选择指南
cn：中国大陆（默认）tw：中国台湾de：欧洲us：美国sg：新加坡
最佳实践：如果设备在中国大陆购买，请使用 cn 服务器；海外版设备根据购买地区选择对应服务器。
高级功能配置与自定义
实体自定义配置
插件提供了强大的实体自定义功能，可以根据设备特性进行精细调整：
# 通过设备型号自定义
xiaomi_miot:
device_customizes:
chuangmi.plug.212a01:
miot_local: true
chunk_properties: 7
interval_seconds: 30
# 通过父实体自定义
switch.your_entity_id:
miot_local: true # 强制使用局域网连接
miot_cloud: true # 启用云端读写
check_lan: true # 云端模式下检查局域网连接
sensor_properties: temperature,humidity # 创建子传感器实体
翻译与本地化配置
支持多语言设备状态显示：
xiaomi_miot:
language: zh # 使用中文翻译
translations:
# 全局字典
idle: '空闲'
busy: '工作中'
# 风扇模式特定翻译
fan.mode:
straight wind: '直吹模式'
natural wind: '自然风'
# 洗衣机烘干级别翻译
washer.drying_level:
moist: '微湿'
extra: '特干'
小贴士：翻译配置可以显著改善设备状态在 HomeAssistant 中的显示效果，特别是对于英文界面用户。
设备兼容性与实体映射
支持的设备类型概览
插件支持超过 50 种设备类型，涵盖智能家居的各个领域：
照明与电器控制
- 智能插座、开关、调光器
- LED 灯泡、灯带、智能灯具
- 风扇、空调、空气净化器
安防与监控
- 智能摄像头、门铃
- 门窗传感器、人体传感器
- 智能门锁、报警器
环境与健康
- 温湿度传感器、空气质量检测
- 加湿器、除湿机
- 体重秤、体脂秤
娱乐与生活
- 智能电视、投影仪
- 小爱音箱、智能闹钟
- 扫地机器人、洗衣机
实体属性过滤优化
过多的实体属性会导致 HomeAssistant 数据库膨胀，可以通过以下配置优化：
xiaomi_miot:
exclude_state_attributes:
- miot_type
- stream_address
- motion_video_latest
- device_token
- firmware_version
服务调用与自动化集成
核心服务功能详解
插件提供了丰富的服务接口，支持高级自动化场景：
属性操作服务
# 设置设备属性
service: xiaomi_miot.set_property
data:
entity_id: camera.isa_hlc7_xxxx
field: camera_control.on
value: true
# 通过 SIID/PIID 设置属性
service: xiaomi_miot.set_miot_property
data:
entity_id: climate.xiaomi_mc5_374e
siid: 2
piid: 1
value: true
# 批量获取属性
service: xiaomi_miot.get_properties
data:
entity_id: camera.isa_hlc7_1ab7
mapping:
- siid: 2
piid: 1
- siid: 3
piid: 2
update_entity: true
设备控制服务
# 执行设备动作
service: xiaomi_miot.call_action
data:
entity_id: vacuum.dreame_p2259_entity_id
siid: 4 # vacuum-extend
aiid: 1 # start-clean
params:
- 18 # 工作模式
- '{"selects":[[7,1,0,2,1]]}' # 清洁扩展数据
# 发送原始命令
service: xiaomi_miot.send_command
data:
entity_id: switch.your_entity_id
method: set_power
params:
- on
小爱同学语音控制
# 小爱音箱文本转语音
service: xiaomi_miot.intelligent_speaker
data:
entity_id: media_player.xiaoai_lx04_xxxx
text: "打开客厅的灯"
execute: true # 执行文本指令
silent: true # 静默执行
# 唤醒小爱同学
service: xiaomi_miot.xiaoai_wakeup
data:
entity_id: media_player.xiaoai_lx04_xxxx
故障排除与性能优化
常见问题解决方案
设备连接失败排查流程
-
网络环境检查
- 确认设备与 HomeAssistant 在同一子网
- 检查路由器防火墙设置
- 验证设备 IP 地址是否正确
-
账号权限验证
- 确认米家账号可以正常登录
- 检查账号是否有二次验证
- 验证服务器地区设置
-
Token 获取与验证
- 使用服务
xiaomi_miot.get_token获取设备 Token - 验证 Token 格式是否正确
- 确认设备支持 MIoT 协议
- 使用服务
调试日志启用
# configuration.yaml
logger:
default: warning
logs:
custom_components.xiaomi_miot: debug
启用调试日志后，可以在 HomeAssistant 日志中查看详细的设备通信信息，帮助定位问题。
性能优化配置
更新间隔调整
# 调整设备状态更新间隔
domain.your_entity_id:
interval_seconds: 30 # 状态更新间隔（秒）
chunk_properties: 10 # 属性分块更新数量
连接模式优化
# 根据设备类型优化连接模式
switch.wifi_device:
miot_local: true # Wi-Fi 设备使用本地连接
sensor.ble_device:
miot_cloud: true # 蓝牙设备使用云端连接
高级功能与扩展应用
智能家居场景集成
自动化场景示例
# 当温度超过阈值时打开空调
automation:
- alias: "高温自动开空调"
trigger:
platform: numeric_state
entity_id: sensor.living_room_temperature
above: 28
action:
- service: climate.turn_on
target:
entity_id: climate.living_room_ac
- service: climate.set_temperature
target:
entity_id: climate.living_room_ac
data:
temperature: 26
设备联动配置
# 摄像头与灯光联动
camera.your_entity_id:
motion_detection_enabled: true
automation:
- alias: "检测到移动时开灯"
trigger:
platform: state
entity_id: binary_sensor.camera_motion
to: "on"
action:
- service: light.turn_on
target:
entity_id: light.living_room
自定义实体创建
通过配置文件创建自定义子实体：
# 为设备创建额外的传感器实体
sensor.parent_entity_id:
sensor_properties: temperature,humidity,illumination
binary_sensor_properties: is_volume_muted,any_boolean_property
switch_properties: on,power
number_properties: volume
select_properties: mode
维护与更新策略
配置重载机制
插件支持配置热重载，无需重启 HomeAssistant：
- 进入开发者工具 > YAML 配置重载
- 查找 "Xiaomi Miot" 配置
- 点击重载按钮应用更改
设备管理最佳实践
定期设备刷新
# 使用服务刷新设备列表
service: xiaomi_miot.renew_devices
data:
username: "您的米家账号"
数据库维护建议
- 定期清理不必要的实体属性
- 监控数据库大小增长
- 使用 exclude_state_attributes 过滤冗余数据
总结与展望
Xiaomi Miot For HomeAssistant 插件通过 MIoT-Spec 协议实现了对小米智能设备的全面支持，为智能家居爱好者提供了稳定、高效的设备接入方案。无论是基础的设备控制，还是复杂的自动化场景，该插件都能提供强大的功能支持。
核心优势总结
- 广泛兼容：支持绝大多数小米 IoT 设备
- 灵活配置：提供多种连接模式和自定义选项
- 性能优化：支持本地和云端混合连接
- 易于扩展：丰富的服务接口支持高级自动化
未来发展方向 随着小米 IoT 生态的不断发展，插件将持续更新以支持新设备和新功能。社区驱动的开发模式确保了插件的活跃度和兼容性，为智能家居用户提供了长期的技术保障。
通过合理配置和优化，Xiaomi Miot 插件能够成为您智能家居系统的核心组件，实现小米设备与 HomeAssistant 平台的完美融合。
项目地址: https://gitcode.com/gh_mirrors/ha/hass-xiaomi-miot 
