python-aidot-cameras 0.17.1__tar.gz → 0.17.3b2__tar.gz

{python_aidot_cameras-0.17.1/python_aidot_cameras.egg-info → python_aidot_cameras-0.17.3b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.17.1
+Version: 0.17.3b2
 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
@@ -66,6 +66,40 @@ Other battery models (A001108, A001360) are recognized in code with the same
 battery handling. See [`docs/CAMERAS.md`](docs/CAMERAS.md#supported-cameras) for
 the authoritative table and per-model notes.
 
+## Local (LAN) control and account ownership
+
+Local control over the devices' TCP:10000 channel - both the light/plug protocol
+and this package's `CameraLanClient` - is accepted **only for the account that
+owns the devices**. A member of a shared home is rejected at the device, even
+though the cloud happily hands that member a full device list, complete with the
+per-device `password` and `aesKey`.
+
+The rejection is easy to misread, because the device answers with a code that
+varies by firmware family and a message that blames the wrong thing:
+
+| Model | Ack |
+| --- | --- |
+| `LK.light.A001493` | 400 `not equal abort user id or password` |
+| `LK.light.A001497`, `LK.plug.A001535` | 4354 `fail` |
+| `LK.IPC.A000088` | 4352 `fail` |
+
+The A001493's message is the honest one: it is the **user id** that does not
+match, not the password. Every credential in the request can be correct and the
+login will still be refused if the `userId` is not the owner's.
+
+Verified 2026-08-08 against ten devices across four model families: every one
+returns 200 for the owning account and one of the codes above for a shared-home
+member.
+
+**If local control never engages, check which account the integration is signed
+in as before looking anywhere else.** A dedicated or secondary login - the sort
+of thing you might use to avoid contending with a phone app over a rotating
+refresh token - will control everything fine through the cloud and never once
+log in locally.
+
+Cameras' live video is unaffected either way: it is WebRTC signaled over cloud
+MQTT and does not use this path.
+
 ## Library install
 
 Install from PyPI (the simplest, recommended method):
@@ -178,6 +212,9 @@ audio, idle release, the sprop cache path) are documented in
 | `AIDOT_DTLS_FAST_LIVEPLAY` | The DTLS (A000088) analogue: skip the `livePlayReq`-echo and `livePlayResp` waits (the dominant LAN cold-start cost) while keeping the full ICE/TURN/DTLS handshake, so remote/relay viewing is unaffected. **On by default**; set to `0`/`false`/`no`/`off` to disable. | enabled (on) |
 | `AIDOT_PERSISTENT_MQTT` | Reuse ONE account-level persistent MQTT connection for commands, attribute fetches, and stream-open signaling (matching the official app) instead of connecting per operation. **On by default** (live soaks cut SDES NO_MEDIA from ~57% to ~11-19%); set to `0`/`false`/`no`/`off` to disable. | enabled (on) |
 | `AIDOT_SERVE_RELAY` | Hold the public stream port via an internal relay that proxies to ffmpeg, so the first (cold) view connects instead of failing while ffmpeg can't pre-bind the port. Set to `0` to serve ffmpeg directly. | `1` (enabled) |
+| `AIDOT_LOGIN_RETRY_LIMIT` | Consecutive failed LAN logins after which a device is left alone (it is retried again the next time something asks for it). Applies to every device, camera or not - the devices that hit this are lights. | `6` |
+| `AIDOT_LOGIN_RETRY_CAP_S` | Ceiling on the exponential delay between those retries. | `60` |
+| `AIDOT_LOGIN_CONNECT_TIMEOUT_S` | Ceiling on one LAN connect+login attempt. A device that completes the TCP handshake and then stops answering is abandoned and its socket closed rather than parking the attempt forever. | `20` |
 | `AIDOT_LIVESTREAM_PARAM` | **No-op (ignored).** Formerly requested the cloud `liveStreamParam` pre-connect for battery cameras. That call provisions the camera toward AWS KVS, so it sends its media there instead of to this library and the live view negotiates and then shows nothing - and battery cameras were the only ones it applied to. Setting it (or `start_keepalive(live_stream_param=True)`) logs one warning and changes nothing. | ignored |
 
 ### Security hardening

{python_aidot_cameras-0.17.1 → python_aidot_cameras-0.17.3b2}/README.md

@@ -35,6 +35,40 @@ Other battery models (A001108, A001360) are recognized in code with the same
 battery handling. See [`docs/CAMERAS.md`](docs/CAMERAS.md#supported-cameras) for
 the authoritative table and per-model notes.
 
+## Local (LAN) control and account ownership
+
+Local control over the devices' TCP:10000 channel - both the light/plug protocol
+and this package's `CameraLanClient` - is accepted **only for the account that
+owns the devices**. A member of a shared home is rejected at the device, even
+though the cloud happily hands that member a full device list, complete with the
+per-device `password` and `aesKey`.
+
+The rejection is easy to misread, because the device answers with a code that
+varies by firmware family and a message that blames the wrong thing:
+
+| Model | Ack |
+| --- | --- |
+| `LK.light.A001493` | 400 `not equal abort user id or password` |
+| `LK.light.A001497`, `LK.plug.A001535` | 4354 `fail` |
+| `LK.IPC.A000088` | 4352 `fail` |
+
+The A001493's message is the honest one: it is the **user id** that does not
+match, not the password. Every credential in the request can be correct and the
+login will still be refused if the `userId` is not the owner's.
+
+Verified 2026-08-08 against ten devices across four model families: every one
+returns 200 for the owning account and one of the codes above for a shared-home
+member.
+
+**If local control never engages, check which account the integration is signed
+in as before looking anywhere else.** A dedicated or secondary login - the sort
+of thing you might use to avoid contending with a phone app over a rotating
+refresh token - will control everything fine through the cloud and never once
+log in locally.
+
+Cameras' live video is unaffected either way: it is WebRTC signaled over cloud
+MQTT and does not use this path.
+
 ## Library install
 
 Install from PyPI (the simplest, recommended method):
@@ -147,6 +181,9 @@ audio, idle release, the sprop cache path) are documented in
 | `AIDOT_DTLS_FAST_LIVEPLAY` | The DTLS (A000088) analogue: skip the `livePlayReq`-echo and `livePlayResp` waits (the dominant LAN cold-start cost) while keeping the full ICE/TURN/DTLS handshake, so remote/relay viewing is unaffected. **On by default**; set to `0`/`false`/`no`/`off` to disable. | enabled (on) |
 | `AIDOT_PERSISTENT_MQTT` | Reuse ONE account-level persistent MQTT connection for commands, attribute fetches, and stream-open signaling (matching the official app) instead of connecting per operation. **On by default** (live soaks cut SDES NO_MEDIA from ~57% to ~11-19%); set to `0`/`false`/`no`/`off` to disable. | enabled (on) |
 | `AIDOT_SERVE_RELAY` | Hold the public stream port via an internal relay that proxies to ffmpeg, so the first (cold) view connects instead of failing while ffmpeg can't pre-bind the port. Set to `0` to serve ffmpeg directly. | `1` (enabled) |
+| `AIDOT_LOGIN_RETRY_LIMIT` | Consecutive failed LAN logins after which a device is left alone (it is retried again the next time something asks for it). Applies to every device, camera or not - the devices that hit this are lights. | `6` |
+| `AIDOT_LOGIN_RETRY_CAP_S` | Ceiling on the exponential delay between those retries. | `60` |
+| `AIDOT_LOGIN_CONNECT_TIMEOUT_S` | Ceiling on one LAN connect+login attempt. A device that completes the TCP handshake and then stops answering is abandoned and its socket closed rather than parking the attempt forever. | `20` |
 | `AIDOT_LIVESTREAM_PARAM` | **No-op (ignored).** Formerly requested the cloud `liveStreamParam` pre-connect for battery cameras. That call provisions the camera toward AWS KVS, so it sends its media there instead of to this library and the live view negotiates and then shows nothing - and battery cameras were the only ones it applied to. Setting it (or `start_keepalive(live_stream_param=True)`) logs one warning and changes nothing. | ignored |
 
 ### Security hardening

{python_aidot_cameras-0.17.1 → python_aidot_cameras-0.17.3b2}/aidot_cameras/camera/client.py

@@ -398,6 +398,21 @@ _BUSY_BACKOFF_S = float(os.environ.get("AIDOT_BUSY_BACKOFF_S", "20"))
 _FUTILE_KEEPALIVE_LIMIT = int(os.environ.get("AIDOT_FUTILE_KEEPALIVE_LIMIT", "5"))
 
 
+def _next_no_media_streak(no_media_streak: int, healthy: bool) -> int:
+    """The streak after a keepalive session that was (or was not) healthy.
+
+    The ceiling counts CONSECUTIVE failures, so a session that delivered media
+    resets it to zero. Without that reset the count is cumulative and a camera
+    that merely fails occasionally - five scattered no-media sessions spread
+    across a day, each one separated by sessions that worked - eventually trips
+    a limit meant for cameras that never deliver anything at all, and has its
+    background keepalive stopped for good.
+    """
+    if healthy:
+        return 0
+    return no_media_streak + 1
+
+
 def _should_abandon_keepalive(no_media_streak: int, *, is_battery: bool,
                               limit: int = _FUTILE_KEEPALIVE_LIMIT) -> bool:
     """Should the background keepalive stop reopening this camera?
@@ -2622,7 +2637,14 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                         _session.wait_done(),
                         timeout=_sdes_snap_seconds + 80,
                     )
-                except (TimeoutError, _asyncio.CancelledError):
+                except _asyncio.CancelledError:
+                    # Not the same event as a timeout.  A timeout means the
+                    # camera was slow and whatever landed in the temp file is
+                    # worth salvaging; a cancellation means the caller is gone,
+                    # so salvaging it (another ffmpeg, up to 15s) is work nobody
+                    # is waiting for and it stops shutdown from completing.
+                    raise
+                except TimeoutError:
                     pass
                 finally:
                     await _session.stop()
@@ -3599,6 +3621,7 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
             # Adaptive bookkeeping: a fast attempt that never delivered media
             # latches the loop onto the full relay path for its remaining opens.
             _healthy = session.last_media_monotonic > 0.0
+            _no_media_streak = _next_no_media_streak(_no_media_streak, _healthy)
             if _healthy:
                 # A session that delivered media is a real, cleanly-used session;
                 # the next open should be a fresh one rather than re-offering on a
@@ -3606,9 +3629,7 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                 _loop_peer_id = self.generate_webrtc_peer_id(
                     live_type=2, stream_id=0, sdes=True)
                 _peer_reuses = 0
-                _no_media_streak = 0
             else:
-                _no_media_streak += 1
                 if _should_abandon_keepalive(
                         _no_media_streak, is_battery=self.is_battery_camera):
                     # Every open so far has cost the camera a wake and returned
@@ -3622,6 +3643,18 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                         self.device_id, _no_media_streak,
                     )
                     self._streaming_active = False
+                    # Same teardown the idle-release exit does. Leaving the
+                    # go2rtc stream registered points it at a serve port with
+                    # nothing listening, so a viewer attaching to a dormant
+                    # camera gets "connection refused" instead of a clean miss -
+                    # exactly what the idle-release path exists to avoid.
+                    self._cancel_keepalive_renew()
+                    try:
+                        await self._deregister_go2rtc()
+                    except Exception:
+                        _LOGGER.debug("camera %s: go2rtc deregister after "
+                                      "abandon failed", self.device_id,
+                                      exc_info=True)
                     return
             if _use_fast and not _healthy and not _fast_failed:
                 _LOGGER.info(

{python_aidot_cameras-0.17.1 → python_aidot_cameras-0.17.3b2}/aidot_cameras/camera/lan_control.py

@@ -164,6 +164,26 @@ class CameraLanError(Exception):
     """A local control operation failed (connect, login, or protocol error)."""
 
 
+class CameraLanLoginRejected(CameraLanError):
+    """The device advertised local control and then refused our login.
+
+    Separate from its parent because the two mean opposite things to a caller.
+    A device that does not offer local control is ordinary and should be quiet;
+    a device that offers it, accepts the connection, decrypts our request with
+    its own key, and STILL answers with a non-200 ack is a defect - either in
+    what we send or in the device - and the caller should be able to say so out
+    loud rather than logging it at the same level as "not supported here".
+
+    ``ack`` is the device's own code, because the refusals differ by family and
+    the number is the only handle on which one happened: A000088 cameras answer
+    4352, A001497 lights and A001535 plugs 4354, A001493 lights 400.
+    """
+
+    def __init__(self, message: str, ack: Any = None) -> None:
+        super().__init__(message)
+        self.ack = ack
+
+
 class CameraLanClient:
     """Short-lived local device-control client for one camera.
 
@@ -291,9 +311,13 @@ class CameraLanClient:
             ) from exc
         if ack != 200:
             # The real device rejected our key-authenticated login; stop using
-            # the LAN path and revert to cloud.
+            # the LAN path and revert to cloud.  Raised as the specific type so
+            # a caller can tell this apart from a device that never offered
+            # local control - see CameraLanLoginRejected.
             self._eligible = False
-            raise CameraLanError(f"{self.device_id}: login rejected ack={ack}")
+            raise CameraLanLoginRejected(
+                f"{self.device_id}: login rejected ack={ack}", ack=ack
+            )
         return (resp.get("payload") or {}).get("ascNumber", 1)
 
     # -- public control ---------------------------------------------------- #