pyezvizapi 1.0.3.3__py3-none-any.whl → 1.0.4.3__py3-none-any.whl

pyezvizapi/feature.py

@@ -2,26 +2,64 @@
 
 from __future__ import annotations
 
-from collections.abc import Mapping, MutableMapping
+from collections.abc import Iterable, Iterator, Mapping, MutableMapping
 from typing import Any, cast
 
-from .utils import coerce_int, decode_json
+from .utils import WILDCARD_STEP, coerce_int, decode_json, first_nested
 
 
 def _feature_video_section(camera_data: Mapping[str, Any]) -> dict[str, Any]:
     """Return the nested Video feature section from feature info payload."""
 
-    feature = camera_data.get("FEATURE_INFO")
-    if not isinstance(feature, Mapping):
+    video = first_nested(
+        camera_data,
+        ("FEATURE_INFO", WILDCARD_STEP, "Video"),
+    )
+    if isinstance(video, MutableMapping):
+        return cast(dict[str, Any], video)
+    return {}
+
+
+def supplement_light_params(camera_data: Mapping[str, Any]) -> dict[str, Any]:
+    """Return SupplementLightMgr parameters if present."""
+
+    video = _feature_video_section(camera_data)
+    if not video:
         return {}
 
-    for group in feature.values():
-        if isinstance(group, Mapping):
-            video = group.get("Video")
-            if isinstance(video, MutableMapping):
-                return cast(dict[str, Any], video)
+    manager: Any = video.get("SupplementLightMgr")
+    manager = decode_json(manager)
+    if not isinstance(manager, Mapping):
+        return {}
 
-    return {}
+    params: Any = manager.get("ImageSupplementLightModeSwitchParams")
+    params = decode_json(params)
+    return dict(params) if isinstance(params, Mapping) else {}
+
+
+def supplement_light_enabled(camera_data: Mapping[str, Any]) -> bool:
+    """Return True when intelligent fill light is enabled."""
+
+    params = supplement_light_params(camera_data)
+    if not params:
+        return False
+
+    enabled = params.get("enabled")
+    if isinstance(enabled, bool):
+        return enabled
+    if isinstance(enabled, str):
+        lowered = enabled.strip().lower()
+        if lowered in {"true", "1", "yes", "on"}:
+            return True
+        if lowered in {"false", "0", "no", "off"}:
+            return False
+    return bool(enabled)
+
+
+def supplement_light_available(camera_data: Mapping[str, Any]) -> bool:
+    """Return True when intelligent fill light parameters are present."""
+
+    return bool(supplement_light_params(camera_data))
 
 
 def lens_defog_config(camera_data: Mapping[str, Any]) -> dict[str, Any]:
@@ -78,6 +116,227 @@ def optionals_mapping(camera_data: Mapping[str, Any]) -> dict[str, Any]:
     return dict(optionals) if isinstance(optionals, Mapping) else {}
 
 
