Sensors¶

Typed detection sensors (motion, object, face, license-plate, audio, classifier, clip) and smart-home sensors (contact, doorbell, lock, garage, light, switch, ptz, security system, environmental).

camera_ui_sdk.sensor ¶

AudioDetectorSensor ¶

AudioDetectorSensor(name: str = 'Audio Sensor', *, native_id: str | None = None)

Bases: AudioSensor[TStorage], Generic[TStorage]

Audio detector that receives audio frames from the backend pipeline.

Extend this class and implement detectAudio and modelSpec. The backend resamples and buffers audio to match modelSpec before each call.

detectAudio `abstractmethod` `async` ¶

detectAudio(audio: AudioFrameData) -> AudioResult

Analyze a single audio frame for events. Called by the backend at the configured cadence.

AudioFrameData ¶

Bases: TypedDict

Audio frame data delivered to audio detector sensors by the backend pipeline.

cameraId `instance-attribute` ¶

cameraId: NotRequired[str]

Camera the frame originated from.

data `instance-attribute` ¶

data: bytes

Raw audio sample buffer.

sampleRate `instance-attribute` ¶

sampleRate: int

Sample rate of the buffer in Hz.

channels `instance-attribute` ¶

channels: int

Channel count of the buffer (typically 1 = mono).

format `instance-attribute` ¶

format: Literal['pcm16', 'float32']

Sample format: pcm16 = 16-bit signed integer PCM, float32 = 32-bit float.

decibels `instance-attribute` ¶

decibels: NotRequired[float]

Pre-computed decibel level for this frame, if available.

timestamp `instance-attribute` ¶

timestamp: NotRequired[int]

Capture timestamp in milliseconds since epoch.

AudioResult ¶

Bases: TypedDict

Return type for AudioDetectorSensor.detectAudio().

detected `instance-attribute` ¶

detected: bool

Whether an audio event is detected in this frame.

detections `instance-attribute` ¶

detections: list[Detection]

Detections emitted for this frame.

decibels `instance-attribute` ¶

decibels: NotRequired[float]

Optional decibel level computed for this frame.

AudioSensor ¶

AudioSensor(name: str = 'Audio Sensor', *, native_id: str | None = None)

Bases: Sensor[AudioSensorProperties, TStorage, str], Generic[TStorage]

Audio sensor that reports audio events and decibel levels.

Plugin authors call reportDetections(list) to push detected audio events (auto-derives detected) and setDecibels(value) to update the audio level.

reportDetections ¶

reportDetections(detected: bool, detections: list[Detection] | None = None) -> None

Report detected audio events.

reportDetections(True): audio detected without specifics. The SDK synthesizes a single full-frame 'audio' detection.
reportDetections(True, [...]): audio detected with explicit detections.
reportDetections(False): clear.

Parameters:

Name	Type	Description	Default
`detected`	`bool`	Whether an audio event is currently detected.	required
`detections`	`list[Detection] \| None`	Optional explicit detections produced for this event.	`None`

Example

sensor.reportDetections(
    True,
    [
        Detection(
            label="glass_break",
            confidence=0.91,
            box=BoundingBox(x=0, y=0, width=1, height=1),
        )
    ],
)
sensor.reportDetections(False)

clearDetections ¶

clearDetections() -> None

Explicitly clear audio detection state (detected = False, detections = []).

setDecibels ¶

setDecibels(value: float) -> None

Update the current audio level (in decibels).

Parameters:

Name	Type	Description	Default
`value`	`float`	Audio level in decibels.	required

Example

sensor.setDecibels(72)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

Sensor ¶

Sensor(name: str, *, native_id: str | None = None, origin: str | None = None, exposed: bool | None = None, hidden: bool | None = None)

Bases: 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.

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.

on_start ¶

on_start() -> Any

Lifecycle hook, called once the sensor is registered and live.

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 swallowed, not logged, so handle failures inside the override. Paired 1:1 with on_stop, which runs on removal, plugin shutdown or cleanup.

Example

async def on_start(self) -> None:
    self._task = asyncio.create_task(self._poll_loop())

on_stop ¶

on_stop() -> Any

Counterpart of on_start: tear down whatever it started, such as timers, subscriptions and external resources.

May be either a plain def or an async def. See on_start for scheduling semantics.

Example

def on_stop(self) -> None:
    if self._task:
        self._task.cancel()

toJSON ¶

toJSON() -> SensorJSON

Serialize this sensor to a JSON-safe dict for RPC transport.

getValue ¶

getValue(property: str) -> Any | None

Get the current value of a sensor property.

getValues ¶

getValues() -> dict[str, Any]

Get a read-only snapshot of all property values.

Returns:

Type	Description
`dict[str, Any]`	Snapshot of every property currently held by the sensor.

Example

snapshot = sensor.getValues()
print(snapshot)

updateValue `abstractmethod` `async` ¶

updateValue(property: str, value: Any) -> None

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.

hasCapability ¶

hasCapability(capability: TCapability | str) -> bool

Check whether the sensor advertises a capability.

Parameters:

Name	Type	Description	Default
`capability`	`TCapability \| str`	Capability flag to look for.	required

Returns:

Type	Description
`bool`	True if the sensor currently advertises it.

Example

dimmable = sensor.hasCapability("brightness")

updateModelSpec ¶

updateModelSpec() -> None

Re-announce the model spec, e.g. once the models finished loading.

The spec a detector reports at registration is what it knows at that moment: models that load in the background are missing from it. Call this after loading, the server replaces its copy.

Example

async def on_start(self) -> None:
    await self._plugin.get_object_detector(model_name)
    self.updateModelSpec()

SensorCategory ¶

Bases: StrEnum

Categorizes a sensor's role in the system.

Determines how the backend treats the sensor (read-only vs. controllable).

Sensor `class-attribute` `instance-attribute` ¶

Sensor = 'sensor'

Read-only detection sensor (motion, object, audio, etc.).

Control `class-attribute` `instance-attribute` ¶

Control = 'control'

Controllable sensor with set methods (light, siren, PTZ, etc.).

Trigger `class-attribute` `instance-attribute` ¶

Trigger = 'trigger'

Event trigger (doorbell ring).

Info `class-attribute` `instance-attribute` ¶

Info = 'info'

Informational read-only state (battery level).

SensorLike ¶

Bases: Protocol

Read-only view of a sensor, as other plugins and the backend see it.

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.

getValue ¶

getValue(property: str) -> Any | None

Get the current value of a sensor property.

getValues ¶

getValues() -> dict[str, Any]

Get a read-only snapshot of all property values.

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

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.

hasCapability ¶

hasCapability(capability: str) -> bool

Whether the sensor advertises the given capability.

SensorPropertyChangeData ¶

Bases: TypedDict

Emitted on the onPropertyChanged Observable.

property `instance-attribute` ¶

property: str

Name of the changed property.

value `instance-attribute` ¶

value: object

New value of the property.

timestamp `instance-attribute` ¶

timestamp: int

Origin timestamp in milliseconds since epoch.

SensorType ¶

Bases: StrEnum

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 `class-attribute` `instance-attribute` ¶

Motion = 'motion'

Video-based motion detection.

Object `class-attribute` `instance-attribute` ¶

Object = 'object'

Object detection (person, vehicle, animal, etc.).

Audio `class-attribute` `instance-attribute` ¶

Audio = 'audio'

Audio event detection (glass break, scream, etc.).

Face `class-attribute` `instance-attribute` ¶

