@camera.ui/server 2.0.14 → 2.0.16

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/camera/enums.py

@@ -12,7 +12,7 @@ Camera device type.
 ZoneType = Literal["intersect", "contain"]
 """
 Detection zone intersection type.
-- `intersect`: Trigger when object touches the zone boundary
+- `intersect`: Trigger when object overlaps the zone at all
 - `contain`: Trigger only when object is fully inside the zone
 """
 
@@ -69,8 +69,11 @@ Video streaming mode for UI playback.
 - `mse`: Media Source Extensions (browser native)
 """
 
-CameraAspectRatio = Literal["16:9", "9:16", "8:3", "4:3", "1:1"]
-"""Camera aspect ratio for UI display."""
+CameraAspectRatioPreset = Literal["16:9", "9:16", "8:3", "4:3", "1:1"]
+"""Built-in aspect ratio presets offered as quick picks in the UI."""
+
+CameraAspectRatio = CameraAspectRatioPreset | str
+"""Camera aspect ratio for UI display: a preset or any custom ``width:height`` ratio."""
 
 Point = tuple[float, float]
 """Zone polygon coordinate as [x, y] tuple (0-100 percentage)."""

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/camera/events.py

@@ -18,7 +18,8 @@ class EventDetection(TypedDict):
     box: NotRequired[BoundingBox]
     """Bounding box of the highest-confidence detection (normalized 0-1)."""
     thumbnail: NotRequired[bytes]
-    """Best-selected JPEG thumbnail crop. Only present on 'end' events."""
+    """Best-selected JPEG thumbnail crop. Present on 'segment-start' and 'segment-end',
+    omitted when it matches the segment thumbnail."""
     trackId: NotRequired[int]
     """Object tracker ID (links this detection across frames)."""
     moving: NotRequired[bool]
@@ -35,7 +36,8 @@ class EventAttribute(TypedDict):
     confidence: NotRequired[float]
     """Detection confidence (0-1)."""
     thumbnail: NotRequired[bytes]
-    """Best-selected JPEG thumbnail crop. Only present on 'end' events."""
+    """Best-selected JPEG thumbnail crop. Present on 'segment-start' and 'segment-end',
+    and on 'segment-update' for unknown faces."""
     embedding: NotRequired[list[float]]
     """Face embedding vector for unknown face persistence. Only present for face attributes."""
     embeddingModel: NotRequired[str]
@@ -90,7 +92,7 @@ class EventSegment(TypedDict):
     lastSeen: int
     """Segment end time (Unix ms)."""
     thumbnail: NotRequired[bytes]
-    """Best-selected JPEG scene thumbnail for this segment. Only present on 'end' events."""
+    """Best-selected JPEG scene thumbnail for this segment. Only present on 'segment-*' messages."""
     detections: list[EventDetection]
     """Object detections in this segment."""
     attributes: list[EventAttribute]

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/camera/recording.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+RecordingMode = Literal["continuous", "event", "adhoc"]
+"""
+How recordings are captured.
+- ``continuous``: record around the clock
+- ``event``: record only around detections, padded by the pre-buffer
+- ``adhoc``: record only when started manually
+"""
+
+RecordingSource = Literal["high", "mid", "low"]
+"""Stream tier to record."""
+
+
+class CameraRecordingSettings(TypedDict):
+    """Recording settings for a camera."""
+
+    enabled: bool
+    """Whether recording is enabled."""
+    mode: RecordingMode
+    """Recording mode."""
+    preBuffer: float
+    """Seconds of video kept before an event (event mode, 0 - 60)."""
+    sources: list[RecordingSource]
+    """Stream tiers to record."""

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/internal/camera_config_internal.py

@@ -20,7 +20,7 @@ class CameraInputSettings(TypedDict):
     hotMode: bool
     """Keep connection always active."""
     preload: bool
-    """Preload stream on startup."""
+    """Buffer the last keyframe group so new viewers get a picture faster."""
     muted: NotRequired[bool]
     """Strip the audio track from this source (defaults to False)."""
     urls: list[str]

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/manager/__init__.py

@@ -13,9 +13,8 @@ class CoreManagerEvent(TypedDict):
     """
     Core manager event payload.
 