+def optionals_dict(camera_data: Mapping[str, Any]) -> dict[str, Any]:
+    """Return convenience wrapper for optionals mapping."""
+
+    return optionals_mapping(camera_data)
+
+
+def custom_voice_volume_config(camera_data: Mapping[str, Any]) -> dict[str, int] | None:
+    """Return current CustomVoice volume configuration."""
+
+    optionals = optionals_mapping(camera_data)
+    config = optionals.get("CustomVoice_Volume")
+    config = decode_json(config)
+    if not isinstance(config, Mapping):
+        return None
+
+    volume = coerce_int(config.get("volume"))
+    mic = coerce_int(config.get("microphone_volume"))
+    result: dict[str, int] = {}
+    if isinstance(volume, int):
+        result["volume"] = volume
+    if isinstance(mic, int):
+        result["microphone_volume"] = mic
+    return result or None
+
+
+def iter_algorithm_entries(camera_data: Mapping[str, Any]) -> Iterator[dict[str, Any]]:
+    """Yield entries from the AlgorithmInfo optionals list."""
+
+    entries = optionals_dict(camera_data).get("AlgorithmInfo")
+    if not isinstance(entries, Iterable):
+        return
+    for entry in entries:
+        if isinstance(entry, Mapping):
+            yield dict(entry)
+
+
+def iter_channel_algorithm_entries(
+    camera_data: Mapping[str, Any], channel: int
+) -> Iterator[dict[str, Any]]:
+    """Yield AlgorithmInfo entries filtered by channel."""
+
+    for entry in iter_algorithm_entries(camera_data):
+        entry_channel = coerce_int(entry.get("channel")) or 1
+        if entry_channel == channel:
+            yield entry
+
+
+def get_algorithm_value(
+    camera_data: Mapping[str, Any], subtype: str, channel: int
+) -> int | None:
+    """Return AlgorithmInfo value for provided subtype/channel."""
+
+    for entry in iter_channel_algorithm_entries(camera_data, channel):
+        if entry.get("SubType") != subtype:
+            continue
+        return coerce_int(entry.get("Value"))
+    return None
+
+
+def has_algorithm_subtype(
+    camera_data: Mapping[str, Any], subtype: str, channel: int = 1
+) -> bool:
+    """Return True when AlgorithmInfo contains subtype for channel."""
+
+    return get_algorithm_value(camera_data, subtype, channel) is not None
+
+
+def support_ext_value(camera_data: Mapping[str, Any], ext_key: str) -> str | None:
+    """Fetch a supportExt entry as a string when present."""
+
+    raw = camera_data.get("supportExt")
+    if not isinstance(raw, Mapping):
+        device_infos = camera_data.get("deviceInfos")
+        if isinstance(device_infos, Mapping):
+            raw = device_infos.get("supportExt")
+
+    if not isinstance(raw, Mapping):
+        return None
+
+    value = raw.get(ext_key)
+    return str(value) if value is not None else None
+
+
+def _normalize_port_list(value: Any) -> list[dict[str, Any]] | None:
+    """Decode a list of port-security entries."""
+
+    value = decode_json(value)
+    if not isinstance(value, Iterable):
+        return None
+
+    normalized: list[dict[str, Any]] = []
+    for raw_entry in value:
+        entry = decode_json(raw_entry)
+        if not isinstance(entry, Mapping):
+            return None
+        port = coerce_int(entry.get("portNo"))
+        if port is None:
+            continue
+        normalized.append({"portNo": port, "enabled": bool(entry.get("enabled"))})
+
+    return normalized
+
+
+def normalize_port_security(payload: Any) -> dict[str, Any]:
+    """Normalize IoT port-security payloads."""
+
+    seen: set[int] = set()
+
+    def _apply_hint(
+        candidate: dict[str, Any] | None, hint_value: bool | None
+    ) -> dict[str, Any] | None:
+        if (
+            candidate is not None
+            and "enabled" not in candidate
+            and isinstance(hint_value, bool)
+        ):
+            candidate["enabled"] = hint_value
+        return candidate
+
+    def _walk_mapping(obj: Mapping[str, Any], hint: bool | None) -> dict[str, Any] | None:
+        obj_id = id(obj)
+        if obj_id in seen:
+            return None
+        seen.add(obj_id)
+
+        enabled_local = obj.get("enabled")
+        if isinstance(enabled_local, bool):
+            hint = enabled_local
+
+        ports = _normalize_port_list(obj.get("portSecurityList"))
+        if ports is not None:
+            return {
+                "portSecurityList": ports,
+                "enabled": bool(enabled_local)
+                if isinstance(enabled_local, bool)
+                else bool(hint)
+                if isinstance(hint, bool)
+                else True,
+            }
+
+        for key in ("PortSecurity", "value", "data", "NetworkSecurityProtection"):
+            if key in obj:
+                candidate = _apply_hint(_walk(obj[key], hint), hint)
+                if candidate:
+                    return candidate
+
+        for value in obj.values():
+            candidate = _apply_hint(_walk(value, hint), hint)
+            if candidate:
+                return candidate
+
+        return None
+
+    def _walk_iterable(values: Iterable[Any], hint: bool | None) -> dict[str, Any] | None:
+        for item in values:
+            candidate = _walk(item, hint)
+            if candidate:
+                return candidate
+        return None
+
+    def _walk(obj: Any, hint: bool | None = None) -> dict[str, Any] | None:
+        obj = decode_json(obj)
+        if obj is None:
+            return None
+
+        if isinstance(obj, Mapping):
+            return _walk_mapping(obj, hint)
+
+        if isinstance(obj, Iterable) and not isinstance(obj, (str, bytes, bytearray)):
+            return _walk_iterable(obj, hint)
+
+        return None
+
+    normalized = _walk(payload)
+    if isinstance(normalized, dict):
+        normalized.setdefault("enabled", True)
+        return normalized
+    return {}
+
+
+def port_security_config(camera_data: Mapping[str, Any]) -> dict[str, Any]:
+    """Return the normalized port-security mapping for a camera payload."""
+
+    direct = camera_data.get("NetworkSecurityProtection")
+    normalized = normalize_port_security(direct)
+    if normalized:
+        return normalized
+
+    feature = camera_data.get("FEATURE_INFO")
+    if isinstance(feature, Mapping):
+        normalized = normalize_port_security(feature)
+        if normalized:
+            return normalized
+
+    return {}
+
+
+def port_security_has_port(camera_data: Mapping[str, Any], port: int) -> bool:
+    """Return True if the normalized config contains the port."""
+
+    ports = port_security_config(camera_data).get("portSecurityList")
+    if not isinstance(ports, Iterable):
+        return False
+    return any(
+        isinstance(entry, Mapping) and coerce_int(entry.get("portNo")) == port
+        for entry in ports
+    )
+
+
+def port_security_port_enabled(camera_data: Mapping[str, Any], port: int) -> bool:
+    """Return True if the specific port is enabled."""
+
+    ports = port_security_config(camera_data).get("portSecurityList")
+    if not isinstance(ports, Iterable):
+        return False
+    for entry in ports:
+        if isinstance(entry, Mapping) and coerce_int(entry.get("portNo")) == port:
+            return bool(entry.get("enabled"))
+    return False
+
+
 def display_mode_value(camera_data: Mapping[str, Any]) -> int:
     """Return display mode value (1..3) from camera data."""
 
