Python控制米家智能家居终极指南：3步实现全屋自动化编程
【免费下载链接】mijia-api米家API，使用Python控制米家设备项目地址: https://gitcode.com/gh_mirrors/mi/mijia-api
米家API（mijiaAPI）是一个功能强大的Python库，专为开发者提供控制小米智能家居设备的完整解决方案。通过简洁的代码接口，您可以轻松实现设备状态监控、属性设置和自动化控制，为智能家居爱好者提供完整的开发工具链。无论您是Python开发者、智能家居爱好者还是自动化系统集成者，这个开源项目都能帮助您快速构建专业的智能家居控制应用。
🤔 为什么需要编程控制米家设备？
传统的小米米家APP虽然功能完善，但缺乏灵活性和扩展性。当您需要批量控制多个设备、创建定时任务、与其他智能系统集成、实现自定义联动逻辑或进行数据分析时，编程控制就显得尤为重要。
实际应用场景分析
- 家庭自动化- 根据时间、天气或传感器数据自动调节灯光、空调
- 能耗管理- 监控设备用电量，优化能源使用
- 安全监控- 创建自定义安防规则和报警系统
- 数据收集- 长期记录设备状态，分析使用习惯
- 远程控制- 通过Web界面或API控制家中设备
🚀 快速入门：3步搭建开发环境
安装方式选择
根据您的开发需求，选择合适的安装方式：
标准安装（推荐）
pip install mijiaAPI源码安装（适合开发者）
git clone https://gitcode.com/gh_mirrors/mi/mijia-api cd mijia-api pip install .现代包管理器
uv add mijiaAPI认证配置实战
首次使用需要进行身份验证，这是控制设备的第一步：
from mijiaAPI import mijiaAPI # 初始化API实例，认证文件将自动保存 api = mijiaAPI() # 扫码登录 - 这是获取设备访问权限的关键步骤 api.login()登录过程会在终端显示二维码，使用米家APP扫描即可完成认证。认证数据默认保存在~/.config/mijia-api/auth.json，后续使用无需重复登录。
🔍 智能设备发现与管理系统
家庭和设备组织结构
米家设备按照家庭进行组织，了解这一结构对高效管理至关重要：
# 获取家庭列表 - 了解您的智能家居布局 homes = api.get_homes_list() print(f"发现 {len(homes)} 个家庭") # 获取所有设备（不包含共享设备） devices = api.get_devices_list() for device in devices: print(f"📱 设备: {device['name']}, 型号: {device['model']}, ID: {device['did']}") # 获取指定家庭的设备 home_id = homes[0]['id'] devices_in_home = api.get_devices_list(home_id=home_id) # 获取共享设备列表 shared_devices = api.get_shared_devices_list()设备规格信息查询
每个米家设备都有详细的规格定义，了解这些规格能帮助您更好地控制设备：
from mijiaAPI import get_device_info # 查询设备技术规格 - 了解设备支持的功能 lamp_info = get_device_info('yeelink.light.lamp4') print(f"设备规格: {lamp_info}")💡 高级设备控制编程技巧
面向对象设备操作模型
mijiaDevice类提供了直观的设备控制接口，让操作变得简单直观：
from mijiaAPI import mijiaAPI, mijiaDevice # 创建API连接 api = mijiaAPI() api.login() # 通过设备名称初始化 - 更人性化的方式 lamp = mijiaDevice(api, dev_name='智能台灯') # 属性式操作控制 - 像操作普通对象一样简单 lamp.on = True # 开启设备 lamp.brightness = 75 # 设置亮度级别 lamp.color_temperature = 4500 # 调整色温参数 # 获取当前状态 current_brightness = lamp.brightness print(f"当前亮度: {current_brightness}%")批量操作性能优化
对于多设备控制场景，批量操作能显著提高效率：
# 高效批量属性获取 - 减少网络请求次数 properties = [ {"did": "device1", "siid": 2, "piid": 2}, {"did": "device2", "siid": 2, "piid": 2}, {"did": "device3", "siid": 2, "piid": 2} ] results = api.get_devices_prop(properties) # 批量设置属性 set_operations = [ {"did": "device1", "siid": 2, "piid": 2, "value": 50}, {"did": "device2", "siid": 2, "piid": 2, "value": 60} ] api.set_devices_prop(set_operations)⚙️ 场景联动与自动化控制
智能场景管理系统
米家API支持复杂的场景联动控制，实现真正的自动化：
# 获取场景配置信息 scenes = api.get_scenes_list() print(f"可用场景: {[scene['name'] for scene in scenes]}") # 执行预设场景 - 一键切换家居模式 api.run_scene(scene_id="sleep_mode", home_id="living_room") # 多场景同时执行 api.run_scene(scene_id=["welcome_home", "lights_on"], home_id="main_home")耗材状态智能监控
对于需要定期更换耗材的设备，提供状态跟踪和提醒功能：
# 监控耗材使用情况 - 及时更换滤芯、灯泡等 consumables = api.get_consumable_items() for item in consumables: remaining_percent = item.get('left', 0) item_name = item.get('name', '未知耗材') if remaining_percent < 20: print(f"⚠️ {item_name}: 剩余 {remaining_percent}%，建议更换！") else: print(f"✅ {item_name}: 剩余 {remaining_percent}%")📊 设备数据分析与统计
能耗数据收集与分析
了解设备能耗模式，优化用电习惯：
import time from datetime import datetime, timedelta # 获取设备统计数据（如耗电量） end_time = int(time.time()) start_time = int(time.time() - 30*24*3600) # 过去30天 result = api.get_statistics({ "did": "device_did", "key": "7.1", # siid.piid "data_type": "stat_month_v3", # 统计类型：stat_hour_v3, stat_day_v3, stat_week_v3, stat_month_v3 "limit": 6, # 返回的最大条目数 "time_start": start_time, "time_end": end_time, }) # 分析能耗数据 total_consumption = sum(item['value'] for item in result) print(f"30天总耗电量: {total_consumption} kWh") print(f"日均耗电量: {total_consumption / 30:.2f} kWh")🔧 命令行工具快速操作
终端直接控制功能
无需编写Python代码，通过命令行即可完成设备控制：
# 设备发现与信息展示 mijiaAPI --list_devices # 属性查询操作 mijiaAPI get --dev_name "卧室台灯" --prop_name "brightness" # 属性设置命令 mijiaAPI set --dev_name "卧室台灯" --prop_name "on" --value True自然语言交互支持
集成小爱音箱的自然语言处理能力，实现语音控制：
# 语音指令执行 - 最自然的交互方式 mijiaAPI --run "打开客厅所有灯光" # 指定音箱设备执行命令 mijiaAPI --run "播放轻音乐" --wifispeaker_name "客厅小爱" # 静默执行，不播放语音反馈 mijiaAPI --run "关闭所有灯" --quiet🛡️ 错误处理与调试技巧
异常捕获与处理机制
完善的错误处理确保程序稳定运行：
from mijiaAPI import ( LoginError, DeviceNotFoundError, DeviceGetError, DeviceSetError, DeviceActionError, APIError ) try: # 设备操作尝试 device = mijiaDevice(api, dev_name="智能台灯") device.brightness = 80 except DeviceNotFoundError as e: print(f"❌ 设备未找到: {e}") # 提示用户检查设备名称或重新扫描 except DeviceSetError as e: print(f"⚠️ 属性设置失败: {e}") # 检查属性值是否在有效范围内 except APIError as e: print(f"🔧 API调用失败: {e}") # 检查网络连接或重新登录日志调试与性能监控
启用详细日志记录辅助开发调试：
import logging # 配置不同级别的日志 logger = logging.getLogger("mijiaAPI") # 开发阶段使用DEBUG级别 logger.setLevel(logging.DEBUG) # 生产环境使用INFO级别 # logger.setLevel(logging.INFO) # 添加控制台处理器 handler = logging.StreamHandler() handler.setFormatter(logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')) logger.addHandler(handler) # 现在所有API调用都会记录详细日志 api = mijiaAPI() api.login()🚀 性能优化与最佳实践
响应时间优化策略
针对不同设备特性调整操作间隔：
# 设置适当的等待时间 - 针对响应较慢的设备 device = mijiaDevice(api, dev_name="我的设备", sleep_time=1.0) # 批量操作时减少等待时间 fast_device = mijiaDevice(api, dev_name="快速设备", sleep_time=0.2)认证数据安全管理
合理配置认证文件存储位置，确保数据安全：
from pathlib import Path import os # 方案1：保存在项目目录（适合开发环境） auth_path = Path(__file__).parent / ".mijia-api" / "auth.json" api = mijiaAPI(str(auth_path)) # 方案2：使用环境变量指定路径（适合生产环境） auth_env_path = os.getenv('MIJIA_AUTH_PATH', '~/.config/mijia-api/auth.json') api = mijiaAPI(auth_env_path) # 方案3：加密存储认证信息（高级安全需求） # 可以使用加密库对auth.json进行加密存储并发控制与资源管理
处理大量设备时的优化策略：
import concurrent.futures from mijiaAPI import mijiaAPI class DeviceManager: def __init__(self, max_workers=5): self.api = mijiaAPI() self.api.login() self.executor = concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) def batch_control(self, device_names, action, value=None): """批量控制多个设备""" futures = [] for name in device_names: future = self.executor.submit(self._control_single_device, name, action, value) futures.append(future) # 等待所有任务完成 results = [] for future in concurrent.futures.as_completed(futures): try: results.append(future.result()) except Exception as e: print(f"设备控制失败: {e}") return results def _control_single_device(self, device_name, action, value): """控制单个设备""" device = mijiaDevice(self.api, dev_name=device_name) if action == 'get': return device.get('on') elif action == 'set': device.set('on', value) return True def __del__(self): self.executor.shutdown() # 使用示例 manager = DeviceManager() devices = ["卧室灯", "客厅灯", "厨房灯"] manager.batch_control(devices, 'set', True)📁 项目结构与模块解析
核心模块功能说明
了解项目结构有助于深度定制和问题排查：
- mijiaAPI/apis.py- API核心接口实现
- mijiaAPI/devices.py- 设备类封装和高级控制
- mijiaAPI/errors.py- 异常处理和错误类型定义
- mijiaAPI/logger.py- 日志系统配置
- mijiaAPI/miutils.py- 工具函数和辅助方法
- demos/- 示例代码和测试脚本
扩展开发指南
如果您需要扩展功能或定制开发：
# 自定义设备控制类 from mijiaAPI import mijiaDevice class CustomDevice(mijiaDevice): def __init__(self, api, dev_name=None, did=None, sleep_time=0.5): super().__init__(api, dev_name, did, sleep_time) def custom_method(self): """添加自定义方法""" # 实现您的自定义逻辑 pass def get_status_summary(self): """获取设备状态摘要""" status = {} for prop_name in self.prop_list: try: value = self.get(prop_name) status[prop_name] = value except Exception: continue return status # 使用自定义类 api = mijiaAPI() api.login() custom_device = CustomDevice(api, dev_name="智能台灯") summary = custom_device.get_status_summary()🔮 未来发展与社区贡献
常见问题解决方案
Q: 登录失败怎么办？A: 确保网络正常，米家APP已登录相同账号，尝试重新扫码登录
Q: 设备无法控制？A: 检查设备是否在线，确认设备名称是否正确，查看日志获取详细信息
Q: 如何批量控制多个设备？A: 使用批量API调用或创建设备管理类进行统一控制
Q: 性能优化建议？A: 减少不必要的API调用，使用批量操作，适当调整sleep_time参数
贡献与反馈
米家API是一个开源项目，欢迎社区贡献：
- 报告问题- 在项目仓库提交Issue
- 贡献代码- 提交Pull Request改进功能
- 分享用例- 分享您的智能家居自动化方案
- 文档改进- 帮助完善文档和示例
通过Python控制米家设备，您将获得前所未有的灵活性和控制力。无论是简单的定时开关，还是复杂的场景联动，米家API都能为您提供强大的技术支持。开始您的智能家居编程之旅，打造真正个性化的智能生活体验！
【免费下载链接】mijia-api米家API，使用Python控制米家设备项目地址: https://gitcode.com/gh_mirrors/mi/mijia-api
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
：C++ 11)