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

pyezvizapi/__init__.py

@@ -34,6 +34,22 @@ from .exceptions import (
     InvalidURL,
     PyEzvizError,
 )
+from .feature import (
+    day_night_mode_value,
+    day_night_sensitivity_value,
+    device_icr_dss_config,
+    display_mode_value,
+    has_osd_overlay,
+    lens_defog_config,
+    lens_defog_value,
+    night_vision_config,
+    night_vision_duration_value,
+    night_vision_luminance_value,
+    night_vision_mode_value,
+    night_vision_payload,
+    optionals_mapping,
+    resolve_channel,
+)
 from .light_bulb import EzvizLightBulb
 from .models import EzvizDeviceRecord, build_device_records_map
 from .mqtt import EzvizToken, MQTTClient, MqttData, ServiceUrls
@@ -71,4 +87,18 @@ __all__ = [
     "SupportExt",
     "TestRTSPAuth",
     "build_device_records_map",
+    "day_night_mode_value",
+    "day_night_sensitivity_value",
+    "device_icr_dss_config",
+    "display_mode_value",
+    "has_osd_overlay",
+    "lens_defog_config",
+    "lens_defog_value",
+    "night_vision_config",
+    "night_vision_duration_value",
+    "night_vision_luminance_value",
+    "night_vision_mode_value",
+    "night_vision_payload",
+    "optionals_mapping",
+    "resolve_channel",
 ]

pyezvizapi/client.py

@@ -126,6 +126,7 @@ from .exceptions import (
     InvalidURL,
     PyEzvizError,
 )
+from .feature import optionals_mapping
 from .light_bulb import EzvizLightBulb
 from .models import EzvizDeviceRecord, build_device_records_map
 from .mqtt import MQTTClient
@@ -1695,6 +1696,47 @@ class EzvizClient:
             error_message="Could not set IoT feature value",
         )
 