-    Emitted when a core system event occurs (e.g. cloud account changes,
-    remote-server availability, plugin lifecycle changes). Subscribe via
-    ``coreManager.onEvent`` to react to system-level state changes.
+    The host currently publishes one event type, ``cloudAccountChanged``.
+    Subscribe via ``coreManager.onEvent`` to react to it.
     """
 
     type: str
@@ -31,8 +30,8 @@ class CoreManager(Protocol):
     Core manager interface for system-level operations.
 
     Provides access to cross-cutting services like the FFmpeg binary path,
-    server addresses, HMAC signing for cloud requests, inter-plugin lookup,
-    and a stream of core system events.
+    server addresses, the cloud server id, inter-plugin lookup, and a stream
+    of core system events.
 
     Accessed via `api.coreManager` in plugins.
 
@@ -95,7 +94,10 @@ class CoreManager(Protocol):
 
     async def getPluginsByInterface(self, interfaceName: PluginInterface) -> list[PluginInfo]:
         """
-        Get all active plugins that implement a specific interface.
+        Get all installed, enabled plugins that implement a specific interface.
+
+        Plugins the admin disabled are excluded. A returned plugin may still be
+        starting up or may have crashed, so a call into one can fail.
 
         Args:
             interfaceName: Plugin interface name (e.g., 'ClipDetection')

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/plugin/contract.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from enum import Enum
+from enum import StrEnum
 from typing import Literal, NotRequired, TypedDict
 
 from ..sensor import SensorType
@@ -11,7 +11,7 @@ ensures a matching interpreter exists in its venv pool before launching the
 plugin; Node and Go plugins ignore this field."""
 
 
-class PluginRole(str, Enum):
+class PluginRole(StrEnum):
     """Role a plugin plays in the system. The role decides which lifecycle
     hooks the host invokes and which contract validations apply."""
 
@@ -41,7 +41,7 @@ class PluginRole(str, Enum):
     by integrations that ship a complete camera + detection stack."""
 
 
-class PluginInterface(str, Enum):
+class PluginInterface(StrEnum):
     """Capability flags a plugin advertises in its contract.
 
     The host uses these to decide which RPC handlers to wire up and which
@@ -102,7 +102,7 @@ class PluginInterface(str, Enum):
     """Implements OAuthClientCredentialsCapable (user-supplied client_id + client_secret)."""
 
 
-class PluginCapability(str, Enum):
+class PluginCapability(StrEnum):
     """Permission a plugin requests so it can call a host-provided system
     feature. Each capability gates one outgoing SDK call — calls without
     the matching capability are rejected by the host."""

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/plugin/notifier.py

@@ -6,13 +6,13 @@ these types directly.
 
 from __future__ import annotations
 
-from enum import Enum
+from enum import StrEnum
 from typing import Any, NotRequired, Protocol, TypedDict, runtime_checkable
 
 from ..storage import JsonSchema
 
 
-class Severity(str, Enum):
+class Severity(StrEnum):
     """Classifies how urgent a Notification is.
 
     Notifiers map this to platform-specific delivery characteristics; the
