5步快速掌握小米智能设备API开发：从零到精通的智能家居控制指南

【免费下载链接】mijia-api 米家API 项目地址: https://gitcode.com/gh_mirrors/mi/mijia-api

想要通过Python代码轻松控制家中的小米智能设备吗？小米智能设备API为开发者提供了强大的智能家居控制能力，让您能够快速上手小米API开发，实现智能设备编程和家居自动化控制。本指南将带您从基础安装到高级应用，全面掌握小米智能设备API开发技巧。

🚀 快速上手：环境配置与认证登录

安装小米智能设备API包

开始之前，首先需要安装mijiaAPI包，这是控制小米智能设备的核心库：

pip install mijiaAPI

或者从源码安装以获得最新功能：

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

安全便捷的二维码登录

使用二维码登录是最推荐的方式，既安全又便捷：

from mijiaAPI import mijiaAPI

# 初始化API，认证文件默认保存在 ~/.config/mijia-api/auth.json
api = mijiaAPI()

# 登录（如果Token有效会自动跳过）
api.login()  # 使用二维码登录

登录时会在终端显示二维码，使用米家APP扫描即可完成身份验证。认证信息会自动保存，后续使用无需重复登录。

验证API可用性

登录成功后，检查API是否可用：

if api.available:
    print("✅ 认证有效，可以开始控制设备")
else:
    print("❌ 认证失败，请重新登录")

🔍 深度探索：设备发现与属性控制

发现智能设备

获取所有可控制的设备列表：

# 获取所有设备
devices = api.get_devices_list()
print(f"🎯 发现 {len(devices)} 个智能设备")

# 查看设备详细信息
for device in devices:
    print(f"📱 设备: {device['name']}")
    print(f"  型号: {device['model']}")
    print(f"  ID: {device['did']}")

获取家庭和设备信息

# 获取家庭列表
homes = api.get_homes_list()
print(f"🏠 您的账户关联了 {len(homes)} 个家庭")

# 获取指定家庭的设备
home_id = homes[0]['id']
devices_in_home = api.get_devices_list(home_id=home_id)

高级设备控制类

mijiaDevice类提供了更人性化的设备控制方式：

from mijiaAPI import mijiaDevice

# 通过设备名称初始化（推荐）
device = mijiaDevice(api, dev_name="卧室台灯")

# 直接使用属性赋值方式控制设备
device.on = True                    # 打开设备
device.brightness = 75              # 设置亮度为75%
device.color_temperature = 4000     # 设置色温为4000K

💡 实战应用：构建智能家居场景

智能灯光控制

实现智能灯光自动化控制：

# 获取设备属性
current_brightness = device.brightness
is_on = device.on

print(f"💡 当前状态: {'开启' if is_on else '关闭'}")
print(f"✨ 当前亮度: {current_brightness}%")

# 智能调光
def smart_light_adjustment():
    if not device.on:
        device.on = True
    device.brightness = 60
    device.color_temperature = 3000  # 暖黄色光
    print("🎨 灯光已调整为舒适模式")

环境传感器数据采集

获取环境传感器数据并实现自动化：

# 创建设备对象
sensor = mijiaDevice(api, dev_name="温湿度计")

# 实时监测环境数据
temperature = sensor.temperature
humidity = sensor.humidity

print(f"🌡️ 当前温度: {temperature}°C")
print(f"💧 当前湿度: {humidity}%")

# 智能联动控制
if temperature > 28:
    air_conditioner = mijiaDevice(api, dev_name="空调")
    air_conditioner.on = True
    air_conditioner.target_temperature = 26
    print("❄️ 温度过高，已自动开启空调")

场景与自动化

# 获取场景列表
scenes = api.get_scenes_list()
print(f"🎭 可用场景: {len(scenes)} 个")

# 执行场景
api.run_scene(scene_id="您的场景ID")

⚡ 专业技巧：性能优化与错误处理

并发设备控制

当需要同时控制多个设备时，使用并发控制提升效率：

import threading

def control_multiple_devices(device_names, action):
    threads = []
    results = []
    
    def control_single_device(name):
        try:
            dev = mijiaDevice(api, dev_name=name)
            if action == 'on':
                dev.on = True
            elif action == 'off':
                dev.on = False
            results.append(f"✅ {name} 控制成功")
        except Exception as e:
            results.append(f"❌ {name} 控制失败: {e}")
    
    for name in device_names:
        thread = threading.Thread(target=control_single_device, args=(name,))
        threads.append(thread)
        thread.start()
    
    for thread in threads:
        thread.join()
    
    return results

# 同时控制多个设备
devices = ["台灯", "空调", "加湿器"]
results = control_multiple_devices(devices, 'on')
for result in results:
    print(result)

完善的错误处理机制

在实际应用中，完善的错误处理必不可少：

import time
from mijiaAPI import DeviceNotFoundError, DeviceGetError

def robust_device_control(device_name, max_retries=3):
    """带重试机制的设备控制函数"""
    
    for attempt in range(max_retries):
        try:
            device = mijiaDevice(api, dev_name=device_name)
            
            # 检查设备状态
            if device.on:
                print(f"🎯 {device_name} 已开启")
            else:
                device.on = True
                print(f"🚀 {device_name} 开启成功")
            
            return True
            
        except DeviceNotFoundError:
            print(f"⚠️ 第{attempt+1}次尝试：设备 {device_name} 未找到")
            time.sleep(2)
            
        except DeviceGetError as e:
            print(f"🔧 第{attempt+1}次尝试：获取设备状态失败 - {e}")
            time.sleep(2)
    
    print(f"💥 设备 {device_name} 控制失败，已达最大重试次数")
    return False

# 使用带重试的控制函数
success = robust_device_control("卧室台灯")

批量操作性能优化

# 高效批量获取属性
device_ids = [device['did'] for device in devices[:5]]  # 限制设备数量
props_list = [{"did": did, "siid": 2, "piid": 2} for did in device_ids]
results = api.get_devices_prop(props_list)

print(f"📊 批量获取了 {len(results)} 个设备的属性")

调试与日志记录

遇到问题时，启用详细日志：

import logging

# 启用debug级别日志
logging.getLogger("mijiaAPI").setLevel(logging.DEBUG)

# 现在所有API调用都会打印详细的调试信息
api = mijiaAPI()
api.login()

🎯 最佳实践总结

通过本指南，您已经全面掌握了小米智能设备API的开发技能。在实际项目中，建议遵循以下最佳实践：

认证管理

• ✅ 使用二维码登录确保账户安全
• ✅ 合理设置认证文件存储路径
• ✅ 定期检查token有效性

性能优化

• ⚡ 使用批量操作减少API调用次数
• ⚡ 合理设置操作间隔时间
• ⚡ 实现并发控制提升效率

错误处理

• 🛡️ 实现完善的异常捕获机制
• 🛡️ 添加合理的重试逻辑
• 🛡️ 记录详细的操作日志

设备控制

• 🎮 优先使用设备名称而非设备ID
• 🎮 设置合理的属性值范围检查
• 🎮 考虑网络异常和设备离线情况

小米智能设备API为Python开发者提供了强大的智能家居控制能力，无论是简单的设备开关，还是复杂的场景自动化，都能轻松实现。现在就开始您的智能家居开发之旅，用代码打造更智能的生活环境！

【免费下载链接】mijia-api 米家API 项目地址: https://gitcode.com/gh_mirrors/mi/mijia-api