@camera.ui/server 2.0.22 → 2.0.24

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

@@ -14,23 +14,29 @@ from .spec import ModelSpec
 
 
 class FaceProperty(StrEnum):
-    """Property names of a face detection sensor."""
+    """Property names of a face sensor."""
 
-    Detected = "detected"  # Whether any face is currently detected
-    Detections = "detections"  # List of detected faces with optional identity, embedding, and thumbnail
+    Detected = "detected"
+    """Whether any face is currently detected."""
+    Detections = "detections"
+    """List of detected faces with optional identity, embedding, and thumbnail."""
 
 
 class FaceDetection(Detection):
     """A face detection result, extending Detection with face-specific fields."""
 
-    attribute: Literal["face"]  # type: ignore[misc]  # Sub-detection attribute, fixed to "face"
-    identity: NotRequired[str]  # Recognized identity name, if matched against known faces
-    embedding: NotRequired[list[float]]  # Face embedding vector for recognition/comparison
-    thumbnail: NotRequired[bytes]  # JPEG thumbnail crop of the detected face
+    attribute: Literal["face"]  # type: ignore[misc]
+    """Sub-detection attribute, fixed to "face"."""
+    identity: NotRequired[str]
+    """Recognized identity name, if matched against known faces."""
+    embedding: NotRequired[list[float]]
+    """Face embedding vector for recognition/comparison."""
+    thumbnail: NotRequired[bytes]
+    """JPEG thumbnail crop of the detected face."""
 
 
 class FaceSensorProperties(TypedDict):
-    """Property shape carried by a FaceSensor."""
+    """Property values of a face sensor."""
 
     detected: bool
     detections: list[FaceDetection]
@@ -39,8 +45,10 @@ class FaceSensorProperties(TypedDict):
 class FacePropertyChangeData(TypedDict):
     """Property change payload emitted on FaceSensorLike.onPropertyChanged."""
 
-    property: str  # FaceProperty value
+    property: str
+    """Name of the changed property, a FaceProperty value."""
     value: bool | list[FaceDetection]
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -54,6 +62,9 @@ class FaceSensorLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.Face
 
+    @property
+    def onPropertyChanged(self) -> Observable[FacePropertyChangeData]: ...
+
     @overload
     def getValue(self, property: Literal[FaceProperty.Detected]) -> bool | None: ...
     @overload
