python-aidot-cameras 0.13.0__tar.gz → 0.13.2__tar.gz

{python_aidot_cameras-0.13.0/python_aidot_cameras.egg-info → python_aidot_cameras-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.13.0
+Version: 0.13.2
 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-0.13.0 → python_aidot_cameras-0.13.2}/aidot_cameras/camera/client.py

@@ -854,6 +854,10 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         self._last_frame_time: float = 0.0
         self._keepalive_rtsp_url: Optional[str] = None  # local serve URL (go2rtc pulls)
         self._go2rtc_url: Optional[str] = None           # go2rtc API base (prefer-go2rtc)
+        # Whether WE own this camera's go2rtc stream registration.  False when the
+        # consumer registers the stream itself and passes the URL for viewer
+        # queries only - in which case we must neither add nor REMOVE it.
+        self._go2rtc_manages_stream: bool = True
         self._go2rtc_pull_url: Optional[str] = None      # go2rtc pull URL once registered
         self._go2rtc_task: "Optional[asyncio.Task[None]]" = None
         # Set by the DTLS serve loop once ffmpeg is bound + serving, so
@@ -956,15 +960,27 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         for _key in ("Battery_remaining", "batteryRemaining", "batteryLevel"):
             if _as_int(_props.get(_key)) is not None:
                 return True
-        # The low-power flag: batteryMode=2 is what a camera that sleeps between
-        # sessions reports (see _async_send_camera_command).  Deliberately NOT
-        # keyed on ``powerType``: that name is also the value we SEND in
-        # livePlayReq, we have never observed the cloud returning it as a device
-        # property, and p2pCache - the field right next to it - reads 2 on every
-        # camera including mains ones.  Reading it here would risk classifying a
-        # mains camera as battery, which would put powerType=2 on ITS wire payload
-        # and can leave an A000088 un-armed.  Evidence has to be unambiguous.
-        if _as_int(_props.get("batteryMode")) == 2:
+        # The low-power flag, but ONLY when corroborated.  ``batteryMode=2`` on
+        # its own is not evidence: measured against the live cloud payload, every
+        # MAINS A000088 on this fleet reports ``batteryMode: '2'`` and nothing
+        # else battery-related, while a real battery model reports it alongside
+        # actual telemetry (``Battery_remaining``, ``lowPowerStatus``,
+        # ``charging``).  Trusting it alone classified four mains cameras as
+        # battery, which put powerType=2 on their wire payload and gave them the
+        # battery idle window instead of the mains warm-hold.
+        #
+        # This is the same trap the paragraph below describes for ``powerType`` /
+        # ``p2pCache`` - a field that reads 2 on every camera - so it gets the
+        # same treatment rather than being taken at face value.  Corroboration is
+        # kept (instead of dropping the flag) so a future battery model that
+        # names its level differently is still caught by the flag plus any one
+        # battery-only field.
+        _BATTERY_TELEMETRY = (
+            "Battery_remaining", "batteryRemaining", "batteryLevel",
+            "lowPowerStatus", "charging",
+        )
+        if (_as_int(_props.get("batteryMode")) == 2
+                and any(_props.get(k) is not None for k in _BATTERY_TELEMETRY)):
             return True
         # Already-parsed status, for a camera refreshed from an attribute push
         # rather than from a device-list dict.
@@ -2789,6 +2805,7 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         fast_connect: Optional[bool] = None,
         sdes_audio: Optional[bool] = None,
         go2rtc_url: Optional[str] = None,
+        go2rtc_register: bool = True,
         live_stream_param: Optional[bool] = None,
         serve_relay: Optional[bool] = None,
         stream_idle_s: Optional[float] = None,
@@ -2828,6 +2845,22 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         ``AIDOT_SERVE_RELAY`` env var (default on); set False to serve ffmpeg
         directly on the public port (the pre-0.7.18 behaviour).
 
+        ``go2rtc_url`` points at a go2rtc API base.  It does two things: register
+        the local serve with go2rtc (exposing its low-latency pull URL), and let
+        the idle-release logic ask go2rtc **who is watching**.
+
+        ``go2rtc_register=False`` keeps the second and drops the first, for a
+        consumer that registers the stream itself - registering it twice
+        re-points the source mid-stream and was observed leaving DTLS cameras
+        producing nothing at all.  Such a consumer must still pass ``go2rtc_url``:
+        withholding it does not merely lose a nicety, it silently disables viewer
+        detection, and in SDES **push** mode that is the only viewer signal there
+        is (the serve port is go2rtc's shared RTSP port, where every camera's own
+        publisher is connected, so a socket check would report a viewer for every
+        camera forever).  With no signal ``_viewer_present`` answers "unknown",
+        ``_idle_release_due`` correctly never releases on unknown, and a battery
+        camera's keepalive renews forever against a camera nobody is watching.
+
         ``stream_idle_s`` sets the no-viewer idle-release window in seconds,
         overriding the ``AIDOT_STREAM_IDLE_S`` env default (120).  ``0`` (or
         negative) keeps the warm WebRTC session forever so re-views are instant
