Python-miio 是一个功能强大的 Python 库和命令行工具，专门用于控制小米智能家居设备。它支持小米的 miIO 和 MIoT 两种通信协议，让用户能够轻松管理扫地机器人、空气净化器、智能灯泡等各类智能设备。本文将详细介绍如何从零开始安装和配置这个项目，让你快速上手使用。
项目地址: https://gitcode.com/gh_mirrors/py/python-miio 🚀 快速开始：环境准备与基础安装
在开始安装 Python-miio 之前，请确保您的系统满足以下基本要求：
系统要求检查
- Python 3.6 或更高版本
- pip 包管理工具
- Git 版本控制系统
您可以使用以下命令验证系统环境：
python --version
pip --version
git --version
安装方式选择
方式一：使用 pip 安装稳定版本
这是最简单快捷的安装方式，适合大多数用户：
pip install python-miio
方式二：安装最新开发版本
如果您需要最新的功能和改进，可以从代码仓库安装：
git clone https://gitcode.com/gh_mirrors/py/python-miio
cd python-miio
pip install .
🔧 设备连接与令牌获取
成功安装后，最关键的一步是获取设备的连接信息。您需要准备设备的 IP 地址和访问令牌。
通过云服务获取设备信息
使用 miiocli cloud 命令可以从您的小米云账户中获取设备信息：
miiocli cloud
系统会提示您输入小米账号和密码，然后显示所有已绑定的设备信息，包括：
- 设备名称和状态
- 设备型号
- 访问令牌
- IP 地址
- 设备 ID
设备信息验证
获取到设备信息后，可以使用以下命令验证连接：
miiocli device --ip <设备IP> --token <设备令牌> info
该命令将返回设备的详细信息，包括硬件版本、固件版本以及推荐的控制命令。
📱 现代 MIoT 设备控制指南
大多数现代小米设备都支持 MIoT 协议，可以通过 genericmiot 集成进行控制。
设备状态查询
查看设备当前状态：
miiocli genericmiot --ip <IP> --token <令牌> status
设备设置调整
修改设备参数设置：
miiocli genericmiot --ip <IP> --token <令牌> set <参数名> <值>
动作执行
列出可用动作：
miiocli genericmiot --ip <IP> --token <令牌> actions
执行特定动作：
miiocli genericmiot --ip <IP> --token <令牌> call <动作名>
🛠️ 传统 miIO 设备控制方案
对于较老的设备，项目提供了专门的模块支持，如：
roborockvacuum- 扫地机器人控制fan- 风扇设备控制light- 智能灯具控制
模块使用示例
miiocli roborockvacuum --ip <IP> --token <令牌> start
🔍 故障排除与调试技巧
启用调试模式
如果遇到问题，可以使用调试模式获取详细信息：
miiocli device --ip <IP> --token <令牌> info -d
常见问题解决
- 设备无法连接：检查 IP 地址和令牌是否正确
- 命令执行失败：确认设备型号是否支持
- 状态获取异常：尝试重新获取设备信息
💻 Python API 编程接口使用
除了命令行工具，您还可以在 Python 程序中使用这个库：
from miio import DeviceFactory
# 创建设备实例
device = DeviceFactory.create("<IP地址>", "<访问令牌>")
# 获取设备状态
status = device.status()
功能自省方法
通过以下方法可以了解设备支持的功能：
sensors()- 获取传感器信息settings()- 获取可调整的设置actions()- 获取可执行的动作
🎯 高级功能与扩展应用
设备测试工具使用
项目提供了设备测试工具，方便开发者测试：
miiocli simulator --help
自定义设备支持
如果您有项目未支持的设备，可以参照现有代码结构添加支持。
📋 支持设备清单
Python-miio 支持广泛的小米智能设备，包括但不限于：
| 设备类型 | 主要型号 |
|---|---|
| 扫地机器人 | 小米扫地机器人 V1、S4、S5、S6、S7 系列 |
| 空气净化器 | 小米空气净化器 2、3H、4、Pro 系列 |
| 智能灯具 | 飞利浦智能灯泡、Yeelight 系列 |
| 其他设备 | 智能插座、空调伴侣、网关设备等 |
🎉 安装完成与后续步骤
恭喜！您已经成功安装并配置了 Python-miio。现在您可以：
- 使用命令行工具控制您的智能设备
- 编写 Python 脚本实现自动化控制
- 集成到您的智能家居系统中
记住，每个设备命令都支持 --help 参数，可以随时查看详细的用法说明。
重要提示：当前项目正在进行重大重构，如果您需要控制现代 MIoT 设备，建议使用 Git 版本或预发布版本以获得最佳体验。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
