@camera.ui/server 2.0.22 → 2.0.23

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

@@ -11,14 +11,14 @@ from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
 class LightCapability(StrEnum):
-    """Optional capabilities for light controls."""
+    """Optional capabilities of a light control."""
 
     Brightness = "brightness"
     """Light supports brightness adjustment (0-100)."""
 
 
 class LightProperty(StrEnum):
-    """Properties for light controls."""
+    """Property names of a light control."""
 
     On = "on"
     """Whether the light is on."""
@@ -27,17 +27,19 @@ class LightProperty(StrEnum):
 
 
 class LightControlProperties(TypedDict):
-    """Property value map for light controls."""
+    """Property values of a light control."""
 
     on: bool
     brightness: int
 
 
 class LightPropertyChangeData(TypedDict):
-    """Emitted on LightControlLike.onPropertyChanged."""
+    """Property change payload emitted on LightControlLike.onPropertyChanged."""
 
-    property: str  # LightProperty value
+    property: str
+    """Name of the changed property, a LightProperty value."""
     value: bool | int
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -51,6 +53,12 @@ class LightControlLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.Light
 
+    @property
+    def onPropertyChanged(self) -> Observable[LightPropertyChangeData]: ...
+
+    @property
+    def onCapabilitiesChanged(self) -> Observable[list[LightCapability]]: ...
+
     @overload
     def getValue(self, property: Literal[LightProperty.On]) -> bool | None: ...
     @overload
