python-aidot-cameras 1.0.0rc15__tar.gz → 1.0.0rc17__tar.gz

{python_aidot_cameras-1.0.0rc15/python_aidot_cameras.egg-info → python_aidot_cameras-1.0.0rc17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 1.0.0rc15
+Version: 1.0.0rc17
 Summary: Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)
 Author-email: cbrightly <chris.brightly@gmail.com>
 License-Expression: MIT

{python_aidot_cameras-1.0.0rc15 → python_aidot_cameras-1.0.0rc17}/aidot_cameras/camera/controls.py

@@ -15,6 +15,24 @@ from .constants import _PTZ_DIR_CODES, _STREAM_QUALITY, SETSTREAMCTRL_CMD
 
 _LOGGER = logging.getLogger(__name__)
 
+#: How the floodlight behaves when the camera sees someone, by the name the
+#: vendor app prints against each value. From the cloud device profile
+#: (LK.IPC.A001513): ``lightBehavior`` is an enum with allowedValues
+#: ``Constant=0, Flash=1``, default 0.
+LIGHT_BEHAVIORS = {"constant": 0, "flash": 1}
+
+#: How long the floodlight stays on after it triggers, in seconds. The camera
+#: enumerates exactly these four (``LingerDuration``, default 30) -- it is not a
+#: free range, and a value outside the set is accepted on the wire and ignored,
+#: which would leave a control reporting a setting the camera never applied.
+LIGHT_LINGER_DURATIONS = (20, 30, 40, 50)
+
+#: The floodlight level the camera accepts (``Dimming``: min 10, max 100).
+#: The floor is 10, not 0: 0 is out of range rather than "off", and off is
+#: LightOnOff.
+LIGHT_BRIGHTNESS_MIN = 10
+LIGHT_BRIGHTNESS_MAX = 100
+
 #: The camera's ack for SETSTREAMCTRL (800).
 SETSTREAMCTRL_RESP_CMD = 801
 #: Measured 0.01-0.03s; short so a control call never holds up a view.
@@ -56,10 +74,65 @@ class _CameraControlsMixin:
         return await self.async_set_device_attribute("OSDEnable", 1 if enabled else 0)
 
     async def async_set_auto_light(self, enabled: bool) -> bool:
-        """Enable or disable floodlight automation (autoLightEnable)."""
+        """Turn the light-up-when-someone-appears automation on or off.
+
+        This is ``autoLightEnable``, which the vendor app labels "When Someone
+        Appears" (or "When Someone Appears at Night" on some models -- that is
+        which label the app prints for the model, not a separate setting).
+        """
         return await self.async_set_device_attribute(
             "autoLightEnable", 1 if enabled else 0)
 
