mijiaAPI 4.1.2__tar.gz → 4.2.0__tar.gz

{mijiaapi-4.1.2 → mijiaapi-4.2.0}/PKG-INFO

@@ -1,108 +1,108 @@
-Metadata-Version: 2.4
-Name: mijiaAPI
-Version: 4.1.2
-Summary: A Python API for Xiaomi Mijia
-Author-email: Do1e <i@do1e.cn>
-License-Expression: GPL-3.0-or-later
-Project-URL: Homepage, https://mijia-api.do1e.com/
-Project-URL: Repository, https://github.com/Do1e/mijia-api
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: <4.0,>=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: fastmcp>=3.4.2
-Requires-Dist: pillow>=11.3.0
-Requires-Dist: pycryptodome>=3.23.0
-Requires-Dist: qrcode>=8.2
-Requires-Dist: requests>=2.32.5
-Requires-Dist: tzlocal>=5.3.1
-Dynamic: license-file
-
-# mijiaAPI
-
-米家 API，可以使用代码、CLI、MCP 直接控制米家设备。
-
-> 🎉 **v4.0.0 版本已支持 MCP**，详见 [MCP 使用文档](https://mijia-api.do1e.com/usage/mcp)
-> 🎉 **v4.1.0 版本已支持 Agent Skill**，详见 [Agent Skill 使用文档](https://mijia-api.do1e.com/usage/skill)
-
-[![GitHub](https://img.shields.io/badge/GitHub-Do1e%2Fmijia--api-blue)](https://github.com/Do1e/mijia-api)
-[![PyPI](https://img.shields.io/badge/PyPI-mijiaAPI-blue)](https://pypi.org/project/mijiaAPI/)
-[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-green.svg)](https://opensource.org/licenses/GPL-3.0)
-
-📖 **完整文档请见 [mijia-api.do1e.com](https://mijia-api.do1e.com)**
-
-[常见问题](https://mijia-api.do1e.com/faq) | [更新日志](https://mijia-api.do1e.com/changelog)
-
-## 安装
-
-> 要求 Python >= 3.10
-
-```bash
-pip install mijiaAPI
-# Or `uv add mijiaAPI` for uv users
-```
-
-其他安装方式（源码安装、AUR）请参考[文档](https://mijia-api.do1e.com/guide/installation)。
-
-## 快速开始
-
-```python
-from mijiaAPI import mijiaAPI, mijiaDevice
-
-# 初始化并扫码登录（认证文件默认保存在 ~/.config/mijia-api/auth.json）
-api = mijiaAPI()
-api.login()
-
-# 通过设备名称控制设备（推荐）
-device = mijiaDevice(api, dev_name="我的台灯")
-device.on = True              # 打开设备
-device.brightness = 60        # 设置亮度为 60%
-
-# 查看设备支持的所有属性和动作
-print(device)
-```
-
-CLI 用法：
-
-```bash
-mijiaAPI login                          # 扫码登录
-mijiaAPI -l                             # 列出所有设备
-mijiaAPI set --dev_name "台灯" --prop_name "brightness" --value 60
-```
-
-MCP 用法：
-
-执行 `uvx mijiaAPI login -p /path/to/auth.json` 登录后，在 MCP 客户端配置中添加以下内容即可接入米家：
-
-```json
-{
-  "mcpServers": {
-    "mijia-api": {
-      "command": "uvx",
-      "args": ["mijiaAPI", "mcp", "-p", "/path/to/auth.json"]
-    }
-  }
-}
-```
-
-更多用法（API 基础调用、MCP Server、CLI 完整参数、最佳实践等）请查阅[完整文档](https://mijia-api.do1e.com)。
-
-## 致谢
-
-* [janzlan/mijia-api](https://gitee.com/janzlan/mijia-api/tree/master)
-* [米家 APP 网络请求的抓包、加解密与构造的代码笔记](https://imkero.net/posts/mihome-app-api/)
-* [al-one/hass-xiaomi-miot](https://github.com/al-one/hass-xiaomi-miot)
-
-## 开源许可
-
-本项目采用 [GPL-3.0](LICENSE) 开源许可证。
-
-**请注意：GPL-3.0 是具有“强传染性”的开源许可证。**  
-如果您在您的项目中使用、修改或分发本项目的代码（包括作为库依赖），您的整个项目也**必须**以 GPL-3.0 或兼容许可证开源发布。
-
-## 免责声明
-
-* 本项目仅供学习交流使用，不得用于商业用途，如有侵权请联系删除
-* 用户使用本项目所产生的任何后果，需自行承担风险
-* 开发者不对使用本项目产生的任何直接或间接损失负责
+Metadata-Version: 2.4
+Name: mijiaAPI
+Version: 4.2.0
+Summary: A Python API for Xiaomi Mijia
+Author-email: Do1e <i@do1e.cn>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://mijia-api.do1e.com/
+Project-URL: Repository, https://github.com/Do1e/mijia-api
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: pillow>=11.3.0
+Requires-Dist: pycryptodome>=3.23.0
+Requires-Dist: qrcode>=8.2
+Requires-Dist: requests>=2.32.5
+Requires-Dist: tzlocal>=5.3.1
+Dynamic: license-file
+
+# mijiaAPI
+
+米家 API，可以使用代码、CLI、MCP 直接控制米家设备。
+
+> 🎉 **v4.0.0 版本已支持 MCP**，详见 [MCP 使用文档](https://mijia-api.do1e.com/usage/mcp)  
+> 🎉 **v4.1.0 版本已支持 Agent Skill**，详见 [Agent Skill 使用文档](https://mijia-api.do1e.com/usage/skill)
+
+[![GitHub](https://img.shields.io/badge/GitHub-Do1e%2Fmijia--api-blue)](https://github.com/Do1e/mijia-api)
+[![PyPI](https://img.shields.io/badge/PyPI-mijiaAPI-blue)](https://pypi.org/project/mijiaAPI/)
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-green.svg)](https://opensource.org/licenses/GPL-3.0)
+
+📖 **完整文档请见 [mijia-api.do1e.com](https://mijia-api.do1e.com)**
+
+[常见问题](https://mijia-api.do1e.com/faq) | [更新日志](https://mijia-api.do1e.com/changelog)
+
+## 安装
+
+> 要求 Python >= 3.10
+
+```bash
+pip install mijiaAPI
+# Or `uv add mijiaAPI` for uv users
+```
+
+其他安装方式（源码安装、AUR）请参考[文档](https://mijia-api.do1e.com/guide/installation)。
+
+## 快速开始
+
+```python
+from mijiaAPI import mijiaAPI, mijiaDevice
+
+# 初始化并扫码登录（认证文件默认保存在 ~/.config/mijia-api/auth.json）
+api = mijiaAPI()
+api.login()
+
+# 通过设备名称控制设备（推荐）
+device = mijiaDevice(api, dev_name="我的台灯")
+device.on = True              # 打开设备
+device.brightness = 60        # 设置亮度为 60%
+
+# 查看设备支持的所有属性和动作
+print(device)
+```
+
+CLI 用法：
+
+```bash
+mijiaAPI login                          # 扫码登录
+mijiaAPI -l                             # 列出所有设备
+mijiaAPI set --dev_name "台灯" --prop_name "brightness" --value 60
+```
+
+MCP 用法：
+
+执行 `uvx mijiaAPI login -p /path/to/auth.json` 登录后，在 MCP 客户端配置中添加以下内容即可接入米家：
+
+```json
+{
+  "mcpServers": {
+    "mijia-api": {
+      "command": "uvx",
+      "args": ["mijiaAPI", "mcp", "-p", "/path/to/auth.json"]
+    }
+  }
+}
+```
+
+更多用法（API 基础调用、MCP Server、CLI 完整参数、最佳实践等）请查阅[完整文档](https://mijia-api.do1e.com)。
+
+## 致谢
+
+* [janzlan/mijia-api](https://gitee.com/janzlan/mijia-api/tree/master)
+* [米家 APP 网络请求的抓包、加解密与构造的代码笔记](https://imkero.net/posts/mihome-app-api/)
+* [al-one/hass-xiaomi-miot](https://github.com/al-one/hass-xiaomi-miot)
+
+## 开源许可
+
+本项目采用 [GPL-3.0](LICENSE) 开源许可证。
+
+**请注意：GPL-3.0 是具有“强传染性”的开源许可证。**  
+如果您在您的项目中使用、修改或分发本项目的代码（包括作为库依赖），您的整个项目也**必须**以 GPL-3.0 或兼容许可证开源发布。
+
+## 免责声明
+
+* 本项目仅供学习交流使用，不得用于商业用途，如有侵权请联系删除
+* 用户使用本项目所产生的任何后果，需自行承担风险
+* 开发者不对使用本项目产生的任何直接或间接损失负责

{mijiaapi-4.1.2 → mijiaapi-4.2.0}/README.md

@@ -2,7 +2,7 @@
 
 米家 API，可以使用代码、CLI、MCP 直接控制米家设备。
 
-> 🎉 **v4.0.0 版本已支持 MCP**，详见 [MCP 使用文档](https://mijia-api.do1e.com/usage/mcp)
+> 🎉 **v4.0.0 版本已支持 MCP**，详见 [MCP 使用文档](https://mijia-api.do1e.com/usage/mcp)  
 > 🎉 **v4.1.0 版本已支持 Agent Skill**，详见 [Agent Skill 使用文档](https://mijia-api.do1e.com/usage/skill)
 
 [![GitHub](https://img.shields.io/badge/GitHub-Do1e%2Fmijia--api-blue)](https://github.com/Do1e/mijia-api)

{mijiaapi-4.1.2 → mijiaapi-4.2.0}/mijiaAPI/__main__.py

@@ -19,6 +19,17 @@ if log_level_name not in ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']:
 log_level = getattr(logging, log_level_name, logging.INFO)
 logging.getLogger("mijiaAPI").setLevel(log_level)
 
+
+def json_object(value: str) -> dict:
+    try:
+        result = json.loads(value)
+    except json.JSONDecodeError as e:
+        raise argparse.ArgumentTypeError(f"无效 JSON: {e.msg}") from e
+    if not isinstance(result, dict):
+        raise argparse.ArgumentTypeError("必须是 JSON 对象")
+    return result
+
+
 def parse_args(args):
     parser = argparse.ArgumentParser(description=f"Mijia API CLI (v{version})")
     subparsers = parser.add_subparsers(dest='command')
@@ -190,6 +201,87 @@ def parse_args(args):
         help="需要设定的属性值",
         required=True,
     )
+
+    action = subparsers.add_parser(
+        'action',
+        help="执行设备动作",
+    )
+    action.set_defaults(func='action')
+    action.add_argument(
+        '-p', '--auth_path',
+        type=Path,
+        default=Path.home() / ".config" / "mijia-api" / "auth.json",
+        help="认证文件保存路径，默认保存在 ~/.config/mijia-api/auth.json",
+    )
+    action_device = action.add_mutually_exclusive_group(required=True)
+    action_device.add_argument(
+        '--did',
+        type=str,
+        help="设备did",
+    )
+    action_device.add_argument(
+        '--dev_name',
+        type=str,
+        help="设备名称，指定为米家APP中设定的名称",
+    )
+    action.add_argument(
+        '--action_name',
+        type=str,
+        help="动作名称，先使用 --get_device_info 获取",
+        required=True,
+    )
+    action.add_argument(
+        '--params',
+        type=json_object,
+        help='动作参数 JSON 对象，例如 {"value":[2]}',
+        default=None,
+    )
+
+    statistics = subparsers.add_parser(
+        'statistics',
+        help="获取设备统计数据",
+    )
+    statistics.set_defaults(func='statistics')
+    statistics.add_argument(
+        '-p', '--auth_path',
+        type=Path,
+        default=Path.home() / ".config" / "mijia-api" / "auth.json",
+        help="认证文件保存路径，默认保存在 ~/.config/mijia-api/auth.json",
+    )
+    statistics.add_argument(
+        '--did',
+        type=str,
+        help="设备did，先使用 --list_devices 获取",
+        required=True,
+    )
+    statistics.add_argument(
+        '--key',
+        type=str,
+        help='设备相关的统计键，例如 lumi.acpartner.mcn04 的 "7.1"',
+        required=True,
+    )
+    statistics.add_argument(
+        '--data_type',
+        type=str,
+        help="统计类型，例如 stat_month_v3；旧设备可能不带 _v3",
+        required=True,
+    )
+    statistics.add_argument(
+        '--limit',
+        type=int,
+        help="返回的最大条目数，默认 6",
+        default=6,
+    )
+    statistics.add_argument(
+        '--time_start',
+        type=int,
+        help="开始时间戳（秒），默认结束时间前 30 天",
+    )
+    statistics.add_argument(
+        '--time_end',
+        type=int,
+        help="结束时间戳（秒），默认为当前时间",
+    )
     return parser.parse_args(args)
 
 def init_api(auth_path: Path) -> mijiaAPI:
@@ -333,6 +425,27 @@ def set(args):
         return
     print(f"{device.name} ({device.did}) 的 {args.prop_name} 值已设置为 {args.value}")
 
+
+def run_action(api: mijiaAPI, args):
+    device = mijiaDevice(api, did=args.did, dev_name=args.dev_name)
+    device.run_action(args.action_name, **(args.params or {}))
+    print(f"{device.name} ({device.did}) 的动作 {args.action_name} 指令已发送")
+
+
+def get_statistics(api: mijiaAPI, args):
+    time_end = args.time_end if args.time_end is not None else int(time.time())
+    time_start = args.time_start if args.time_start is not None else time_end - 30 * 24 * 3600
+    result = api.get_statistics({
+        "did": args.did,
+        "key": args.key,
+        "data_type": args.data_type,
+        "limit": args.limit,
+        "time_start": time_start,
+        "time_end": time_end,
+    })
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
 def main(args):
     args = parse_args(args)
 
@@ -390,6 +503,10 @@ def main(args):
             get(args)
         if args.func == 'set':
             set(args)
+        if args.func == 'action':
+            run_action(api, args)
+        if args.func == 'statistics':
+            get_statistics(api, args)
         if args.func == 'run':
             if device_mapping is None:
                 device_mapping = get_devices_list(api, verbose=False)

{mijiaapi-4.1.2 → mijiaapi-4.2.0}/mijiaAPI/devices.py

@@ -1,6 +1,7 @@
 import json
 import re
 import time
+from collections import Counter
 from pathlib import Path
 from typing import Optional, Union
 
@@ -20,6 +21,19 @@ from .version import version
 
 
 device_url = "https://home.miot-spec.com/spec/"
+device_info_version = 1
+
+
+def _deduplicate_names(items: list[dict], iid_key: str) -> None:
+    name_counts = Counter(item["name"] for item in items)
+    for item in items:
+        if name_counts[item["name"]] > 1:
+            item["name"] = f"{item['name']}-{item['method']['siid']}"
+
+    name_counts = Counter(item["name"] for item in items)
+    for item in items:
+        if name_counts[item["name"]] > 1:
+            item["name"] = f"{item['name']}-{item['method'][iid_key]}"
 
 
 class DevProp():
@@ -252,6 +266,7 @@ def get_device_info(device_model: str, cache_path: Optional[Union[str, Path]] =
 
     返回值:
         dict: 设备规格信息字典，包含以下字段：
+            - version (int): 设备信息缓存格式版本
             - name (str): 设备名称
             - model (str): 设备型号
             - properties (list): 设备属性列表，每个属性包含以下字段：
@@ -275,12 +290,16 @@ def get_device_info(device_model: str, cache_path: Optional[Union[str, Path]] =
         >>> print(info['name'])  # 输出设备名称
         >>> print(info['properties'][0]['name'])  # 输出第一个属性的名称
     """
+    cache_file = None
     if cache_path is not None:
         cache_file = Path(cache_path) / f"{device_model}.json"
         if cache_file.exists():
             logger.debug(f"从缓存加载设备信息: {cache_file}")
             with cache_file.open("r", encoding="utf-8") as f:
-                return json.load(f)
+                cached_result = json.load(f)
+            if cached_result.get("version") == device_info_version:
+                return cached_result
+            logger.debug(f"设备信息缓存版本不匹配，重新获取: {cache_file}")
     response = requests.get(device_url + device_model, headers={
         "User-Agent": f"mijiaAPI/{version}"
     })
@@ -297,6 +316,7 @@ def get_device_info(device_model: str, cache_path: Optional[Union[str, Path]] =
     model = product["model"]
     i18n_zh = content["props"]["i18n"]["zh_cn"]
     result = {
+        "version": device_info_version,
         "name": name,
         "model": model,
         "properties": [],
@@ -304,11 +324,8 @@ def get_device_info(device_model: str, cache_path: Optional[Union[str, Path]] =
     }
     services = content["props"]["tree"]["services"]
 
-    properties_name = []
-    actions_name = []
     for svc in services:
         siid = svc["iid"]
-        svc_type = svc["type"]
         for prop in svc.get("properties", []):
             piid = prop["iid"]
             if prop["format"].startswith("int"):
@@ -345,9 +362,6 @@ def get_device_info(device_model: str, cache_path: Optional[Union[str, Path]] =
                     if vl_zh:
                         vl_entry["desc_zh_cn"] = vl_zh
                     item["value-list"].append(vl_entry)
-            if item["name"] in properties_name:
-                item["name"] = f"{svc_type}-{item['name']}"
-            properties_name.append(item["name"])
             result["properties"].append(item)
         for act in svc.get("actions", []):
             aiid = act["iid"]
@@ -360,15 +374,13 @@ def get_device_info(device_model: str, cache_path: Optional[Union[str, Path]] =
                     "aiid": aiid
                 }
             }
-            if act_item["name"] in actions_name:
-                act_item["name"] = f"{svc_type}-{act_item['name']}"
-            actions_name.append(act_item["name"])
             result["actions"].append(act_item)
 
-    if cache_path is not None:
-        cache_path = Path(cache_path)
-        cache_path.mkdir(parents=True, exist_ok=True)
-        cache_file = cache_path / f"{device_model}.json"
+    _deduplicate_names(result["properties"], "piid")
+    _deduplicate_names(result["actions"], "aiid")
+
+    if cache_file is not None:
+        cache_file.parent.mkdir(parents=True, exist_ok=True)
         logger.debug(f"缓存设备信息到: {cache_file}")
         with cache_file.open("w", encoding="utf-8") as f:
             json.dump(result, f, indent=2, ensure_ascii=False)

{mijiaapi-4.1.2 → mijiaapi-4.2.0}/mijiaAPI/mcp_server.py

@@ -68,7 +68,7 @@ def run(auth_path: Path) -> None:
                 f"请调用 login 工具重新登录后再使用其他工具"
             )
 
-    mcp.run()
+    mcp.run(show_banner=False)
 
 
 @mcp.tool
@@ -274,13 +274,20 @@ def get_statistics(
 
     参数:
         did: 设备ID，可从 list_devices 获取。
-        key: 统计数据键，格式为 siid.piid（如 "7.1"），需根据设备型号确定。
-        data_type: 统计粒度，可选 stat_hour_v3 / stat_day_v3 / stat_week_v3 / stat_month_v3。
+        key: 设备相关的统计键，通常为 siid.piid。例如 lumi.acpartner.mcn04
+             的耗电量使用 "7.1"，lumi.acpartner.mcn02 使用 "powerCost"。
+        data_type: 统计粒度：stat_hour_v3 / stat_day_v3 / stat_week_v3 /
+                   stat_month_v3。较旧设备可能使用不带 _v3 的对应类型。
         limit: 返回最大条目数，默认6。
         time_start: 起始时间戳（秒），不传默认为30天前。
         time_end: 结束时间戳（秒），不传默认为当前时间。
 
-    返回统计条目列表（时间戳与数值）。
+    返回 JSON 编码的统计条目列表。每项包含 time 时间戳和 value；value 通常仍是
+    JSON 数组字符串，例如 "[48.476]"。
+
+    注意：统计接口仅支持部分设备，不同型号可能需要不同的 key、data_type，甚至使用
+    不同 API。详见 https://github.com/Do1e/mijia-api/issues/46
+    参考 https://iot.mi.com/new/doc/accesses/direct-access/extension-development/extension-functions/statistical-interface
     """
     import time
     api = _get_api()

mijiaapi-4.2.0/mijiaAPI/version.py

@@ -0,0 +1 @@
+version = "4.2.0"

{mijiaapi-4.1.2 → mijiaapi-4.2.0}/setup.cfg

@@ -1,4 +1,4 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-
+[egg_info]
+tag_build = 
+tag_date = 0
+

mijiaapi-4.1.2/mijiaAPI/version.py

@@ -1 +0,0 @@
-version = "4.1.2"