5步精通小米设备控制：开发者与智能家居爱好者实践指南

小米生态链设备已成为现代智能家居的重要组成部分，但复杂的设备控制接口常常让开发者望而却步。本文将系统介绍MiService项目的技术架构与应用方法，帮助开发者与智能家居爱好者快速掌握小米设备的程序化控制能力，实现从基础操作到自动化场景的完整落地。

一、基础认知：小米设备控制技术解析 🧩

1.1 小米设备通信架构

小米智能设备采用MIoT（Xiaomi IoT）协议作为统一通信标准，所有设备通过云端API与客户端进行数据交互。MiService作为协议封装层，简化了复杂的认证流程和指令编码，提供了面向开发者的友好接口🔌。

1.2 核心概念解析

• 设备ID（DID）：每台小米设备的唯一标识符，相当于设备的"身份证"
• 服务ID（SIID）：设备功能模块的分类标识，如"2"通常代表音频服务
• 属性ID（PIID）：具体功能参数的标识，如"1"可能对应音量属性
• 动作指令：触发设备执行特定操作的命令，如文本转语音播报

二、环境搭建：从安装到配置的完整路径 🛠️

2.1 开发环境准备

git clone https://gitcode.com/gh_mirrors/mi/MiService
cd MiService
pip3 install aiohttp aiofiles

[!NOTE] 确保Python版本≥3.7，建议使用虚拟环境隔离依赖包

2.2 账号认证配置

通过环境变量设置小米账号信息：

export MI_USER=您的小米账号
export MI_PASS=您的小米账号密码

2.3 设备发现流程

执行设备扫描命令获取网络中的小米设备列表：

python3 micli.py list

三、核心功能：设备控制的四大支柱 🔑

3.1 设备状态查询（智能家居自动化基础）

通过服务ID和属性ID组合查询设备当前状态：

export MI_DID=您的设备ID
python3 micli.py 2-1

适用场景：家庭安防系统状态监控、能源消耗统计分析

3.2 属性参数设置

调整设备运行参数的标准格式：

python3 micli.py 2=#60  # 设置服务2的属性值为60（通常对应音量）

适用场景：夜间模式自动调节适用于卧室智能灯、离家模式下自动降低空调温度

3.3 动作指令执行

触发设备特定功能的调用格式：

python3 micli.py 5 "欢迎使用智能家居控制系统"  # 调用文本播报功能

适用场景：门禁系统触发欢迎语音、厨房设备完成烹饪时的提示播报

3.4 设备接口规格查询

获取设备完整能力描述：

python3 micli.py spec

设备指令差异对比表

设备类型	查询指令格式	设置指令格式	动作指令格式
智能音箱	siid-piid	siid=#value	siid "content"
智能灯泡	siid-piid	siid=#value	siid [param1,param2]
智能插座	siid-piid	siid=#value	-

四、创新应用：突破单一控制的场景拓展 💡

4.1 设备联动规则设置

通过组合多个设备的状态和动作，实现自动化场景：

# 伪代码示例：当门窗传感器检测到开门时自动开灯
if door_sensor.status == "open" and light.status == "off":
    light.set_property(2, 1, "on")  # 开启灯光
    speaker.action(5, "欢迎回家")  # 播放欢迎语

适用场景：回家模式（自动开灯+开空调+拉窗帘）、离家模式（关闭所有设备电源）

4.2 第三方系统集成方法

MiService可通过HTTP接口与外部系统集成：

# Flask服务示例：提供HTTP接口控制小米设备
from flask import Flask, request
from miservice.miioservice import MiIOService

app = Flask(__name__)
service = MiIOService()

@app.route('/control', methods=['POST'])
def control_device():
    did = request.json.get('did')
    siid = request.json.get('siid')
    piid = request.json.get('piid')
    value = request.json.get('value')
    service.miio_set_prop(did, f"{siid}-{piid}", value)
    return {"status": "success"}

if __name__ == '__main__':
    app.run()

适用场景：与Home Assistant集成、接入企业监控系统、自定义语音助手控制

五、专家指南：从入门到精通的进阶路径 🚀

5.1 初级：基础操作优化

• 环境变量持久化：将账号信息写入~/.bashrc或~/.zshrc

  echo 'export MI_USER="您的账号"' >> ~/.bashrc
  echo 'export MI_PASS="您的密码"' >> ~/.bashrc
  source ~/.bashrc
  

• 设备别名设置：使用设备名称代替ID进行操作
• 命令别名创建：简化常用命令

  alias milist="python3 micli.py list"
  

5.2 中级：功能扩展开发

• 批量设备管理：编写脚本同时控制多个设备
• 属性监听：实现设备状态变化的实时监控
• 自定义指令封装：创建业务逻辑层简化复杂操作

5.3 高级：系统架构设计

• 异步任务队列：处理大量设备的并发控制请求
• 数据持久化：存储设备历史状态用于分析和报表
• 错误重试机制：提高系统稳定性和容错能力

常见问题速查表

Q1: 执行命令时提示"认证失败"如何解决？
A1: 1. 检查账号密码是否正确；2. 确认网络环境可访问小米云服务；3. 删除.mi.token文件后重新登录

Q2: 设备列表为空但设备已联网怎么办？
A2: 1. 确认设备已绑定到当前小米账号；2. 尝试重启设备；3. 使用python3 micli.py list --refresh强制刷新设备列表

Q3: 如何获取设备支持的所有SIID和PIID？
A3: 执行python3 micli.py spec命令查看设备完整接口规格，或查阅小米官方MIoT设备文档