mijiaAPI 1.3.14__tar.gz → 1.4.0__tar.gz

{mijiaapi-1.3.14 → mijiaapi-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: mijiaAPI
-Version: 1.3.14
+Version: 1.4.0
 Summary: A Python API for Xiaomi Mijia
 License: GPLv3
 Author: Do1e
@@ -100,6 +100,19 @@ poetry install
 
 **注意**：并非所有米家产品库中列出的方法都可用，需要自行测试验证。
 
+### 设备信息获取
+
+使用 `get_device_info()` 函数可从米家规格平台在线获取设备属性字典：
+
+```python
+from mijiaAPI import get_device_info
+
+# 获取设备规格信息
+device_info = get_device_info('yeelink.light.lamp4')  # 米家台灯 1S 的 model
+```
+
+详细示例：[demos/test_get_device_info.py](demos/test_get_device_info.py)
+
 ### 设备控制封装
 
 `mijiaDevices`：基于 `mijiaAPI` 的高级封装，提供更简便的设备控制方式。
@@ -112,8 +125,14 @@ mijiaDevices(api: mijiaAPI, dev_info: dict = None, dev_name: str = None, did: st
 
 * `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秒）
   - **重要**：设置属性后立即获取可能不符合预期，需设置适当延迟
 
@@ -142,19 +161,66 @@ current_temp = device.color_temperature  # 获取色温
 * 使用自然语言让小爱音箱执行：[demos/test_devices_wifispeaker.py](demos/test_devices_wifispeaker.py)
 * 通过属性直接控制台灯：[demos/test_devices_v2_light.py](demos/test_devices_v2_light.py)
 
-### 设备信息获取
+### Mijia API CLI
+`mijiaAPI` 还提供了一个命令行工具，可以直接在终端中使用。
 
-使用 `get_device_info()` 函数可从米家规格平台在线获取设备属性字典：
-
-```python
-from mijiaAPI import get_device_info
-
-# 获取设备规格信息
-device_info = get_device_info('yeelink.light.lamp4')  # 米家台灯 1S 的 model
+```
+> python -m mijiaAPI --help
+> mijiaAPI --help
+usage: __main__.py [-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]
+                   {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 获取
 ```
 
-详细示例：[demos/test_get_device_info.py](demos/test_get_device_info.py)
+```
+> 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         需要设定的属性值
+```
 
 ## 致谢
 

{mijiaapi-1.3.14 → mijiaapi-1.4.0}/README.md

@@ -76,6 +76,19 @@ poetry install
 
 **注意**：并非所有米家产品库中列出的方法都可用，需要自行测试验证。
 
+### 设备信息获取
+
+使用 `get_device_info()` 函数可从米家规格平台在线获取设备属性字典：
+
+```python
+from mijiaAPI import get_device_info
+
+# 获取设备规格信息
+device_info = get_device_info('yeelink.light.lamp4')  # 米家台灯 1S 的 model
+```
+
+详细示例：[demos/test_get_device_info.py](demos/test_get_device_info.py)
+
 ### 设备控制封装
 
 `mijiaDevices`：基于 `mijiaAPI` 的高级封装，提供更简便的设备控制方式。
@@ -88,8 +101,14 @@ mijiaDevices(api: mijiaAPI, dev_info: dict = None, dev_name: str = None, did: st
 
 * `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秒）
   - **重要**：设置属性后立即获取可能不符合预期，需设置适当延迟
 
@@ -118,19 +137,66 @@ current_temp = device.color_temperature  # 获取色温
 * 使用自然语言让小爱音箱执行：[demos/test_devices_wifispeaker.py](demos/test_devices_wifispeaker.py)
 * 通过属性直接控制台灯：[demos/test_devices_v2_light.py](demos/test_devices_v2_light.py)
 
-### 设备信息获取
+### Mijia API CLI
+`mijiaAPI` 还提供了一个命令行工具，可以直接在终端中使用。
 
-使用 `get_device_info()` 函数可从米家规格平台在线获取设备属性字典：
-
-```python
-from mijiaAPI import get_device_info
-
-# 获取设备规格信息
-device_info = get_device_info('yeelink.light.lamp4')  # 米家台灯 1S 的 model
+```
+> python -m mijiaAPI --help
+> mijiaAPI --help
+usage: __main__.py [-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]
+                   {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 获取
 ```
 
-详细示例：[demos/test_get_device_info.py](demos/test_get_device_info.py)
+```
+> 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         需要设定的属性值
+```
 
 ## 致谢
 

mijiaapi-1.4.0/mijiaAPI/__main__.py

@@ -0,0 +1,286 @@
+from typing import Optional
+import argparse
+import json
+import os
+import sys
+import time
+
+from .apis import mijiaAPI
+from .devices import mijiaDevices, get_device_info
+from .login import mijiaLogin
+
+def parse_args(args):
+    parser = argparse.ArgumentParser(description="Mijia API CLI")
+    subparsers = parser.add_subparsers(dest='command')
+    parser.add_argument(
+        '-p', '--auth_path',
+        type=str,
+        default=os.path.join(os.path.expanduser("~"), ".config", "mijia-api-auth.json"),
+        help="认证文件保存路径，默认保存在~/.config/mijia-api-auth.json",
+    )
+    parser.add_argument(
+        '-l', '--list_devices',
+        action='store_true',
+        help="列出所有米家设备",
+    )
+    parser.add_argument(
+        '--list_homes',
+        action='store_true',
+        help="列出家庭列表",
+    )
+    parser.add_argument(
+        '--list_scenes',
+        action='store_true',
+        help="列出场景列表",
+    )
+    parser.add_argument(
+        '--list_consumable_items',
+        action='store_true',
+        help="列出耗材列表",
+    )
+    parser.add_argument(
+        '--run_scene',
+        type=str,
+        help="运行场景，指定场景ID或名称",
+        nargs='+',
+        metavar='SCENE_ID/SCENE_NAME',
+    )
+    parser.add_argument(
+        '--get_device_info',
+        type=str,
+        help="获取设备信息，指定设备model，先使用 --list_devices 获取",
+        metavar='DEVICE_MODEL',
+    )
+
+    get = subparsers.add_parser(
+        'get',
+        help="获取设备属性",
+    )
+    get.set_defaults(func='get')
+    get.add_argument(
+        '-p', '--auth_path',
+        type=str,
+        default=os.path.join(os.path.expanduser("~"), ".config", "mijia-api-auth.json"),
+        help="认证文件保存路径，默认保存在~/.config/mijia-api-auth.json",
+    )
+    get.add_argument(
+        '--dev_name',
+        type=str,
+        help="设备名称，指定为米家APP中设定的名称",
+        required=True,
+    )
+    get.add_argument(
+        '--prop_name',
+        type=str,
+        help="属性名称，先使用 --get_device_info 获取",
+        required=True,
+    )
+
+    set = subparsers.add_parser(
+        'set',
+        help="设置设备属性",
+    )
+    set.set_defaults(func='set')
+    set.add_argument(
+        '-p', '--auth_path',
+        type=str,
+        default=os.path.join(os.path.expanduser("~"), ".config", "mijia-api-auth.json"),
+        help="认证文件保存路径，默认保存在~/.config/mijia-api-auth.json",
+    )
+    set.add_argument(
+        '--dev_name',
+        type=str,
+        help="设备名称，指定为米家APP中设定的名称",
+        required=True,
+    )
+    set.add_argument(
+        '--prop_name',
+        type=str,
+        help="属性名称，先使用 --get_device_info 获取",
+        required=True,
+    )
+    set.add_argument(
+        '--value',
+        type=str,
+        help="需要设定的属性值",
+        required=True,
+    )
+    return parser.parse_args(args)
+
+def init_api(auth_path: str) -> mijiaAPI:
+    if os.path.isdir(auth_path):
+        auth_path = os.path.join(auth_path, "mijia-api-auth.json")
+    if os.path.exists(auth_path):
+        try:
+            with open(auth_path, 'r') as f:
+                auth = json.load(f)
+            api = mijiaAPI(auth_data=auth)
+            if not api.available:
+                raise ValueError("Saved auth is no longer valid")
+        except (json.JSONDecodeError, ValueError):
+            api = mijiaLogin(save_path=auth_path)
+            auth = api.QRlogin()
+            api = mijiaAPI(auth_data=auth)
+    else:
+        api = mijiaLogin(save_path=auth_path)
+        auth = api.QRlogin()
+        api = mijiaAPI(auth_data=auth)
+    return api
+
+def get_devices_list(api: mijiaAPI, verbose: bool = True) -> dict:
+    devices = api.get_devices_list()
+    if 'list' in devices:
+        devices = devices['list']
+    else:
+        devices = []
+    if verbose:
+        print("Devices:")
+        for device in devices:
+            print(f"  - {device['name']}\n"
+                    f"    did: {device['did']}\n"
+                    f"    model: {device['model']}\n"
+                    f"    online: {device['isOnline']}")
+    device_mapping = {device['did']: device for device in devices}
+    return device_mapping
+
+def get_homes_list(api: mijiaAPI, verbose: bool = True, device_mapping: Optional[dict] = None) -> dict:
+    if verbose:
+        if device_mapping is None:
+            device_mapping = get_devices_list(api, verbose=False)
+    homes = api.get_homes_list()
+    if 'homelist' in homes:
+        homes = homes['homelist']
+    else:
+        homes = []
+    if verbose:
+        print("Homes:")
+        for home in homes:
+            print(f"  - {home['name']}\n"
+                f"    id: {home['id']}\n"
+                f"    address: {home['address']}\n"
+                f"    room count: {len(home['roomlist'])}\n"
+                f"    create time: {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(home['create_time']))}")
+            print("    Rooms:")
+            for room in home['roomlist']:
+                devices_name = []
+                if room['dids']:
+                    for did in room['dids']:
+                        if did in device_mapping:
+                            devices_name.append(device_mapping[did]['name'])
+                        else:
+                            devices_name.append(did)
+                dids = ', '.join(devices_name)
+                print(f"    - {room['name']}\n"
+                      f"      id: {room['id']}\n"
+                      f"      dids: {dids}\n"
+                      f"      create time: {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(room['create_time']))}")
+    home_mapping = {home['id']: home for home in homes}
+    return home_mapping
+
+def get_scenes_list(api: mijiaAPI, verbose: bool = True, home_mapping: Optional[dict] = None) -> dict:
+    if home_mapping is None:
+        home_mapping = get_homes_list(api, verbose=False)
+    scene_mapping = {}
+    for home_id, home in home_mapping.items():
+        scenes = api.get_scenes_list(home_id)
+        if 'scene_info_list' in scenes:
+            scenes = scenes['scene_info_list']
+        else:
+            scenes = []
+        if scenes and verbose:
+            print(f"Scenes in {home['name']} ({home_id}):")
+            for scene in scenes:
+                print(f"  - {scene['name']}\n"
+                      f"    id: {scene['scene_id']}\n"
+                      f"    create time: {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(int(scene['create_time'])))}\n"
+                      f"    update time: {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(int(scene['update_time'])))}")
+        scene_mapping.update({scene['scene_id']: scene for scene in scenes})
+    return scene_mapping
+
+def get_consumable_items(api: mijiaAPI, home_mapping: Optional[dict] = None):
+    if home_mapping is None:
+        home_mapping = get_homes_list(api, verbose=False)
+    for home_id, home in home_mapping.items():
+        items = api.get_consumable_items(home_id)
+        if 'items' in items:
+            items = items['items'][0]['consumes_data']
+        else:
+            items = []
+        print(f"Consumable items in {home['name']} ({home_id}):")
+        for item in items:
+            print(f"  - {item['details'][0]['description']} in {item['name']}({item['did']})\n"
+                  f"    value: {item['details'][0]['value']}")
+
+def run_scene(api: mijiaAPI, scene_id: str, scene_mapping: Optional[dict] = None) -> bool:
+    if scene_mapping is None:
+        scene_mapping = get_scenes_list(api, verbose=False)
+    if scene_id not in scene_mapping:
+        scene_name_to_find = scene_id
+        found = False
+        for sid, scene in scene_mapping.items():
+            if scene['name'] == scene_name_to_find:
+                scene_id = sid
+                found = True
+                break
+        if not found:
+            print(f"Scene {scene_name_to_find} not found")
+            return False
+    scene_name = scene_mapping[scene_id]['name']
+    ret = api.run_scene(scene_id)
+    if ret:
+        print(f"Scene {scene_name}({scene_id}) run successfully")
+        return True
+    else:
+        print(f"Failed to run scene {scene_name}({scene_id})")
+        return False
+
+def get(args):
+    api = init_api(args.auth_path)
+    device = mijiaDevices(api, dev_name=args.dev_name)
+    value = device.get(args.prop_name)
+    unit = device.prop_list[args.prop_name].unit
+    print(f"The {args.prop_name} of {args.dev_name} is {value} {unit if unit else ''}")
+
+def set(args):
+    api = init_api(args.auth_path)
+    device = mijiaDevices(api, dev_name=args.dev_name)
+    ret = device.set_v2(args.prop_name, args.value)
+    unit = device.prop_list[args.prop_name].unit
+    if ret:
+        print(f"The {args.prop_name} of {args.dev_name} is set to {args.value} {unit if unit else ''}")
+    else:
+        print(f"Failed to set the {args.prop_name} of {args.dev_name} to {args.value}")
+
+
+def main(args):
+    args = parse_args(args)
+    api = init_api(args.auth_path)
+    device_mapping = None
+    home_mapping = None
+    scenes_mapping = None
+
+    if args.list_devices:
+        device_mapping = get_devices_list(api)
+    if args.list_homes:
+        home_mapping = get_homes_list(api, device_mapping=device_mapping)
+    if args.list_scenes:
+        scenes_mapping = get_scenes_list(api, home_mapping=home_mapping)
+    if args.list_consumable_items:
+        get_consumable_items(api, home_mapping=home_mapping)
+    if args.run_scene:
+        for scene_id in args.run_scene:
+            run_scene(api, scene_id, scene_mapping=scenes_mapping)
+    if args.get_device_info:
+        device_info = get_device_info(args.get_device_info)
+        print(json.dumps(device_info, indent=2, ensure_ascii=False))
+    if hasattr(args, 'func') and args.func is not None:
+        if args.func == 'get':
+            get(args)
+        if args.func == 'set':
+            set(args)
+
+def cli():
+    main(sys.argv[1:])
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

{mijiaapi-1.3.14 → mijiaapi-1.4.0}/mijiaAPI/devices.py

@@ -174,7 +174,23 @@ class mijiaDevices(object):
             if value not in [item['value'] for item in prop.value_list]:
                 raise ValueError(f'Invalid value: {value}, should be in {prop.value_list}')
         if prop.type == 'bool':
-            if not isinstance(value, bool):
+            if isinstance(value, str):
+                if value.lower() == 'true':
+                    value = True
+                elif value.lower() == 'false':
+                    value = False
+                elif value in ['0', '1']:
+                    value = bool(int(value))
+                else:
+                    raise ValueError(f'Invalid value for bool: {value}, should be True or False')
+            elif isinstance(value, int):
+                if value == 0:
+                    value = False
+                elif value == 1:
+                    value = True
+                else:
+                    raise ValueError(f'Invalid value for bool: {value}, should be True or False')
+            elif not isinstance(value, bool):
                 raise ValueError(f'Invalid value for bool: {value}, should be True or False')
         elif prop.type in ['int', 'uint']:
             value = int(value)

{mijiaapi-1.3.14 → mijiaapi-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mijiaAPI"
-version = "1.3.14"
+version = "1.4.0"
 description = "A Python API for Xiaomi Mijia"
 readme = "README.md"
 requires-python = ">=3.9,<4.0"
@@ -10,9 +10,12 @@ dependencies = [
     "requests>=2.32.3,<3.0.0",
 ]
 
+[project.scripts]
+mijiaAPI = "mijiaAPI.__main__:cli"
+
 [tool.poetry]
 name = "mijiaAPI"
-version = "1.3.14"
+version = "1.4.0"
 description = "A Python API for Xiaomi Mijia"
 authors = ["Do1e <dpj.email@qq.com>"]
 license = "GPLv3"
@@ -34,6 +37,9 @@ requests = "^2.32.3"
 qrcode = "^8.0"
 pillow = "^11.0.0"
 
+[tool.poetry.scripts]
+mijiaAPI = "mijiaAPI.__main__:cli"
+
 [tool.poetry-dynamic-versioning]
 enable = false