@@ -85,10 +344,9 @@ def display_mode_value(camera_data: Mapping[str, Any]) -> int:
     display_mode = optionals.get("display_mode")
     display_mode = decode_json(display_mode)
 
-    if isinstance(display_mode, Mapping):
-        mode = display_mode.get("mode")
-    else:
-        mode = display_mode
+    mode = (
+        display_mode.get("mode") if isinstance(display_mode, Mapping) else display_mode
+    )
 
     if isinstance(mode, int) and mode in (1, 2, 3):
         return mode
@@ -96,6 +354,33 @@ def display_mode_value(camera_data: Mapping[str, Any]) -> int:
     return 1
 
 
+def blc_current_value(camera_data: Mapping[str, Any]) -> int:
+    """Return BLC position (0..5) from camera data. 0 = Off."""
+    optionals = optionals_mapping(camera_data)
+    inverse_mode = optionals.get("inverse_mode")
+    inverse_mode = decode_json(inverse_mode)
+
+    # Expected: {"mode": int, "enable": 0|1, "position": 0..5}
+    if isinstance(inverse_mode, Mapping):
+        enable = inverse_mode.get("enable", 0)
+        position = inverse_mode.get("position", 0)
+        if (
+            isinstance(enable, int)
+            and enable == 1
+            and isinstance(position, int)
+            and position in (1, 2, 3, 4, 5)
+        ):
+            return position
+        return 0
+
+    # Fallbacks if backend ever returns a bare int (position) instead of the object
+    if isinstance(inverse_mode, int) and inverse_mode in (0, 1, 2, 3, 4, 5):
+        return inverse_mode
+
+    # Default to Off
+    return 0
+
+
 def device_icr_dss_config(camera_data: Mapping[str, Any]) -> dict[str, Any]:
     """Decode and return the device_ICR_DSS configuration."""
 

pyezvizapi/light_bulb.py

@@ -176,7 +176,7 @@ class EzvizLightBulb:
     def set_brightness(self, value: int) -> bool:
         """Set the light bulb brightness.
 
-        The value must be in range 1–100. Returns True on success.
+        The value must be in range 1-100. Returns True on success.
 
         Raises:
             PyEzvizError: On API failures.

pyezvizapi/mqtt.py

@@ -83,27 +83,27 @@ class MqttData(TypedDict):
 # Payload decoding helpers
 # ---------------------------------------------------------------------------
 
-# Field names in the comma‑separated ``ext`` payload from EZVIZ.
+# Field names in the comma-separated ``ext`` payload from EZVIZ.
 EXT_FIELD_NAMES: Final[tuple[str, ...]] = (
     "channel_type",
     "time",
     "device_serial",
     "channel_no",
     "alert_type_code",
-    "unused1",
-    "unused2",
-    "unused3",
-    "unused4",
+    "default_pic_url",
+    "media_url_alt1",
+    "media_url_alt2",
+    "resource_type",
     "status_flag",
     "file_id",
     "is_encrypted",
     "picChecksum",
-    "unknown_flag",
-    "unused5",
+    "is_dev_video",
+    "metadata",
     "msgId",
     "image",
     "device_name",
-    "unused6",
+    "reserved",
     "sequence_number",
 )
 
@@ -113,8 +113,10 @@ EXT_INT_FIELDS: Final[frozenset[str]] = frozenset(
         "channel_type",
         "channel_no",
         "alert_type_code",
+        "resource_type",
         "status_flag",
         "is_encrypted",
+        "is_dev_video",
         "sequence_number",
     }
 )
@@ -247,7 +249,7 @@ class MQTTClient:
                 # Stop background thread and disconnect
                 self.mqtt_client.loop_stop()
                 self.mqtt_client.disconnect()
-            except Exception as err:  # noqa: BLE001
+            except (OSError, ValueError, RuntimeError) as err:
                 _LOGGER.debug("MQTT disconnect failed: %s", err)
         # Always attempt to stop push on server side
         self._stop_ezviz_push()
@@ -535,13 +537,17 @@ class MQTTClient:
         """
         broker = self._mqtt_data["push_url"]
 
