camera.ui Node SDK

Appearance

@camera.ui/sdk / sensor / PTZControl

Class: PTZControl<TStorage> ​

Defined in: sensor/ptz.ts:120

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?, options?): PTZControl<TStorage>

Defined in: sensor/ptz.ts:124

Parameters ​

name? ​

string = 'PTZ'

options? ​

SensorOptions

Returns ​

PTZControl<TStorage>

Overrides ​

Sensor.constructor

Properties ​

category ​

readonly category: Control = SensorCategory.Control

Defined in: sensor/ptz.ts:122

Overrides ​

Sensor.category

name ​

readonly name: string

Defined in: sensor/base.ts:238

Inherited from ​

Sensor.name

onAssignmentChanged ​

readonly onAssignmentChanged: Observable<readonly string[]>

Defined in: sensor/base.ts:266

Inherited from ​

Sensor.onAssignmentChanged

onCapabilitiesChanged ​

readonly onCapabilitiesChanged: Observable<PTZCapability[]>

Defined in: sensor/base.ts:258

Inherited from ​

Sensor.onCapabilitiesChanged

onConnectedChanged ​

readonly onConnectedChanged: Observable<boolean>

Defined in: sensor/base.ts:268

Inherited from ​

Sensor.onConnectedChanged

onPropertyChanged ​

readonly onPropertyChanged: Observable<PropertyChangeOf<PTZControlProperties>>

Defined in: sensor/base.ts:256

Inherited from ​

Sensor.onPropertyChanged

type ​

readonly type: PTZ = SensorType.PTZ

Defined in: sensor/ptz.ts:121

Overrides ​

Sensor.type

Accessors ​

address ​

Get Signature ​

get address(): string | undefined

Defined in: sensor/base.ts:300

Returns ​

string | undefined

Inherited from ​

VibrationSensor.address

assignedCameraIds ​

Get Signature ​

get assignedCameraIds(): readonly string[]

Defined in: sensor/base.ts:316

Returns ​

readonly string[]

Inherited from ​

Sensor.assignedCameraIds

assignmentLocked ​

Get Signature ​

get assignmentLocked(): boolean

Defined in: sensor/base.ts:320

Returns ​

boolean

Inherited from ​

Sensor.assignmentLocked

capabilities ​

Get Signature ​

get capabilities(): TCapability[]

Defined in: sensor/base.ts:339

Returns ​

TCapability[]

Set Signature ​

set capabilities(value): void

Defined in: sensor/base.ts:344

Set capabilities, deduplicated, and notify backend plus local listeners.

Parameters ​
value ​

TCapability[]

Returns ​

void

Inherited from ​

Sensor.capabilities

connected ​

Get Signature ​

get connected(): boolean

Defined in: sensor/base.ts:312

Returns ​

boolean

Inherited from ​

Sensor.connected

displayName ​

Get Signature ​

get displayName(): string

Defined in: sensor/base.ts:304

Returns ​

string

Inherited from ​

Sensor.displayName

id ​

Get Signature ​

get id(): string

Defined in: sensor/base.ts:284

Returns ​

string

Inherited from ​

Sensor.id

isAssigned ​

Get Signature ​

get isAssigned(): boolean

Defined in: sensor/base.ts:308

Returns ​

boolean

Inherited from ​

VibrationSensor.isAssigned

moving ​

Get Signature ​

get moving(): boolean

Defined in: sensor/ptz.ts:138

Returns ​

boolean

nativeId ​

Get Signature ​

get nativeId(): string | undefined

Defined in: sensor/base.ts:288

Returns ​

string | undefined

Inherited from ​

Sensor.nativeId

origin ​

Get Signature ​

get origin(): string | undefined

Defined in: sensor/base.ts:292

Returns ​

string | undefined

Inherited from ​

VibrationSensor.origin

pluginId ​

Get Signature ​

get pluginId(): string | undefined

Defined in: sensor/base.ts:324

Returns ​

string | undefined

Inherited from ​

Sensor.pluginId

position ​

Get Signature ​

get position(): PTZPosition

Defined in: sensor/ptz.ts:134

Returns ​

PTZPosition

presets ​

Get Signature ​

get presets(): string[]

Defined in: sensor/ptz.ts:142

Returns ​

string[]

props ​

Get Signature ​

get protected props(): Readonly<TProperties>

Defined in: sensor/base.ts:558

Returns ​

Readonly<TProperties>

Inherited from ​

Sensor.props

sourceState ​

Get Signature ​

get sourceState(): SensorSourceState | undefined

