解锁米家智能设备控制新维度：用Python构建个性化智能家居系统

您是否曾想过用代码掌控家中的智能设备？是否渴望突破官方APP的功能限制，打造真正符合个人习惯的智能生活体验？米家API（mijia-api）正是为解决这些需求而生的Python开发工具包，它让你能够通过编程直接与米家生态链设备通信，实现从简单控制到复杂自动化的全场景智能家居解决方案。

认知篇：揭开米家API的神秘面纱

什么是米家API？

米家API是一个开源的Python库（开源协议：MIT），它封装了小米智能设备通信协议，提供简洁易用的编程接口，让开发者无需深入了解底层网络通信细节，就能轻松实现对米家设备的控制。简单来说，它就像一座桥梁，连接你的Python代码与家中的智能设备。

为什么选择编程控制智能家居？

想象这样的场景：当你下班回家，不需要掏出手机操作APP，系统会根据你的位置、时间和天气自动调节室内温度、开启灯光并播放喜欢的音乐。这种个性化体验正是编程控制智能家居的核心优势：

• 打破APP限制：实现官方应用不支持的自定义功能
• 深度场景联动：跨设备、跨平台的复杂自动化逻辑
• 数据驱动决策：基于设备运行数据优化使用体验
• 无限扩展可能：结合其他服务打造完整智能生态

支持哪些设备类型？

米家API支持米家生态链中的大部分智能设备，包括但不限于：

• 照明设备：智能灯泡、吸顶灯、灯带
• 环境控制：空调、加湿器、空气净化器
• 安防设备：智能门锁、摄像头、人体传感器
• 厨房电器：电饭煲、微波炉、扫地机器人
• 生活电器：风扇、暖气、窗帘电机

实践篇：从零开始的米家控制之旅

环境搭建全流程

开始使用米家API前，需要准备Python 3.8+环境。根据你的使用场景，选择最适合的安装方式：

快速体验（推荐新手）：

pip install mijiaAPI

开发定制（适合进阶用户）：

git clone https://gitcode.com/gh_mirrors/mi/mijia-api
cd mijia-api
pip install -e .  #  editable模式安装，便于修改源码

安装完成后，建议通过简单命令验证安装是否成功：

python -m mijiaAPI --version

身份认证安全指南

与米家设备通信前需要进行身份验证，确保只有授权用户能控制你的智能设备。米家API提供多种认证方式，其中二维码登录是最安全便捷的方式：

from mijiaAPI import mijiaAPI

# 创建API实例，指定配置文件存储路径
api = mijiaAPI(config_path="~/.mijia/config.json")

# 生成登录二维码
qr_code = api.generate_login_qr()

# 显示二维码（实际应用中可保存为图片或直接显示在GUI中）
print("请使用米家APP扫描以下二维码登录：")
print(qr_code)

# 等待用户扫描并确认
api.wait_for_login()

# 验证登录状态
if api.is_logged_in():
    print("登录成功！认证信息已保存")
else:
    print("登录失败，请重试")

安全提示：认证信息包含敏感数据，建议将配置文件设置为仅当前用户可读写（权限700）

设备发现与连接

成功登录后，下一步是发现并连接你的智能设备：

# 获取所有家庭
homes = api.get_homes()
print(f"发现{len(homes)}个家庭：")
for home in homes:
    print(f"- {home['name']} (ID: {home['id']})")

# 选择第一个家庭并获取设备列表
selected_home = homes[0]
devices = api.get_home_devices(selected_home['id'])

print(f"\n家庭「{selected_home['name']}」中的设备：")
for device in devices:
    # 设备基本信息：名称、型号、ID、在线状态
    status = "在线" if device['online'] else "离线"
    print(f"• {device['name']} ({device['model']}) - {status}")
    print(f"  设备ID: {device['did']}")

设备控制核心操作

掌握设备控制的基本操作是构建智能场景的基础。以下是最常用的控制模式：

1. 获取设备属性

# 获取指定设备的所有属性
device = devices[0]  # 选择第一个设备
properties = api.get_device_properties(device['did'])

print(f"\n设备「{device['name']}」属性：")
for prop in properties:
    # 打印属性ID、名称、当前值和单位
    print(f"- {prop['name']} ({prop['piid']}): {prop['value']} {prop.get('unit', '')}")