@@ -58,30 +66,24 @@ class LightControlLike(SensorLike, Protocol):
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[LightPropertyChangeData]: ...
-
-    @property
-    def onCapabilitiesChanged(self) -> Observable[list[LightCapability]]: ...
-
 
 class LightControl(Sensor[LightControlProperties, TStorage, LightCapability], Generic[TStorage]):
     """Light control sensor. Override ``setOn()``/``setOff()`` to drive your
     hardware, then ``await super().setOn()`` / ``await super().setOff()`` to
     sync the SDK state.
 
-    Plugins that have no hardware-action use case can leave the methods
-    unoverridden — the base implementation just updates the state.
+    Plugins with no hardware-action use case can leave the methods unoverridden,
+    the base implementation just updates the state.
 
     For hardware-pushed updates (someone manually flipped the switch), call
-    ``super().setOn()`` / ``super().setOff()`` from your event handler — that
+    ``super().setOn()`` / ``super().setOff()`` from your event handler. That
     bypasses any plugin override and only syncs state.
     """
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Light") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Light", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state(
             {
                 LightProperty.On.value: False,
@@ -146,7 +148,10 @@ class LightControl(Sensor[LightControlProperties, TStorage, LightCapability], Ge
         self._write_state({LightProperty.Brightness.value: max(0, min(100, value))})
 
     async def updateValue(self, property: str, value: Any) -> None:
-        """Routes generic property writes to semantic methods."""
+        """Routes generic property writes to the semantic setters.
+
+        Only on and brightness are externally writable.
+        """
         if property == LightProperty.On.value:
             if value:
                 await self.setOn()
@@ -156,4 +161,3 @@ class LightControl(Sensor[LightControlProperties, TStorage, LightCapability], Ge
         if property == LightProperty.Brightness.value:
             await self.setBrightness(int(value))
             return
-        # Unknown / non-writable property — ignored.

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

@@ -11,15 +11,18 @@ from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
 class LockState(IntEnum):
-    """Lock states (HomeKit-compatible values)."""
+    """Lock states."""
 
     Secured = 0
+    """Locked."""
     Unsecured = 1
+    """Unlocked."""
     Unknown = 2
+    """State cannot be determined, e.g. while a motorized lock is moving."""
 
 
 class LockProperty(StrEnum):
-    """Properties for lock controls."""
+    """Property names of a lock control."""
 
     CurrentState = "currentState"
     """The actual current state of the lock."""
@@ -28,17 +31,19 @@ class LockProperty(StrEnum):
 
 
 class LockControlProperties(TypedDict):
-    """Property value map for lock controls."""
+    """Property values of a lock control."""
 
     currentState: int
     targetState: int
 
 
 class LockPropertyChangeData(TypedDict):
-    """Emitted on LockControlLike.onPropertyChanged."""
+    """Property change payload emitted on LockControlLike.onPropertyChanged."""
 
-    property: str  # LockProperty value
+    property: str
+    """Name of the changed property, a LockProperty value."""
     value: LockState
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -52,6 +57,9 @@ class LockControlLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.Lock
 
+    @property
+    def onPropertyChanged(self) -> Observable[LockPropertyChangeData]: ...
+
     @overload
     def getValue(self, property: Literal[LockProperty.CurrentState]) -> LockState | None: ...
     @overload
@@ -59,15 +67,12 @@ class LockControlLike(SensorLike, Protocol):
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[LockPropertyChangeData]: ...
-
 
 class LockControl(Sensor[LockControlProperties, TStorage, str], Generic[TStorage]):
     """Lock control.
 
     Override `setTargetState()` to drive hardware and call
-    `await super().setTargetState(value)` once the hardware confirms — the base
+    `await super().setTargetState(value)` once the hardware confirms. The base
     implementation updates both `targetState` and `currentState` to the new value.
 
     For asymmetric flows (long-running unlock with intermediate state) override
@@ -76,8 +81,8 @@ class LockControl(Sensor[LockControlProperties, TStorage, str], Generic[TStorage
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Lock") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Lock", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state(
             {
                 LockProperty.CurrentState.value: int(LockState.Secured),
@@ -105,7 +110,7 @@ class LockControl(Sensor[LockControlProperties, TStorage, str], Generic[TStorage
 
     async def setTargetState(self, value: LockState) -> None:
         """Set the target state. Override to drive hardware and call
-        `await super().setTargetState(value)` after success — the base implementation
+        `await super().setTargetState(value)` after success. The base implementation
         syncs both `targetState` and `currentState` to the new value.
 
         Args:
@@ -126,11 +131,11 @@ class LockControl(Sensor[LockControlProperties, TStorage, str], Generic[TStorage
         )
 
     def setCurrentState(self, value: LockState) -> None:
-        """Publish the actual lock state. Use this to drive transitions where
-        the physical state diverges from the user-requested target — e.g.
-        motorized smart locks that take time to rotate (publish ``Unknown``
-        while moving), or hardware reporting an out-of-band state change.
-        Read-only from cross-process consumers (``updateValue`` ignores it).
+        """Publish the actual lock state. Use it when the physical state diverges
+        from the requested target: motorized locks that take time to rotate
+        (publish ``Unknown`` while moving), or hardware reporting an out-of-band
+        state change. Read-only from cross-process consumers (``updateValue``
+        ignores it).
 
         Args:
             value: Current physical lock state from the ``LockState`` enum.
@@ -145,7 +150,9 @@ class LockControl(Sensor[LockControlProperties, TStorage, str], Generic[TStorage
         self._write_state({LockProperty.CurrentState.value: int(value)})
 
     async def updateValue(self, property: str, value: Any) -> None:
-        """Routes generic property writes to semantic methods."""
+        """Routes generic property writes to the semantic setters.
+
+        Only targetState is externally writable, currentState is observed-only.
+        """
         if property == LockProperty.TargetState.value:
             await self.setTargetState(LockState(value))
-        # Unknown / non-writable property (incl. currentState) — ignored.

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

@@ -19,7 +19,7 @@ from .detection import (
     VideoFrameData,
 )
 
-# Re-exports kept for backward compatibility — original public surface of this module.
+# detection types are re-exported here, plugins import them from this module
 __all__ = [
     "BoundingBox",
     "DETECTION_ATTRIBUTES",
@@ -41,16 +41,18 @@ __all__ = [
 class MotionProperty(StrEnum):
     """Property names of a motion sensor."""
 
-    Detected = "detected"  # Whether motion is currently detected
-    Detections = "detections"  # List of detection results with bounding boxes
-    Blocked = "blocked"  # When true, detection updates are suppressed (set by the backend dwell logic)
-    LastTriggered = (
-        "lastTriggered"  # Timestamp in milliseconds of the last detection trigger, set by the backend
-    )
+    Detected = "detected"
+    """Whether motion is currently detected."""
+    Detections = "detections"
+    """List of detection results with bounding boxes."""
+    Blocked = "blocked"
+    """When true, detection updates are suppressed (set by the backend dwell logic)."""
+    LastTriggered = "lastTriggered"
+    """Timestamp in milliseconds of the last detection trigger, set by the backend."""
 
 
 class MotionSensorProperties(TypedDict):
-    """Property shape carried by a MotionSensor."""
+    """Property values of a motion sensor."""
 
     detected: bool
     detections: list[Detection]
@@ -60,8 +62,10 @@ class MotionSensorProperties(TypedDict):
 class MotionPropertyChangeData(TypedDict):
     """Property change payload emitted on MotionSensorLike.onPropertyChanged."""
 
-    property: str  # MotionProperty value
+    property: str
+    """Name of the changed property, a MotionProperty value."""
     value: bool | list[Detection]
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -75,6 +79,9 @@ class MotionSensorLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.Motion
 
+    @property
+    def onPropertyChanged(self) -> Observable[MotionPropertyChangeData]: ...
+
     @overload
     def getValue(self, property: Literal[MotionProperty.Detected]) -> bool | None: ...
     @overload
@@ -84,23 +91,19 @@ class MotionSensorLike(SensorLike, Protocol):
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[MotionPropertyChangeData]: ...
-
 
 class MotionSensor(Sensor[MotionSensorProperties, TStorage, str], Generic[TStorage]):
     """Motion sensor that reports motion state and detection results.
 
     Plugin authors call `reportDetections(list)` to push detection results.
-    `detected` is auto-derived from the detection list. `blocked` is read-only
-    and is set by the backend (dwell logic) — `reportDetections()` becomes a
-    no-op while the sensor is blocked.
+    `detected` is auto-derived from the detection list. `blocked` is read-only and
+    set by the backend dwell logic, `reportDetections()` is a no-op while it is set.
     """
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Motion Sensor") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Motion Sensor", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state(
             {
                 MotionProperty.Detected.value: False,
@@ -119,26 +122,23 @@ class MotionSensor(Sensor[MotionSensorProperties, TStorage, str], Generic[TStora
 
     @property
     def detected(self) -> bool:
-        """Whether motion is currently detected."""
         return bool(self.props.detected)
 
     @property
     def detections(self) -> list[Detection]:
-        """Current detection list."""
         return self.props.detections or []
 
     @property
     def blocked(self) -> bool:
-        """Whether the sensor is currently blocked. Read-only — set by the backend dwell logic, not by plugin code."""
         return bool(self.props.blocked)
 
     def reportDetections(self, detected: bool, detections: list[Detection] | None = None) -> None:
         """Report a motion detection result.
 
-        - ``reportDetections(True)`` — motion detected without bbox (e.g. Ring camera).
+        - ``reportDetections(True)``: motion detected without bbox (e.g. Ring camera).
           The SDK synthesizes a single full-frame ``'motion'`` detection.
-        - ``reportDetections(True, [...])`` — motion detected with explicit detections.
-        - ``reportDetections(False)`` — no motion (clears detections).
+        - ``reportDetections(True, [...])``: motion detected with explicit detections.
+        - ``reportDetections(False)``: no motion (clears detections).
 
         No-op while the sensor is blocked by backend dwell logic.
 
@@ -176,15 +176,16 @@ class MotionSensor(Sensor[MotionSensorProperties, TStorage, str], Generic[TStora
         self.reportDetections(False)
 
     async def updateValue(self, property: str, value: Any) -> None:
-        """Read-only sensor: external writes are ignored. State is reported via `reportDetections`."""
-        # No-op — motion state is reported by the plugin, not set externally.
+        """Read-only sensor: external writes are ignored."""
 
 
 class MotionResult(TypedDict):
     """Return type for MotionDetectorSensor.detectMotion()."""
 
-    detected: bool  # Ignored by the backend, which re-derives it from the detections
-    detections: list[Detection]  # Detections emitted for this frame
+    detected: bool
+    """Whether motion is detected in this frame. Ignored by the backend, which re-derives it from the detections."""
+    detections: list[Detection]
+    """Detections emitted for this frame."""
 
 
 class MotionDetectorSensor(MotionSensor[TStorage], Generic[TStorage]):

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

@@ -16,17 +16,18 @@ from .spec import ObjectModelSpec
 class ObjectProperty(StrEnum):
     """Property names of an object detection sensor."""
 
-    Detected = "detected"  # Whether any object is currently detected
-    Detections = "detections"  # List of detected objects with labels and bounding boxes
-    Labels = "labels"  # Unique labels of the current detections (auto-derived when reporting detections)
+    Detected = "detected"
+    """Whether any object is currently detected."""
+    Detections = "detections"
+    """List of detected objects with labels and bounding boxes."""
+    Labels = "labels"
+    """Unique labels of the current detections (auto-derived when reporting detections)."""
 
 
 class TrackVelocity(TypedDict):
-    """Signed centroid velocity vector in normalized units per frame step.
-
-    Positive x = moving right, positive y = moving down. Consumers doing
-    motion prediction (PTZ autotrack, trajectory estimation) should use this
-    instead of deriving velocity from frame-to-frame position deltas.
+    """Signed centroid velocity in normalized units per frame. Positive x = moving
+    right, positive y = moving down. Prefer this over deriving velocity from
+    position deltas.
     """
 
     x: float
@@ -36,15 +37,20 @@ class TrackVelocity(TypedDict):
 class TrackedDetection(Detection, total=False):
     """Detection enriched with tracking metadata (stable IDs, velocity)."""
 
-    trackId: int  # Stable sequential ID for this object across frames
-    trackAge: int  # Number of frames this object has been continuously tracked
-    trackSpeed: float  # Velocity magnitude in normalized units per frame; 0 = stationary
-    trackVelocity: TrackVelocity  # Signed centroid velocity vector in normalized units per frame
-    trackLost: bool  # True if the object was not matched in the current frame
+    trackId: int
+    """Stable sequential ID for this object across frames."""
+    trackAge: int
+    """Number of frames this object has been continuously tracked."""
+    trackSpeed: float
+    """Velocity magnitude in normalized units per frame. 0 = stationary."""
+    trackVelocity: TrackVelocity
+    """Signed centroid velocity in normalized units per frame."""
+    trackLost: bool
+    """True if the object was not matched in the current frame."""
 
 
 class ObjectSensorProperties(TypedDict):
-    """Property shape carried by an ObjectSensor."""
+    """Property values of an object detection sensor."""
 
     detected: bool
     detections: list[TrackedDetection]
@@ -54,8 +60,10 @@ class ObjectSensorProperties(TypedDict):
 class ObjectPropertyChangeData(TypedDict):
     """Property change payload emitted on ObjectSensorLike.onPropertyChanged."""
 
-    property: str  # ObjectProperty value
+    property: str
+    """Name of the changed property, an ObjectProperty value."""
     value: bool | list[Detection] | list[DetectionLabel]
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -69,6 +77,9 @@ class ObjectSensorLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.Object
 
+    @property
+    def onPropertyChanged(self) -> Observable[ObjectPropertyChangeData]: ...
+
     @overload
     def getValue(self, property: Literal[ObjectProperty.Detected]) -> bool | None: ...
     @overload
@@ -78,9 +89,6 @@ class ObjectSensorLike(SensorLike, Protocol):
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[ObjectPropertyChangeData]: ...
-
 
 class ObjectSensor(Sensor[ObjectSensorProperties, TStorage, str], Generic[TStorage]):
     """Object detection sensor that reports detected objects (person, vehicle, animal, etc.).
@@ -91,8 +99,8 @@ class ObjectSensor(Sensor[ObjectSensorProperties, TStorage, str], Generic[TStora
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Object Sensor") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Object Sensor", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state(
             {
                 ObjectProperty.Detected.value: False,
@@ -111,17 +119,14 @@ class ObjectSensor(Sensor[ObjectSensorProperties, TStorage, str], Generic[TStora
 
     @property
     def detected(self) -> bool:
-        """Whether any object is currently detected."""
         return bool(self.props.detected)
 
     @property
     def detections(self) -> list[TrackedDetection]:
-        """Current detection list."""
         return self.props.detections or []
 
     @property
     def labels(self) -> list[DetectionLabel]:
-        """Unique labels of the current detections."""
         return self.props.labels or []
 
     def reportDetections(
@@ -132,11 +137,11 @@ class ObjectSensor(Sensor[ObjectSensorProperties, TStorage, str], Generic[TStora
         """Report detected objects. Auto-derives ``detected`` and ``labels``
         from the list.
 
-        - ``reportDetections(True)`` — something detected without specific data.
+        - ``reportDetections(True)``: something detected without specific data.
           The SDK synthesizes a single full-frame ``'motion'`` detection as a
           generic fallback.
-        - ``reportDetections(True, [...])`` — explicit detections (typical case).
-        - ``reportDetections(False)`` — clear.
+        - ``reportDetections(True, [...])``: explicit detections (typical case).
+        - ``reportDetections(False)``: clear.
 
         Args:
             detected: Whether any object is currently detected.
@@ -177,15 +182,16 @@ class ObjectSensor(Sensor[ObjectSensorProperties, TStorage, str], Generic[TStora
         self.reportDetections(False)
 
     async def updateValue(self, property: str, value: Any) -> None:
-        """Read-only sensor: external writes are ignored. State is reported via `reportDetections`."""
-        # No-op — object detection state is reported by the plugin, not set externally.
+        """Read-only sensor: external writes are ignored."""
 
 
 class ObjectResult(TypedDict):
     """Return type for ObjectDetectorSensor.detectObjects()."""
 
-    detected: bool  # Whether any object is detected in this frame
-    detections: list[TrackedDetection]  # Detections emitted for this frame
+    detected: bool
+    """Whether any object is detected in this frame."""
+    detections: list[TrackedDetection]
+    """Detections emitted for this frame."""
 
 
 class ObjectDetectorSensor(ObjectSensor[TStorage], Generic[TStorage]):
@@ -200,9 +206,7 @@ class ObjectDetectorSensor(ObjectSensor[TStorage], Generic[TStorage]):
 
     @property
     @abstractmethod
-    def modelSpec(self) -> ObjectModelSpec:
-        """Declares the expected input dimensions. The backend scales frames to match."""
-        ...
+    def modelSpec(self) -> ObjectModelSpec: ...
 
     @abstractmethod
     async def detectObjects(self, frame: VideoFrameData) -> ObjectResult:

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

@@ -11,23 +11,25 @@ from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
 class OccupancyProperty(StrEnum):
-    """Properties for occupancy sensors."""
+    """Property names of an occupancy sensor."""
 
     Detected = "detected"
     """Whether occupancy is detected (true = occupied)."""
 
 
 class OccupancySensorProperties(TypedDict):
-    """Property value map for occupancy sensors."""
+    """Property values of an occupancy sensor."""
 
     detected: bool
 
 
 class OccupancyPropertyChangeData(TypedDict):
-    """Emitted on OccupancySensorLike.onPropertyChanged."""
+    """Property change payload emitted on OccupancySensorLike.onPropertyChanged."""
 
-    property: str  # OccupancyProperty value
+    property: str
+    """Name of the changed property, an OccupancyProperty value."""
     value: bool
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -41,22 +43,22 @@ class OccupancySensorLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.Occupancy
 
+    @property
+    def onPropertyChanged(self) -> Observable[OccupancyPropertyChangeData]: ...
+
     @overload
     def getValue(self, property: Literal[OccupancyProperty.Detected]) -> bool | None: ...
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[OccupancyPropertyChangeData]: ...
-
 
 class OccupancySensor(Sensor[OccupancySensorProperties, TStorage, str], Generic[TStorage]):
     """Occupancy sensor for detecting presence in a room or area."""
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Occupancy Sensor") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Occupancy Sensor", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state({OccupancyProperty.Detected.value: False})
 
     @property
@@ -86,4 +88,3 @@ class OccupancySensor(Sensor[OccupancySensorProperties, TStorage, str], Generic[
 
     async def updateValue(self, property: str, value: Any) -> None:
         """Read-only sensor: external writes are ignored."""
-        # No-op — occupancy state is reported by the plugin, not set externally.