@@ -2860,6 +2893,7 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
             return
         self._keepalive_rtsp_url = rtsp_push_url
         self._go2rtc_url = go2rtc_url
+        self._go2rtc_manages_stream = bool(go2rtc_register)
         self._streaming_active = True
         # App parity: keep a battery camera awake for the whole view (mains cams
         # never sleep, so this is a no-op there). Single-instance; cancelled in
@@ -2874,7 +2908,18 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         # Prefer-go2rtc: if a go2rtc server is configured, register the local
         # serve with it once ready and expose its pull URL (ffmpeg fallback
         # otherwise). Opt-in: with no go2rtc_url, behaviour is unchanged.
-        if go2rtc_url:
+        #
+        # ``go2rtc_register=False`` stores the URL for QUERIES ONLY and skips
+        # registration.  That exists for a consumer that registers the stream
+        # itself: registering it twice re-points the source while a stream is
+        # mid-flight, which was observed leaving DTLS cameras producing nothing
+        # at all.  Such a consumer previously had to withhold go2rtc_url
+        # entirely, which silently disabled viewer detection - and in SDES push
+        # mode that means a battery camera can never idle-release, because
+        # ``_viewer_present`` answers "unknown" and ``_idle_release_due``
+        # (correctly) never releases on unknown.  The keepalive then renews
+        # forever against a camera nobody is watching.
+        if go2rtc_url and go2rtc_register:
             self._go2rtc_task = asyncio.ensure_future(self._register_with_go2rtc())
 
     @property
@@ -2934,9 +2979,17 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
             _LOGGER.debug("camera %s: swallowed exception in %s", getattr(self, "device_id", "?"), '_register_with_go2rtc', exc_info=True)
 
     async def _deregister_go2rtc(self) -> None:
-        """Remove this camera's stream from go2rtc (best-effort)."""
+        """Remove this camera's stream from go2rtc (best-effort).
+
+        Only ever removes a registration this client created.  With
+        ``go2rtc_register=False`` the consumer owns the stream and merely lent us
+        the URL to ask who is watching; deleting its stream on stop or
+        idle-release would tear down the very thing it is serving from.
+        """
         base = self._go2rtc_url
         self._go2rtc_pull_url = None
+        if not self._go2rtc_manages_stream:
+            return
         # Deliberately NOT gated on `pull`: go2rtc answers the register call with
         # 400 when it cannot immediately validate the source (a camera that has
         # not started producing yet), yet it still keeps the stream registered.
@@ -3099,22 +3152,21 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
 
         name = self._go2rtc_stream_name()
         base = self._go2rtc_url
-        if not base:
-            # No go2rtc to ask.  In PUSH mode the fallback below is not merely
-            # unavailable, it is WRONG: the "serve port" is go2rtc's shared RTSP
-            # port (8554), where every camera's own publisher is connected, so the
-            # check reports a viewer for every camera forever and nothing ever
-            # releases.  Answer "unknown" instead of a confident lie - the caller
-            # then holds the stream rather than tearing down a live view, and the
-            # honest way out is for the consumer to pass go2rtc_url.
-            if self._keepalive_rtsp_url and not str(
-                    self._keepalive_rtsp_url).startswith("http"):
-                _LOGGER.debug(
-                    "no go2rtc url and the serve is an RTSP push to a shared "
-                    "port; cannot tell whether anyone is watching",
-                )
-                self._viewer_cache = (_now_mono, None)
-                return None
+
+        # In PUSH mode the "serve port" is go2rtc's SHARED RTSP port (8554),
+        # where every camera's own publisher is connected - so the socket
+        # fallback below is not merely unavailable, it is WRONG: it would report
+        # a viewer for every camera forever and nothing would ever release.
+        # Tracked separately from `base` because it must gate the fallback even
+        # when go2rtc IS configured but the query fails.
+        push_mode = bool(self._keepalive_rtsp_url) and not str(
+            self._keepalive_rtsp_url).startswith("http")
+
+        # Ask go2rtc when we can. This is the only viewer signal that works in
+        # push mode, which is why a consumer that registers its own stream
+        # should still pass go2rtc_url with go2rtc_register=False rather than
+        # withholding it (withholding it silently pins push-mode cameras to
+        # "unknown", and unknown never releases).
         if base and name:
             try:
                 import aiohttp