Defined in: sensor/base.ts:296

Returns ​

SensorSourceState | undefined

Inherited from ​

VibrationSensor.sourceState

storage ​

Get Signature ​

get storage(): DeviceStorage<TStorage>

Defined in: sensor/base.ts:328

Returns ​

DeviceStorage<TStorage>

Inherited from ​

Sensor.storage

storageSchema ​

Get Signature ​

get storageSchema(): JsonSchema[]

Defined in: sensor/base.ts:335

Returns ​

JsonSchema[]

Inherited from ​

VibrationSensor.storageSchema

targetPreset ​

Get Signature ​

get targetPreset(): string | undefined

Defined in: sensor/ptz.ts:150

Returns ​

string | undefined

velocity ​

Get Signature ​

get velocity(): PTZDirection | undefined

Defined in: sensor/ptz.ts:146

Returns ​

PTZDirection | undefined

Methods ​

getValue() ​

Call Signature ​

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

Defined in: sensor/base.ts:368

Get the current value of a sensor property. Calling the generic overload with a property enum value gives 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:369

Get the current value of a sensor property. Calling the generic overload with a property enum value gives a properly typed result.

Parameters ​
property ​

string

Returns ​

unknown

Inherited from ​

Sensor.getValue

getValues() ​

getValues(): Readonly<TProperties>

Defined in: sensor/base.ts:385

Get a read-only snapshot of all property values.

Returns ​

Readonly<TProperties>

Shallow copy 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:256

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:411

Check whether the sensor advertises a capability.

Parameters ​

capability ​

string

Capability flag to look for.

Returns ​

boolean

True if the sensor currently advertises it.

Example ​

ts
const dimmable = sensor.hasCapability('brightness');

Inherited from ​

Sensor.hasCapability

onStart() ​

protected onStart(): void | Promise<void>

Defined in: sensor/base.ts:647

Lifecycle hook, called once the sensor is registered and live (storage and RPC are wired up). Override it to start work whose lifetime matches the sensor's: polling loops, event subscriptions, timers.

Errors thrown here are swallowed, not logged. Handle failures inside the override. Paired 1:1 with onStop, which runs on removal, plugin shutdown or cleanup.

Returns ​

void | Promise<void>

Example ​

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

Inherited from ​

Sensor.onStart

onStop() ​

protected onStop(): void | Promise<void>

Defined in: sensor/base.ts:660

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

Returns ​

void | Promise<void>

Example ​

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

Inherited from ​

Sensor.onStop

setAddress() ​

setAddress(address): void

Defined in: sensor/base.ts:444

Report the sensor's current address at the source, e.g. after a Home Assistant entity was renamed. The identity (nativeId) stays.

Parameters ​

address ​

string

Current address at the source

Returns ​

void

Example ​

typescript
sensor.setAddress(entry.entity_id);

Inherited from ​

Sensor.setAddress

setDisplayName() ​

setDisplayName(value): void

Defined in: sensor/base.ts:360

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:244

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:165

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:230

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']);

setRelativeMove() ​

setRelativeMove(value): Promise<void>

Defined in: sensor/ptz.ts:200

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 ​

value ​

PTZRelativeMove

Per-axis displacement, normalized to the field of view.

Returns ​

Promise<void>

Example ​

ts
// 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 });

setSourceState() ​

setSourceState(state): void

Defined in: sensor/base.ts:427

Report what the source behind this sensor looks like right now. The host shows the state with its reason on the sensors page and never deletes on it. Only meaningful for adopted sensors.

Parameters ​

state ​

SensorSourceState

Current source state

Returns ​

void

Example ​

typescript
sensor.setSourceState(registryHasEntity ? 'connected' : 'removed');

Inherited from ​

Sensor.setSourceState

setTargetPreset() ​

setTargetPreset(value): Promise<void>

Defined in: sensor/ptz.ts:216

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. undefined is ignored and the published targetPreset keeps its last value.

Returns ​

Promise<void>

Example ​

ts
await ptz.setTargetPreset('Driveway');

setVelocity() ​

setVelocity(value): Promise<void>

Defined in: sensor/ptz.ts:182

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]. Stop is zero on every axis. undefined is ignored and the published velocity keeps its last value.

Returns ​

Promise<void>

Example ​

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

updateModelSpec() ​

updateModelSpec(): void

Defined in: sensor/base.ts:577

Re-announces 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.

Returns ​

void

Example ​

typescript
async onStart(): Promise<void> {
  await this.loadModel();
  this.updateModelSpec();
}

Inherited from ​

Sensor.updateModelSpec