Face = 'face'

Face detection and recognition.

LicensePlate `class-attribute` `instance-attribute` ¶

LicensePlate = 'licensePlate'

License plate detection and OCR.

Classifier `class-attribute` `instance-attribute` ¶

Classifier = 'classifier'

General-purpose image classifier.

Clip `class-attribute` `instance-attribute` ¶

Clip = 'clip'

CLIP embedding generation for semantic search.

ObjectAssist `class-attribute` `instance-attribute` ¶

ObjectAssist = 'objectAssist'

Locates objects in a frame so secondary detectors get real crops from camera-side detections.

CarbonDioxide `class-attribute` `instance-attribute` ¶

CarbonDioxide = 'carbonDioxide'

Carbon dioxide sensor (ppm).

CarbonMonoxide `class-attribute` `instance-attribute` ¶

CarbonMonoxide = 'carbonMonoxide'

Carbon monoxide detector.

Cold `class-attribute` `instance-attribute` ¶

Cold = 'cold'

Cold alarm.

Contact `class-attribute` `instance-attribute` ¶

Contact = 'contact'

Contact/open-close sensor (door, window).

Gas `class-attribute` `instance-attribute` ¶

Gas = 'gas'

Gas detector.

Heat `class-attribute` `instance-attribute` ¶

Heat = 'heat'

Heat alarm.

Humidity `class-attribute` `instance-attribute` ¶

Humidity = 'humidity'

Humidity sensor (0-100%).

Illuminance `class-attribute` `instance-attribute` ¶

Illuminance = 'illuminance'

Illuminance sensor (lx).

Leak `class-attribute` `instance-attribute` ¶

Leak = 'leak'

Water leak detector.

Occupancy `class-attribute` `instance-attribute` ¶

Occupancy = 'occupancy'

Occupancy/presence sensor.

Power `class-attribute` `instance-attribute` ¶

Power = 'power'

Power detection sensor.

Problem `class-attribute` `instance-attribute` ¶

Problem = 'problem'

Generic problem/fault sensor.

Smoke `class-attribute` `instance-attribute` ¶

Smoke = 'smoke'

Smoke detector.

Tamper `class-attribute` `instance-attribute` ¶

Tamper = 'tamper'

Tamper sensor.

Temperature `class-attribute` `instance-attribute` ¶

Temperature = 'temperature'

Temperature sensor (°C).

Vibration `class-attribute` `instance-attribute` ¶

Vibration = 'vibration'

Vibration sensor.

Light `class-attribute` `instance-attribute` ¶

Light = 'light'

Light on/off and brightness control.

Siren `class-attribute` `instance-attribute` ¶

Siren = 'siren'

Siren on/off and volume control.

Switch `class-attribute` `instance-attribute` ¶

Switch = 'switch'

Generic on/off switch.

Lock `class-attribute` `instance-attribute` ¶

Lock = 'lock'

Lock/unlock control.

Garage `class-attribute` `instance-attribute` ¶

Garage = 'garage'

Garage door opener.

PTZ `class-attribute` `instance-attribute` ¶

PTZ = 'ptz'

Pan-tilt-zoom camera control.

SecuritySystem `class-attribute` `instance-attribute` ¶

SecuritySystem = 'securitySystem'

Security system arm/disarm control.

Doorbell `class-attribute` `instance-attribute` ¶

Doorbell = 'doorbell'

Doorbell ring trigger.

Battery `class-attribute` `instance-attribute` ¶

Battery = 'battery'

Battery level and charging state.

BatteryCapability ¶

Bases: StrEnum

Optional capabilities of a battery info sensor.

LowBattery `class-attribute` `instance-attribute` ¶

LowBattery = 'lowBattery'

Sensor reports low-battery alerts.

Charging `class-attribute` `instance-attribute` ¶

Charging = 'charging'

Sensor reports charging state.

BatteryInfo ¶

BatteryInfo(name: str = 'Battery', *, native_id: str | None = None)

Bases: Sensor[BatteryInfoProperties, TStorage, BatteryCapability], Generic[TStorage]

Battery info sensor. Reports battery level, charging state, and low-battery alerts.

Plugin authors call setLevel(value), setCharging(state), and setLow(value) to push updates from the device.

setLevel ¶

setLevel(value: int) -> None

Report a new battery level (percentage). Clamped to [0, 100].

Parameters:

Name	Type	Description	Default
`value`	`int`	Battery level percentage in the range 0-100.	required

Example

battery.setLevel(87)

setCharging ¶

setCharging(value: ChargingState) -> None

Report the current charging state.

Parameters:

Name	Type	Description	Default
`value`	`ChargingState`	Current charging state from the `ChargingState` enum.	required

Example

from camera_ui_sdk import ChargingState

battery.setCharging(ChargingState.Charging)

setLow ¶

setLow(value: bool) -> None

Report whether the battery is critically low.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when the battery has crossed the low-battery threshold.	required

Example