@@ -3128,6 +3180,18 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                     return _answer
             except Exception as exc:
                 _LOGGER.debug("go2rtc viewer check failed: %s", exc)
+
+        if push_mode:
+            # Answer "unknown" instead of a confident lie - the caller then holds
+            # the stream rather than tearing down a live view.
+            _LOGGER.debug(
+                "cannot tell whether anyone is watching: the serve is an RTSP "
+                "push to a shared port and go2rtc %s",
+                "did not answer" if base else "was not configured",
+            )
+            self._viewer_cache = (_now_mono, None)
+            return None
+
         _answer = self._sdes_serve_consumer_present(port)
         self._viewer_cache = (_now_mono, _answer)
         return _answer

{python_aidot_cameras-0.13.0 → python_aidot_cameras-0.13.2}/pyproject.toml

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

{python_aidot_cameras-0.13.0 → python_aidot_cameras-0.13.2/python_aidot_cameras.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.13.0
+Version: 0.13.2
 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-0.13.0 → python_aidot_cameras-0.13.2}/python_aidot_cameras.egg-info/SOURCES.txt

@@ -71,6 +71,7 @@ tests/test_aioice_compat.py
 tests/test_alarm_event.py
 tests/test_backoff.py
 tests/test_battery_detection.py
+tests/test_battery_evidence_corroboration.py
 tests/test_battery_skip_turn.py
 tests/test_constants_imports_resolve.py
 tests/test_deferred_hardening.py
@@ -151,5 +152,6 @@ tests/test_turn_create_permission.py
 tests/test_upstream_compat.py
 tests/test_viewer_check_throttle.py
 tests/test_viewer_presence.py
+tests/test_viewer_present_push_mode.py
 tests/test_wait_or_event.py
 tests/test_wake_readiness_retry.py

{python_aidot_cameras-0.13.0 → python_aidot_cameras-0.13.2}/tests/test_battery_detection.py

@@ -91,9 +91,36 @@ def test_numeric_string_battery_level_counts():
     assert _cam("LK.IPC.A009999", props={"Battery_remaining": "38"}).is_battery_camera
 
 
-def test_battery_mode_two_counts():
-    assert _cam("LK.IPC.A009999", props={"batteryMode": 2}).is_battery_camera is True
-    assert _cam("LK.IPC.A009999", props={"batteryMode": "2"}).is_battery_camera is True
+def test_battery_mode_two_alone_is_not_evidence():
+    """REVISED 2026-08-02 against the live cloud payload.
+
+    This test used to assert that ``batteryMode=2`` alone proves a battery, on
+    the reasonable reading of the field's name. The account's actual device list
+    disproves it: every MAINS A000088 reports ``batteryMode: '2'`` and no other
+    battery field, while real battery models report it alongside real telemetry
+    (``Battery_remaining``, ``lowPowerStatus``, ``charging``).
+
+    Trusting it alone classified four mains cameras as battery, which put
+    powerType=2 on their wire payload and gave them the battery idle window
+    instead of the mains warm-hold - the same trap
+    ``test_power_type_property_is_deliberately_not_evidence`` guards for
+    ``powerType``/``p2pCache``, which also read 2 on every camera.
+    """
+    for value in (2, "2"):
+        assert _cam("LK.IPC.A009999",
+                    props={"batteryMode": value}).is_battery_camera is False
+
+
+def test_battery_mode_two_counts_when_corroborated():
+    """The flag is still a signal - it just needs one real battery field.
+
+    Kept (rather than dropping the flag) so a battery model whose level field we
+    have not seen is still caught, provided it reports any battery-only field.
+    """
+    for extra in ({"charging": "0"}, {"lowPowerStatus": "0"},
+                  {"Battery_remaining": "100"}):
+        assert _cam("LK.IPC.A009999",
+                    props={"batteryMode": "2", **extra}).is_battery_camera is True
 
 
 def test_battery_mode_one_is_not_evidence():

python_aidot_cameras-0.13.2/tests/test_battery_evidence_corroboration.py