@@ -61,21 +72,18 @@ class FaceSensorLike(SensorLike, Protocol):
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[FacePropertyChangeData]: ...
-
 
 class FaceSensor(Sensor[FaceSensorProperties, TStorage, str], Generic[TStorage]):
     """Face sensor that reports detected faces and optional identity matches.
 
-    Plugin authors call `reportDetections(list)` to push detected faces.
-    `detected` is auto-derived from the detection list.
+    Plugin authors call ``reportDetections(list)`` to push detected faces.
+    ``detected`` is auto-derived from the detection list.
     """
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Face Sensor") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Face Sensor", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state(
             {
                 FaceProperty.Detected.value: False,
@@ -93,23 +101,21 @@ class FaceSensor(Sensor[FaceSensorProperties, TStorage, str], Generic[TStorage])
 
     @property
     def detected(self) -> bool:
-        """Whether any face is currently detected."""
         return bool(self.props.detected)
 
     @property
     def detections(self) -> list[FaceDetection]:
-        """Current detection list."""
         return self.props.detections or []
 
     def reportDetections(self, detected: bool, detections: list[FaceDetection] | None = None) -> None:
         """Report detected faces.
 
-        - ``reportDetections(True)`` — face detected without specifics (e.g. a
+        - ``reportDetections(True)``: face detected without specifics (e.g. a
           bare face-event from a discovery provider). The SDK synthesizes a
           single full-frame face detection without identity.
-        - ``reportDetections(True, [...])`` — explicit face detections with
+        - ``reportDetections(True, [...])``: explicit face detections with
           identity, embedding, and/or thumbnail.
-        - ``reportDetections(False)`` — clear.
+        - ``reportDetections(False)``: clear.
 
         Args:
             detected: Whether any face is currently detected.
@@ -151,30 +157,30 @@ class FaceSensor(Sensor[FaceSensorProperties, TStorage, str], Generic[TStorage])
 
     async def updateValue(self, property: str, value: Any) -> None:
         """Read-only sensor: external writes are ignored."""
-        # No-op — face detection state is reported by the plugin, not set externally.
 
 
 class FaceResult(TypedDict):
     """Return type for FaceDetectorSensor.detectFaces()."""
 
-    detected: bool  # Whether any face is detected in this frame
-    detections: list[FaceDetection]  # Detections emitted for this frame
+    detected: bool
+    """Whether any face is detected in this frame."""
+    detections: list[FaceDetection]
+    """Detections emitted for this frame."""
 
 
 class FaceDetectorSensor(FaceSensor[TStorage], Generic[TStorage]):
     """Face detector that receives video frames from the backend pipeline.
 
     Extend this class and implement ``detectFaces`` for face detection and
-    recognition.
+    recognition. The backend scales frames to match ``modelSpec.input``
+    dimensions before each call.
     """
 
     _requires_frames = True
 
     @property
     @abstractmethod
-    def modelSpec(self) -> ModelSpec:
-        """Declares the expected input dimensions and trigger labels. The backend scales frames to match."""
-        ...
+    def modelSpec(self) -> ModelSpec: ...
 
     @abstractmethod
     async def detectFaces(self, frames: list[VideoFrameData]) -> list[FaceResult]:

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

@@ -11,17 +11,22 @@ from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
 class GarageState(IntEnum):
-    """Garage door states (HomeKit-compatible values)."""
+    """Garage door states."""
 
     Open = 0
+    """Door is fully open."""
     Closed = 1
+    """Door is fully closed."""
     Opening = 2
+    """Door is moving towards open."""
     Closing = 3
+    """Door is moving towards closed."""
     Stopped = 4
+    """Door stopped part-way."""
 
 
 class GarageProperty(StrEnum):
-    """Properties for garage controls."""
+    """Property names of a garage control."""
 
     CurrentState = "currentState"
     """The actual current state of the garage door."""
@@ -32,7 +37,7 @@ class GarageProperty(StrEnum):
 
 
 class GarageControlProperties(TypedDict):
-    """Property value map for garage controls."""
+    """Property values of a garage control."""
 
     currentState: int
     targetState: int
@@ -40,10 +45,12 @@ class GarageControlProperties(TypedDict):
 
 
 class GaragePropertyChangeData(TypedDict):
-    """Emitted on GarageControlLike.onPropertyChanged."""
+    """Property change payload emitted on GarageControlLike.onPropertyChanged."""
 
-    property: str  # GarageProperty value
+    property: str
+    """Name of the changed property, a GarageProperty value."""
     value: GarageState | bool
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -57,6 +64,9 @@ class GarageControlLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.Garage
 
+    @property
+    def onPropertyChanged(self) -> Observable[GaragePropertyChangeData]: ...
+
     @overload
     def getValue(self, property: Literal[GarageProperty.CurrentState]) -> GarageState | None: ...
     @overload
@@ -66,25 +76,22 @@ class GarageControlLike(SensorLike, Protocol):
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[GaragePropertyChangeData]: ...
-
 
 class GarageControl(Sensor[GarageControlProperties, TStorage, str], Generic[TStorage]):
     """Garage door control.
 
-    Override `setTargetState()` to drive hardware and call
-    `await super().setTargetState(value)` once the hardware confirms — the base
-    implementation updates both `targetState` and `currentState`.
+    Override ``setTargetState()`` to drive hardware and call
+    ``await super().setTargetState(value)`` once the hardware confirms: the base
+    implementation updates both ``targetState`` and ``currentState``.
 
     For long-running transitions (Opening/Closing intermediate states) override
-    `setTargetState` and write `currentState` separately as the door moves.
+    ``setTargetState`` and write ``currentState`` separately as the door moves.
     """
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Garage") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Garage", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state(
             {
                 GarageProperty.CurrentState.value: int(GarageState.Closed),
@@ -117,8 +124,8 @@ class GarageControl(Sensor[GarageControlProperties, TStorage, str], Generic[TSto
 
     async def setTargetState(self, value: GarageState) -> None:
         """Set the target state. Override to drive hardware and call
-        `await super().setTargetState(value)` after success — the base implementation
-        syncs both `targetState` and `currentState` to the new value.
+        ``await super().setTargetState(value)`` after success: the base implementation
+        syncs both ``targetState`` and ``currentState`` to the new value.
 
         Args:
             value: Desired target state from the ``GarageState`` enum.
@@ -139,7 +146,7 @@ class GarageControl(Sensor[GarageControlProperties, TStorage, str], Generic[TSto
 
     def setCurrentState(self, value: GarageState) -> None:
         """Publish the actual door state. Use this to drive long-running
-        transitions (e.g. Open → Closing → Closed) independently of the
+        transitions (Open, then Closing, then Closed) independently of the
         user-requested target state. Read-only from cross-process consumers
         (``updateValue`` ignores it).
 
@@ -157,7 +164,7 @@ class GarageControl(Sensor[GarageControlProperties, TStorage, str], Generic[TSto
 
     def setObstructionDetected(self, value: bool) -> None:
         """Publish the obstruction-detected state. Read-only from the consumer
-        side (``updateValue`` ignores it) — plugin code calls this when its
+        side (``updateValue`` ignores it), plugin code calls this when its
         hardware reports an obstruction sensor change.
 
         Args:
@@ -171,7 +178,9 @@ class GarageControl(Sensor[GarageControlProperties, TStorage, str], Generic[TSto
         self._write_state({GarageProperty.ObstructionDetected.value: 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.
+        """
         if property == GarageProperty.TargetState.value:
             await self.setTargetState(GarageState(value))
-        # Unknown / non-writable property (incl. currentState, obstructionDetected) — ignored.

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

@@ -11,23 +11,25 @@ from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
 class HumidityProperty(StrEnum):
-    """Properties for humidity info sensors."""
+    """Property names of a humidity sensor."""
 
     Current = "current"
     """Current relative humidity (0-100%)."""
 
 
 class HumidityInfoProperties(TypedDict):
-    """Property value map for humidity info sensors."""
+    """Property values of a humidity sensor."""
 
     current: float
 
 
 class HumidityPropertyChangeData(TypedDict):
-    """Emitted on HumidityInfoLike.onPropertyChanged."""
+    """Property change payload emitted on HumidityInfoLike.onPropertyChanged."""
 
-    property: str  # HumidityProperty value
+    property: str
+    """Name of the changed property, a HumidityProperty value."""
     value: float
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -35,28 +37,28 @@ TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
 
 @runtime_checkable
 class HumidityInfoLike(SensorLike, Protocol):
-    """Read-only proxy interface for a humidity info sensor."""
+    """Read-only proxy interface for a humidity sensor."""
 
     @property
     def type(self) -> SensorType:
         return SensorType.Humidity
 
+    @property
+    def onPropertyChanged(self) -> Observable[HumidityPropertyChangeData]: ...
+
     @overload
     def getValue(self, property: Literal[HumidityProperty.Current]) -> float | None: ...
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[HumidityPropertyChangeData]: ...
-
 
 class HumidityInfo(Sensor[HumidityInfoProperties, TStorage, str], Generic[TStorage]):
     """Humidity info sensor. Reports current relative humidity in %."""
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Humidity") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Humidity", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state({HumidityProperty.Current.value: 50.0})
 
     @property
@@ -72,9 +74,17 @@ class HumidityInfo(Sensor[HumidityInfoProperties, TStorage, str], Generic[TStora
         return float(self.props.current or 0.0)
 
     def setCurrent(self, value: float) -> None:
-        """Report a new humidity reading. Clamped to [0, 100] %."""
+        """Report a new humidity reading. Clamped to [0, 100] %.
+
+        Args:
+            value: Relative humidity percentage in the range 0-100.
+
+        Example:
+            ```python
+            humidity.setCurrent(63)
+            ```
+        """
         self._write_state({HumidityProperty.Current.value: max(0.0, min(100.0, value))})
 
     async def updateValue(self, property: str, value: Any) -> None:
         """Read-only sensor: external writes are ignored."""
-        # No-op — humidity is reported by the plugin, not set externally.

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

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

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

@@ -14,24 +14,27 @@ from .spec import ModelSpec
 
 
 class LicensePlateProperty(StrEnum):
-    """Property names of a license plate detection sensor."""
+    """Property names of a license plate sensor."""
 
-    Detected = "detected"  # Whether any license plate is currently detected
-    Detections = "detections"  # List of detected plates with OCR text
+    Detected = "detected"
+    """Whether any license plate is currently detected."""
+    Detections = "detections"
+    """List of detected plates with OCR text."""
 
 
 class LicensePlateDetection(Detection):
     """A license plate detection result, extending Detection with OCR fields."""
 
-    attribute: Literal["license_plate"]  # type: ignore[misc]  # Sub-detection attribute, fixed to "license_plate"
-    plateText: str  # Recognized plate text (e.g. "ABC 1234")
-    ocrConfidence: NotRequired[
-        float
-    ]  # Average text recognition confidence (0-1), separate from the box confidence
+    attribute: Literal["license_plate"]  # type: ignore[misc]
+    """Sub-detection attribute, fixed to ``"license_plate"``."""
+    plateText: str
+    """Recognized plate text (e.g. ``"ABC 1234"``)."""
+    ocrConfidence: NotRequired[float]
+    """Average text recognition confidence (0-1), separate from the box confidence."""
 
 
 class LicensePlateSensorProperties(TypedDict):
-    """Property shape carried by a LicensePlateSensor."""
+    """Property values of a license plate sensor."""
 
     detected: bool
     detections: list[LicensePlateDetection]
@@ -40,8 +43,10 @@ class LicensePlateSensorProperties(TypedDict):
 class LicensePlatePropertyChangeData(TypedDict):
     """Property change payload emitted on LicensePlateSensorLike.onPropertyChanged."""
 
-    property: str  # LicensePlateProperty value
+    property: str
+    """Name of the changed property, a LicensePlateProperty value."""
     value: bool | list[LicensePlateDetection]
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -55,6 +60,9 @@ class LicensePlateSensorLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.LicensePlate
 
+    @property
+    def onPropertyChanged(self) -> Observable[LicensePlatePropertyChangeData]: ...
+
     @overload
     def getValue(self, property: Literal[LicensePlateProperty.Detected]) -> bool | None: ...
     @overload
@@ -64,9 +72,6 @@ class LicensePlateSensorLike(SensorLike, Protocol):
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[LicensePlatePropertyChangeData]: ...
-
 
 class LicensePlateSensor(Sensor[LicensePlateSensorProperties, TStorage, str], Generic[TStorage]):
     """License plate sensor that reports detected plates with OCR text.
@@ -77,8 +82,8 @@ class LicensePlateSensor(Sensor[LicensePlateSensorProperties, TStorage, str], Ge
 
     _requires_frames = False
 
-    def __init__(self, name: str = "License Plate Sensor") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "License Plate Sensor", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state(
             {
                 LicensePlateProperty.Detected.value: False,
@@ -96,12 +101,10 @@ class LicensePlateSensor(Sensor[LicensePlateSensorProperties, TStorage, str], Ge
 
     @property
     def detected(self) -> bool:
-        """Whether any license plate is currently detected."""
         return bool(self.props.detected)
 
     @property
     def detections(self) -> list[LicensePlateDetection]:
-        """Current detection list."""
         return self.props.detections or []
 
     def reportDetections(
@@ -111,10 +114,10 @@ class LicensePlateSensor(Sensor[LicensePlateSensorProperties, TStorage, str], Ge
     ) -> None:
         """Report detected license plates.
 
-        - ``reportDetections(True)`` — plate detected without specifics. The SDK
+        - ``reportDetections(True)``: plate detected without specifics. The SDK
           synthesizes a single full-frame detection with empty plateText.
-        - ``reportDetections(True, [...])`` — explicit plate detections with OCR text.
-        - ``reportDetections(False)`` — clear.
+        - ``reportDetections(True, [...])``: explicit plate detections with OCR text.
+        - ``reportDetections(False)``: clear.
 
         Args:
             detected: Whether any license plate is currently detected.
@@ -155,36 +158,37 @@ class LicensePlateSensor(Sensor[LicensePlateSensorProperties, TStorage, str], Ge
         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 — license plate state is reported by the plugin, not set externally.
+        """Read-only sensor: external writes are ignored."""
 
 
 class LicensePlateResult(TypedDict):
     """Return type for LicensePlateDetectorSensor.detectLicensePlates()."""
 
-    detected: bool  # Whether any license plate is detected in this frame
-    detections: list[LicensePlateDetection]  # Detections emitted for this frame
+    detected: bool
+    """Whether any license plate is detected in this frame."""
+    detections: list[LicensePlateDetection]
+    """Detections emitted for this frame."""
 
 
 class LicensePlateDetectorSensor(LicensePlateSensor[TStorage], Generic[TStorage]):
     """License plate detector that receives video frames from the backend pipeline.
 
     Extend this class and implement ``detectLicensePlates`` for plate detection
-    and OCR.
+    and OCR. The backend scales frames to match ``modelSpec.input`` dimensions
+    before each call.
     """
 
     _requires_frames = True
 
     @property
     @abstractmethod
-    def modelSpec(self) -> ModelSpec:
-        """Declares the expected input dimensions and trigger labels. The backend scales frames to match."""
-        ...
+    def modelSpec(self) -> ModelSpec: ...
 
     @abstractmethod
     async def detectLicensePlates(self, frames: list[VideoFrameData]) -> list[LicensePlateResult]:
         """Detect license plates in batch. Each frame is pre-scaled to ``modelSpec['input']``:
-        normally a vehicle region cropped by the upstream object detector, but the whole scene
-        when no decoded frame is available. Must return exactly one LicensePlateResult per
-        input frame, in the same order."""
+        normally a vehicle region cropped by the upstream object detector, but the whole
+        scene when no decoded frame is available. Must return exactly one result per input
+        frame, in the same order.
+        """
         ...