米家智能设备Python编程接口全解析：从基础集成到高级自动化

2026-03-16 02:34:38作者：齐冠琰

引言：智能家居编程的新时代

智能家居已成为现代生活的重要组成部分，而米家生态系统凭借其丰富的设备种类和高性价比，赢得了广大用户的青睐。本文将深入探讨如何利用Python编程接口，突破传统APP控制的局限，实现对米家智能设备的深度控制与个性化自动化。无论您是希望构建自定义智能家居系统的开发者，还是对智能家居自动化感兴趣的技术爱好者，本指南都将为您提供全面的技术支持和实践指导。

一、环境搭建与基础配置

1.1 安装策略与版本选择

米家API提供了多种安装方式，可根据您的实际需求选择最适合的方案：

快速部署方案：适合希望立即开始使用的用户

pip install mijiaAPI

开发调试方案：适合需要定制功能或贡献代码的开发者

git clone https://gitcode.com/gh_mirrors/mi/mijia-api
cd mijia-api
pip install .

系统集成方案：适合Arch Linux用户

yay -S python-mijia-api

版本注意事项：v1.5.0和v3.0.0版本包含架构性变更，从旧版本升级前，请务必查阅项目根目录中的CHANGELOG.md文件，了解详细的API变更和迁移指南。

1.2 开发环境准备

成功安装后，建议配置一个隔离的Python开发环境，以避免依赖冲突：

# 创建虚拟环境
python -m venv mijia-env

# 激活虚拟环境
source mijia-env/bin/activate  # Linux/Mac
mijia-env\Scripts\activate     # Windows

# 安装依赖
pip install mijiaAPI

二、认证机制与安全连接

2.1 认证流程详解

米家API采用安全的认证机制，确保只有授权用户能够访问和控制智能设备。推荐使用二维码认证方式：

实例化API对象并启动认证流程
在终端中显示二维码图像
使用米家APP扫描二维码完成授权
系统自动保存认证凭证

认证信息默认存储在用户配置目录下的加密文件中，您也可以通过参数指定自定义存储路径，确保认证的安全性和便捷性。

2.2 安全最佳实践

凭证管理：避免在代码中硬编码认证信息
会话保护：设置合理的会话超时时间
权限控制：遵循最小权限原则，仅授予必要权限
定期更新：保持API库和依赖包的最新版本

三、设备控制核心功能

3.1 设备发现与管理

在进行设备控制前，首先需要发现和识别网络中的智能设备：

from mijiaAPI import mijiaAPI

# 初始化API连接
mijia = mijiaAPI()
mijia.login()  # 如需重新认证，可添加force=True参数

# 获取家庭结构信息
family_units = mijia.get_homes()

# 遍历家庭并列出设备
for home in family_units:
    print(f"家庭名称: {home['name']}")
    devices = mijia.get_home_devices(home['id'])
    for device in devices:
        print(f"  - {device['name']} ({device['model']}): {device['did']}")

3.2 设备属性操作

米家API提供了统一的设备属性操作接口，支持大多数米家智能设备的核心功能：

单设备属性控制：

# 控制智能灯泡
light_did = "your_light_device_id"

# 打开灯光
mijia.set_device_prop(light_did, 2, 1, True)

# 设置亮度为70%
mijia.set_device_prop(light_did, 2, 2, 70)

# 调整色温为4000K
mijia.set_device_prop(light_did, 2, 3, 4000)

多设备批量控制：

# 同时控制多个设备
device_operations = [
    {"did": "light_did_1", "siid": 2, "piid": 1, "value": True},
    {"did": "light_did_2", "siid": 2, "piid": 1, "value": True},
    {"did": "thermostat_did", "siid": 2, "piid": 5, "value": 26}
]

results = mijia.set_devices_props(device_operations)

# 处理操作结果
for result in results:
    if result['code'] == 0:
        print(f"设备 {result['did']} 操作成功")
    else:
        print(f"设备 {result['did']} 操作失败: {result['message']}")

3.3 设备状态监控

实时监控设备状态变化，是实现智能自动化的基础：

# 监听设备状态变化
def device_status_callback(device_id, properties):
    print(f"设备 {device_id} 状态更新:")
    for prop in properties:
        print(f"  {prop['piid']}: {prop['value']}")

# 订阅设备状态更新
mijia.subscribe_device_status("device_id", device_status_callback)

# 保持程序运行以接收更新
import time
try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    print("程序退出")

四、高级应用开发

4.1 场景自动化实现

通过编程实现复杂的自动化场景，让智能家居系统根据环境变化自动响应：

环境自适应照明系统：

import time
from datetime import datetime

def adaptive_lighting_control():
    while True:
        # 获取当前时间和光照强度
        now = datetime.now()
        light_sensor_data = mijia.get_device_prop("light_sensor_did", 3, 1)
        current_brightness = light_sensor_data['value']
        
        # 根据时间和光照调整灯光
        if 6 <= now.hour < 8 or 17 <= now.hour < 20:  # 日出日落时段
            if current_brightness < 300:
                # 调整为暖光模式
                mijia.set_device_prop("main_light_did", 2, 3, 3000)  # 色温
                mijia.set_device_prop("main_light_did", 2, 2, 60)    # 亮度
        elif now.hour >= 20 or now.hour < 6:  # 夜间
            if current_brightness < 100:
                # 开启夜灯模式
                mijia.set_device_prop("night_light_did", 2, 1, True)
                mijia.set_device_prop("night_light_did", 2, 2, 10)
        time.sleep(60)  # 每分钟检查一次

