小米米家设备的API，可以使用代码直接控制米家设备。
pip install mijiaAPIgit clone https://github.com/Do1e/mijia-api.git
cd mijia-api
pip install .
# Or `pip install -e .` for editable mode或者使用 poetry：
poetry install使用实例可以参考 demos 文件夹下的示例代码，以下是基本使用说明。
mijiaLogin：登录小米账号，获取控制设备必须的 userId, ssecurity, deviceId, serviceToken 等信息。
-
QRlogin() -> dict：扫描二维码登录（推荐）- 在支持 tty 的终端直接显示二维码
- 或在当前目录查看生成的
qr.png文件
-
login(username: str, password: str) -> dict：账号密码登录- 注意：此方法大概率需要手机验证码验证，建议优先使用二维码登录
mijiaAPI：核心API实现，使用 mijiaLogin 登录后返回的信息进行初始化。
-
__init__(auth_data: dict)：初始化 API 对象auth_data必须包含userId,deviceId,ssecurity,serviceToken四个字段
-
available -> bool：检查传入的auth_data是否有效，根据auth_data中的expireTime字段判断
get_devices_list() -> list：获取设备列表get_homes_list() -> list：获取家庭列表（包含房间信息）get_scenes_list(home_id: str) -> list：获取手动场景列表- 在米家 App 中通过 米家→添加→手动控制 设置
run_scene(scene_id: str) -> bool：运行指定场景get_consumable_items(home_id: str) -> list：获取设备的耗材信息get_devices_prop(data: list) -> list：获取设备属性set_devices_prop(data: list) -> list：设置设备属性run_action(data: dict) -> dict：执行设备的特定动作
设备属性和动作的相关参数（siid, piid, aiid）可以从 米家产品库 查询：
- 访问
https://home.miot-spec.com/spec/{model}（model在设备列表中获取） - 例如：米家台灯 1S
注意：并非所有米家产品库中列出的方法都可用，需要自行测试验证。
使用 get_device_info() 函数可从米家规格平台在线获取设备属性字典：
from mijiaAPI import get_device_info
# 获取设备规格信息
device_info = get_device_info('yeelink.light.lamp4') # 米家台灯 1S 的 model详细示例：demos/test_get_device_info.py
mijiaDevices：基于 mijiaAPI 的高级封装，提供更简便的设备控制方式。
mijiaDevices(api: mijia
8000
API, dev_info: dict = None, dev_name: str = None, did: str = None, sleep_time: float = 0.5)api：已初始化的mijiaAPI对象dev_info：设备属性字典（可选）- 可通过
get_device_info()函数获取 - 注意：如果提供了
dev_info，则不需要提供dev_name
- 可通过
dev_name：设备名称，用于自动查找设备（可选）- 例如：
dev_name='台灯'，会自动查找名称包含“台灯”的设备 - 注意：如果提供了
dev_name，则不需要提供dev_info和did
- 例如：
did：设备ID，便于直接通过属性名访问（可选）- 如果初始化时未提供，无法使用属性样式访问，需要使用
get()和set()方法指定did - 使用
dev_name初始化时，did会自动获取
- 如果初始化时未提供，无法使用属性样式访问，需要使用
sleep_time：属性操作间隔时间，单位秒（默认0.5秒）- 重要：设置属性后立即获取可能不符合预期，需设置适当延迟
set(name: str, did: str, value: Union[bool, int]) -> bool：设置设备属性get(name: str, did: str) -> Union[bool, int, float, str]：获取设备属性run_action(name: str, did: str = None, value: Any = None, **kwargs) -> bool：执行设备动作
需在初始化时提供 did 或者使用 dev_name 初始化
# 示例：控制台灯
device = mijiaDevices(api, dev_name='台灯')
device.on = True # 打开灯
device.brightness = 60 # 设置亮度
current_temp = device.color_temperature # 获取色温属性名规则：使用下划线替代连字符（如 color-temperature 变为 color_temperature）
- 使用自然语言让小爱音箱执行：demos/test_devices_wifispeaker.py
- 通过属性直接控制台灯：demos/test_devices_v2_light.py
mijiaAPI 还提供了一个命令行工具，可以直接在终端中使用。
> python -m mijiaAPI --help
> mijiaAPI --help
usage: mijiaAPI [-h] [-p AUTH_PATH] [-l] [--list_homes] [--list_scenes] [--list_consumable_items]
[--run_scene SCENE_ID/SCENE_NAME [SCENE_ID/SCENE_NAME ...]] [--get_device_info DEVICE_MODEL] [--run PROMPT]
[--wifispeaker_name WIFISPEAKER_NAME] [--quiet]
{get,set} ...
Mijia API CLI
positional arguments:
{get,set}
get 获取设备属性
set 设置设备属性
options:
-h, --help show this help message and exit
-p AUTH_PATH, --auth_path AUTH_PATH
认证文件保存路径，默认保存在~/.config/mijia-api-auth.json
-l, --list_devices 列出所有米家设备
--list_homes 列出家庭列表
--list_scenes 列出场景列表
--list_consumable_items
列出耗材列表
--run_scene SCENE_ID/SCENE_NAME [SCENE_ID/SCENE_NAME ...]
运行场景，指定场景ID或名称
--get_device_info DEVICE_MODEL
获取设备信息，指定设备model，先使用 --list_devices 获取
--run PROMPT 使用自然语言描述你的需求，如果你有小爱音箱的话
--wifispeaker_name WIFISPEAKER_NAME
指定小爱音箱名称，默认是获取到的第一个小爱音箱
--quiet 小爱音箱静默执行
> python -m mijiaAPI get --help
> mijiaAPI get --help
usage: __main__.py get [-h] [-p AUTH_PATH] --dev_name DEV_NAME --prop_name PROP_NAME
options:
-h, --help show this help message and exit
-p AUTH_PATH, --auth_path AUTH_PATH
认证文件保存路径，默认保存在~/.config/mijia-api-auth.json
--dev_name DEV_NAME 设备名称，指定为米家APP中设定的名称
--prop_name PROP_NAME
属性名称，先使用 --get_device_info 获取
> python -m mijiaAPI set --help
> mijiaAPI set --help
usage: __main__.py set [-h] [-p AUTH_PATH] --dev_name DEV_NAME --prop_name PROP_NAME --value VALUE
options:
-h, --help show this help message and exit
-p AUTH_PATH, --auth_path AUTH_PATH
认证文件保存路径，默认保存在~/.config/mijia-api-auth.json
--dev_name DEV_NAME 设备名称，指定为米家APP中设定的名称
--prop_name PROP_NAME
属性名称，先使用 --get_device_info 获取
--value VALUE 需要设定的属性值
或者直接使用uvx忽略安装步骤：
uvx mijiaAPI --helpmijiaAPI -l # 列出所有米家设备
mijiaAPI --list_homes # 列出家庭列表
mijiaAPI --list_scenes # 列出场景列表
mijiaAPI --list_consumable_items # 列出耗材列表
mijiaAPI --run_scene SCENE_ID/SCENE_NAME # 运行场景，指定场景ID或名称
mijiaAPI --get_device_info DEVICE_MODEL # 获取设备信息，指定设备model，先使用 --list_devices 获取
mijiaAPI get --dev_name DEV_NAME --prop_name PROP_NAME # 获取设备属性
mijiaAPI set --dev_name DEV_NAME --prop_name PROP_NAME --value VALUE # 设置设备属性
mijiaAPI --run 明天天气如何
mijiaAPI --run 打开台灯并将亮度调至最大 --quiet本项目采用 GPL-3.0 开源许可证。
- 本项目仅供学习交流使用，不得用于商业用途，如有侵权请联系删除
- 用户使用本项目所产生的任何后果，需自行承担风险
- 开发者不对使用本项目产生的任何直接或间接损失负责