@@ -70,9 +70,10 @@ class Notification(TypedDict):
     Defaults to :attr:`Severity.Info` if omitted."""
 
     tag: NotRequired[str]
-    """Collapse-key for dedup at both manager and notifier level (e.g.
-    ``motion:cam-1`` — multiple events with the same tag inside the throttle
-    window collapse into one notification on the device)."""
+    """Collapse-key (e.g. ``motion:cam-1``). The host uses it to replace an older
+    entry with the same tag in the in-app notification list. Delivery is not
+    throttled: every publish is sent. Notifiers may map it to a platform
+    collapse-id."""
 
     thumbnail: NotRequired[bytes]
     """Optional inline JPEG attached to the notification."""

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

@@ -42,10 +42,12 @@ from .contact import (
 from .detection import (
     DETECTION_ATTRIBUTES,
     DETECTION_LABELS,
+    OBJECT_DETECTION_LABELS,
     BoundingBox,
     Detection,
     DetectionAttribute,
     DetectionLabel,
+    ObjectDetectionLabel,
     VideoFrameData,
 )
 from .doorbell import (
@@ -141,6 +143,8 @@ __all__ = [
     "BASE_AUDIO_LABELS",
     "DETECTION_LABELS",
     "DETECTION_ATTRIBUTES",
+    "OBJECT_DETECTION_LABELS",
+    "ObjectDetectionLabel",
     "AudioLabel",
     "BaseAudioLabel",
     "DetectionLabel",

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

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from abc import abstractmethod
 from collections.abc import Mapping
-from enum import Enum
+from enum import StrEnum
 from typing import Any, Generic, Literal, NotRequired, Protocol, overload, runtime_checkable
 
 from typing_extensions import TypedDict, TypeVar
@@ -48,7 +48,7 @@ BaseAudioLabel = Literal[
 AudioLabel = BaseAudioLabel | str
 
 
-class AudioProperty(str, Enum):
+class AudioProperty(StrEnum):
     """Property names of an audio detection sensor."""
 
     Detected = "detected"  # Whether an audio event is currently detected

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

@@ -5,7 +5,7 @@ import contextlib
 import time
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Mapping
-from enum import Enum
+from enum import StrEnum
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -31,7 +31,7 @@ if TYPE_CHECKING:
     from ..storage import DeviceStorage, JsonSchema
 
 
-class SensorType(str, Enum):
+class SensorType(StrEnum):
     """Type of sensor. Each maps to a smart-home concept (HomeKit service)."""
 
     Motion = "motion"  # Video-based motion detection
@@ -58,7 +58,7 @@ class SensorType(str, Enum):
     Battery = "battery"  # Battery level and charging state
 
 
-class SensorCategory(str, Enum):
+class SensorCategory(StrEnum):
     """Categorizes a sensor's role in the system."""
 
     Sensor = "sensor"  # Read-only detection sensor

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

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
-from enum import Enum
+from enum import StrEnum
 from typing import Any, Generic, Literal, Protocol, overload, runtime_checkable
 
 from typing_extensions import TypedDict, TypeVar
@@ -10,7 +10,7 @@ from ..observable import Observable
 from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
-class BatteryCapability(str, Enum):
+class BatteryCapability(StrEnum):
     """Optional capabilities for battery info sensors."""
 
     LowBattery = "lowBattery"
@@ -19,15 +19,18 @@ class BatteryCapability(str, Enum):
     """Sensor reports charging state."""
 
 
-class BatteryProperty(str, Enum):
+class BatteryProperty(StrEnum):
     """Properties for battery info sensors."""
 
     Level = "level"
+    """Battery level percentage (0-100)."""
     Charging = "charging"
+    """Current charging state."""
     Low = "low"
+    """Whether battery is critically low."""
 
 
-class ChargingState(str, Enum):
+class ChargingState(StrEnum):
     """Battery charging state."""
 
     NotChargeable = "NOT_CHARGEABLE"