@@ -0,0 +1,139 @@
+"""``batteryMode=2`` alone must not make a mains camera look like a battery one.
+
+Every property payload below is the REAL one from the live cloud account
+(2026-08-02), not a construction. That matters: the bug was believing a field
+meant what its name suggests, and only the actual payload disproves it.
+
+    A001513 (real battery): batteryMode=2, Battery_remaining, lowPowerStatus, charging
+    A000088 (MAINS):        batteryMode=2   <- and nothing else
+    A001064 (mains PTZ):    {}
+
+Misclassification is costly in BOTH directions, which is why the corroboration
+rule is "flag AND telemetry" rather than dropping the flag or trusting it:
+
+* battery read as mains loses the SDES TURN pre-allocation (a cloud-woken
+  battery camera has no LAN host candidate, so the relay is its ONLY return
+  path), the keep-alive renew and the HTTP wake;
+* mains read as battery puts powerType=2 on its wire payload and hands it the
+  battery idle window instead of the mains warm-hold - which is what shipped.
+"""
+
+import types
+
+import pytest
+
+from aidot_cameras.camera.client import CameraMixin
+
+# --- real payloads, verbatim from the cloud device list --------------------- #
+L2_BATTERY = {"batteryMode": "2", "lowPowerStatus": "0",
+              "Battery_remaining": "100", "charging": "0"}
+M3_PRO_MAINS = {"batteryMode": "2"}
+PTZ_MAINS: dict = {}
+
+
+class _Cam:
+    """The real classification code on a minimal object.
+
+    The methods and properties are taken straight off CameraMixin rather than
+    reimplemented, so these tests exercise shipping logic; only the three
+    attributes it reads are stubbed.
+    """
+
+    _BATTERY_MODELS = CameraMixin._BATTERY_MODELS
+    _battery_evidence = CameraMixin._battery_evidence
+    is_battery_camera = CameraMixin.is_battery_camera
+    live_power_type = CameraMixin.live_power_type
+
+    def __init__(self, props, model="LK.IPC.A000088"):
+        self._raw_device = {"properties": props}
+        self.info = types.SimpleNamespace(model_id=model)
+        self.status = None
+
+
+def _cam(props, model="LK.IPC.A000088"):
+    return _Cam(props, model)
+
+
+# --------------------------------------------------------------------------- #
+# the regression
+# --------------------------------------------------------------------------- #
+
+@pytest.mark.parametrize("name", ["M3 Pro_180", "Family Room Cam",
+                                  "Bedroom M3 Pro", "Deck"])
+def test_mains_a000088_reporting_batterymode_is_not_a_battery_camera(name):
+    """The shipped bug: four mains cameras classified as battery.
+
+    They report `batteryMode: '2'` and no other battery field. Trusting the flag
+    alone gave them powerType=2 and the battery idle window.
+    """
+    cam = _cam(M3_PRO_MAINS, model="LK.IPC.A000088")
+    assert cam._battery_evidence() is None, name
+    assert cam.is_battery_camera is False, name
+
+
+def test_mains_ptz_with_no_battery_fields_stays_mains():
+    cam = _cam(PTZ_MAINS, model="LK.IPC.A001064")
+    assert cam.is_battery_camera is False
+
+
+# --------------------------------------------------------------------------- #
+# the thing that must NOT regress
+# --------------------------------------------------------------------------- #
+
+def test_a_real_battery_camera_is_still_detected():
+    """A001513 must stay battery - losing this costs it the TURN pre-alloc."""
+    cam = _cam(L2_BATTERY, model="LK.IPC.A001513")
+    assert cam._battery_evidence() is True
+    assert cam.is_battery_camera is True
+
+
+def test_battery_detection_does_not_lean_on_the_model_list_alone():
+    """Evidence must carry it, so an unlisted battery revision still works."""
+    cam = _cam(L2_BATTERY, model="LK.IPC.A999999-2")
+    assert cam.is_battery_camera is True
+
+
+def test_a_listed_model_with_no_properties_is_still_battery():
+    """The model list is the backstop when the payload carries nothing."""
+    cam = _cam({}, model="LK.IPC.A001513")
+    assert cam._battery_evidence() is None
+    assert cam.is_battery_camera is True
+
+
+# --------------------------------------------------------------------------- #
+# the corroboration rule itself
+# --------------------------------------------------------------------------- #
+
+@pytest.mark.parametrize("corroborating", [
+    {"Battery_remaining": "55"},
+    {"batteryRemaining": "55"},
+    {"batteryLevel": "55"},
+    {"lowPowerStatus": "0"},
+    {"charging": "1"},
+])
+def test_batterymode_counts_when_any_battery_field_corroborates(corroborating):
+    """The flag is kept as a signal, not discarded - it just needs backing.
+
+    This is what catches a future battery model whose level field we have not
+    seen, provided it reports any battery-only field at all.
+    """
+    cam = _cam({"batteryMode": "2", **corroborating}, model="LK.IPC.A000088")
+    assert cam._battery_evidence() is True
+
+
+def test_a_zero_valued_battery_field_still_corroborates():
+    """`charging: '0'` is a report, not an absence - presence is the signal."""
+    cam = _cam({"batteryMode": "2", "charging": "0"}, model="LK.IPC.A000088")
+    assert cam._battery_evidence() is True
+
+
+def test_evidence_never_returns_false_so_it_cannot_demote_a_known_model():
+    """It may only ADD to the battery set, never remove - preserved property."""
+    for props in (M3_PRO_MAINS, PTZ_MAINS, {"batteryMode": "1"}):
+        assert _cam(props)._battery_evidence() in (True, None)
+
+
+def test_power_type_follows_the_classification():
+    """powerType on the wire must never disagree with the battery guards."""
+    assert _cam(M3_PRO_MAINS, model="LK.IPC.A000088").live_power_type == 1
+    assert _cam(L2_BATTERY, model="LK.IPC.A001513").live_power_type == 2