# 在后台线程中运行自适应照明控制
import threading
lighting_thread = threading.Thread(target=adaptive_lighting_control, daemon=True)
lighting_thread.start()

4.2 数据采集与分析

收集设备运行数据，进行分析和可视化，帮助优化能源使用：

import csv
from datetime import datetime
import matplotlib.pyplot as plt

# 记录温度数据
def log_temperature_data():
    with open('temperature_log.csv', 'a', newline='') as file:
        writer = csv.writer(file)
        # 写入表头（如果文件为空）
        if file.tell() == 0:
            writer.writerow(['timestamp', 'temperature', 'humidity'])
        
        # 获取传感器数据
        temp_data = mijia.get_device_prop("thermostat_did", 3, 1)
        humidity_data = mijia.get_device_prop("thermostat_did", 3, 2)
        
        # 写入数据
        writer.writerow([
            datetime.now().isoformat(),
            temp_data['value'],
            humidity_data['value']
        ])

# 每10分钟记录一次数据
while True:
    log_temperature_data()
    time.sleep(600)

4.3 多设备协同控制

实现不同类型设备间的智能联动，创造更智能的生活体验：

def security_mode_activation():
    # 获取门窗传感器状态
    door_status = mijia.get_device_prop("door_sensor_did", 2, 1)
    
    if door_status['value'] is False:  # 门被打开
        # 打开玄关灯
        mijia.set_device_prop("entrance_light_did", 2, 1, True)
        
        # 启动摄像头录制
        mijia.execute_device_action("camera_did", 5, 1)
        
        # 发送通知
        send_notification("家门已打开，已启动安全监控")

# 设置定时检查
import schedule

schedule.every(10).seconds.do(security_mode_activation)

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

五、故障排除与性能优化

5.1 常见问题诊断

连接问题排查流程：

确认网络连接正常，设备可访问互联网
检查米家服务器状态（可通过米家APP验证）
验证认证凭证是否过期，必要时重新登录
检查设备是否在线且正常工作

API调用失败处理：

def safe_api_call(api_method, *args, **kwargs):
    max_retries = 3
    retry_delay = 2
    
    for attempt in range(max_retries):
        try:
            return api_method(*args, **kwargs)
        except Exception as e:
            print(f"API调用失败 (尝试 {attempt+1}/{max_retries}): {str(e)}")
            if attempt < max_retries - 1:
                time.sleep(retry_delay)
    
    # 所有重试都失败，返回None或抛出异常
    return None

5.2 性能优化策略

请求优化：

批量处理设备操作，减少API调用次数
合理设置请求超时和重试机制
利用缓存减少重复请求

资源管理：

及时释放不再需要的设备连接
对长时间运行的程序实现资源回收机制
使用异步编程模型提高并发处理能力

代码示例：

# 使用缓存减少重复请求
from functools import lru_cache

@lru_cache(maxsize=128)
def get_cached_device_info(device_id):
    return mijia.get_device_info(device_id)

# 批量获取设备属性
def batch_get_properties(device_list):
    properties = [{"did": did, "siid": 2, "piid": 1} for did in device_list]
    return mijia.get_devices_prop(properties)

六、实际应用案例

6.1 智能办公环境

打造自动化办公空间，提升工作效率：

def office_automation():
    # 工作日早上8点开启办公室设备
    schedule.every().monday.to.friday.at("08:00").do(lambda: 
        mijia.set_devices_props([
            {"did": "office_light_did", "siid": 2, "piid": 1, "value": True},
            {"did": "air_conditioner_did", "siid": 2, "piid": 1, "value": True},
            {"did": "air_conditioner_did", "siid": 2, "piid": 5, "value": 24}
        ])
    )
    
    # 工作日晚上7点关闭所有设备
    schedule.every().monday.to.friday.at("19:00").do(lambda:
        mijia.set_devices_props([
            {"did": "office_light_did", "siid": 2, "piid": 1, "value": False},
            {"did": "air_conditioner_did", "siid": 2, "piid": 1, "value": False},
            {"did": "projector_did", "siid": 2, "piid": 1, "value": False}
        ])
    )
    
    # 持续运行调度器
    while True:
        schedule.run_pending()
        time.sleep(60)

6.2 能源管理系统

智能监控和管理家庭能源使用：

def energy_management_system():
    # 监控高能耗设备
    high_energy_devices = ["water_heater_did", "air_conditioner_did"]
    
    while True:
        # 获取设备能耗数据
        energy_data = []
        for device_id in high_energy_devices:
            data = mijia.get_device_prop(device_id, 4, 1)  # 假设siid=4, piid=1是能耗属性
            energy_data.append({
                "device_id": device_id,
                "consumption": data['value'],
                "timestamp": datetime.now()
            })
        
        # 分析能耗数据，超过阈值时发送警报
        for item in energy_data:
            if item["consumption"] > 5.0:  # 假设阈值是5kWh
                send_alert(f"设备 {item['device_id']} 能耗过高: {item['consumption']}kWh")
        
        time.sleep(3600)  # 每小时检查一次

七、进阶开发与未来展望

7.1 自定义设备支持

对于API未直接支持的设备，可以通过自定义协议实现控制：

class CustomDevice:
    def __init__(self, api, device_id):
        self.api = api
        self.device_id = device_id
    
    def custom_command(self, service_id, action_id, params):
        """发送自定义命令到设备"""
        return self.api.execute_device_action(
            self.device_id, 
            service_id, 
            action_id,
            params
        )

# 使用示例
my_device = CustomDevice(mijia, "custom_device_did")
response = my_device.custom_command(6, 2, {"mode": "eco"})