@camera.ui/server 2.0.22 → 2.0.23

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/sensor/base.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import asyncio
-import contextlib
 import time
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Mapping
@@ -19,8 +18,6 @@ from uuid import uuid4
 
 from ..internal.sensor_rpc import (
     CapabilityUpdateFn,
-    PropertyChangedEvent,
-    PropertyChangeListener,
     PropertyUpdateFn,
     SensorJSON,
 )
@@ -32,75 +29,143 @@ if TYPE_CHECKING:
 
 
 class SensorType(StrEnum):
-    """Type of sensor. Each maps to a smart-home concept (HomeKit service)."""
-
-    Motion = "motion"  # Video-based motion detection
-    Object = "object"  # Object detection (person, vehicle, animal, etc.)
-    Audio = "audio"  # Audio event detection (glass break, scream, etc.)
-    Face = "face"  # Face detection and recognition
-    LicensePlate = "licensePlate"  # License plate detection and OCR
-    Classifier = "classifier"  # General-purpose image classifier
-    Clip = "clip"  # CLIP embedding sensor
-    ObjectAssist = "objectAssist"  # Object assist that locates objects in a frame so secondaries get real crops from camera-side detections
-    Contact = "contact"  # Contact/open-close sensor (door, window)
-    Humidity = "humidity"  # Humidity level sensor
-    Leak = "leak"  # Water leak detection sensor
-    Occupancy = "occupancy"  # Occupancy/presence detection sensor
-    Smoke = "smoke"  # Smoke detection sensor
-    Temperature = "temperature"  # Temperature sensor
-    Light = "light"  # Light on/off and brightness control
-    Siren = "siren"  # Siren on/off and volume control
-    Switch = "switch"  # Generic on/off switch
-    Lock = "lock"  # Lock/unlock control
-    Garage = "garage"  # Garage door open/close control
-    PTZ = "ptz"  # Pan-tilt-zoom camera control
-    SecuritySystem = "securitySystem"  # Security system arm/disarm control
-    Doorbell = "doorbell"  # Doorbell ring trigger
-    Battery = "battery"  # Battery level and charging state
+    """Type of sensor. "Sensor" is camera.ui's umbrella term for the smallest
+    smart-home unit. It covers measuring devices and controllable ones alike. The concrete
+    classes carry the real meaning (`LightControl`, `MotionSensor`, ...).
+    Plugins create sensors of these types, either standalone via the sensor
+    manager or attached to a camera via `camera.addSensor()`.
+    """
+
+    Motion = "motion"
+    """Video-based motion detection."""
+    Object = "object"
+    """Object detection (person, vehicle, animal, etc.)."""
+    Audio = "audio"
+    """Audio event detection (glass break, scream, etc.)."""
+    Face = "face"
+    """Face detection and recognition."""
+    LicensePlate = "licensePlate"
+    """License plate detection and OCR."""
+    Classifier = "classifier"
+    """General-purpose image classifier."""
+    Clip = "clip"
+    """CLIP embedding generation for semantic search."""
+    ObjectAssist = "objectAssist"
+    """Locates objects in a frame so secondary detectors get real crops from camera-side detections."""
+    Contact = "contact"
+    """Contact/open-close sensor (door, window)."""
+    Humidity = "humidity"
+    """Humidity sensor (0-100%)."""
+    Leak = "leak"
+    """Water leak detector."""
+    Occupancy = "occupancy"
+    """Occupancy/presence sensor."""
+    Smoke = "smoke"
+    """Smoke detector."""
+    Temperature = "temperature"
+    """Temperature sensor (°C)."""
+    Light = "light"
+    """Light on/off and brightness control."""
+    Siren = "siren"
+    """Siren on/off and volume control."""
+    Switch = "switch"
+    """Generic on/off switch."""
+    Lock = "lock"
+    """Lock/unlock control."""
+    Garage = "garage"
+    """Garage door opener."""
+    PTZ = "ptz"
+    """Pan-tilt-zoom camera control."""
+    SecuritySystem = "securitySystem"
+    """Security system arm/disarm control."""
+    Doorbell = "doorbell"
+    """Doorbell ring trigger."""
+    Battery = "battery"
+    """Battery level and charging state."""
 
 
 class SensorCategory(StrEnum):