-        self.mqtt_client = mqtt.Client(
-            callback_api_version=mqtt.CallbackAPIVersion.VERSION1,
-            client_id=self._mqtt_data["mqtt_clientid"],
-            clean_session=clean_session,
-            protocol=mqtt.MQTTv311,
-            transport="tcp",
-        )
+        client_kwargs: dict[str, Any] = {
+            "client_id": self._mqtt_data["mqtt_clientid"],
+            "clean_session": clean_session,
+            "protocol": mqtt.MQTTv311,
+            "transport": "tcp",
+        }
+        callback_api_version = getattr(mqtt, "CallbackAPIVersion", None)
+        if callback_api_version is not None:
+            client_kwargs["callback_api_version"] = callback_api_version.VERSION1
+
+        self.mqtt_client = mqtt.Client(**client_kwargs)
 
         # Bind callbacks
         self.mqtt_client.on_connect = self._on_connect

pyezvizapi/test_cam_rtsp.py

@@ -4,11 +4,14 @@ from __future__ import annotations
 
 import base64
 import hashlib
+import logging
 import socket
 from typing import TypedDict
 
 from .exceptions import AuthTestResultFailed, InvalidHost
 
+_LOGGER = logging.getLogger(__name__)
+
 
 def genmsg_describe(url: str, seq: int, user_agent: str, auth_seq: str) -> str:
     """Generate RTSP DESCRIBE request message."""
@@ -110,15 +113,14 @@ class TestRTSPAuth:
         describe = genmsg_describe(
             url, seq, self._rtsp_details["defaultUserAgent"], auth_seq
         )
-        print(describe)
+        _LOGGER.debug("RTSP DESCRIBE (basic):\n%s", describe)
         session.send(describe.encode())
         msg1: bytes = session.recv(self._rtsp_details["bufLen"])
         seq += 1
 
         decoded = msg1.decode()
         if "200 OK" in decoded:
-            print(f"Basic auth result: {decoded}")
-            print("Basic Auth test passed. Credentials Valid!")
+            _LOGGER.info("Basic auth result: %s", decoded)
             return
 
         if "Unauthorized" in decoded:
@@ -140,20 +142,16 @@ class TestRTSPAuth:
             describe = genmsg_describe(
                 url, seq, self._rtsp_details["defaultUserAgent"], auth_seq
             )
-            print(describe)
+            _LOGGER.debug("RTSP DESCRIBE (digest):\n%s", describe)
             session.send(describe.encode())
             msg1 = session.recv(self._rtsp_details["bufLen"])
             decoded = msg1.decode()
-            print(f"Digest auth result: {decoded}")
+            _LOGGER.info("Digest auth result: %s", decoded)
 
             if "200 OK" in decoded:
-                print("Digest Auth test Passed. Credentials Valid!")
                 return
 
             if "401 Unauthorized" in decoded:
                 raise AuthTestResultFailed("Credentials not valid!!")
 
-        print("Basic Auth test passed. Credentials Valid!")
-
-
-# ruff: noqa: T201
+        _LOGGER.info("Basic Auth test passed. Credentials Valid!")

pyezvizapi/test_mqtt.py

@@ -8,6 +8,7 @@ with MFA similar to the main CLI.
 from __future__ import annotations
 
 import argparse
+import base64
 from getpass import getpass
 import json
 import logging
@@ -18,19 +19,60 @@ from typing import Any, cast
 
 from .client import EzvizClient
 from .exceptions import EzvizAuthVerificationCode, PyEzvizError
+from .mqtt import MQTTClient
 
 logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+_LOGGER = logging.getLogger(__name__)
 
 LOG_FILE = Path("mqtt_messages.jsonl")  # JSON Lines format
+RAW_LOG_FILE = Path("mqtt_raw_messages.jsonl")
 
 
 def message_handler(msg: dict[str, Any]) -> None:
     """Handle new MQTT messages by printing and saving them to a file."""