{python_aidot_cameras-0.13.0 → python_aidot_cameras-0.13.2}/tests/test_live_validate_policy.py

@@ -279,3 +279,58 @@ def test_media_seen_accepts_dtls_frames(lv):
     ok, evidence = lv._media_seen(object(), frames=42, out_path=None)
     assert ok
     assert evidence["frames"] == 42
+
+
+# --------------------------------------------------------------------------- #
+# absent-camera early exit
+# --------------------------------------------------------------------------- #
+
+def test_slotless_budget_is_smaller_than_the_dtls_budget(lv):
+    """The early exit must actually save attempts, or it is decoration."""
+    assert lv.SLOTLESS_MAX_ATTEMPTS < lv.ATTEMPTS_DTLS
+
+
+def test_one_retry_is_still_allowed_for_a_single_missed_response(lv):
+    """A camera silent ONCE may just have missed a webrtcResp on a busy account.
+
+    Dropping to a single attempt would turn one unlucky timeout into a failed
+    release, so the budget must be >1.
+    """
+    assert lv.SLOTLESS_MAX_ATTEMPTS > 1
+
+
+def test_only_the_no_session_verdict_is_treated_as_absent(lv):
+    """ERROR alone means no session was opened, so nothing was probabilistic.
+
+    NO_MEDIA and BUSY DID reach the camera - those are exactly the flaky cases
+    the retry budget exists for, and they must keep their full allowance.
+    """
+    assert lv._SLOTLESS_VERDICTS == frozenset({"ERROR"})
+    for reached_the_camera in ("PASS", "NO_MEDIA", "BUSY"):
+        assert reached_the_camera not in lv._SLOTLESS_VERDICTS
+
+
+def test_a_camera_that_reached_us_once_keeps_its_full_budget(lv):
+    """The early exit requires EVERY attempt to be slotless.
+
+    A camera that returns NO_MEDIA then ERROR is flaky, not absent, and must not
+    be cut short - which is why the loop checks all() rather than the last one.
+    """
+    mixed = [{"verdict": "NO_MEDIA"}, {"verdict": "ERROR"}]
+    assert not all(a["verdict"] in lv._SLOTLESS_VERDICTS for a in mixed)
+
+    absent = [{"verdict": "ERROR"}, {"verdict": "ERROR"}]
+    assert all(a["verdict"] in lv._SLOTLESS_VERDICTS for a in absent)
+
+
+def test_an_absent_camera_still_reaches_a_failing_verdict(lv, tmp_path):
+    """Skipping attempts must not soften the verdict - absent is still ERROR.
+
+    The saving is wall clock, not leniency: a required model with no working
+    camera must still fail the release.
+    """
+    report = {"cameras": [_cam(lv, "LK.IPC.A000088", "ERROR", name="Deck")]}
+    report["cameras"][0]["attempts_used"] = lv.SLOTLESS_MAX_ATTEMPTS
+    assert lv._summarize(report, _args(tmp_path)) == 1
+    assert report["verdict"] == "FAIL"
+    assert report["required_failed"] == ["Deck"]