@@ -125,7 +128,7 @@ class BatteryInfo(Sensor[BatteryInfoProperties, TStorage, BatteryCapability], Ge
         """Report a new battery level (percentage). Clamped to [0, 100].
 
         Args:
-            value: Battery level percentage in the range 0–100.
+            value: Battery level percentage in the range 0-100.
 
         Example:
             ```python

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

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from abc import abstractmethod
 from collections.abc import Mapping
-from enum import Enum
+from enum import StrEnum
 from typing import Any, Generic, Literal, Protocol, overload, runtime_checkable
 
 from typing_extensions import TypedDict, TypeVar
@@ -13,7 +13,7 @@ from .detection import Detection, VideoFrameData
 from .spec import ModelSpec
 
 
-class ClassifierProperty(str, Enum):
+class ClassifierProperty(StrEnum):
     """Property names of a classifier sensor."""
 
     Detected = "detected"  # Whether any classification result is active
@@ -190,7 +190,8 @@ class ClassifierDetectorSensor(ClassifierSensor[TStorage], Generic[TStorage]):
 
     @abstractmethod
     async def detectClassifications(self, frames: list[VideoFrameData]) -> list[ClassifierResult]:
-        """Classify frames in batch. Each frame is a pre-cropped, pre-scaled trigger region
-        produced by the upstream object detector. Must return exactly one ClassifierResult per
-        input frame, in the same order."""
+        """Classify frames in batch. Each frame is pre-scaled to ``modelSpec['input']``:
+        normally a trigger region cropped by the upstream object detector, but the whole
+        scene when no decoded frame is available. Must return exactly one ClassifierResult
+        per input frame, in the same order."""
         ...

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

@@ -57,9 +57,10 @@ class ClipDetectorSensor(Sensor[dict[str, Any], TStorage, str], Generic[TStorage
 
     @abstractmethod
     async def detectEmbeddings(self, frames: list[VideoFrameData]) -> list[ClipResult]:
-        """Generate CLIP embeddings in batch. Each frame is a pre-cropped, pre-scaled trigger region
-        produced by the upstream object detector. Must return exactly one ClipResult per input
-        frame, in the same order. Use ``frame['label']`` to tag the emitted embedding."""
+        """Generate CLIP embeddings in batch. Each frame is pre-scaled to ``modelSpec['input']``:
+        normally a trigger region cropped by the upstream object detector, but the whole scene
+        when no decoded frame is available. Must return exactly one ClipResult per input frame,
+        in the same order. Use ``frame['label']`` to tag the emitted embedding."""
         ...
 
     async def updateValue(self, property: str, value: Any) -> None:

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

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
-from enum import Enum
+from enum import StrEnum
 from typing import Any, Generic, Literal, Protocol, overload, runtime_checkable
 
 from typing_extensions import TypedDict, TypeVar
@@ -10,10 +10,11 @@ from ..observable import Observable
 from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
-class ContactProperty(str, Enum):
+class ContactProperty(StrEnum):
     """Properties for contact sensors."""
 
     Detected = "detected"
+    """Whether the contact is open (true = open, false = closed)."""
 
 
 class ContactSensorProperties(TypedDict):

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

@@ -4,8 +4,14 @@ from typing import Literal, NotRequired
 
 from typing_extensions import TypedDict
 
+#: Object-detection labels the detector groups its classes into.
+OBJECT_DETECTION_LABELS = ("person", "vehicle", "animal", "package")
+
+#: Union of the object-detection label strings.
+ObjectDetectionLabel = Literal["person", "vehicle", "animal", "package"]
+
 #: Built-in detection label types recognized across the system.
-DETECTION_LABELS = ("motion", "person", "vehicle", "animal", "package", "audio")
+DETECTION_LABELS = ("motion", *OBJECT_DETECTION_LABELS, "audio")
 
 #: Union of the built-in detection label strings.
 DetectionLabel = Literal["motion", "person", "vehicle", "animal", "package", "audio"]

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

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import threading
 from collections.abc import Mapping
-from enum import Enum
+from enum import StrEnum
 from typing import Any, Generic, Literal, Protocol, overload, runtime_checkable
 
 from typing_extensions import TypedDict, TypeVar
@@ -11,10 +11,11 @@ from ..observable import Observable
 from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
-class DoorbellProperty(str, Enum):
+class DoorbellProperty(StrEnum):
     """Properties for doorbell triggers."""
 
     Ring = "ring"
+    """Whether the doorbell is currently ringing."""
 
 
 class DoorbellTriggerProperties(TypedDict):

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

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from abc import abstractmethod
 from collections.abc import Mapping
-from enum import Enum
+from enum import StrEnum
 from typing import Any, Generic, Literal, NotRequired, Protocol, overload, runtime_checkable
 
 from typing_extensions import TypedDict, TypeVar
@@ -13,7 +13,7 @@ from .detection import Detection, VideoFrameData
 from .spec import ModelSpec
 
 
-class FaceProperty(str, Enum):
+class FaceProperty(StrEnum):
     """Property names of a face detection sensor."""
 
     Detected = "detected"  # Whether any face is currently detected
@@ -178,7 +178,8 @@ class FaceDetectorSensor(FaceSensor[TStorage], Generic[TStorage]):
 
     @abstractmethod
     async def detectFaces(self, frames: list[VideoFrameData]) -> list[FaceResult]:
-        """Detect faces in batch. Each frame is a pre-cropped, pre-scaled person region
-        produced by the upstream object detector. Must return exactly one FaceResult per
+        """Detect faces in batch. Each frame is pre-scaled to ``modelSpec['input']``:
+        normally a person region cropped by the upstream object detector, but the whole
+        scene when no decoded frame is available. Must return exactly one FaceResult per
         input frame, in the same order."""
         ...

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

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
-from enum import Enum, IntEnum
+from enum import IntEnum, StrEnum
 from typing import Any, Generic, Literal, Protocol, overload, runtime_checkable
 
 from typing_extensions import TypedDict, TypeVar
@@ -20,12 +20,15 @@ class GarageState(IntEnum):
     Stopped = 4
 
 
-class GarageProperty(str, Enum):
+class GarageProperty(StrEnum):
     """Properties for garage controls."""
 
     CurrentState = "currentState"
+    """The actual current state of the garage door."""
     TargetState = "targetState"
+    """The desired target state (set by user, transitions to currentState)."""
     ObstructionDetected = "obstructionDetected"
+    """Whether an obstruction is detected."""
 
 
 class GarageControlProperties(TypedDict):

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

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
-from enum import Enum
+from enum import StrEnum
 from typing import Any, Generic, Literal, Protocol, overload, runtime_checkable
 
 from typing_extensions import TypedDict, TypeVar
@@ -10,10 +10,11 @@ from ..observable import Observable
 from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
-class HumidityProperty(str, Enum):
+class HumidityProperty(StrEnum):
     """Properties for humidity info sensors."""
 
     Current = "current"
+    """Current relative humidity (0-100%)."""
 
 
 class HumidityInfoProperties(TypedDict):

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

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
-from enum import Enum
+from enum import StrEnum
 from typing import Any, Generic, Literal, Protocol, overload, runtime_checkable
 
 from typing_extensions import TypedDict, TypeVar
@@ -10,10 +10,11 @@ from ..observable import Observable
 from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
-class LeakProperty(str, Enum):
+class LeakProperty(StrEnum):
     """Properties for leak sensors."""
 
     Detected = "detected"
+    """Whether a leak is detected."""
 
 
 class LeakSensorProperties(TypedDict):

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

@@ -2,8 +2,8 @@ from __future__ import annotations
 
 from abc import abstractmethod
 from collections.abc import Mapping
-from enum import Enum
-from typing import Any, Generic, Literal, Protocol, overload, runtime_checkable
+from enum import StrEnum
+from typing import Any, Generic, Literal, NotRequired, Protocol, overload, runtime_checkable
 
 from typing_extensions import TypedDict, TypeVar
 
@@ -13,7 +13,7 @@ from .detection import Detection, VideoFrameData
 from .spec import ModelSpec
 
 
-class LicensePlateProperty(str, Enum):
+class LicensePlateProperty(StrEnum):
     """Property names of a license plate detection sensor."""
 
     Detected = "detected"  # Whether any license plate is currently detected
@@ -25,6 +25,9 @@ class LicensePlateDetection(Detection):
 
     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):