2. 设置设备属性

# 以智能灯泡为例，设置亮度和色温
# 首先查找亮度和色温对应的属性ID
brightness_piid = None
color_temp_piid = None

for prop in properties:
    if prop['name'] == 'brightness':
        brightness_piid = prop['piid']
    elif prop['name'] == 'color_temperature':
        color_temp_piid = prop['piid']

# 设置亮度为80%，色温为4000K
if brightness_piid and color_temp_piid:
    result = api.set_device_properties(
        device['did'],
        [
            {'piid': brightness_piid, 'value': 80},
            {'piid': color_temp_piid, 'value': 4000}
        ]
    )
    if result['code'] == 0:
        print("设备属性设置成功")
    else:
        print(f"设置失败：{result['message']}")

3. 执行设备动作

# 执行设备特定动作，如开关切换、模式切换等
# 首先获取设备支持的动作列表
actions = api.get_device_actions(device['did'])
print("\n设备支持的动作：")
for action in actions:
    print(f"- {action['name']} (aiid: {action['aiid']})")

# 以"toggle"动作为例（开关切换）
toggle_action = next((a for a in actions if a['name'] == 'toggle'), None)
if toggle_action:
    result = api.execute_device_action(
        device['did'],
        toggle_action['aiid'],
        []  # 无参数动作
    )
    print(f"执行开关切换：{'成功' if result['code'] == 0 else '失败'}")

批量设备管理技巧

当你有多个设备需要管理时，批量操作能显著提升效率：

# 批量获取多个设备的指定属性
# 构建属性请求列表：(设备ID, 服务ID, 属性ID)
property_requests = [
    (devices[0]['did'], 2, 2),  # 第一个设备的亮度
    (devices[1]['did'], 2, 2),  # 第二个设备的亮度
    (devices[0]['did'], 2, 3)   # 第一个设备的色温
]

# 批量请求
results = api.get_batch_properties(property_requests)

# 处理结果
for res in results:
    if res['code'] == 0:
        device_name = next(d['name'] for d in devices if d['did'] == res['did'])
        print(f"{device_name}: {res['value']} {res.get('unit', '')}")
    else:
        print(f"获取设备 {res['did']} 属性失败: {res['message']}")

拓展篇：构建智能生活新体验

场景联动设计思路

真正的智能家居不仅是单个设备的控制，而是多个设备的智能联动。以下是场景设计的核心思路：

1. 事件触发：确定什么情况下触发场景（时间、位置、设备状态变化等）
2. 条件判断：设置执行场景的前提条件（如"当室内温度>26℃时"）
3. 动作序列：定义需要执行的设备操作序列
4. 反馈机制：设置执行结果的通知方式

场景化应用案例

案例1：智能晨光唤醒系统

import time
from datetime import datetime, timedelta

def morning_wake_up_routine(api, bedroom_light_did, alarm_time="07:00"):
    """
    模拟自然日出唤醒场景
    - 提前30分钟开始逐渐增加灯光亮度
    - 缓慢调整色温从暖光到白光
    """
    target_time = datetime.strptime(alarm_time, "%H:%M")
    current_time = datetime.now().time()
    
    # 检查是否到达启动时间
    if not (target_time - timedelta(minutes=30)).time() <= current_time <= target_time.time():
        print("未到唤醒时间")
        return
    
    # 逐渐增加亮度 (0-100%)
    for brightness in range(1, 101, 5):
        api.set_device_properties(bedroom_light_did, [{'piid': 2, 'value': brightness}])
        # 逐渐调整色温 (2700K-5000K)
        color_temp = 2700 + int((brightness/100) * 2300)
        api.set_device_properties(bedroom_light_did, [{'piid': 3, 'value': color_temp}])
        time.sleep(18)  # 每5%亮度调整间隔18秒，总共30分钟
    
    print("晨光唤醒完成")

# 使用示例
# morning_wake_up_routine(api, "your_bedroom_light_did")

案例2：环境自适应调节系统