-    """Categorizes a sensor's role in the system."""
+    """Categorizes a sensor's role in the system.
+
+    Determines how the backend treats the sensor (read-only vs. controllable).
+    """
 
-    Sensor = "sensor"  # Read-only detection sensor
-    Control = "control"  # Controllable sensor with set methods
-    Trigger = "trigger"  # Event trigger
-    Info = "info"  # Informational read-only state
+    Sensor = "sensor"
+    """Read-only detection sensor (motion, object, audio, etc.)."""
+    Control = "control"
+    """Controllable sensor with set methods (light, siren, PTZ, etc.)."""
+    Trigger = "trigger"
+    """Event trigger (doorbell ring)."""
+    Info = "info"
+    """Informational read-only state (battery level)."""
 
 
 class SensorPropertyChangeData(TypedDict):
     """Emitted on the onPropertyChanged Observable."""
 
     property: str
+    """Name of the changed property."""
     value: object
+    """New value of the property."""
     timestamp: int
+    """Origin timestamp in milliseconds since epoch."""
 
 
 @runtime_checkable
 class SensorLike(Protocol):
-    """Read-only proxy interface for a sensor. Use this type when consuming sensors, not creating them.
+    """Read-only view of a sensor, as other plugins and the backend see it.
 
-    All state-modifying methods (`setOn`, `reportDetections`, etc.) live on the
+    Use this type when consuming sensors, not when creating them. All
+    state-modifying methods (`setOn`, `reportDetections`, etc.) live on the
     concrete sensor classes, not on `SensorLike`. Code that holds a `SensorLike`
-    reference can only READ state and observe changes.
+    reference can only read state and observe changes.
     """
 
     @property
     def id(self) -> str: ...
+
     @property
     def type(self) -> SensorType: ...
+
     @property
     def name(self) -> str: ...
+
+    @property
+    def nativeId(self) -> str | None: ...
+
     @property
     def pluginId(self) -> str | None: ...
+
     @property
     def capabilities(self) -> list[str]: ...
 
+    @property
+    def connected(self) -> bool: ...
+
+    @property
+    def assignedCameraIds(self) -> list[str]: ...
+
+    @property
+    def assignmentLocked(self) -> bool: ...
+
     @property
     def displayName(self) -> str: ...
+
     @displayName.setter
     def displayName(self, value: str) -> None: ...
 
+    @property
+    def onPropertyChanged(self) -> Observable[Any]: ...
+
+    @property
+    def onCapabilitiesChanged(self) -> Observable[Any]: ...
+
+    @property
+    def onConnectedChanged(self) -> Observable[bool]: ...
+
+    @property
+    def onAssignmentChanged(self) -> Observable[list[str]]: ...
+
     def getValue(self, property: str) -> Any | None:
         """Get the current value of a sensor property."""
         ...
@@ -110,23 +175,17 @@ class SensorLike(Protocol):
         ...
 
     async def updateValue(self, property: str, value: Any) -> None:
-        """Write a property generically. Cross-process bridges (e.g. HomeKit) bind
-        generic property names to UI characteristics and call this on a sensor
-        proxy — the proxy forwards via RPC to the owning sensor, where control
-        sensor classes (`Light`, `Siren`, etc.) override `updateValue` to dispatch
-        to the appropriate semantic method (`setOn`, `setActive`, ...). This means
-        plugin-side hardware-action overrides ARE honored end-to-end.
-
-        Plugin authors **must not** call this — they should call the semantic
-        methods directly on the concrete sensor class.
+        """Generic property write used by cross-process bridges.
+
+        The owning sensor dispatches it to the matching semantic method, so
+        plugin-side hardware overrides still run. Plugin authors call the
+        semantic methods instead.
         """
         ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[Any]: ...
