5分钟快速上手：用Python-miio掌控小米智能家居的终极指南 [特殊字符]

史淳莹Deirdre

326人浏览 · 2026-04-18 12:13:09

史淳莹Deirdre · 2026-04-18 12:13:09 发布

5分钟快速上手：用Python-miio掌控小米智能家居的终极指南 🏠

【免费下载链接】python-miio Python library & console tool for controlling Xiaomi smart appliances 项目地址: https://gitcode.com/gh_mirrors/py/python-miio

Python-miio是一款专为小米智能设备设计的Python库和命令行工具，让您能够通过编程方式完全控制家中的小米智能设备。无论您是智能家居爱好者还是开发者，这个开源工具都能让您的小米设备发挥最大潜力，实现自动化控制和个性化定制。通过简单的Python代码或命令行指令，您可以轻松控制扫地机器人、空气净化器、智能灯具等各种小米生态产品。

🚀 Python-miio核心优势：为什么选择它？

全面覆盖小米生态链设备

Python-miio支持超过80%的小米智能设备，包括：

清洁设备：Roborock、Dreame系列扫地机器人
环境电器：空气净化器、加湿器、风扇、空调伴侣
智能照明：Yeelight全系列智能灯具
厨房家电：电饭煲、净水器、咖啡机
安防设备：摄像头、网关、传感器

双协议完美兼容

miIO协议：支持传统小米设备的通信协议
MIoT协议：适配新一代智能设备的统一协议架构

多种控制方式灵活选择

命令行工具：无需编程基础，直接通过miiocli控制设备
Python API：编写自定义脚本实现复杂自动化场景
集成支持：无缝对接Home Assistant等智能家居平台

📦 快速安装：3步完成环境搭建

第一步：环境检查

确保您的系统满足以下要求：

Python 3.6或更高版本
pip包管理器
网络连接正常

验证环境：

python3 --version
pip3 --version

第二步：安装Python-miio

选择最适合您的安装方式：

方式一：通过pip快速安装（推荐）

pip3 install python-miio

方式二：从源码安装（获取最新功能）

git clone https://gitcode.com/gh_mirrors/py/python-miio
cd python-miio
pip3 install .

第三步：验证安装

安装完成后，运行以下命令检查是否成功：

miiocli --version

看到版本号输出即表示安装成功！🎉

🔐 设备连接准备：获取Token和IP地址

什么是设备Token？

Token是小米设备的身份验证密钥，类似于设备的"密码"，用于加密通信确保安全。

获取Token的两种方法

方法一：使用官方App提取（最简单）

在小米智能家居App中绑定您的设备
使用项目提供的Token提取工具：

python -m miio.extract_tokens

按照提示输入小米账号密码，即可获取所有已绑定设备的IP和Token信息

方法二：网络数据包分析（高级用户）

使用内置的网络工具分析通信数据：

python -m miio.devtools.pcapparser

该工具位于miio/devtools/pcapparser.py，可以解析网络数据包并提取设备Token

🎯 实用操作示例：立即开始控制设备

示例1：查询设备基本信息

miiocli device --ip 192.168.1.100 --token YOUR_DEVICE_TOKEN info

此命令将返回设备型号、固件版本、网络状态等详细信息

示例2：控制Yeelight智能灯具

# 开启灯光
miiocli yeelight --ip 192.168.1.101 --token YOUR_TOKEN on

# 设置亮度为50%
miiocli yeelight --ip 192.168.1.101 --token YOUR_TOKEN set_brightness 50

# 切换灯光颜色
miiocli yeelight --ip 192.168.1.101 --token YOUR_TOKEN set_rgb 255 0 0

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 pause

# 返回充电座
miiocli vacuum --ip 192.168.1.102 --token YOUR_TOKEN home

# 查询清扫状态
miiocli vacuum --ip 192.168.1.102 --token YOUR_TOKEN status

支持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脚本自动化控制

创建smart_home_automation.py文件：

from miio import Device

# 初始化设备连接
device_ip = "192.168.1.100"
device_token = "YOUR_DEVICE_TOKEN"
device = Device(device_ip, device_token)

# 查询设备属性
properties = device.send("get_prop", ["power", "mode", "temperature"])
print(f"设备状态: {properties}")

# 控制设备开关
device.send("set_power", ["on"])

# 设置设备模式
device.send("set_mode", ["auto"])

运行脚本：python3 smart_home_automation.py

🛠️ 常见问题与解决方案

问题1：设备连接失败或超时

解决方案：

确认设备已通电并连接到Wi-Fi网络
检查IP地址是否正确（可在路由器管理界面查看）
验证Token是否准确无误（区分大小写）
尝试重启路由器和智能设备
确保防火墙没有阻止设备通信

问题2：命令执行返回错误

解决方案： 查看设备支持的所有命令：

miiocli device --ip <设备IP> --token <设备Token> raw_command help

问题3：找不到特定设备型号支持

解决方案： Python-miio采用模块化设计，新设备支持可以通过扩展miio/integrations/目录实现。如果遇到不支持的设备：

在项目仓库提交issue请求支持
参考现有设备实现，贡献代码
使用通用MIoT设备接口尝试控制

📚 进阶学习与开发资源

官方文档与参考资料

项目文档位于docs/目录，包含：

设备支持详细列表：docs/device_docs/
协议技术详解：docs/legacy_token_extraction.rst
模拟器使用指南：docs/simulator.rst

核心源码结构

深入了解Python-miio的内部实现：

设备基类：miio/device.py
通信协议：miio/protocol.py
命令行接口：miio/cli.py

开发贡献指南

如果您想为项目贡献力量，请参考：

贡献规范：CONTRIBUTING.md
代码风格指南
测试编写规范

💡 实用技巧与最佳实践

自动化场景示例

创建定时任务，让设备按计划运行：

import schedule
import time
from miio import Device

def morning_routine():
    # 早上7点开启空气净化器
    air_purifier = Device("192.168.1.103", "TOKEN")
    air_purifier.send("set_power", ["on"])
    
    # 早上7:05开启咖啡机
    coffee_maker = Device("192.168.1.104", "TOKEN")
    coffee_maker.send("start_brewing", [])

# 设置定时任务
schedule.every().day.at("07:00").do(morning_routine)

while True:
    schedule.run_pending()
    time.sleep(1)

设备状态监控

实时监控设备状态并发送通知：

import requests
from miio import Device

def check_device_health():
    devices = [
        ("192.168.1.100", "TOKEN1", "客厅灯"),
        ("192.168.1.101", "TOKEN2", "卧室空调"),
        ("192.168.1.102", "TOKEN3", "扫地机器人")
    ]
    
    for ip, token, name in devices:
        try:
            device = Device(ip, token)
            status = device.send("get_prop", ["power"])
            print(f"{name}状态正常: {status}")
        except Exception as e:
            print(f"{name}连接异常: {e}")
            # 发送通知到手机
            send_alert(f"{name}设备异常")

check_device_health()