+    async def async_set_light_behavior(self, behavior: str) -> bool:
+        """Set how the light behaves when it triggers: "constant" or "flash".
+
+        **This write acks and does not land.** Measured 2026-09-07 against an
+        A001513 (which declares ``lightBehavior`` in its profile) and an
+        A000088 (which does not): six attempts across both models, as int 1 and
+        as string "1", every one returning True and every read-back over the
+        following 20 s still reporting the old value. On the same camera in the
+        same session ``LingerDuration`` and ``Dimming`` both landed within 4 s,
+        so this is the attribute, not the camera being asleep or the cloud
+        lagging. The one hypothesis left untested is that the camera takes it
+        only while ``autoLightEnable`` is 1 -- untested because arming it makes
+        a real floodlight come on in someone's house.
+
+        The method is kept because the command is well-formed and a future
+        firmware may honour it, but **nothing should build a control on it**
+        until a read-back confirms one: a setting that reports a value the
+        camera never applied is worse than no setting. Same call as
+        ``async_set_resolution``.
+
+        Refuses a name the camera does not offer rather than sending it: the
+        attribute is an enum, and an out-of-range write is accepted silently.
+        """
+        try:
+            value = LIGHT_BEHAVIORS[behavior]
+        except KeyError:
+            raise ValueError(
+                f"unknown light behavior {behavior!r}; "
+                f"expected one of {sorted(LIGHT_BEHAVIORS)}") from None
+        return await self.async_set_device_attribute("lightBehavior", value)
+
+    async def async_set_light_linger_duration(self, seconds: int) -> bool:
+        """Set how long the light stays on after it triggers, in seconds."""
+        if seconds not in LIGHT_LINGER_DURATIONS:
+            raise ValueError(
+                f"unsupported linger duration {seconds!r}; "
+                f"the camera offers {list(LIGHT_LINGER_DURATIONS)}")
+        return await self.async_set_device_attribute("LingerDuration", seconds)
+
+    async def async_set_light_brightness(self, level: int) -> bool:
+        """Set the floodlight level (10-100), clamped to what the camera takes.
+
+        Separate from :meth:`async_set_floodlight`'s optional brightness, which
+        is part of turning the light on by hand; this is the level the camera
+        uses when its own automation fires.
+        """
+        return await self.async_set_device_attribute(
+            "Dimming",
+            max(LIGHT_BRIGHTNESS_MIN, min(LIGHT_BRIGHTNESS_MAX, int(level))))
+
     async def async_set_voice_prompts(self, enabled: bool) -> bool:
         """Enable or disable spoken prompts from the camera speaker (voiceEnable)."""
         return await self.async_set_device_attribute(

{python_aidot_cameras-1.0.0rc15 → python_aidot_cameras-1.0.0rc17}/aidot_cameras/camera/models.py

@@ -97,8 +97,18 @@ class CameraStatusData(DeviceStatusData):
     status_led: Optional[bool] = None
     #: Timestamp/OSD overlay burned into the video (OSDEnable).
     osd_timestamp: Optional[bool] = None
-    #: Floodlight automation (autoLightEnable).
+    #: Floodlight automation (autoLightEnable). The vendor app labels this
+    #: "When Someone Appears" -- it is the person-triggered light, not a
+    #: generic schedule, and the three fields below are its settings.
     auto_light: Optional[bool] = None
+    #: How the light behaves when it triggers: "constant" or "flash"
+    #: (lightBehavior 0/1). An unmodelled number is carried through as itself.
+    light_behavior: Optional[str] = None
+    #: How long the light stays on after a trigger, in seconds (LingerDuration).
+    light_linger_duration: Optional[int] = None
+    #: Floodlight level 10-100 (Dimming). Kept apart from `dimming`, which is
+    #: the light platform's brightness -- see _LIGHT_ONLY_ATTR_KEYS.
+    light_brightness: Optional[int] = None
     #: Spoken prompts from the camera speaker (voiceEnable).
     voice_prompts: Optional[bool] = None
     #: HDR (HDRStatus).
@@ -153,6 +163,16 @@ class CameraStatusData(DeviceStatusData):
             self.osd_timestamp = b
         if (b := _as_bool(attr.get("autoLightEnable"))) is not None:
             self.auto_light = b
+        if (v := attr.get("lightBehavior")) is not None:
+            lb = _as_int(v)
+            # Same shape as nightVisionMode: name the values we know and carry
+            # anything else through, so a firmware that grows a third mode
+            # cannot be reported as one of the two we do know.
+            self.light_behavior = (
+                {0: "constant", 1: "flash"}.get(lb, str(lb))
+                if lb is not None else str(v))
+        if (i := _as_int(attr.get("LingerDuration"))) is not None:
+            self.light_linger_duration = i
         if (b := _as_bool(attr.get("voiceEnable"))) is not None:
             self.voice_prompts = b
         if (b := _as_bool(attr.get("HDRStatus"))) is not None:
@@ -201,6 +221,13 @@ class CameraStatusData(DeviceStatusData):
         ``properties`` dict - both share the same camera attribute keys
         (Battery_remaining, Occupancy, SDcardStatus, MotionDetection_*, ...).
         """
+        # Dimming is filtered out below because on a LIGHT it is the entity's
+        # brightness, and a camera's must never be read as one. On a camera it
+        # is nonetheless a real setting -- the floodlight's level, 10-100 in the
+        # device profile, and what the app's Brightness page writes -- so read
+        # it here into its own field rather than letting the filter lose it.
+        if (i := _as_int(attrs.get(CONF_DIMMING))) is not None:
+            self.light_brightness = i
         self.update({
             k: v for k, v in attrs.items()
             if k not in self._LIGHT_ONLY_ATTR_KEYS
@@ -220,6 +247,55 @@ class CameraDeviceInformation(DeviceInformation):
     # for a pan-only camera, [1,2,3,6] = full PTZ).  Empty means unknown - callers
     # should treat unknown as "show all" for backward compatibility.
     ptz_directions: list
+    # Every property identity this MODEL declares in its cloud profile - the
+    # same list the vendor app gates its settings pages on.  Distinct from the
+    # device's `properties` dict, which is what the cloud currently REPORTS and
+    # carries defaults for keys the model never implemented: an A000088 reports
+    # LingerDuration = "30" and, asked directly over LAN, has no such attribute
+    # and ignores writes to it.  Gate a control on this, not on a reported
+    # value, whenever offering it on the wrong model would mean a control that
+    # acknowledges and does nothing.
+    #
+    # Empty means the profile was absent or unreadable, which is UNKNOWN rather
+    # than "declares nothing" - so a caller that has other evidence a setting
+    # works (`Dimming` is real on the A000088 and verified by read-back there,
+    # though the profile omits it) should keep using that evidence instead.
+    declared_properties: frozenset
+
+    @staticmethod
+    def _collect_declared_properties(device: dict) -> frozenset:
+        """Property identities from the model profile, or empty if unreadable.
+
+        Keyed on ``identity``/``code``, never on ``name``: the profile's display
+        name is often a placeholder like
+        ``propertyName_lightBehavior_1679075889207132162``, and a name-keyed
+        search reported that no model declared a property every model declared.
+
+        The profile is remote data of no guaranteed shape, so every level is
+        type-checked rather than trusted; a malformed one yields an empty set
+        instead of killing device setup.
+        """
+        out = set()
+        try:
+            product = device.get(CONF_PRODUCT)
+            modules = product.get(CONF_SERVICE_MODULES) if isinstance(product, dict) else None
+            if not isinstance(modules, list):
+                return frozenset()
+            for service in modules:
+                if not isinstance(service, dict):
+                    continue
+                props = service.get(CONF_PROPERTIES)
+                if not isinstance(props, list):
+                    continue
+                for prop in props:
+                    if not isinstance(prop, dict):
+                        continue
+                    ident = prop.get("identity") or prop.get("code")
+                    if isinstance(ident, str) and ident:
+                        out.add(ident)
+        except Exception:
+            return frozenset()
+        return frozenset(out)
 
     def __init__(self, device: dict[str, Any]) -> None:
         super().__init__(device)
@@ -229,6 +305,7 @@ class CameraDeviceInformation(DeviceInformation):
             str(_aes) if _aes else "")
         self.device_password = device.get("password") or ""
         self.ptz_directions = []
+        self.declared_properties = self._collect_declared_properties(device)
         if CONF_PRODUCT in device and CONF_SERVICE_MODULES in device[CONF_PRODUCT]:
             for service in device[CONF_PRODUCT][CONF_SERVICE_MODULES]:
                 for prop in service.get(CONF_PROPERTIES) or []:

{python_aidot_cameras-1.0.0rc15 → python_aidot_cameras-1.0.0rc17}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-aidot-cameras"
-version = "1.0.0rc15"
+version = "1.0.0rc17"
 description = "Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)"
 readme = "README.md"
 license = "MIT"

{python_aidot_cameras-1.0.0rc15 → python_aidot_cameras-1.0.0rc17/python_aidot_cameras.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 1.0.0rc15
+Version: 1.0.0rc17
 Summary: Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)
 Author-email: cbrightly <chris.brightly@gmail.com>
 License-Expression: MIT

{python_aidot_cameras-1.0.0rc15 → python_aidot_cameras-1.0.0rc17}/python_aidot_cameras.egg-info/SOURCES.txt

@@ -84,6 +84,7 @@ tests/test_answer_sdp_video_pt.py
 tests/test_answer_section_selection.py
 tests/test_audio_mux_offline.py
 tests/test_auto_alarm.py
+tests/test_auto_light_settings.py
 tests/test_avio_ctrl_uses_the_session_dseq.py
 tests/test_avio_request.py
 tests/test_avio_response_parse.py
@@ -104,6 +105,7 @@ tests/test_cloud_count.py
 tests/test_cloud_plan.py
 tests/test_constants_imports_resolve.py
 tests/test_control_verdicts.py
+tests/test_declared_properties.py
 tests/test_deferred_hardening.py
 tests/test_detection_types.py
 tests/test_device_cmd_seq_match.py

python_aidot_cameras-1.0.0rc17/tests/test_auto_light_settings.py

@@ -0,0 +1,143 @@
+"""The camera's "light up when someone appears" settings.
+
+The vendor app calls the master toggle "When Someone Appears" and it is the
+`autoLightEnable` attribute this library already exposes. The three settings
+that sit UNDER it in the app were missing:
+
+  lightBehavior   enum   Constant=0, Flash=1        (default 0)
+  LingerDuration  enum   20 / 30 / 40 / 50 seconds  (default 30)
+  Dimming         int    10..100 step 1             (default 100)
+
+Read from the cloud device profile 2026-09-07 (LK.IPC.A001513, the L2), and
+every one of the three is carried as a live property value by the L2 and by the
+A000088 alike. Of the three, `LingerDuration` and `Dimming` were confirmed on
+hardware to land (written, read back changed, restored); `lightBehavior` acks
+and does NOT land on either model, so the library keeps the setter and Home
+Assistant deliberately ships no control for it -- see
+`async_set_light_behavior`. The A001064 has neither `lightBehavior` nor `LingerDuration` in
+its profile or its properties, so those controls must stay absent there rather
+than appear reading "unknown" -- which is why every getter here answers None
+for a camera that never reported the key.
+"""
+
+import asyncio
+
+import pytest
+
+from aidot_cameras.camera.controls import (
+    LIGHT_BEHAVIORS,
+    LIGHT_LINGER_DURATIONS,
+    _CameraControlsMixin,
+)
+from aidot_cameras.camera.models import CameraStatusData
+
+
+class _Cam(_CameraControlsMixin):
+    device_id = "cam1"
+
+    def __init__(self):
+        self.attrs: list = []
+
+    async def async_set_device_attribute(self, attr, value, **kw):
+        self.attrs.append((attr, value))
+        return True
+
+
+# --- reading -----------------------------------------------------------------
+
+def test_light_behavior_reads_as_a_name_not_a_number():
+    s = CameraStatusData()
+    s.update_from_camera_attributes({"lightBehavior": "1"})
+    assert s.light_behavior == "flash"
+    s.update_from_camera_attributes({"lightBehavior": "0"})
+    assert s.light_behavior == "constant"
+
+
+def test_an_unmodelled_behavior_value_is_carried_through_not_dropped():
+    """A firmware that grows a third mode must not read as one we know."""
+    s = CameraStatusData()
+    s.update_from_camera_attributes({"lightBehavior": "7"})
+    assert s.light_behavior == "7"
+
+
+def test_linger_duration_reads_as_seconds():
+    s = CameraStatusData()
+    s.update_from_camera_attributes({"LingerDuration": "40"})
+    assert s.light_linger_duration == 40
+
+
+def test_trigger_brightness_reads_from_dimming():
+    s = CameraStatusData()
+    s.update_from_camera_attributes({"Dimming": "80"})
+    assert s.light_brightness == 80
+
+
+def test_dimming_still_does_not_become_the_light_entity_brightness():
+    """The camera's Dimming is its floodlight level, and it has its own field.
+
+    It must not leak into `dimming`, which is the LIGHT platform's brightness
+    and is why _LIGHT_ONLY_ATTR_KEYS filters the key in the first place.
+    """
+    s = CameraStatusData()
+    s.update_from_camera_attributes({"Dimming": "80"})
+    assert s.dimming is None
+
+
+def test_a_camera_that_never_reported_them_is_unknown_not_defaulted():
+    s = CameraStatusData()
+    s.update_from_camera_attributes({"MotionDetection_Enable": "1"})
+    assert s.light_behavior is None
+    assert s.light_linger_duration is None
+    assert s.light_brightness is None
+
+
+def test_a_partial_push_does_not_clear_what_a_full_poll_established():
+    s = CameraStatusData()
+    s.update_from_camera_attributes(
+        {"lightBehavior": "1", "LingerDuration": "50", "Dimming": "60"})
+    s.update_from_camera_attributes({"Occupancy": "1"})
+    assert (s.light_behavior, s.light_linger_duration, s.light_brightness) == (
+        "flash", 50, 60)
+
+
+# --- writing -----------------------------------------------------------------
+
+def test_setting_the_behavior_sends_the_camera_its_own_number():
+    cam = _Cam()
+    assert asyncio.run(cam.async_set_light_behavior("flash")) is True
+    assert cam.attrs == [("lightBehavior", 1)]
+
+
+def test_an_unknown_behavior_is_refused_and_nothing_is_sent():
+    cam = _Cam()
+    with pytest.raises(ValueError):
+        asyncio.run(cam.async_set_light_behavior("strobe"))
+    assert cam.attrs == []
+
+
+def test_setting_the_linger_duration_sends_seconds():
+    cam = _Cam()
+    assert asyncio.run(cam.async_set_light_linger_duration(20)) is True
+    assert cam.attrs == [("LingerDuration", 20)]
+
+
+def test_a_duration_the_camera_does_not_offer_is_refused():
+    """The camera enumerates exactly four; 35 would be accepted and ignored."""
+    cam = _Cam()
+    with pytest.raises(ValueError):
+        asyncio.run(cam.async_set_light_linger_duration(35))
+    assert cam.attrs == []
+
+
+def test_trigger_brightness_is_clamped_to_the_range_the_camera_declares():
+    """The profile's minimum is 10, not 0 -- 0 is not "off", it is out of range."""
+    cam = _Cam()
+    asyncio.run(cam.async_set_light_brightness(0))
+    asyncio.run(cam.async_set_light_brightness(150))
+    asyncio.run(cam.async_set_light_brightness(55))
+    assert cam.attrs == [("Dimming", 10), ("Dimming", 100), ("Dimming", 55)]
+
+
+def test_the_offered_values_match_what_the_camera_profile_declares():
+    assert LIGHT_BEHAVIORS == {"constant": 0, "flash": 1}
+    assert LIGHT_LINGER_DURATIONS == (20, 30, 40, 50)

python_aidot_cameras-1.0.0rc17/tests/test_declared_properties.py

@@ -0,0 +1,85 @@
+"""What the MODEL declares it has, as distinct from what the cloud reports.
+
+These are not the same thing, and the difference is what makes a control lie.
+Measured 2026-09-08 on an A000088:
+
+    cloud property list   LingerDuration = "30"
+    the camera, asked
+    directly over LAN     LingerDuration = absent
+    writing it            acked, and nothing changed anywhere
+
+The cloud carries a DEFAULT for a key that model has never implemented. Gating
+a control on "the cloud reported a value" therefore offers it on cameras where
+it cannot work -- which is exactly what shipped in 2.23.0 and had to be pulled
+back. The vendor app gates on the product profile instead, and so must we.
+"""
+
+from aidot_cameras.camera.models import CameraDeviceInformation
+
+
+def _device(props, **extra):
+    d = {"id": "cam1", "aesKey": ["k" * 16], "password": "p",
+         "product": {"serviceModules": [{"identity": "IPC/common attr",
+                                         "properties": props}]}}
+    d.update(extra)
+    return d
+
+
+def test_declared_properties_collects_what_the_model_offers():
+    info = CameraDeviceInformation(_device([
+        {"identity": "LingerDuration", "code": "LingerDuration"},
+        {"identity": "Dimming", "code": "Dimming"},
+    ]))
+    assert "LingerDuration" in info.declared_properties
+    assert "Dimming" in info.declared_properties
+
+
+def test_a_placeholder_display_name_does_not_hide_a_property():
+    """The profile's `name` is often `propertyName_<x>_<productId>`.
+
+    Keying on it instead of `identity` reported "no model declares
+    lightBehavior" when every model did.
+    """
+    info = CameraDeviceInformation(_device([
+        {"identity": "lightBehavior", "code": "lightBehavior",
+         "name": "propertyName_lightBehavior_1679075889207132162"},
+    ]))
+    assert "lightBehavior" in info.declared_properties
+
+
+def test_a_property_with_only_a_code_is_still_collected():
+    info = CameraDeviceInformation(_device([{"code": "Dimming"}]))
+    assert "Dimming" in info.declared_properties
+
+
+def test_a_device_with_no_profile_declares_nothing_and_does_not_raise():
+    info = CameraDeviceInformation({"id": "c", "aesKey": ["k" * 16]})
+    assert info.declared_properties == frozenset()
+
+
+def test_a_malformed_profile_yields_nothing_rather_than_raising():
+    """The profile is remote data of no guaranteed shape.
+
+    Asserted against the collector directly, not through the constructor: the
+    UPSTREAM base class parses the same profile first and indexes it without
+    type checks, so a string where a list belongs raises there before this code
+    runs. That fragility is pre-existing and shared with the light path, so it
+    is noted rather than widened into here.
+    """
+    collect = CameraDeviceInformation._collect_declared_properties
+    for bad in ({"product": {"serviceModules": "nope"}},
+                {"product": {"serviceModules": [None]}},
+                {"product": {"serviceModules": [{"properties": "nope"}]}},
+                {"product": {"serviceModules": [{"properties": ["str"]}]}},
+                {"product": "nope"},
+                {}):
+        assert collect(bad) == frozenset()
+
+
+def test_declaring_nothing_is_not_the_same_as_reporting_nothing():
+    """The A000088 case, locked in: the cloud reports it, the model does not.
+
+    A gate built on the reported value would say yes here. That is the bug.
+    """
+    info = CameraDeviceInformation(_device([{"identity": "Dimming"}]))
+    assert "LingerDuration" not in info.declared_properties