如何用Python-miio控制小米智能设备？2025完整入门指南 🚀
项目地址: https://gitcode.com/gh_mirrors/py/python-miio Python-miio是一款强大的开源工具，让你轻松通过Python代码或命令行掌控小米智能家电。无论是扫地机器人、空气净化器还是智能灯泡，它都能完美支持miIO和MIoT协议，让你的智能家居设备秒变可编程的「智能伙伴」！
📌 为什么选择Python-miio？核心优势解析
✅ 全设备支持
覆盖小米生态80%以上智能设备，包括：
- 扫地机器人（如Roborock、Dreame系列）
- 环境电器（空气净化器、加湿器、风扇）
- 照明设备（Yeelight全系智能灯）
- 生活家电（电饭煲、净水器、空调伴侣）
✅ 双协议兼容
- miIO协议：支持传统小米设备通信
- MIoT协议：适配新一代智能设备的统一协议
✅ 灵活控制方式
- 命令行工具：无需编程，直接通过
miiocli控制设备 - Python API：编写自定义脚本实现自动化场景
- 集成支持：可无缝对接Home Assistant等智能家居平台
📥 零基础安装指南：3步快速上手
1️⃣ 准备环境
确保系统已安装：
- Python 3.6+及pip包管理器
- Git版本控制工具
检查Python版本：
python --version # 应显示3.6以上版本
pip --version # 确保pip已安装
2️⃣ 安装Python-miio
推荐两种安装方式，选择其一即可：
方法A：通过pip快速安装
pip install python-miio
方法B：从源码安装（获取最新功能）
git clone https://gitcode.com/gh_mirrors/py/python-miio
cd python-miio
pip install .
3️⃣ 验证安装
安装完成后，输入以下命令检查是否成功：
miiocli --version
出现版本号即表示安装成功！🎉
🔑 设备连接：获取Token和IP地址
什么是Token？
Token是小米设备的「密钥」，用于加密通信。获取方式有两种：
方法1：通过官方App提取（推荐）
- 在小米智能家居App中绑定设备
- 使用
miio-extract-tokens工具导出：
miio-extract-tokens
按照提示输入小米账号密码，即可获取所有设备的IP和Token
方法2：本地网络嗅探（高级用户）
使用项目提供的抓包工具：
python -m miio.devtools.pcapparser
该工具位于miio/devtools/pcapparser.py，支持解析网络数据包提取Token
🎮 开始控制设备：5个实用示例
示例1：查询设备信息
miiocli device --ip 192.168.1.100 --token YOUR_TOKEN info
输出设备型号、固件版本、支持的功能等信息
示例2：控制Yeelight智能灯
# 打开灯光
miiocli yeelight --ip 192.168.1.101 --token YOUR_TOKEN on
# 设置亮度为70%
miiocli yeelight --ip 192.168.1.101 --token YOUR_TOKEN set_brightness 70
Yeelight设备支持丰富的色彩和场景模式，相关控制逻辑位于miio/integrations/yeelight/目录
示例3：控制扫地机器人
# 开始清扫
miiocli vacuum --ip 192.168.1.102 --token YOUR_TOKEN start
# 返回充电座
miiocli vacuum --ip 192.168.1.102 --token YOUR_TOKEN home
支持Roborock、Dreame等主流扫地机器人型号，完整功能见miio/integrations/roborock/vacuum/
示例4：查询空气净化器状态
miiocli airpurifier --ip 192.168.1.103 --token YOUR_TOKEN status
输出PM2.5浓度、滤芯寿命、运行模式等信息，设备支持位于miio/integrations/zhimi/airpurifier/
示例5：Python脚本控制（高级）
创建control_device.py：
from miio import Device
# 初始化设备
device = Device("192.168.1.100", "YOUR_TOKEN")
# 发送命令
result = device.send("get_prop", ["power"])
print(f"设备状态: {result}")
运行脚本：python control_device.py
🛠️ 常见问题解决
问题1：设备连接超时
- 检查设备是否在线，IP地址是否正确
- 确认Token无误（区分大小写）
- 尝试重启路由器和智能设备
问题2：命令执行失败
查看设备支持的命令列表：
miiocli device --ip <IP> --token <TOKEN> raw_command help
问题3：找不到设备型号
Python-miio采用模块化设计，新设备支持可通过miio/integrations/目录扩展。如果遇到不支持的设备，可以：
- 提交issue到项目仓库
- 参考现有设备实现，贡献代码
📚 进阶学习资源
官方文档
项目文档位于docs/目录，包含：
- 设备支持列表（
docs/device_docs/） - 协议详解（
docs/legacy_token_extraction.rst） - 模拟器使用（
docs/simulator.rst）
开发指南
如果想参与项目开发，可参考：
- 贡献指南：
CONTRIBUTING.md - 代码结构：
miio/device.py（设备基类）、miio/protocol.py（通信协议）
🎯 总结
Python-miio为小米智能设备提供了强大的控制能力，无论是简单的命令行操作还是复杂的自动化脚本，都能轻松实现。通过本文的指南，你已经掌握了从安装到高级控制的全流程。现在就动手试试，让你的智能家居设备发挥更大潜力吧！💡
如果觉得这个工具对你有帮助，别忘了给项目点赞支持哦！👍
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
