camera.ui Node SDK

Appearance

@camera.ui/sdk / sensor / PTZControl

Class: PTZControl<TStorage> ​

Defined in: sensor/ptz.ts:97

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.

Extends ​

Type Parameters ​

TStorage ​

TStorage extends object = Record<string, any>

Constructors ​

Constructor ​

new PTZControl<TStorage>(name?): PTZControl<TStorage>

Defined in: sensor/ptz.ts:101

Parameters ​

name? ​

string = 'PTZ'

Returns ​

PTZControl<TStorage>

Overrides ​

Sensor.constructor

Properties ​

_requiresFrames? ​

optional _requiresFrames?: boolean

Defined in: sensor/base.ts:223

Inherited from ​

Sensor._requiresFrames

category ​

readonly category: Control = SensorCategory.Control

Defined in: sensor/ptz.ts:99

Overrides ​

Sensor.category

id ​

readonly id: string

Defined in: sensor/base.ts:190

Inherited from ​

Sensor.id

name ​

readonly name: string

Defined in: sensor/base.ts:189

Inherited from ​

Sensor.name

onAssignmentChanged ​

readonly onAssignmentChanged: Observable<boolean>

Defined in: sensor/base.ts:209

Inherited from ​

ClipDetectorSensor.onAssignmentChanged

onCapabilitiesChanged ​

readonly onCapabilitiesChanged: Observable<PTZCapability[]>

Defined in: sensor/base.ts:200

Observable for capability changes. Emits the full capabilities array when capabilities change.

Inherited from ​

Sensor.onCapabilitiesChanged

onPropertyChanged ​

readonly onPropertyChanged: Observable<PropertyChangeOf<PTZControlProperties>>

Defined in: sensor/base.ts:198

Observable for property changes. Emits { property, value, timestamp } when any property changes.

Inherited from ​

Sensor.onPropertyChanged

type ​

readonly type: PTZ = SensorType.PTZ

Defined in: sensor/ptz.ts:98

Overrides ​

Sensor.type

Accessors ​

cameraId ​

Get Signature ​

get cameraId(): string

Defined in: sensor/base.ts:257

Camera ID this sensor belongs to. Throws if sensor not yet added to a camera.

Returns ​

string

Inherited from ​

ClipDetectorSensor.cameraId

capabilities ​

Get Signature ​

get capabilities(): TCapability[]

Defined in: sensor/base.ts:277

Optional feature flags advertised by this sensor (e.g., PTZ pan/tilt/zoom)

Returns ​

TCapability[]

Set Signature ​

set capabilities(value): void

Defined in: sensor/base.ts:282

Set capabilities and notify the backend. Automatically deduplicates.

Parameters ​
value ​

TCapability[]

Returns ​

void

Inherited from ​

Sensor.capabilities

displayName ​

Get Signature ​

get displayName(): string

Defined in: sensor/base.ts:233

Returns ​

string

Inherited from ​

Sensor.displayName

isAssigned ​

Get Signature ​

get isAssigned(): boolean

Defined in: sensor/base.ts:252

Whether this sensor has been assigned to a camera in the backend

Returns ​

boolean

Inherited from ​

ClipDetectorSensor.isAssigned

moving ​

Get Signature ​

get moving(): boolean

Defined in: sensor/ptz.ts:115

Returns ​

boolean

pluginId ​

Get Signature ​

get pluginId(): string | undefined

Defined in: sensor/base.ts:264

Returns ​

string | undefined

Inherited from ​

Sensor.pluginId

position ​

Get Signature ​

get position(): PTZPosition

Defined in: sensor/ptz.ts:111

Returns ​

PTZPosition

presets ​

Get Signature ​

get presets(): string[]

Defined in: sensor/ptz.ts:119

Returns ​

string[]

props ​

Get Signature ​

get protected props(): Readonly<TProperties>

Defined in: sensor/base.ts:295

Read-only access to the internal property store. Subclasses use this to read current state when implementing semantic methods (e.g., if (this.blocked) return).

Returns ​

Readonly<TProperties>

Inherited from ​

Sensor.props

storage ​

Get Signature ​

get storage(): DeviceStorage<TStorage>

Defined in: sensor/base.ts:269

Per-sensor persistent storage. Throws if sensor not yet added to a camera.

Returns ​

DeviceStorage<TStorage>

Inherited from ​

Sensor.storage

storageSchema ​

Get Signature ​

get storageSchema(): JsonSchema[]

Defined in: sensor/base.ts:216

Override to provide a JSON schema for per-sensor storage settings UI

Returns ​

JsonSchema[]

Inherited from ​

ClipDetectorSensor.storageSchema

targetPreset ​

Get Signature ​

get targetPreset(): string | undefined

Defined in: sensor/ptz.ts:127

Returns ​

string | undefined

velocity ​

Get Signature ​

get velocity(): PTZDirection | undefined

Defined in: sensor/ptz.ts:123

Returns ​