-    print("📩 New MQTT message:", msg)
+    _LOGGER.info("📩 New MQTT message: %s", msg)
     with LOG_FILE.open("a", encoding="utf-8") as f:
         f.write(json.dumps(msg, ensure_ascii=False) + "\n")
 
 
+def _log_raw_payload(payload: bytes) -> None:
+    """Persist the raw MQTT payload to a log file for debugging."""
+    entry: dict[str, Any]
+    try:
+        decoded = payload.decode("utf-8")
+        entry = {"encoding": "utf-8", "payload": decoded}
+    except UnicodeDecodeError:
+        entry = {
+            "encoding": "base64",
+            "payload": base64.b64encode(payload).decode("ascii"),
+        }
+
+    entry["timestamp"] = time.time()
+    _LOGGER.info("🧾 Raw MQTT payload (%s): %s", entry["encoding"], entry["payload"])
+    with RAW_LOG_FILE.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+
+def _enable_raw_logging(mqtt_client: MQTTClient) -> None:
+    """Wrap the internal paho-mqtt callback to capture raw payloads."""
+    if getattr(mqtt_client, "_raw_logging_enabled", False):
+        return
+    paho_client = getattr(mqtt_client, "mqtt_client", None)
+    if paho_client is None:
+        _LOGGER.warning("Unable to enable raw logging: MQTT client not configured yet")
+        return
+
+    original_on_message = paho_client.on_message
+
+    def _raw_logging_wrapper(client: Any, userdata: Any, msg: Any) -> None:
+        _log_raw_payload(getattr(msg, "payload", b""))
+        if original_on_message:
+            original_on_message(client, userdata, msg)
+
+    paho_client.on_message = _raw_logging_wrapper
+    mqtt_client._raw_logging_enabled = True  # type: ignore[attr-defined]  # noqa: SLF001
+
+
 def _load_token_file(path: str | None) -> dict[str, Any] | None:
     if not path:
         return None
@@ -40,7 +82,7 @@ def _load_token_file(path: str | None) -> dict[str, Any] | None:
     try:
         return cast(dict[str, Any], json.loads(p.read_text(encoding="utf-8")))
     except (OSError, json.JSONDecodeError):
-        logging.getLogger(__name__).warning("Failed to read token file: %s", p)
+        _LOGGER.warning("Failed to read token file: %s", p)
         return None
 
 
@@ -50,9 +92,9 @@ def _save_token_file(path: str | None, token: dict[str, Any]) -> None:
     p = Path(path)
     try:
         p.write_text(json.dumps(token, indent=2), encoding="utf-8")
-        logging.getLogger(__name__).info("Saved token to %s", p)
+        _LOGGER.info("Saved token to %s", p)
     except OSError:
-        logging.getLogger(__name__).warning("Failed to save token file: %s", p)
+        _LOGGER.warning("Failed to save token file: %s", p)
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -87,7 +129,7 @@ def main(argv: list[str] | None = None) -> int:
 
     # If no token and missing username/password, prompt interactively
     if not token and (not username or not password):
-        print("No token found. Please enter Ezviz credentials.")
+        _LOGGER.info("No token found. Please enter Ezviz credentials")
         if not username:
             username = input("Username: ")
         if not password:
@@ -107,29 +149,29 @@ def main(argv: list[str] | None = None) -> int:
                 code_int = None
             client.login(sms_code=code_int)
         except PyEzvizError as exp:
-            print(f"Login failed: {exp}")
+            _LOGGER.error("Login failed: %s", exp)
             return 1
 
     # Start MQTT client
     mqtt_client = client.get_mqtt_client(on_message_callback=message_handler)
     mqtt_client.connect()
+    _enable_raw_logging(mqtt_client)
 
     try:
-        print("Listening for MQTT messages... (Ctrl+C to quit)")
+        _LOGGER.info("Listening for MQTT messages... (Ctrl+C to quit)")
         while True:
             time.sleep(1)
     except KeyboardInterrupt:
-        print("\nStopping...")
+        _LOGGER.info("Stopping listener (keyboard interrupt)")
     finally:
         mqtt_client.stop()
-        print("Stopped.")
+        _LOGGER.info("Listener stopped")
 
     if args.save_token and args.token_file:
-        _save_token_file(args.token_file, cast(dict[str, Any], client._token))  # noqa: SLF001
+        _save_token_file(args.token_file, client.export_token())
 
     return 0
 
 
 if __name__ == "__main__":
     sys.exit(main())
-# ruff: noqa: T201