-    @property
-    def onCapabilitiesChanged(self) -> Observable[Any]: ...
-    def hasCapability(self, capability: str) -> bool: ...
+    def hasCapability(self, capability: str) -> bool:
+        """Whether the sensor advertises the given capability."""
+        ...
 
 
 TProperties = TypeVar("TProperties", bound=Mapping[str, Any])
@@ -135,9 +194,10 @@ TCapability = TypeVar("TCapability", bound=str)
 
 
 class PropertiesProxy(Generic[TProperties]):
-    """Read-only view over a sensor's property store. Subclasses use this to read
-    current state when implementing semantic methods (e.g. `if self.props.blocked: return`).
-    Writes go through `Sensor._write_state` — assignments through this proxy are not allowed.
+    """Read-only view over a sensor's property store.
+
+    Subclasses read current state from here when implementing semantic methods.
+    Writes go through `Sensor._write_state`, assignments through this proxy raise.
     """
 
     _store: dict[str, Any]
@@ -170,26 +230,41 @@ class PropertiesProxy(Generic[TProperties]):
 
 
 class Sensor(ABC, Generic[TProperties, TStorage, TCapability]):
-    """Abstract base class for all sensors. Plugins extend this (or use specialized subclasses like MotionSensor, LightControl, etc.) to implement sensor logic."""
+    """Abstract base class for all sensors. Plugins extend this (or use specialized
+    subclasses like MotionSensor, LightControl, etc.) to implement sensor logic.
+
+    Sensors are standalone entities: the plugin supplies the durable identity
+    (``native_id``), everything else belongs to the user: camera assignments,
+    display name and whether the sensor is exported or not. A plugin
+    never decides where its sensor is used and never handles the export itself.
+
+    The ``id`` is provisional until registration, when the host swaps in the
+    persistent entity id. Reading ``storage`` before registration raises.
+    Override ``storage_schema`` to return a JSON schema and get a per-sensor
+    settings UI.
+    """
 
     _requires_frames: bool = False
 
-    def __init__(self, name: str) -> None:
-        self._camera_id: str | None = None
+    def __init__(self, name: str, *, native_id: str | None = None) -> None:
         self._name = name
-        self._id = str(uuid4())
+        self._id = str(uuid4())  # provisional id, replaced by the host's persistent id at registration
+        self._native_id = native_id
         self._display_name = name
         self._plugin_id: str | None = None
+        self._assigned_camera_ids: list[str] = []
+        self._assignment_locked = False
         self._capabilities: list[TCapability] = []
         self._property_changed_subject: Subject[SensorPropertyChangeData] = Subject()
         self._capabilities_changed_subject: Subject[list[TCapability]] = Subject()
-        self._detailed_listeners: set[PropertyChangeListener] = set()
-        self._assignment_changed_subject: Subject[bool] = Subject()
+        self._assignment_changed_subject: Subject[list[str]] = Subject()
+        self._connected_changed_subject: Subject[bool] = Subject()
 
         self._update_fn: PropertyUpdateFn | None = None
         self._capabilities_change_fn: Callable[[list[str]], None] | None = None
         self._storage: DeviceStorage[TStorage] | None = None
-        self._is_assigned: bool = False
+        self._registered: bool = False
+        self._active: bool = False
         self._properties_store: dict[str, Any] = {}
         self._properties_proxy: PropertiesProxy[TProperties] = PropertiesProxy(
             self._properties_store,
@@ -207,6 +282,10 @@ class Sensor(ABC, Generic[TProperties, TStorage, TCapability]):
     def id(self) -> str:
         return self._id
 
+    @property
+    def nativeId(self) -> str | None:
+        return self._native_id
+
     @property
     def name(self) -> str:
         return self._name
@@ -217,16 +296,6 @@ class Sensor(ABC, Generic[TProperties, TStorage, TCapability]):
 
     @displayName.setter
     def displayName(self, value: str) -> None:
-        """Set the display name (the only mutable identifier on a sensor).
-
-        Args:
-            value: Human-readable label shown in the UI.
-
-        Example:
-            ```python
-            sensor.displayName = "Front Door Motion"
-            ```
-        """
         self._display_name = value
 
     @property
@@ -234,8 +303,16 @@ class Sensor(ABC, Generic[TProperties, TStorage, TCapability]):
         return self._plugin_id
 
     @property
-    def cameraId(self) -> str | None:
-        return self._camera_id
+    def assignedCameraIds(self) -> list[str]:
+        return self._assigned_camera_ids.copy()
+
+    @property
+    def assignmentLocked(self) -> bool:
+        return self._assignment_locked
+
+    @property
+    def connected(self) -> bool:
+        return self._registered
 
     @property
     def capabilities(self) -> list[TCapability]:
@@ -243,6 +320,7 @@ class Sensor(ABC, Generic[TProperties, TStorage, TCapability]):
 
     @capabilities.setter
     def capabilities(self, value: list[TCapability]) -> None:
+        """Set capabilities, deduplicated, and notify backend plus local listeners."""
         self._capabilities = list(dict.fromkeys(value))
         if self._capabilities_change_fn:
             caps_list: list[str] = [str(c) for c in self._capabilities]
@@ -255,18 +333,16 @@ class Sensor(ABC, Generic[TProperties, TStorage, TCapability]):
 
     @property
     def storage_schema(self) -> list[JsonSchema]:
-        """Override to provide a JSON schema for per-sensor storage settings UI."""
         return []
 
     @property
     def storage(self) -> DeviceStorage[TStorage]:
-        """Per-sensor persistent storage. Raises if not yet added to a camera."""
-        assert self._storage is not None, "Storage not initialized - sensor not added to camera yet"
+        assert self._storage is not None, "Storage not initialized - sensor not registered yet"
         return self._storage
 
     @property
     def isAssigned(self) -> bool:
-        return self._is_assigned
+        return len(self._assigned_camera_ids) > 0
 
     @property
     def props(self) -> PropertiesProxy[TProperties]:
@@ -276,164 +352,68 @@ class Sensor(ABC, Generic[TProperties, TStorage, TCapability]):
     def rawProps(self) -> dict[str, Any]:
         return self._properties_store
 
-    def _write_state(self, partial: Mapping[str, Any]) -> None:
-        """SDK-internal state-write API. Performs deep-equal change detection over
-        the partial, writes changed properties to the store, fires a single batched
-        RPC update with the delta, and notifies local listeners per-property.
-
-        Used by the semantic helper methods on each sensor type (`setOn`,
-        `reportDetections`, etc.) — **not for plugin authors**. Plugin code should
-        call the semantic helpers, not write state directly.
-
-        One `_write_state` call → one `_update_fn` invocation. The receiver sees an
-        atomic state transition for this sensor.
-        """
-        delta: dict[str, Any] = {}
-        changes: list[tuple[str, Any, Any]] = []
-
-        for key, value in partial.items():
-            if value is None:
-                continue
-            previous = self._properties_store.get(key)
-            if is_equal(previous, value, True):
-                continue
-            self._properties_store[key] = value
-            delta[key] = value
-            changes.append((key, value, previous))
-
-        if not delta:
-            return
-
-        if self._update_fn:
-            self._update_fn(delta)
-
-        for key, value, previous in changes:
-            self._notifyListeners(key, value, previous)
+    @property
+    def onAssignmentChanged(self) -> Observable[list[str]]:
+        return self._assignment_changed_subject.as_observable()
 
-    def _normalize_reported_detections(
-        self,
-        detected: bool,
-        detections: list[dict[str, Any]] | None,
-        fallback_label: str,
-        fallback_extra: dict[str, Any] | None = None,
-    ) -> list[dict[str, Any]]:
-        """Helper for `reportDetections(detected, detections?)` flows.
-
-        - If `detected` is False → returns `[]` (clear).
-        - If `detected` is True and `detections` has items → returns them, substituting a full-frame box where missing.
-        - If `detected` is True and `detections` is missing/empty → returns a single
-          synthesized full-frame detection with the given `fallback_label` and any
-          `fallback_extra` fields (used for type-specific properties like `attribute`,
-          `plateText`, etc.).
-        """
-        if not detected:
-            return []
-        if detections:
-            # Smart-camera plugins report labels without coordinates, while
-            # downstream consumers (detection coordinator, zone matching)
-            # require a box on every detection — substitute full-frame.
-            return [
-                detection
-                if detection.get("box")
-                else {**detection, "box": {"x": 0, "y": 0, "width": 1, "height": 1}}
-                for detection in detections
-            ]
-        synthesized: dict[str, Any] = {
-            "label": fallback_label,
-            "confidence": 1,
-            "box": {"x": 0, "y": 0, "width": 1, "height": 1},
-        }
-        if fallback_extra:
-            synthesized.update(fallback_extra)
-        return [synthesized]
+    @property
+    def onConnectedChanged(self) -> Observable[bool]:
+        return self._connected_changed_subject.as_observable()
 
-    def _setStorage(self, storage: DeviceStorage[TStorage]) -> None:
-        self._storage = storage
+    @property
+    def onPropertyChanged(self) -> Observable[SensorPropertyChangeData]:
+        return self._property_changed_subject.as_observable()
 
-    def on_assigned(self) -> Any:
-        """Lifecycle hook: the sensor just became assigned to a camera.
+    @property
+    def onCapabilitiesChanged(self) -> Observable[list[TCapability]]:
+        return self._capabilities_changed_subject.as_observable()
 