battery.setLow(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

ChargingState ¶

Bases: StrEnum

Battery charging state.

NotChargeable `class-attribute` `instance-attribute` ¶

NotChargeable = 'NOT_CHARGEABLE'

Device has no rechargeable battery.

NotCharging `class-attribute` `instance-attribute` ¶

NotCharging = 'NOT_CHARGING'

Battery is not charging.

Charging `class-attribute` `instance-attribute` ¶

Charging = 'CHARGING'

Battery is currently charging.

Full `class-attribute` `instance-attribute` ¶

Full = 'FULL'

Battery is fully charged.

CarbonDioxideInfo ¶

CarbonDioxideInfo(name: str = 'Carbon Dioxide', *, native_id: str | None = None)

Bases: Sensor[CarbonDioxideInfoProperties, TStorage, str], Generic[TStorage]

Carbon dioxide info sensor. Reports current CO2 concentration in ppm.

setCurrent ¶

setCurrent(value: float) -> None

Report a new CO2 reading. Clamped to [0, 40000] ppm.

Parameters:

Name	Type	Description	Default
`value`	`float`	CO2 reading in parts per million.	required

Example

carbonDioxide.setCurrent(600)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

CarbonMonoxideSensor ¶

CarbonMonoxideSensor(name: str = 'Carbon Monoxide Sensor', *, native_id: str | None = None)

Bases: Sensor[CarbonMonoxideSensorProperties, TStorage, str], Generic[TStorage]

Carbon monoxide detector sensor.

setDetected ¶

setDetected(value: bool) -> None

Report carbon monoxide detection state.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when carbonMonoxide is currently detected.	required

Example

carbonMonoxide.setDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

ClassifierDetection ¶

Bases: Detection

A classifier detection result with an open attribute for classifier categories.

attribute `instance-attribute` ¶

attribute: str

Classifier category (e.g. "bird", "delivery"). Open string for any classifier.

subAttribute `instance-attribute` ¶

subAttribute: str

Classifier sub-category (e.g. "woodpecker", "amazon").

ClassifierDetectorSensor ¶

ClassifierDetectorSensor(name: str = 'Classifier', *, native_id: str | None = None)

Bases: ClassifierSensor[TStorage], Generic[TStorage]

Classifier detector that receives video frames from the backend pipeline.

Extend this class and implement detectClassifications to run image classification models against trigger regions. The backend scales frames to match modelSpec.input dimensions before each call.

detectClassifications `abstractmethod` `async` ¶

detectClassifications(frames: list[VideoFrameData]) -> list[ClassifierResult]

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.

ClassifierResult ¶

Bases: TypedDict

Return type for ClassifierDetectorSensor.detectClassifications().

detected `instance-attribute` ¶

detected: bool

Whether any classification result is emitted for this frame.

detections `instance-attribute` ¶

detections: list[ClassifierDetection]

Detections emitted for this frame.

ClassifierSensor ¶

ClassifierSensor(name: str = 'Classifier', *, native_id: str | None = None)

Bases: Sensor[ClassifierSensorProperties, TStorage, str], Generic[TStorage]

General-purpose image classifier sensor.

Plugin authors call reportDetections(list) to push classification results. detected and labels are auto-derived from the detection list.

reportDetections ¶

reportDetections(detected: bool, detections: list[ClassifierDetection] | None = None) -> None

Report classification results. Auto-derives detected and labels from the list.

reportDetections(True): generic classification trigger. The SDK synthesizes a single full-frame detection with empty attribute and sub-attribute.
reportDetections(True, [...]): explicit classifier detections.
reportDetections(False): clear.

Parameters:

Name	Type	Description	Default
`detected`	`bool`	Whether any classification result is active.	required
`detections`	`list[ClassifierDetection] \| None`	Optional explicit classifier detections to publish.	`None`

Example

sensor.reportDetections(
    True,
    [
        ClassifierDetection(
            label="animal",
            confidence=0.88,
            box=BoundingBox(x=0.1, y=0.2, width=0.3, height=0.4),
            attribute="bird",
            subAttribute="woodpecker",
        )
    ],
)
sensor.reportDetections(False)

clearDetections ¶

clearDetections() -> None

Explicitly clear classifier state (detected = False, detections = [], labels = []).

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

ClipDetectorSensor ¶

ClipDetectorSensor(name: str = 'CLIP Sensor', *, native_id: str | None = None)

Bases: Sensor[dict[str, Any], TStorage, str], Generic[TStorage]

CLIP detector sensor that receives video frames and generates semantic embeddings.

Extend this class and implement detectEmbeddings to produce CLIP embeddings for downstream semantic search.

detectEmbeddings `abstractmethod` `async` ¶

detectEmbeddings(frames: list[VideoFrameData]) -> list[ClipResult]

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.

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

ClipEmbedding ¶

Bases: TypedDict

A CLIP embedding result for a detected region.

label `instance-attribute` ¶

label: str

Detection label this embedding was computed for (e.g. "person", "vehicle").

box `instance-attribute` ¶

box: BoundingBox

Bounding box of the detected region in normalized coordinates.

embedding `instance-attribute` ¶

embedding: list[float]

CLIP embedding vector.

ClipResult ¶

Bases: TypedDict

Return type for ClipDetectorSensor.detectEmbeddings().

embeddings `instance-attribute` ¶

embeddings: list[ClipEmbedding]

Embeddings emitted for this frame.

embeddingModel `instance-attribute` ¶

embeddingModel: str

Identifier of the embedding model used to produce the vectors.

ColdSensor ¶

ColdSensor(name: str = 'Cold Sensor', *, native_id: str | None = None)

Bases: Sensor[ColdSensorProperties, TStorage, str], Generic[TStorage]

Cold alarm sensor.

setDetected ¶

setDetected(value: bool) -> None

Report abnormal cold detection state.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when cold is currently detected.	required

Example

cold.setDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

ContactSensor ¶

ContactSensor(name: str = 'Contact Sensor', *, native_id: str | None = None)

Bases: Sensor[ContactSensorProperties, TStorage, str], Generic[TStorage]

Contact sensor for door/window open-close state.

setDetected ¶

setDetected(value: bool) -> None

Report contact state (True = open, False = closed).

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when the contact is open, False when closed.	required

Example

contact.setDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

BoundingBox ¶

Bases: TypedDict

Bounding box of a detection.

All coordinates are normalized to 0-1 (fraction of frame dimensions), so they are independent of resolution.

x `instance-attribute` ¶

x: float

X coordinate of the top-left corner (0-1).

y `instance-attribute` ¶

y: float

Y coordinate of the top-left corner (0-1).

width `instance-attribute` ¶

width: float

Width as a fraction of frame width (0-1).

height `instance-attribute` ¶

height: float

Height as a fraction of frame height (0-1).

Detection ¶

Bases: TypedDict

A single detection result emitted by any detection sensor.

label `instance-attribute` ¶

label: DetectionLabel

Detection label (e.g. "person", "vehicle").

confidence `instance-attribute` ¶

confidence: float

Confidence score in the range 0-1.

box `instance-attribute` ¶

box: BoundingBox

Bounding box in normalized coordinates.

attribute `instance-attribute` ¶

attribute: NotRequired[str]

Optional sub-detection attribute (DetectionAttribute or classifier-specific).

VideoFrameData ¶

Bases: TypedDict

Video frame data delivered to detector sensors by the backend pipeline.

The backend handles capture, decoding and scaling. Detectors only process the pixel payload.

id `instance-attribute` ¶

id: str

Unique frame or crop identifier used to map batch results back to inputs.

cameraId `instance-attribute` ¶

cameraId: NotRequired[str]

Camera the frame originated from.

data `instance-attribute` ¶

data: bytes

Raw pixel buffer.

width `instance-attribute` ¶

width: int

Frame width in pixels.

height `instance-attribute` ¶

height: int

Frame height in pixels.

format `instance-attribute` ¶

format: Literal['nv12', 'rgb', 'rgba', 'gray']

Pixel format: rgb=3 bytes/pixel, rgba=4 bytes/pixel, gray=1 byte/pixel, nv12=YUV semi-planar.

timestamp `instance-attribute` ¶

timestamp: NotRequired[int]

Capture timestamp in milliseconds since epoch.

label `instance-attribute` ¶

label: NotRequired[str]

Trigger label propagated by the coordinator for secondary detectors.

DoorbellTrigger ¶

DoorbellTrigger(name: str = 'Doorbell', *, native_id: str | None = None)

Bases: Sensor[DoorbellTriggerProperties, TStorage, str], Generic[TStorage]

Doorbell trigger sensor.

Plugin authors call trigger() to fire a doorbell event. The ring property is set to True and automatically reset to False after a short delay (RING_AUTO_RESET_MS). Calling trigger() again while still ringing resets the timer (extends the ring phase).

trigger ¶

trigger() -> None

Trigger a doorbell ring. Sets ring = True and auto-resets after a short delay. Re-triggering while still ringing extends the ring phase.

Example

doorbell.trigger()

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Routes generic property writes to the semantic setters.

Writing ring=false is ignored, the auto-reset timer owns the off transition.

FaceDetection ¶

Bases: Detection

A face detection result, extending Detection with face-specific fields.

attribute `instance-attribute` ¶

attribute: Literal['face']

Sub-detection attribute, fixed to "face".

identity `instance-attribute` ¶

identity: NotRequired[str]

Recognized identity name, if matched against known faces.

embedding `instance-attribute` ¶

embedding: NotRequired[list[float]]

Face embedding vector for recognition/comparison.

thumbnail `instance-attribute` ¶

thumbnail: NotRequired[bytes]

JPEG thumbnail crop of the detected face.

FaceDetectorSensor ¶

FaceDetectorSensor(name: str = 'Face Sensor', *, native_id: str | None = None)

Bases: 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. The backend scales frames to match modelSpec.input dimensions before each call.

detectFaces `abstractmethod` `async` ¶

detectFaces(frames: list[VideoFrameData]) -> list[FaceResult]

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.

FaceResult ¶

Bases: TypedDict

Return type for FaceDetectorSensor.detectFaces().

detected `instance-attribute` ¶

detected: bool

Whether any face is detected in this frame.

detections `instance-attribute` ¶

detections: list[FaceDetection]

Detections emitted for this frame.

FaceSensor ¶

FaceSensor(name: str = 'Face Sensor', *, native_id: str | None = None)

Bases: 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.

reportDetections ¶

reportDetections(detected: bool, detections: list[FaceDetection] | None = None) -> None

Report detected faces.

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 identity, embedding, and/or thumbnail.
reportDetections(False): clear.

Parameters:

Name	Type	Description	Default
`detected`	`bool`	Whether any face is currently detected.	required
`detections`	`list[FaceDetection] \| None`	Optional explicit face detections to publish.	`None`

Example

sensor.reportDetections(
    True,
    [
        FaceDetection(
            label="person",
            confidence=0.94,
            box=BoundingBox(x=0.4, y=0.2, width=0.15, height=0.25),
            attribute="face",
            identity="Alice",
        )
    ],
)
sensor.reportDetections(False)

clearDetections ¶

clearDetections() -> None

Explicitly clear face detection state (detected = False, detections = []).

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

GarageControl ¶

GarageControl(name: str = 'Garage', *, native_id: str | None = None)

Bases: 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.

For long-running transitions (Opening/Closing intermediate states) override setTargetState and write currentState separately as the door moves.

setTargetState `async` ¶

setTargetState(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.

Parameters:

Name	Type	Description	Default
`value`	`GarageState`	Desired target state from the `GarageState` enum.	required

Example

from camera_ui_sdk import GarageState

await garage.setTargetState(GarageState.Open)

setCurrentState ¶

setCurrentState(value: GarageState) -> None

Publish the actual door state. Use this to drive long-running transitions (Open, then Closing, then Closed) independently of the user-requested target state. Read-only from cross-process consumers (updateValue ignores it).

Parameters:

Name	Type	Description	Default
`value`	`GarageState`	Current physical door state from the `GarageState` enum.	required

Example

from camera_ui_sdk import GarageState

garage.setCurrentState(GarageState.Closing)

setObstructionDetected ¶

setObstructionDetected(value: bool) -> None

Publish the obstruction-detected state. Read-only from the consumer side (updateValue ignores it), plugin code calls this when its hardware reports an obstruction sensor change.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when an obstruction is currently detected.	required

Example

garage.setObstructionDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Routes generic property writes to the semantic setters.

Only targetState is externally writable.

GarageState ¶

Bases: IntEnum

Garage door states.

Open `class-attribute` `instance-attribute` ¶

Open = 0

Door is fully open.

Closed `class-attribute` `instance-attribute` ¶

Closed = 1

Door is fully closed.

Opening `class-attribute` `instance-attribute` ¶

Opening = 2

Door is moving towards open.

Closing `class-attribute` `instance-attribute` ¶

Closing = 3

Door is moving towards closed.

Stopped `class-attribute` `instance-attribute` ¶

Stopped = 4

Door stopped part-way.

GasSensor ¶

GasSensor(name: str = 'Gas Sensor', *, native_id: str | None = None)

Bases: Sensor[GasSensorProperties, TStorage, str], Generic[TStorage]

Gas detector sensor.

setDetected ¶

setDetected(value: bool) -> None

Report gas detection state.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when gas is currently detected.	required

Example

gas.setDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

HeatSensor ¶

HeatSensor(name: str = 'Heat Sensor', *, native_id: str | None = None)

Bases: Sensor[HeatSensorProperties, TStorage, str], Generic[TStorage]

Heat alarm sensor.

setDetected ¶

setDetected(value: bool) -> None

Report abnormal heat detection state.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when heat is currently detected.	required

Example

heat.setDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

HumidityInfo ¶

HumidityInfo(name: str = 'Humidity', *, native_id: str | None = None)

Bases: Sensor[HumidityInfoProperties, TStorage, str], Generic[TStorage]

Humidity info sensor. Reports current relative humidity in %.

setCurrent ¶

setCurrent(value: float) -> None

Report a new humidity reading. Clamped to [0, 100] %.

Parameters:

Name	Type	Description	Default
`value`	`float`	Relative humidity percentage in the range 0-100.	required

Example

humidity.setCurrent(63)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

IlluminanceInfo ¶

IlluminanceInfo(name: str = 'Illuminance', *, native_id: str | None = None)

Bases: Sensor[IlluminanceInfoProperties, TStorage, str], Generic[TStorage]

Illuminance info sensor. Reports current light level in lux.

setCurrent ¶

setCurrent(value: float) -> None

Report a new illuminance reading. Clamped to [0, 200000] lx.

Parameters:

Name	Type	Description	Default
`value`	`float`	Illuminance reading in lux.	required

Example

illuminance.setCurrent(120)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

LeakSensor ¶

LeakSensor(name: str = 'Leak Sensor', *, native_id: str | None = None)

Bases: Sensor[LeakSensorProperties, TStorage, str], Generic[TStorage]

Water leak detector sensor.

setDetected ¶

setDetected(value: bool) -> None

Report leak detection state.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when a water leak is currently detected.	required

Example

leak.setDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

LicensePlateDetection ¶

Bases: Detection

A license plate detection result, extending Detection with OCR fields.

attribute `instance-attribute` ¶

attribute: Literal['license_plate']

Sub-detection attribute, fixed to "license_plate".

plateText `instance-attribute` ¶

plateText: str

Recognized plate text (e.g. "ABC 1234").

ocrConfidence `instance-attribute` ¶

ocrConfidence: NotRequired[float]

Average text recognition confidence (0-1), separate from the box confidence.

LicensePlateDetectorSensor ¶

LicensePlateDetectorSensor(name: str = 'License Plate Sensor', *, native_id: str | None = None)

Bases: 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. The backend scales frames to match modelSpec.input dimensions before each call.

detectLicensePlates `abstractmethod` `async` ¶

detectLicensePlates(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 result per input frame, in the same order.

LicensePlateResult ¶

Bases: TypedDict

Return type for LicensePlateDetectorSensor.detectLicensePlates().

detected `instance-attribute` ¶

detected: bool

Whether any license plate is detected in this frame.

detections `instance-attribute` ¶

detections: list[LicensePlateDetection]

Detections emitted for this frame.

LicensePlateSensor ¶

LicensePlateSensor(name: str = 'License Plate Sensor', *, native_id: str | None = None)

Bases: Sensor[LicensePlateSensorProperties, TStorage, str], Generic[TStorage]

License plate sensor that reports detected plates with OCR text.

Plugin authors call reportDetections(list) to push detected plates. detected is auto-derived from the detection list.

reportDetections ¶

reportDetections(detected: bool, detections: list[LicensePlateDetection] | None = None) -> None

Report detected license plates.

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.

Parameters:

Name	Type	Description	Default
`detected`	`bool`	Whether any license plate is currently detected.	required
`detections`	`list[LicensePlateDetection] \| None`	Optional explicit plate detections to publish.	`None`

Example

sensor.reportDetections(
    True,
    [
        LicensePlateDetection(
            label="vehicle",
            confidence=0.93,
            box=BoundingBox(x=0.2, y=0.5, width=0.2, height=0.08),
            attribute="license_plate",
            plateText="ABC 1234",
        )
    ],
)
sensor.reportDetections(False)

clearDetections ¶

clearDetections() -> None

Explicitly clear license plate state (detected = False, detections = []).

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

LightCapability ¶

Bases: StrEnum

Optional capabilities of a light control.

Brightness `class-attribute` `instance-attribute` ¶

Brightness = 'brightness'

Light supports brightness adjustment (0-100).

LightControl ¶

LightControl(name: str = 'Light', *, native_id: str | None = None)

Bases: 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 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 bypasses any plugin override and only syncs state.

setOn `async` ¶

setOn() -> None

Turn the light on. Override to drive hardware and call await super().setOn() after the hardware call succeeds to sync the SDK state.

Example

await light.setOn()

setOff `async` ¶

setOff() -> None

Turn the light off. Override to drive hardware and call await super().setOff() after the hardware call succeeds to sync the SDK state.

Example

await light.setOff()

setBrightness `async` ¶

setBrightness(value: int) -> None

Set brightness. Override to drive hardware and call await super().setBrightness(value) after the hardware call succeeds. The default implementation clamps the value to [0, 100].

Parameters:

Name	Type	Description	Default
`value`	`int`	Brightness level in the range 0-100.	required

Example

await light.setBrightness(75)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Routes generic property writes to the semantic setters.

Only on and brightness are externally writable.

LockControl ¶

LockControl(name: str = 'Lock', *, native_id: str | None = None)

Bases: 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 implementation updates both targetState and currentState to the new value.

For asymmetric flows (long-running unlock with intermediate state) override setTargetState and write currentState separately when transitions complete.

setTargetState `async` ¶

setTargetState(value: LockState) -> 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.

Parameters:

Name	Type	Description	Default
`value`	`LockState`	Desired lock state from the `LockState` enum.	required

Example

from camera_ui_sdk import LockState

await lock.setTargetState(LockState.Secured)

setCurrentState ¶

setCurrentState(value: LockState) -> None

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).

Parameters:

Name	Type	Description	Default
`value`	`LockState`	Current physical lock state from the `LockState` enum.	required

Example

from camera_ui_sdk import LockState

lock.setCurrentState(LockState.Unknown)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Routes generic property writes to the semantic setters.

Only targetState is externally writable, currentState is observed-only.

LockState ¶

Bases: IntEnum

Lock states.

Secured `class-attribute` `instance-attribute` ¶

Secured = 0

Locked.

Unsecured `class-attribute` `instance-attribute` ¶

Unsecured = 1

Unlocked.

Unknown `class-attribute` `instance-attribute` ¶

Unknown = 2

State cannot be determined, e.g. while a motorized lock is moving.

MotionDetectorSensor ¶

MotionDetectorSensor(name: str = 'Motion Sensor', *, native_id: str | None = None)

Bases: MotionSensor[TStorage], Generic[TStorage]

Motion detector that receives video frames from the backend pipeline.

Extend this class and implement detectMotion to analyze frames for motion. The backend calls detectMotion at the configured frame interval, zone-filters the returned detections and applies them. detected is re-derived from the surviving detections, so a result with no detections reports no motion.

detectMotion `abstractmethod` `async` ¶

detectMotion(frame: VideoFrameData) -> MotionResult

Analyze a single video frame for motion. Called by the backend at the configured interval.

MotionResult ¶

Bases: TypedDict

Return type for MotionDetectorSensor.detectMotion().

detected `instance-attribute` ¶

detected: bool

Whether motion is detected in this frame. Ignored by the backend, which re-derives it from the detections.

detections `instance-attribute` ¶

detections: list[Detection]

Detections emitted for this frame.

MotionSensor ¶

MotionSensor(name: str = 'Motion Sensor', *, native_id: str | None = None)

Bases: 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 set by the backend dwell logic, reportDetections() is a no-op while it is set.

reportDetections ¶

reportDetections(detected: bool, detections: list[Detection] | None = None) -> None

Report a motion detection result.

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).

No-op while the sensor is blocked by backend dwell logic.

Parameters:

Name	Type	Description	Default
`detected`	`bool`	Whether motion is currently detected.	required
`detections`	`list[Detection] \| None`	Optional explicit detections produced for this frame.	`None`

Example

sensor.reportDetections(
    True,
    [
        Detection(
            label="motion",
            confidence=0.85,
            box=BoundingBox(x=0.1, y=0.2, width=0.3, height=0.4),
        )
    ],
)
sensor.reportDetections(False)

clearDetections ¶

clearDetections() -> None

Explicitly clear motion state (detected = False, detections = []).

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

ObjectDetectorSensor ¶

ObjectDetectorSensor(name: str = 'Object Sensor', *, native_id: str | None = None)

Bases: ObjectSensor[TStorage], Generic[TStorage]

Object detector that receives video frames from the backend pipeline.

Extend this class and implement detectObjects and modelSpec. The backend scales frames to match modelSpec.input dimensions before each call.

detectObjects `abstractmethod` `async` ¶

detectObjects(frame: VideoFrameData) -> ObjectResult

Analyze a single video frame for objects. Called by the backend at the configured interval.

ObjectResult ¶

Bases: TypedDict

Return type for ObjectDetectorSensor.detectObjects().

detected `instance-attribute` ¶

detected: bool

Whether any object is detected in this frame.

detections `instance-attribute` ¶

detections: list[TrackedDetection]

Detections emitted for this frame.

ObjectSensor ¶

ObjectSensor(name: str = 'Object Sensor', *, native_id: str | None = None)

Bases: Sensor[ObjectSensorProperties, TStorage, str], Generic[TStorage]

Object detection sensor that reports detected objects (person, vehicle, animal, etc.).

Plugin authors call reportDetections(list) to push detection results. detected and labels are auto-derived from the detection list.

reportDetections ¶

reportDetections(detected: bool, detections: list[TrackedDetection] | None = None) -> None

Report detected objects. Auto-derives detected and labels from the list.

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.

Parameters:

Name	Type	Description	Default
`detected`	`bool`	Whether any object is currently detected.	required
`detections`	`list[TrackedDetection] \| None`	Optional explicit object detections (with optional tracking metadata).	`None`

Example

sensor.reportDetections(
    True,
    [
        TrackedDetection(
            label="person",
            confidence=0.92,
            box=BoundingBox(x=0.1, y=0.2, width=0.3, height=0.4),
        )
    ],
)
sensor.reportDetections(False)

clearDetections ¶

clearDetections() -> None

Explicitly clear detection state (detected = False, detections = [], labels = []).

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

TrackedDetection ¶

Bases: Detection

Detection enriched with tracking metadata (stable IDs, velocity).

trackId `instance-attribute` ¶

trackId: int

Stable sequential ID for this object across frames.

trackAge `instance-attribute` ¶

trackAge: int

Number of frames this object has been continuously tracked.

trackSpeed `instance-attribute` ¶

trackSpeed: float

Velocity magnitude in normalized units per frame. 0 = stationary.

trackVelocity `instance-attribute` ¶

trackVelocity: TrackVelocity

Signed centroid velocity in normalized units per frame.

trackLost `instance-attribute` ¶

trackLost: bool

True if the object was not matched in the current frame.

stationarySince `instance-attribute` ¶

stationarySince: float

Epoch ms since the object has been still. Only present while it is settled.

OccupancySensor ¶

OccupancySensor(name: str = 'Occupancy Sensor', *, native_id: str | None = None)

Bases: Sensor[OccupancySensorProperties, TStorage, str], Generic[TStorage]

Occupancy sensor for detecting presence in a room or area.

setDetected ¶

setDetected(value: bool) -> None

Report occupancy state.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when the area is currently occupied.	required

Example

occupancy.setDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

PowerSensor ¶

PowerSensor(name: str = 'Power Sensor', *, native_id: str | None = None)

Bases: Sensor[PowerSensorProperties, TStorage, str], Generic[TStorage]

Power detection sensor.

setDetected ¶

setDetected(value: bool) -> None

Report power detection state.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when power is currently detected.	required

Example

power.setDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

ProblemSensor ¶

ProblemSensor(name: str = 'Problem Sensor', *, native_id: str | None = None)

Bases: Sensor[ProblemSensorProperties, TStorage, str], Generic[TStorage]

Generic problem/fault sensor.

setDetected ¶

setDetected(value: bool) -> None

Report the problem state.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when problem is currently detected.	required

Example

problem.setDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

PTZCapability ¶

Bases: StrEnum

Optional capabilities of a PTZ control.

Pan `class-attribute` `instance-attribute` ¶

Pan = 'pan'

Camera supports panning (horizontal movement).

Tilt `class-attribute` `instance-attribute` ¶

Tilt = 'tilt'

Camera supports tilting (vertical movement).

Zoom `class-attribute` `instance-attribute` ¶

Zoom = 'zoom'

Camera supports zoom.

Presets `class-attribute` `instance-attribute` ¶

Presets = 'presets'

Camera supports named position presets.

Home `class-attribute` `instance-attribute` ¶

Home = 'home'

Camera supports a home position.

RelativeMove `class-attribute` `instance-attribute` ¶

RelativeMove = 'relativeMove'

Camera executes relative displacement moves.

AbsolutePosition `class-attribute` `instance-attribute` ¶

AbsolutePosition = 'absolutePosition'

Camera accepts absolute position writes via setPosition().

VelocityControl `class-attribute` `instance-attribute` ¶

VelocityControl = 'velocityControl'

Camera accepts continuous-move commands via setVelocity().

PTZControl ¶

PTZControl(name: str = 'PTZ', *, native_id: str | None = None)

Bases: Sensor[PTZControlProperties, TStorage, PTZCapability], Generic[TStorage]

Pan-tilt-zoom camera control.

Override setPosition() / setVelocity() / setTargetPreset() to drive hardware, then call the corresponding super().X() method after success to sync the SDK state. For hardware-pushed state updates (e.g. PTZ position change events), call the super methods from your event handler. That bypasses any plugin override and only syncs state.

Set capabilities to advertise supported axes and features. Use setPresets() to publish the discovered preset list and setMoving() to publish movement state.

setPosition `async` ¶

setPosition(value: PTZPosition) -> None

Move to an absolute pan/tilt/zoom position. Override to drive hardware and call await super().setPosition(value) after success to sync the SDK state.

Parameters:

Name	Type	Description	Default
`value`	`PTZPosition`	Absolute pan/tilt/zoom target position.	required

Example

await ptz.setPosition({"pan": 0.25, "tilt": -0.1, "zoom": 0.5})

setVelocity `async` ¶

setVelocity(value: PTZDirection | None) -> None

Continuous-move command. Override to drive hardware and call await super().setVelocity(value) after success to sync the SDK state.

Parameters:

Name	Type	Description	Default
`value`	`PTZDirection \| None`	Per-axis speeds in `[-1, 1]`. Stop is zero on every axis. `None` is ignored and the published `velocity` keeps its last value.	required

Example

await ptz.setVelocity({"panSpeed": 0.5, "tiltSpeed": 0, "zoomSpeed": 0})
await ptz.setVelocity({"panSpeed": 0, "tiltSpeed": 0, "zoomSpeed": 0})  # stop

setRelativeMove `async` ¶

setRelativeMove(value: PTZRelativeMove) -> None

Relative displacement move. Override to drive hardware (e.g. ONVIF RelativeMove in a translation space) and call await super().setRelativeMove(value) after success to sync the SDK state. Advertise PTZCapability.RelativeMove when the camera supports it.

Parameters:

Name	Type	Description	Default
`value`	`PTZRelativeMove`	Per-axis displacement, normalized to the field of view.	required

Example

# move the view a third of a frame to the right, a tenth down
await ptz.setRelativeMove({"panDelta": 0.33, "tiltDelta": -0.1, "zoomDelta": 0})

setTargetPreset `async` ¶

setTargetPreset(value: str | None) -> None

Preset-move command. Override to drive hardware and call await super().setTargetPreset(value) after success to sync the SDK state.

Parameters:

Name	Type	Description	Default
`value`	`str \| None`	Preset name to move to. `None` is ignored and the published `targetPreset` keeps its last value.	required

Example

await ptz.setTargetPreset("Driveway")

setPresets ¶

setPresets(value: list[str]) -> None

Publish the discovered preset list (typically called once at startup).

Parameters:

Name	Type	Description	Default
`value`	`list[str]`	List of preset names supported by the camera.	required

Example

ptz.setPresets(["Home", "Driveway", "Backyard"])

setMoving ¶

setMoving(value: bool) -> None

Publish movement state (e.g. when continuous-move starts/stops).

Parameters:

Name	Type	Description	Default
`value`	`bool`	True while the camera is moving.	required

Example

ptz.setMoving(True)

goHome `async` ¶

goHome() -> None

Move the camera to the home position (pan=0, tilt=0, zoom=0).

Example

await ptz.goHome()

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Routes generic property writes to the semantic setters.

PTZDirection ¶

Bases: TypedDict

PTZ movement speed for continuous move commands.

Speeds are in normalized range [-1, 1] where:

-1 = maximum speed in negative direction
0 = stop movement
1 = maximum speed in positive direction

Conventions: positive panSpeed = right, positive tiltSpeed = up, positive zoomSpeed = zoom in. Plugins should clamp values to [-1, 1] and map them to hardware-specific speeds.

PTZPosition ¶

Bases: TypedDict

Absolute PTZ position.

PTZRelativeMove ¶

Bases: TypedDict

Relative displacement for a single PTZ move.

Deltas are normalized to the camera's field of view: panDelta: 1 moves the view by one full frame width, tiltDelta: 1 by one full frame height. Conventions match :class:PTZDirection: positive panDelta = right, positive tiltDelta = up, positive zoomDelta = zoom in. Plugins map the deltas to hardware-specific translation spaces (e.g. ONVIF RelativeMove).

SecuritySystem ¶

SecuritySystem(name: str = 'Security System', *, native_id: str | None = None)

Bases: Sensor[SecuritySystemProperties, TStorage, str], Generic[TStorage]

Security system control.

Override setTargetState() to drive hardware and call await super().setTargetState(value) once the hardware confirms. The base implementation updates both targetState and currentState.

setTargetState `async` ¶

setTargetState(value: SecuritySystemState) -> 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.

Parameters:

Name	Type	Description	Default
`value`	`SecuritySystemState`	Desired armed/disarmed state from `SecuritySystemState`.	required

Example

from camera_ui_sdk import SecuritySystemState

await alarm.setTargetState(SecuritySystemState.AwayArm)

setCurrentState ¶

setCurrentState(value: SecuritySystemState) -> None

Publish the actual security system state. Use this for transitions that diverge from the user-requested target: AlarmTriggered when an intruder is detected, or arming-delay intermediate states. Read-only from cross-process consumers (updateValue ignores it).

Parameters:

Name	Type	Description	Default
`value`	`SecuritySystemState`	Current security system state from `SecuritySystemState`.	required

Example

from camera_ui_sdk import SecuritySystemState

alarm.setCurrentState(SecuritySystemState.AlarmTriggered)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Routes generic property writes to the semantic setters.

SecuritySystemState ¶

Bases: IntEnum

Security system arm/disarm states.

StayArm `class-attribute` `instance-attribute` ¶

StayArm = 0

Armed, occupants home.

AwayArm `class-attribute` `instance-attribute` ¶

AwayArm = 1

Armed, occupants away.

NightArm `class-attribute` `instance-attribute` ¶

NightArm = 2

Armed for night mode.

Disarmed `class-attribute` `instance-attribute` ¶

Disarmed = 3

System disarmed.

AlarmTriggered `class-attribute` `instance-attribute` ¶

AlarmTriggered = 4

Alarm is triggered.

SirenCapability ¶

Bases: StrEnum

Optional capabilities of a siren control.

Volume `class-attribute` `instance-attribute` ¶

Volume = 'volume'

Siren supports volume adjustment (0-100).

SirenControl ¶

SirenControl(name: str = 'Siren', *, native_id: str | None = None)

Bases: Sensor[SirenControlProperties, TStorage, SirenCapability], Generic[TStorage]

Siren control sensor. Override setActive()/setInactive() to drive your hardware, then await super().setActive() / await super().setInactive() to sync the SDK state. For hardware-pushed updates, call the super methods from your event handler. That bypasses any plugin override and only syncs state.

setActive `async` ¶

setActive() -> None

Activate the siren. Override to drive hardware and call await super().setActive() after success to sync the SDK state.

Example

await siren.setActive()

setInactive `async` ¶

setInactive() -> None

Deactivate the siren. Override to drive hardware and call await super().setInactive() after success to sync the SDK state.

Example

await siren.setInactive()

setVolume `async` ¶

setVolume(value: int) -> None

Set volume. Override to drive hardware and call await super().setVolume(value) after success. The default implementation clamps the value to [0, 100].

Parameters:

Name	Type	Description	Default
`value`	`int`	Volume level in the range 0-100.	required

Example

await siren.setVolume(80)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Routes generic property writes to the semantic setters.

SmokeSensor ¶

SmokeSensor(name: str = 'Smoke Sensor', *, native_id: str | None = None)

Bases: Sensor[SmokeSensorProperties, TStorage, str], Generic[TStorage]

Smoke detector sensor.

setDetected ¶

setDetected(value: bool) -> None

Report smoke detection state.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when smoke is currently detected.	required

Example

smoke.setDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

AudioInputSpec ¶

Bases: TypedDict

Expected audio input format for an audio detector model.

sampleRate `instance-attribute` ¶

sampleRate: int

Sample rate in Hz the model expects.

channels `instance-attribute` ¶

channels: int

Channel count the model expects (typically 1 = mono).

format `instance-attribute` ¶

format: Literal['pcm16', 'float32']

Sample format: pcm16=16-bit signed integer PCM, float32=32-bit float.

samplesPerFrame `instance-attribute` ¶

samplesPerFrame: NotRequired[int]

Number of samples per audio frame the detector expects; the backend buffers audio to deliver exactly this many samples per call.

AudioModelSpec ¶

Bases: ModelRuntime

Model spec for audio detectors.

input `instance-attribute` ¶

input: AudioInputSpec

Required input audio format.

LoadedModel ¶

Bases: TypedDict

One model a sensor has loaded. Reported for the metrics view and for debugging.

name `instance-attribute` ¶

name: str

Resolved model name, after any "default" placeholder (e.g. "yolo-v9-s-320").

role `instance-attribute` ¶

role: NotRequired[str]

What this model does inside a sensor that loads several: "detect", "embed", "ocr", "text".

device `instance-attribute` ¶

device: NotRequired[str]

Where inference runs, resolved to the real device (e.g. "GPU.0", "ANE", "TPU:0", "CPU").

precision `instance-attribute` ¶

precision: NotRequired[str]

Weight precision: "fp32", "fp16", "int8".

loadMs `instance-attribute` ¶

loadMs: NotRequired[int]

How long loading this model took, in milliseconds.

ModelRuntime ¶

Bases: TypedDict

What a sensor runs on. Optional throughout: a plugin that reports nothing simply shows nothing.

runtime `instance-attribute` ¶

runtime: NotRequired[str]

Inference framework and version, e.g. "openvino 2025.3.0".

models `instance-attribute` ¶

models: NotRequired[list[LoadedModel]]

Models this sensor has loaded, primary one first.

ModelSpec ¶

Bases: ModelRuntime

Model spec for detectors with fixed output labels (face, classifier, license plate).

Declares the input shape the backend should produce and the trigger labels that should activate this detector.

input `instance-attribute` ¶

input: VideoInputSpec

Required input frame dimensions and pixel format.

triggerLabels `instance-attribute` ¶

triggerLabels: list[str]

Labels emitted by an upstream object detector that activate this detector.

embeddingModel `instance-attribute` ¶

embeddingModel: NotRequired[str]

Embedding model identifier. Required for face recognition and for CLIP: embeddings are stored and matched under this id.

ObjectModelSpec ¶

Bases: ModelRuntime

Model spec for object detectors.

Only declares input dimensions, the output label set is dynamic and comes from the model itself.

input `instance-attribute` ¶

input: VideoInputSpec

Required input frame dimensions and pixel format.

VideoInputSpec ¶

Bases: TypedDict

Expected video input dimensions and pixel format for a detector model.

width `instance-attribute` ¶

width: int

Expected frame width in pixels.

height `instance-attribute` ¶

height: int

Expected frame height in pixels.

format `instance-attribute` ¶

format: Literal['rgb', 'nv12', 'gray']

Pixel format: rgb=3 bytes/pixel, gray=1 byte/pixel, nv12=YUV semi-planar.

SwitchControl ¶

SwitchControl(name: str = 'Switch', *, native_id: str | None = None)

Bases: Sensor[SwitchControlProperties, TStorage, str], Generic[TStorage]

Generic on/off switch control. Override setOn() / setOff() to drive hardware and call await super().setOn() / await super().setOff() after success to sync the SDK state. For hardware-pushed updates, call the super methods from your event handler. That bypasses any plugin override and only syncs state.

setOn `async` ¶

setOn() -> None

Turn the switch on. Override to drive hardware and call await super().setOn() after success to sync the SDK state.

Example

await sw.setOn()

setOff `async` ¶

setOff() -> None

Turn the switch off. Override to drive hardware and call await super().setOff() after success to sync the SDK state.

Example

await sw.setOff()

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Routes generic property writes to the semantic setters.

TamperSensor ¶

TamperSensor(name: str = 'Tamper Sensor', *, native_id: str | None = None)

Bases: Sensor[TamperSensorProperties, TStorage, str], Generic[TStorage]

Tamper sensor.

setDetected ¶

setDetected(value: bool) -> None

Report tampering detection state.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when tamper is currently detected.	required

Example

tamper.setDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

TemperatureInfo ¶

TemperatureInfo(name: str = 'Temperature', *, native_id: str | None = None)

Bases: Sensor[TemperatureInfoProperties, TStorage, str], Generic[TStorage]

Temperature info sensor. Reports current temperature in degrees Celsius.

setCurrent ¶

setCurrent(value: float) -> None

Report a new temperature reading. Clamped to [-270, 100] degrees Celsius.

Parameters:

Name	Type	Description	Default
`value`	`float`	Temperature reading in degrees Celsius.	required

Example

temperature.setCurrent(21.5)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

VibrationSensor ¶

VibrationSensor(name: str = 'Vibration Sensor', *, native_id: str | None = None)

Bases: Sensor[VibrationSensorProperties, TStorage, str], Generic[TStorage]

Vibration sensor.

setDetected ¶

setDetected(value: bool) -> None

Report vibration detection state.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True when vibration is currently detected.	required

Example

vibration.setDetected(True)

updateValue `async` ¶

updateValue(property: str, value: Any) -> None

Read-only sensor: external writes are ignored.

Sensors¶

camera_ui_sdk.sensor ¶

AudioDetectorSensor ¶

detectAudio abstractmethod async ¶

AudioFrameData ¶

cameraId instance-attribute ¶

data instance-attribute ¶

sampleRate instance-attribute ¶

channels instance-attribute ¶

format instance-attribute ¶

decibels instance-attribute ¶

timestamp instance-attribute ¶

AudioResult ¶

detected instance-attribute ¶

detections instance-attribute ¶

decibels instance-attribute ¶

AudioSensor ¶

reportDetections ¶

clearDetections ¶

setDecibels ¶

updateValue async ¶

Sensor ¶

on_start ¶

on_stop ¶

toJSON ¶

getValue ¶

getValues ¶

updateValue abstractmethod async ¶

hasCapability ¶

updateModelSpec ¶

SensorCategory ¶

Sensor class-attribute instance-attribute ¶

Control class-attribute instance-attribute ¶

Trigger class-attribute instance-attribute ¶

Info class-attribute instance-attribute ¶

SensorLike ¶

getValue ¶

getValues ¶

updateValue async ¶

hasCapability ¶

SensorPropertyChangeData ¶

property instance-attribute ¶

value instance-attribute ¶

timestamp instance-attribute ¶

SensorType ¶

Motion class-attribute instance-attribute ¶

Object class-attribute instance-attribute ¶

Audio class-attribute instance-attribute ¶

Face class-attribute instance-attribute ¶

LicensePlate class-attribute instance-attribute ¶

Classifier class-attribute instance-attribute ¶

Clip class-attribute instance-attribute ¶

ObjectAssist class-attribute instance-attribute ¶

CarbonDioxide class-attribute instance-attribute ¶

CarbonMonoxide class-attribute instance-attribute ¶

Cold class-attribute instance-attribute ¶

Contact class-attribute instance-attribute ¶

Gas class-attribute instance-attribute ¶

Heat class-attribute instance-attribute ¶

Humidity class-attribute instance-attribute ¶

Illuminance class-attribute instance-attribute ¶

Leak class-attribute instance-attribute ¶

Occupancy class-attribute instance-attribute ¶

Power class-attribute instance-attribute ¶

Problem class-attribute instance-attribute ¶

Smoke class-attribute instance-attribute ¶

Tamper class-attribute instance-attribute ¶

Temperature class-attribute instance-attribute ¶

Vibration class-attribute instance-attribute ¶

Light class-attribute instance-attribute ¶

Siren class-attribute instance-attribute ¶

Switch class-attribute instance-attribute ¶

Lock class-attribute instance-attribute ¶

Garage class-attribute instance-attribute ¶

PTZ class-attribute instance-attribute ¶

SecuritySystem class-attribute instance-attribute ¶

Doorbell class-attribute instance-attribute ¶

Battery class-attribute instance-attribute ¶

BatteryCapability ¶

LowBattery class-attribute instance-attribute ¶

detectAudio `abstractmethod` `async` ¶

cameraId `instance-attribute` ¶

data `instance-attribute` ¶

sampleRate `instance-attribute` ¶

channels `instance-attribute` ¶

format `instance-attribute` ¶

decibels `instance-attribute` ¶

timestamp `instance-attribute` ¶

detected `instance-attribute` ¶

detections `instance-attribute` ¶

decibels `instance-attribute` ¶

updateValue `async` ¶

updateValue `abstractmethod` `async` ¶

Sensor `class-attribute` `instance-attribute` ¶

Control `class-attribute` `instance-attribute` ¶

Trigger `class-attribute` `instance-attribute` ¶

Info `class-attribute` `instance-attribute` ¶

updateValue `async` ¶

property `instance-attribute` ¶

value `instance-attribute` ¶

timestamp `instance-attribute` ¶

Motion `class-attribute` `instance-attribute` ¶

Object `class-attribute` `instance-attribute` ¶

Audio `class-attribute` `instance-attribute` ¶

Face `class-attribute` `instance-attribute` ¶

LicensePlate `class-attribute` `instance-attribute` ¶

Classifier `class-attribute` `instance-attribute` ¶

Clip `class-attribute` `instance-attribute` ¶

ObjectAssist `class-attribute` `instance-attribute` ¶

CarbonDioxide `class-attribute` `instance-attribute` ¶

CarbonMonoxide `class-attribute` `instance-attribute` ¶

Cold `class-attribute` `instance-attribute` ¶

Contact `class-attribute` `instance-attribute` ¶

Gas `class-attribute` `instance-attribute` ¶

Heat `class-attribute` `instance-attribute` ¶

Humidity `class-attribute` `instance-attribute` ¶

Illuminance `class-attribute` `instance-attribute` ¶

Leak `class-attribute` `instance-attribute` ¶

Occupancy `class-attribute` `instance-attribute` ¶

Power `class-attribute` `instance-attribute` ¶

Problem `class-attribute` `instance-attribute` ¶

Smoke `class-attribute` `instance-attribute` ¶

Tamper `class-attribute` `instance-attribute` ¶

Temperature `class-attribute` `instance-attribute` ¶

Vibration `class-attribute` `instance-attribute` ¶

Light `class-attribute` `instance-attribute` ¶

Siren `class-attribute` `instance-attribute` ¶

Switch `class-attribute` `instance-attribute` ¶

Lock `class-attribute` `instance-attribute` ¶

Garage `class-attribute` `instance-attribute` ¶

PTZ `class-attribute` `instance-attribute` ¶

SecuritySystem `class-attribute` `instance-attribute` ¶

Doorbell `class-attribute` `instance-attribute` ¶

Battery `class-attribute` `instance-attribute` ¶

LowBattery `class-attribute` `instance-attribute` ¶

Charging `class-attribute` `instance-attribute` ¶

updateValue `async` ¶

NotChargeable `class-attribute` `instance-attribute` ¶

NotCharging `class-attribute` `instance-attribute` ¶

Charging `class-attribute` `instance-attribute` ¶

Full `class-attribute` `instance-attribute` ¶

updateValue `async` ¶

updateValue `async` ¶

attribute `instance-attribute` ¶

subAttribute `instance-attribute` ¶

detectClassifications `abstractmethod` `async` ¶

detected `instance-attribute` ¶

detections `instance-attribute` ¶

updateValue `async` ¶

detectEmbeddings `abstractmethod` `async` ¶

updateValue `async` ¶

label `instance-attribute` ¶

box `instance-attribute` ¶

embedding `instance-attribute` ¶

embeddings `instance-attribute` ¶

embeddingModel `instance-attribute` ¶

updateValue `async` ¶

updateValue `async` ¶

x `instance-attribute` ¶

y `instance-attribute` ¶