@@ -180,7 +183,8 @@ class LicensePlateDetectorSensor(LicensePlateSensor[TStorage], Generic[TStorage]
 
     @abstractmethod
     async def detectLicensePlates(self, frames: list[VideoFrameData]) -> list[LicensePlateResult]:
-        """Detect license plates in batch. Each frame is a pre-cropped, pre-scaled vehicle region
-        produced by the upstream object detector. Must return exactly one LicensePlateResult per
+        """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."""
         ...

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

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
-from enum import Enum
+from enum import StrEnum
 from typing import Any, Generic, Literal, Protocol, overload, runtime_checkable
 
 from typing_extensions import TypedDict, TypeVar
@@ -10,18 +10,20 @@ from ..observable import Observable
 from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
-class LightCapability(str, Enum):
+class LightCapability(StrEnum):
     """Optional capabilities for light controls."""
 
     Brightness = "brightness"
-    """Light supports brightness adjustment (0–100)."""
+    """Light supports brightness adjustment (0-100)."""
 
 
-class LightProperty(str, Enum):
+class LightProperty(StrEnum):
     """Properties for light controls."""
 
     On = "on"
+    """Whether the light is on."""
     Brightness = "brightness"
+    """Brightness level (0-100)."""
 
 
 class LightControlProperties(TypedDict):
@@ -134,7 +136,7 @@ class LightControl(Sensor[LightControlProperties, TStorage, LightCapability], Ge
         succeeds. The default implementation clamps the value to [0, 100].
 
         Args:
-            value: Brightness level in the range 0–100.
+            value: Brightness level in the range 0-100.
 
         Example:
             ```python

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

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
-from enum import Enum, IntEnum
+from enum import IntEnum, StrEnum
 from typing import Any, Generic, Literal, Protocol, overload, runtime_checkable
 
 from typing_extensions import TypedDict, TypeVar
@@ -18,11 +18,13 @@ class LockState(IntEnum):
     Unknown = 2
 
 
-class LockProperty(str, Enum):
+class LockProperty(StrEnum):
     """Properties for lock controls."""
 
     CurrentState = "currentState"
+    """The actual current state of the lock."""
     TargetState = "targetState"
+    """The desired target state (set by user, transitions to currentState)."""
 
 
 class LockControlProperties(TypedDict):