+    def set_lens_defog_mode(
+        self,
+        serial: str,
+        value: int,
+        *,
+        local_index: str = "1",
+        max_retries: int = 0,
+    ) -> tuple[bool, str]:
+        """Update the lens defog configuration using canonical option index.
+
+        Args:
+            serial: Device serial number.
+            value: Select option index (0=auto, 1=on, 2=off).
+            local_index: Channel index for multi-channel devices.
+            max_retries: Number of retries for transient failures.
+
+        Returns:
+            A tuple of (enabled flag, defog mode string) reflecting the
+            configuration that was sent to the device.
+        """
+
+        if value == 1:
+            enabled, mode = True, "open"
+        elif value == 2:
+            enabled, mode = False, "auto"
+        else:
+            enabled, mode = True, "auto"
+
+        payload = {"value": {"enabled": enabled, "defogMode": mode}}
+        self.set_iot_feature(
+            serial,
+            resource_identifier="Video",
+            local_index=local_index,
+            domain_id="LensCleaning",
+            action_id="DefogCfg",
+            value=payload,
+            max_retries=max_retries,
+        )
+
+        return enabled, mode
+
     def update_device_name(
         self,
         serial: str,
@@ -2936,33 +2978,109 @@ class EzvizClient:
 
         return True
 
+    def _resolve_osd_text(
+        self,
+        serial: str,
+        *,
+        name: str | None = None,
+        camera_data: Mapping[str, Any] | None = None,
+    ) -> str:
+        """Return the preferred OSD label for a camera."""
+
+        if isinstance(name, str) and name.strip():
+            return name.strip()
+
+        candidates: list[Mapping[str, Any]] = []
+
+        if isinstance(camera_data, Mapping):
+            candidates.append(camera_data)
+
+        cached = self._cameras.get(serial)
+        if isinstance(cached, Mapping):
+            candidates.append(cached)
+
+        for data in candidates:
+            direct = data.get("name")
+            if isinstance(direct, str) and direct.strip():
+                return direct.strip()
+
+            device_info = data.get("deviceInfos")
+            if isinstance(device_info, Mapping):
+                alt = device_info.get("name")
+                if isinstance(alt, str) and alt.strip():
+                    return alt.strip()
+
+            optionals = optionals_mapping(data)
+            osd_entries = optionals.get("OSD")
+            if isinstance(osd_entries, Mapping):
+                osd_entries = [osd_entries]
+            if isinstance(osd_entries, list):
+                for entry in osd_entries:
+                    if not isinstance(entry, Mapping):
+                        continue
+                    text = entry.get("name")
+                    if isinstance(text, str) and text.strip():
+                        return text.strip()
+
+        return serial
+
     def set_camera_osd(
         self,
         serial: str,
-        text: str = "",
+        text: str | None = None,
+        *,
+        enabled: bool | None = None,
+        name: str | None = None,
+        camera_data: Mapping[str, Any] | None = None,
         channel: int = 1,
         max_retries: int = 0,
     ) -> bool:
-        """Set OSD (on screen display) text.
+        """Set or clear the on-screen display text for a camera.
 
         Args:
-            serial (str): The camera serial.
-            text (str, optional): The osd text to set. The default of "" will clear.
-            channel (int, optional): The cammera channel to set this on. Defaults to 1.
-            max_retries (int, optional): Number of retries attempted. Defaults to 0.
-
-        Raises:
-            PyEzvizError: If max retries are exceeded or if the response indicates failure.
-            HTTPError: If an HTTP error occurs (other than a 401, which triggers re-login).
+            serial: Camera serial number that should receive the update.
+            text: Explicit OSD label to apply. If provided it takes precedence over
+                all other inputs and `enabled` is ignored.
+            enabled: Convenience flag used when `text` is omitted. When set to
+                `True`, the client derives a label automatically (optionally using
+                `name`/`camera_data`). When `False`, the overlay is cleared.
+            name: Optional friendly name to favour when building the automatic
+                overlay text.
+            camera_data: Optional camera payload (matching coordinator data) that
+                can be inspected for existing OSD labels and names.
+            channel: Camera channel identifier (defaults to the primary channel).
+            max_retries: Number of retry attempts for transient API failures.
 
         Returns:
-            bool: True if the operation was successful.
-
+            bool: ``True`` when the request is accepted by the Ezviz backend.
         """
+
+        if text is not None:
+            resolved = text
+        elif enabled is False:
+            resolved = ""
+        else:
+            if camera_data is None:
+                camera_data = self._cameras.get(serial)
+            if camera_data is None:
+                raise PyEzvizError(
+                    "Camera data unavailable; call load_devices() before setting the OSD"
+                )
+
+            resolved = (
+                self._resolve_osd_text(
+                    serial,
+                    name=name,
+                    camera_data=camera_data,
+                )
+                if enabled
+                else ""
+            )
+
         json_output = self._request_json(
             "PUT",
             f"{API_ENDPOINT_OSD}{serial}/{channel}/osd",
-            data={"osd": text},
+            data={"osd": resolved},
             retry_401=True,
             max_retries=max_retries,
         )

pyezvizapi/feature.py

@@ -0,0 +1,251 @@
+"""Helpers for working with Ezviz feature metadata payloads."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+from typing import Any, cast
+
+from .utils import coerce_int, decode_json
+
+
+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):
+        return {}
+
+    for group in feature.values():
+        if isinstance(group, Mapping):
+            video = group.get("Video")
+            if isinstance(video, MutableMapping):
+                return cast(dict[str, Any], video)
+
+    return {}
+
+
+def lens_defog_config(camera_data: Mapping[str, Any]) -> dict[str, Any]:
+    """Return the LensCleaning defog configuration if present."""
+
+    video = _feature_video_section(camera_data)
+    lens = video.get("LensCleaning") if isinstance(video, Mapping) else None
+    if not isinstance(lens, MutableMapping):
+        return {}
+
+    config = lens.get("DefogCfg")
+    if isinstance(config, MutableMapping):
+        return cast(dict[str, Any], config)
+    return {}
+
+
+def lens_defog_value(camera_data: Mapping[str, Any]) -> int:
+    """Return canonical defogging mode (0=auto,1=on,2=off)."""
+
+    cfg = lens_defog_config(camera_data)
+    if not cfg:
+        return 0
+
+    enabled = bool(cfg.get("enabled"))
+    mode = str(cfg.get("defogMode") or "").lower()
+
+    if not enabled:
+        return 2
+
+    if mode == "open":
+        return 1
+
+    return 0
+
+
+def optionals_mapping(camera_data: Mapping[str, Any]) -> dict[str, Any]:
+    """Return decoded optionals mapping from the camera payload."""
+
+    status_info = camera_data.get("statusInfo")
+    optionals: Any = None
+    if isinstance(status_info, Mapping):
+        optionals = status_info.get("optionals")
+
+    optionals = decode_json(optionals)
+
+    if not isinstance(optionals, Mapping):
+        optionals = decode_json(camera_data.get("optionals"))
+
+    if not isinstance(optionals, Mapping):
+        status = camera_data.get("STATUS")
+        if isinstance(status, Mapping):
+            optionals = decode_json(status.get("optionals"))
+
+    return dict(optionals) if isinstance(optionals, Mapping) else {}
+
+
+def display_mode_value(camera_data: Mapping[str, Any]) -> int:
+    """Return display mode value (1..3) from camera data."""
+
+    optionals = optionals_mapping(camera_data)
+    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
+
+    if isinstance(mode, int) and mode in (1, 2, 3):
+        return mode
+
+    return 1
+
+
+def device_icr_dss_config(camera_data: Mapping[str, Any]) -> dict[str, Any]:
+    """Decode and return the device_ICR_DSS configuration."""
+
+    optionals = optionals_mapping(camera_data)
+    icr = decode_json(optionals.get("device_ICR_DSS"))
+
+    return dict(icr) if isinstance(icr, Mapping) else {}
+
+
+def day_night_mode_value(camera_data: Mapping[str, Any]) -> int:
+    """Return current day/night mode (0=auto,1=day,2=night)."""
+
+    config = device_icr_dss_config(camera_data)
+    mode = config.get("mode")
+    if isinstance(mode, int) and mode in (0, 1, 2):
+        return mode
+    return 0
+
+
+def day_night_sensitivity_value(camera_data: Mapping[str, Any]) -> int:
+    """Return current day/night sensitivity value (1..3)."""
+
+    config = device_icr_dss_config(camera_data)
+    sensitivity = config.get("sensitivity")
+    if isinstance(sensitivity, int) and sensitivity in (1, 2, 3):
+        return sensitivity
+    return 2
+
+
+def resolve_channel(camera_data: Mapping[str, Any]) -> int:
+    """Return the channel number to use for devconfig operations."""
+
+    candidate = camera_data.get("channelNo") or camera_data.get("channel_no")
+    if isinstance(candidate, int):
+        return candidate
+    if isinstance(candidate, str) and candidate.isdigit():
+        return int(candidate)
+    return 1
+
+
+def night_vision_config(camera_data: Mapping[str, Any]) -> dict[str, Any]:
+    """Return decoded NightVision_Model configuration mapping."""
+
+    optionals = optionals_mapping(camera_data)
+    config: Any = optionals.get("NightVision_Model")
+    if config is None:
+        config = camera_data.get("NightVision_Model")
+
+    config = decode_json(config)
+
+    return dict(config) if isinstance(config, Mapping) else {}
+
+
+def night_vision_mode_value(camera_data: Mapping[str, Any]) -> int:
+    """Return current night vision mode (0=BW,1=colour,2=smart,5=super)."""
+
+    config = night_vision_config(camera_data)
+    mode = coerce_int(config.get("graphicType"))
+    if mode is None:
+        return 0
+    return mode if mode in (0, 1, 2, 5) else 0
+
+
+def night_vision_luminance_value(camera_data: Mapping[str, Any]) -> int:
+    """Return the configured night vision luminance (default 40)."""
+
+    config = night_vision_config(camera_data)
+    value = coerce_int(config.get("luminance"))
+    if value is None:
+        value = 40
+    return max(0, value)
+
+
+def night_vision_duration_value(camera_data: Mapping[str, Any]) -> int:
+    """Return the configured smart night vision duration (default 60)."""
+
+    config = night_vision_config(camera_data)
+    value = coerce_int(config.get("duration"))
+    return value if value is not None else 60
+
+
+def night_vision_payload(
+    camera_data: Mapping[str, Any],
+    *,
+    mode: int | None = None,
+    luminance: int | None = None,
+    duration: int | None = None,
+) -> dict[str, Any]:
+    """Return a sanitized NightVision_Model payload for updates."""
+
+    config = dict(night_vision_config(camera_data))
+
+    resolved_mode = (
+        int(mode)
+        if mode is not None
+        else int(config.get("graphicType") or night_vision_mode_value(camera_data))
+    )
+    config["graphicType"] = resolved_mode
+
+    if luminance is None:
+        luminance_value = night_vision_luminance_value(camera_data)
+    else:
+        coerced_luminance = coerce_int(luminance)
+        luminance_value = (
+            coerced_luminance
+            if coerced_luminance is not None
+            else night_vision_luminance_value(camera_data)
+        )
+    if resolved_mode == 1:
+        config["luminance"] = 0 if luminance_value <= 0 else max(20, luminance_value)
+    elif resolved_mode == 2:
+        config["luminance"] = max(
+            20,
+            luminance_value if luminance_value > 0 else 40,
+        )
+    else:
+        config["luminance"] = max(0, luminance_value)
+
+    if duration is None:
+        duration_value = night_vision_duration_value(camera_data)
+    else:
+        coerced_duration = coerce_int(duration)
+        duration_value = (
+            coerced_duration
+            if coerced_duration is not None
+            else night_vision_duration_value(camera_data)
+        )
+    if resolved_mode == 2:
+        config["duration"] = max(15, min(120, duration_value))
+    else:
+        config.pop("duration", None)
+
+    return config
+
+
+def has_osd_overlay(camera_data: Mapping[str, Any]) -> bool:
+    """Return True when the camera has an active OSD label."""
+
+    optionals = optionals_mapping(camera_data)
+    osd_entries = optionals.get("OSD")
+
+    if isinstance(osd_entries, Mapping):
+        entries: list[Mapping[str, Any]] = [osd_entries]
+    elif isinstance(osd_entries, list):
+        entries = [entry for entry in osd_entries if isinstance(entry, Mapping)]
+    else:
+        return False
+
+    for entry in entries:
+        name = entry.get("name")
+        if isinstance(name, str) and name.strip():
+            return True
+    return False