PTZDirection | undefined

Methods ​

getValue() ​

Call Signature ​

getValue<K>(property): PTZControlProperties[K] | undefined

Defined in: sensor/base.ts:303

Get the current value of a sensor property. Type-safe via the generic overload — call with a property enum value to get a properly typed result.

Type Parameters ​
K ​

K extends keyof PTZControlProperties

Parameters ​
property ​

K

Returns ​

PTZControlProperties[K] | undefined

Inherited from ​

Sensor.getValue

Call Signature ​

getValue(property): unknown

Defined in: sensor/base.ts:304

Get the current value of a sensor property. Type-safe via the generic overload — call with a property enum value to get a properly typed result.

Parameters ​
property ​

string

Returns ​

unknown

Inherited from ​

Sensor.getValue

getValues() ​

getValues(): Readonly<TProperties>

Defined in: sensor/base.ts:320

Get a read-only snapshot of all property values.

Returns ​

Readonly<TProperties>

Frozen view of every property currently held by the sensor.

Example ​

ts
const snapshot = sensor.getValues();
console.log(snapshot);

Inherited from ​

Sensor.getValues

goHome() ​

goHome(): Promise<void>

Defined in: sensor/ptz.ts:213

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

Returns ​

Promise<void>

Example ​

ts
await ptz.goHome();

hasCapability() ​

hasCapability(capability): boolean

Defined in: sensor/base.ts:423

Parameters ​

capability ​

string

Returns ​

boolean

Inherited from ​

Sensor.hasCapability

onAssigned() ​

protected onAssigned(): void | Promise<void>

Defined in: sensor/base.ts:473

Lifecycle hook: the sensor just became assigned to a camera. Override to start background work that should only run while this sensor is live — polling loops, event subscriptions, timers, external connections.

Called AFTER cameraId, storage, and RPC channels are wired up, so the override can safely access this.cameraId, this.storage, and publish properties via the semantic helper methods.

Errors thrown here are caught and logged — they will NOT break assignment bookkeeping. If your work can fail, handle it inside the override.

Paired 1:1 with onDeassigned — for every onAssigned call there is exactly one matching onDeassigned later (on deassignment or cleanup).

Default: no-op. Most sensors don't need lifecycle hooks.

Returns ​

void | Promise<void>

Example ​

ts
protected override async onAssigned(): Promise<void> {
  this._timer = setInterval(() => this.poll(), 5_000);
}

Inherited from ​

Sensor.onAssigned

onDeassigned() ​

protected onDeassigned(): void | Promise<void>

Defined in: sensor/base.ts:493

Lifecycle hook: the sensor is being deassigned. Override to tear down whatever was started in onAssigned — clear timers, close subscriptions, release external resources.

Always called exactly once for each prior onAssigned. Also called from _cleanup if the sensor is being removed while still assigned, so you can rely on this as the single teardown point.

Default: no-op.

Returns ​

void | Promise<void>

Example ​

ts
protected override onDeassigned(): void {
  if (this._timer) clearInterval(this._timer);
}

Inherited from ​

Sensor.onDeassigned

setDisplayName() ​

setDisplayName(value): void

Defined in: sensor/base.ts:247

Set the display name (the only mutable identifier on a sensor).

Parameters ​

value ​

string

Human-readable label shown in the UI.

Returns ​

void

Example ​

ts
sensor.setDisplayName('Front Door Motion');

Inherited from ​

Sensor.setDisplayName

setMoving() ​

setMoving(value): void

Defined in: sensor/ptz.ts:201

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

Parameters ​

value ​

boolean

True while the camera is moving.

Returns ​

void

Example ​

ts
ptz.setMoving(true);

setPosition() ​

setPosition(value): Promise<void>

Defined in: sensor/ptz.ts:142

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 ​

value ​

PTZPosition

Absolute pan/tilt/zoom target position.

Returns ​

Promise<void>

Example ​

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

setPresets() ​

setPresets(value): void

Defined in: sensor/ptz.ts:187

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

Parameters ​

value ​

string[]

List of preset names supported by the camera.

Returns ​

void

Example ​

ts
ptz.setPresets(['Home', 'Driveway', 'Backyard']);

setTargetPreset() ​

setTargetPreset(value): Promise<void>

Defined in: sensor/ptz.ts:173

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

Parameters ​

value ​

string | undefined

Preset name to move to, or undefined to clear.

Returns ​

Promise<void>

Example ​

ts
await ptz.setTargetPreset('Driveway');

setVelocity() ​

setVelocity(value): Promise<void>

Defined in: sensor/ptz.ts:158

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

Parameters ​

value ​

PTZDirection | undefined

Per-axis speeds in [-1, 1], or undefined to stop.

Returns ​

Promise<void>

Example ​

ts
await ptz.setVelocity({ panSpeed: 0.5, tiltSpeed: 0, zoomSpeed: 0 });
await ptz.setVelocity(undefined); // stop