-        Override to start background work that should only run while this
-        sensor is live — polling loops, event subscriptions, timers, external
-        connections.
+    def on_start(self) -> Any:
+        """Lifecycle hook, called once the sensor is registered and live.
 
-        Called AFTER ``cameraId``, ``storage``, and RPC channels are wired up,
-        so the override can safely access ``self.cameraId``, ``self.storage``,
-        and publish properties via the semantic helper methods.
+        Storage and RPC are wired up by then. Override it to start work whose
+        lifetime matches the sensor's: polling loops, event subscriptions, timers.
 
         May be either a plain ``def`` or an ``async def``. If async, the SDK
         schedules it on the running event loop (fire-and-forget). Errors are
-        caught and swallowed — they will NOT break assignment bookkeeping.
-
-        Paired 1:1 with ``on_deassigned`` — for every ``on_assigned`` call
-        there is exactly one matching ``on_deassigned`` later (on deassignment
-        or cleanup).
-
-        Default: no-op. Most sensors don't need lifecycle hooks.
+        swallowed, not logged, so handle failures inside the override. Paired
+        1:1 with ``on_stop``, which runs on removal, plugin shutdown or cleanup.
 
         Example:
             ```python
-            async def on_assigned(self) -> None:
+            async def on_start(self) -> None:
                 self._task = asyncio.create_task(self._poll_loop())
             ```
         """
         return None
 