def auto_environment_adjustment(api, temp_sensor_did, humidifier_did, air_conditioner_did):
    """
    基于温湿度传感器自动调节加湿器和空调
    - 温度高于26℃开启空调
    - 湿度低于40%开启加湿器
    - 达到目标值后自动关闭
    """
    # 获取当前环境数据
    temp_prop = api.get_device_properties(temp_sensor_did, [{'siid': 3, 'piid': 7}])  # 温度属性
    humid_prop = api.get_device_properties(temp_sensor_did, [{'siid': 3, 'piid': 8}]) # 湿度属性
    
    current_temp = temp_prop[0]['value']
    current_humidity = humid_prop[0]['value']
    
    print(f"当前环境：温度{current_temp}℃，湿度{current_humidity}%")
    
    # 温度控制逻辑
    if current_temp > 26:
        api.set_device_properties(air_conditioner_did, [{'piid': 2, 'value': True}])  # 开空调
        api.set_device_properties(air_conditioner_did, [{'piid': 5, 'value': 24}])   # 设置24℃
    elif current_temp < 22:
        api.set_device_properties(air_conditioner_did, [{'piid': 2, 'value': False}]) # 关空调
    
    # 湿度控制逻辑
    if current_humidity < 40:
        api.set_device_properties(humidifier_did, [{'piid': 2, 'value': True}])  # 开加湿器
    elif current_humidity > 60:
        api.set_device_properties(humidifier_did, [{'piid': 2, 'value': False}]) # 关加湿器

# 使用示例
# auto_environment_adjustment(api, "temp_sensor_did", "humidifier_did", "ac_did")

案例3：离家安全监控系统

def离家安全检查(api, door_sensor_did, window_sensor_did, camera_did, alarm_did):
    """
    离家时自动检查门窗状态并启动安防系统
    - 检查所有门窗是否关闭
    - 开启摄像头监控
    - 启动安防报警
    """
    # 检查门窗状态
    door_status = api.get_device_properties(door_sensor_did, [{'siid': 2, 'piid': 1}])
    window_status = api.get_device_properties(window_sensor_did, [{'siid': 2, 'piid': 1}])
    
    # 假设1为关闭，0为打开
    if door_status[0]['value'] != 1 or window_status[0]['value'] != 1:
        print("警告：检测到未关闭的门窗！")
        # 发送通知到手机（实际应用中可集成推送服务）
        return
    
    # 启动安防系统
    api.set_device_properties(camera_did, [{'piid': 2, 'value': True}])  # 开启摄像头
    api.set_device_properties(alarm_did, [{'piid': 2, 'value': True}])   # 启动报警器
    
    print("离家安全系统已启动")

# 使用示例
#离家安全检查(api, "door_sensor_did", "window_sensor_did", "camera_did", "alarm_did")

性能优化与常见问题

提升控制响应速度的技巧

1. 批量操作合并：将多个设备的控制请求合并为一个批量请求
2. 合理设置超时：根据设备类型调整请求超时时间（网络设备通常需要更长超时）
3. 本地缓存设备信息：减少重复获取设备列表和属性的请求
4. 异步操作处理：使用异步编程模型处理多个设备的并行控制

常见错误及解决方案

错误类型	可能原因	解决方案
登录失败	网络问题或账号安全限制	检查网络连接，确保米家APP可正常登录
设备无响应	设备离线或网络不稳定	检查设备电源和网络连接，尝试重新连接
属性设置无效	属性值超出范围或设备不支持	查阅设备文档确认支持的属性值范围
频繁请求被拒绝	API调用频率过高	增加请求间隔，实现请求限流机制

未来发展与生态扩展

米家API作为开源项目，持续在以下方向发展：

• 设备支持扩展：不断增加对新设备型号的支持
• API功能增强：添加更丰富的控制接口和事件通知机制
• 第三方集成：与Home Assistant、OpenHAB等智能家居平台深度集成
• 低代码平台：开发可视化配置工具，降低使用门槛

总结：开启智能家居编程之旅

通过米家API，你已经拥有了构建个性化智能家居系统的强大工具。从简单的设备控制到复杂的场景联动，从单一功能实现到完整生态构建，这个开源项目为你打开了智能家居编程的无限可能。

无论你是想实现简单的定时开关，还是构建复杂的环境自适应系统，米家API都能满足你的需求。现在就开始探索，用代码定义你的智能生活吧！

如果你在使用过程中遇到问题或有创新想法，欢迎参与项目贡献，一起完善这个开源生态系统。