pyezvizapi/utils.py

@@ -18,6 +18,32 @@ from .exceptions import PyEzvizError
 _LOGGER = logging.getLogger(__name__)
 
 
+def coerce_int(value: Any) -> int | None:
+    """Best-effort coercion to int for mixed payloads."""
+
+    if isinstance(value, bool):
+        return int(value)
+
+    if isinstance(value, (int, float)):
+        return int(value)
+
+    try:
+        return int(str(value))
+    except (TypeError, ValueError):
+        return None
+
+
+def decode_json(value: Any) -> Any:
+    """Decode a JSON string when possible, otherwise return the original value."""
+
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except (TypeError, ValueError):
+            return None
+    return value
+
+
 def convert_to_dict(data: Any) -> Any:
     """Recursively convert a string representation of a dictionary to a dictionary."""
     if isinstance(data, dict):

{pyezvizapi-1.0.3.1.dist-info → pyezvizapi-1.0.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyezvizapi
-Version: 1.0.3.1
+Version: 1.0.3.3
 Summary: Pilot your Ezviz cameras
 Home-page: https://github.com/RenierM26/pyEzvizApi/
 Author: Renier Moorcroft

{pyezvizapi-1.0.3.1.dist-info → pyezvizapi-1.0.3.3.dist-info}/RECORD

@@ -1,21 +1,22 @@
-pyezvizapi/__init__.py,sha256=IDnIN_nfIISVwuy0cVBh4wspgAav6MuOJCQGajjyU3g,1881
+pyezvizapi/__init__.py,sha256=mp3XbdXy00TyittfvvGrQ2oAaDeoebLE6_QU0Sbuf8o,2668
 pyezvizapi/__main__.py,sha256=9uttTuOfO22tzyomJIV8ebFJ-G-YUNDYOadZ_0AgdNA,20925
 pyezvizapi/api_endpoints.py,sha256=2M5Vs4YB1VWZGcowT-4Fj2hhRNjFh976LT3jtRrqvrc,5754
 pyezvizapi/camera.py,sha256=Pl5oIEdrFcv1Hz5sQI1IyyJIDCMjOjQdtExgKzmLoK8,22102
 pyezvizapi/cas.py,sha256=3zHe-_a0KchCmGeAj1of-pV6oMPRUmSCIiDqBFsTK8A,6025
-pyezvizapi/client.py,sha256=k6j7MLYfeUN74feJKhBipYVwQ0MKdETrGUJkqunItxQ,136976
+pyezvizapi/client.py,sha256=rQ95oGgx16M69BWA8WTmmpyX9d4kHdxt6biVMrjDmOQ,140990
 pyezvizapi/constants.py,sha256=5AxJYfof6NvebBcFvPkoKI6xinpkwmCnaauUvhvBMDY,12810
 pyezvizapi/exceptions.py,sha256=8rmxEUQdrziqMe-M1SeeRd0HtP2IDQ2xpJVj7wvOQyo,976
+pyezvizapi/feature.py,sha256=Sc-L-2qqz7GXmaWf0_j6QF84KRSw_emy1cWKhcs5HzE,7654
 pyezvizapi/light_bulb.py,sha256=9wgycG3dTvBbrsxQjQnXal-GA8VXPsIN1m-CTtRh8i0,7797
 pyezvizapi/models.py,sha256=NQzwTP0yEe2IWU-Vc6nAn87xulpTuo0MX2Rcf0WxifA,4176
 pyezvizapi/mqtt.py,sha256=aOL-gexZgYvCCaNQ03M4vZan91d5p2Fl_qsFykn9NW4,22365
 pyezvizapi/test_cam_rtsp.py,sha256=O9NHh-vcNFfnzNw8jbuhM9a_5TWfNZIMXaJP7Lmkaj4,5162
 pyezvizapi/test_mqtt.py,sha256=Orn-fwZPJIE4G5KROMX0MRAkLwU6nLb9LUtXyb2ZCQs,4147
-pyezvizapi/utils.py,sha256=G8gGjG0ecdN05Y0vxOHvcQMtQXgVB7nHzyvCzz66kLk,12148
-pyezvizapi-1.0.3.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-pyezvizapi-1.0.3.1.dist-info/licenses/LICENSE.md,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-pyezvizapi-1.0.3.1.dist-info/METADATA,sha256=nD4Ea6CgpDZPAbI-8SQ3IQxhFC4oBD0QIHfofu5dtog,695
-pyezvizapi-1.0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pyezvizapi-1.0.3.1.dist-info/entry_points.txt,sha256=_BSJ3eNb2H_AZkRdsv1s4mojqWn3N7m503ujvg1SudA,56
-pyezvizapi-1.0.3.1.dist-info/top_level.txt,sha256=gMZTelIi8z7pXyTCQLLaIkxVRrDQ_lS2NEv0WgfHrHs,11
-pyezvizapi-1.0.3.1.dist-info/RECORD,,
+pyezvizapi/utils.py,sha256=ozGncEyaIJJ8VYw8f-xfM2OBmqR8eNYLq728FFvbvr8,12757
+pyezvizapi-1.0.3.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pyezvizapi-1.0.3.3.dist-info/licenses/LICENSE.md,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pyezvizapi-1.0.3.3.dist-info/METADATA,sha256=zSGxukJtv5F88ejmK6fPoG8kPwQXO-y9t-xseLDVMQU,695
+pyezvizapi-1.0.3.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyezvizapi-1.0.3.3.dist-info/entry_points.txt,sha256=_BSJ3eNb2H_AZkRdsv1s4mojqWn3N7m503ujvg1SudA,56
+pyezvizapi-1.0.3.3.dist-info/top_level.txt,sha256=gMZTelIi8z7pXyTCQLLaIkxVRrDQ_lS2NEv0WgfHrHs,11
+pyezvizapi-1.0.3.3.dist-info/RECORD,,