-    def on_deassigned(self) -> Any:
-        """Lifecycle hook: the sensor is being deassigned.
-
-        Override to tear down whatever was started in ``on_assigned`` — clear
-        timers, close subscriptions, release external resources.
+    def on_stop(self) -> Any:
+        """Counterpart of ``on_start``: tear down whatever it started, such as
+        timers, subscriptions and external resources.
 
-        Always called exactly once for each prior ``on_assigned``. Also called
-        from ``_cleanup`` if the sensor is being removed while still assigned,
-        so you can rely on this as the single teardown point.
-
-        May be either a plain ``def`` or an ``async def``. See ``on_assigned``
+        May be either a plain ``def`` or an ``async def``. See ``on_start``
         for scheduling semantics.
 
-        Default: no-op.
-
         Example:
             ```python
-            def on_deassigned(self) -> None:
+            def on_stop(self) -> None:
                 if self._task:
                     self._task.cancel()
             ```
         """
         return None
 
-    def _fire_lifecycle(self, assigned: bool) -> None:
-        """Internal helper — invoke the appropriate lifecycle hook and, if the
-        override returned a coroutine, schedule it on the running loop."""
-        try:
-            result = self.on_assigned() if assigned else self.on_deassigned()
-        except Exception:  # noqa: BLE001 - lifecycle errors must not break bookkeeping
-            return
-        if asyncio.iscoroutine(result):
-            try:
-                loop = asyncio.get_running_loop()
-            except RuntimeError:
-                # No loop running — the coroutine won't execute. Swallow so
-                # the coroutine isn't logged as "never awaited".
-                result.close()
-                return
-            task = loop.create_task(result)
-            # Swallow exceptions from async lifecycle work so they don't
-            # surface as "Task exception was never retrieved" warnings.
-            task.add_done_callback(lambda t: t.exception() if not t.cancelled() else None)
-
-    def _setAssigned(self, assigned: bool) -> None:
-        if self._is_assigned == assigned:
-            return
-        self._is_assigned = assigned
-        self._assignment_changed_subject.next(assigned)
-        self._fire_lifecycle(assigned)
+    def on_assigned(self) -> Any:
+        """Deprecated: renamed to ``on_start``. Stub window: still fired
+        alongside ``on_start``, remove in the first minor after the
+        standalone-sensors release."""
+        return None
 
-    @property
-    def onAssignmentChanged(self) -> Observable[bool]:
-        """Observable for assignment state changes (sensor added/removed from camera)."""
-        return self._assignment_changed_subject.as_observable()
+    def on_deassigned(self) -> Any:
+        """Deprecated: renamed to ``on_stop``. Stub window: still fired
+        alongside ``on_stop``, remove in the first minor after the
+        standalone-sensors release."""
+        return None
 
     def toJSON(self) -> SensorJSON:
         """Serialize this sensor to a JSON-safe dict for RPC transport."""
@@ -443,24 +423,16 @@ class Sensor(ABC, Generic[TProperties, TStorage, TCapability]):
             "name": self.name,
             "displayName": self.displayName or self.name,
             "category": self.category,
-            "cameraId": self._camera_id or "",
             "properties": self._getProperties(),
             "capabilities": [str(c) for c in self.capabilities],
             "requiresFrames": self._requires_frames,
         }
+        if self._native_id:
+            result["nativeId"] = self._native_id
         if self._plugin_id:
             result["pluginId"] = self._plugin_id
         return result
 
-    def _setPropertyInternal(self, key: str, value: Any, timestamp: int | None = None) -> None:
-        old_value = self._properties_store.get(key)
-        if old_value != value:
-            self._properties_store[key] = value
-            self._notifyListeners(key, value, old_value, timestamp)
-
-    def _onBackendPropertyChanged(self, property: str, value: Any, timestamp: int | None = None) -> None:
-        self._setPropertyInternal(property, value, timestamp)
-
     def getValue(self, property: str) -> Any | None:
         """Get the current value of a sensor property."""
         return self._properties_store.get(property)
@@ -481,80 +453,181 @@ class Sensor(ABC, Generic[TProperties, TStorage, TCapability]):
 
     @abstractmethod
     async def updateValue(self, property: str, value: Any) -> None:
-        """External-consumer entry point that satisfies the `SensorLike.updateValue`
-        contract. Each concrete sensor class implements this — read-only sensors
-        leave it as a no-op, control sensors dispatch known properties to the
-        appropriate semantic methods (`setOn`, `setActive`, `setTargetState`, ...)
-        so plugin overrides drive hardware. Unknown / non-writable properties are
-        silently ignored.
-
-        **Plugin authors must not call this** — they should call the semantic
-        methods directly on the concrete sensor class.
+        """Generic property write coming from a consumer.
+
+        Read-only sensors implement it as a no-op, control sensors dispatch known
+        properties to their semantic methods (`setOn`, `setActive`,
+        `setTargetState`) so plugin overrides drive hardware. Unknown or
+        non-writable properties are ignored.
+
+        Plugin authors call the semantic methods on the concrete class instead.
         """
         ...
 
     def hasCapability(self, capability: TCapability | str) -> bool:
+        """Check whether the sensor advertises a capability.
+
+        Args:
+            capability: Capability flag to look for.
+
+        Returns:
+            True if the sensor currently advertises it.
+
+        Example:
+            ```python
+            dimmable = sensor.hasCapability("brightness")
+            ```
+        """
         return capability in self._capabilities
 
-    @property
-    def onPropertyChanged(self) -> Observable[SensorPropertyChangeData]:
-        """Observable for property changes."""
-        return self._property_changed_subject.as_observable()
+    def _write_state(self, partial: Mapping[str, Any]) -> None:
+        """Write changed properties, fire one batched RPC update and notify listeners.
+
+        Used by the semantic helpers on each sensor type, not by plugin code.
+        """
+        delta: dict[str, Any] = {}
+        changes: list[tuple[str, Any, Any]] = []
+
+        for key, value in partial.items():
+            if value is None:
+                continue
+            previous = self._properties_store.get(key)
+            if is_equal(previous, value, True):
+                continue
+            self._properties_store[key] = value
+            delta[key] = value
+            changes.append((key, value, previous))
+
+        if not delta:
+            return
+
+        if self._update_fn:
+            self._update_fn(delta)
+
+        for key, value, previous in changes:
+            self._notifyListeners(key, value, previous)
+
+    def _normalize_reported_detections(
+        self,
+        detected: bool,
+        detections: list[dict[str, Any]] | None,
+        fallback_label: str,
+        fallback_extra: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Normalize the arguments of a `reportDetections(detected, detections)` call.
+
+        - `detected` is False: returns `[]` (clear).
+        - `detected` is True with detections: returns them, substituting a full-frame box where missing.
+        - `detected` is True without detections: returns one synthesized full-frame
+          detection carrying `fallback_label` and `fallback_extra`.
+        """
+        if not detected:
+            return []
+        if detections:
+            # smart-camera plugins report labels without coordinates, downstream
+            # consumers (coordinator, zone matching) require a box on every detection
+            return [
+                detection
+                if detection.get("box")
+                else {**detection, "box": {"x": 0, "y": 0, "width": 1, "height": 1}}
+                for detection in detections
+            ]
+        synthesized: dict[str, Any] = {
+            "label": fallback_label,
+            "confidence": 1,
+            "box": {"x": 0, "y": 0, "width": 1, "height": 1},
+        }
+        if fallback_extra:
+            synthesized.update(fallback_extra)
+        return [synthesized]
+
+    def _setStorage(self, storage: DeviceStorage[TStorage]) -> None:
+        self._storage = storage
+
+    def _fire_lifecycle(self, active: bool) -> None:
+        """Invoke the lifecycle hooks and schedule them if an override is async."""
+        hooks = (self.on_start, self.on_assigned) if active else (self.on_stop, self.on_deassigned)
+        for hook in hooks:
+            try:
+                result = hook()
+            except Exception:  # noqa: BLE001 - lifecycle errors must not break bookkeeping
+                continue
+            if asyncio.iscoroutine(result):
+                try:
+                    loop = asyncio.get_running_loop()
+                except RuntimeError:
+                    # no loop, close so the coroutine isn't logged as "never awaited"
+                    result.close()
+                    continue
+                task = loop.create_task(result)
+                # swallow, otherwise "Task exception was never retrieved" warnings
+                task.add_done_callback(lambda t: t.exception() if not t.cancelled() else None)
+
+    def _setActive(self, active: bool) -> None:
+        if self._active == active:
+            return
+        self._active = active
+        self._connected_changed_subject.next(active)
+        self._fire_lifecycle(active)
+
+    def _setPropertyInternal(self, key: str, value: Any, timestamp: int | None = None) -> None:
+        old_value = self._properties_store.get(key)
+        if old_value != value:
+            self._properties_store[key] = value
+            self._notifyListeners(key, value, old_value, timestamp)
+
+    def _onBackendPropertyChanged(self, property: str, value: Any, timestamp: int | None = None) -> None:
+        self._setPropertyInternal(property, value, timestamp)
 
     def _notifyListeners(
-        self, property: str, value: Any, previousValue: Any, timestamp: int | None = None
+        self,
+        property: str,
+        value: Any,
+        previousValue: Any,
+        timestamp: int | None = None,
     ) -> None:
-        if not self._camera_id:
+        # skip constructor-time writes, listeners only matter once registered
+        if not self._registered:
             return
 
         ts = timestamp or int(time.time() * 1000)
-        if self._detailed_listeners:
-            event: PropertyChangedEvent = {
-                "cameraId": self._camera_id,
-                "sensorId": self._id,
-                "sensorType": self.type,
-                "property": property,
-                "value": value,
-                "previousValue": previousValue,
-                "timestamp": ts,
-            }
-            for detailed_listener in self._detailed_listeners:
-                with contextlib.suppress(Exception):
-                    detailed_listener(event)
         self._property_changed_subject.next({"property": property, "value": value, "timestamp": ts})
 
-    @property
-    def onCapabilitiesChanged(self) -> Observable[list[TCapability]]:
-        """Observable for capability changes. Emits the full capabilities array when capabilities change."""
-        return self._capabilities_changed_subject.as_observable()
+    def _setId(self, id: str) -> None:
+        self._id = id
+
+    def _setAssignedCameras(self, camera_ids: list[str]) -> None:
+        self._assigned_camera_ids = list(camera_ids)
+        self._assignment_changed_subject.next(self._assigned_camera_ids.copy())
 
-    def _setCameraId(self, camera_id: str) -> None:
-        self._camera_id = camera_id
+    def _setAssignmentLocked(self) -> None:
+        self._assignment_locked = True
 
     def _setPluginId(self, plugin_id: str) -> None:
         self._plugin_id = plugin_id
 
     def _init(self, update_fn: PropertyUpdateFn) -> None:
         self._update_fn = update_fn
+        self._registered = True
 
     def _initCapabilities(self, update_fn: CapabilityUpdateFn) -> None:
         self._capabilities_change_fn = update_fn
 
     def _cleanup(self) -> None:
-        # Trigger on_deassigned if we're still assigned — guarantees the hook
-        # is paired 1:1 even when the sensor is force-removed without going
-        # through a proper deassignment path.
-        if self._is_assigned:
-            self._is_assigned = False
+        # pair on_stop even when the sensor is force-removed without teardown
+        if self._active:
+            self._active = False
             self._fire_lifecycle(False)
 
         self._update_fn = None
         self._capabilities_change_fn = None
         self._storage = None
-        self._detailed_listeners.clear()
+        self._registered = False
+        self._assigned_camera_ids = []
         self._property_changed_subject.complete()
         self._capabilities_changed_subject.complete()
         self._assignment_changed_subject.complete()
+        self._connected_changed_subject.complete()
 
     def _getProperties(self) -> dict[str, Any]:
         return self._properties_store.copy()