traits/ptz.proto

Table of Contents

• traits/ptz.proto

  • CreatePtzPresetRequest

  • DescribePtzRequest

  • GetPtzRequest

  • Ptz

  • PtzBounds

  • PtzMovement

  • PtzPosition

  • PtzPreset

  • PtzSupport

  • PtzVector

  • PullPtzRequest

  • PullPtzResponse

  • PullPtzResponse.Change

  • StopPtzRequest

  • UpdatePtzRequest

  • PtzApi

  • PtzInfo

• Scalar Value Types

Top

traits/ptz.proto

CreatePtzPresetRequest

Field	Type	Label	Description
name	string		the name of the device to update the state of
preset	PtzPreset		Details for the preset

DescribePtzRequest

Field	Type	Label	Description
name	string		The name of the device

GetPtzRequest

Field	Type	Label	Description
name	string		The name of the device to request state from
read_mask	google.protobuf.FieldMask		which fields do we want to fetch

Ptz

The current or intended state for the device

Field	Type	Label	Description
position	PtzPosition		The current position of the PTZ device (if known)
movement	PtzMovement		The current motion of the PTZ device (if known)
preset	string		The current preset selected for the device (if known)
preset_speed	int32		The speed the preset should be applied. 0 for 'use device default'

PtzBounds

The minimum and maximum values each of the PTZ vector axes can take.

Field	Type	Label	Description
min	PtzVector
max	PtzVector

PtzMovement

A description of the movement for the PTZ device

Field	Type	Label	Description
direction	PtzVector		Which direction are we moving. Only the sign of the dimensions of the vector are used to denote direction of movement
speed	int32		The speed at which the PTZ device should move. If not specified the device may ramp speed on its own
speed_tween	smartcore.types.Tween		How the speed changes or should change over time. On write only duration should be set.
target_speed	int32		Read-only, the target speed value after a transition

PtzPosition

A description of the current position of the PTZ device.

Field	Type	Label	Description
position	PtzVector		The current position.
tween	smartcore.types.Tween		How the position changes or should change over time. On write only duration should be set.
target_position	PtzVector		The target position that will be reached after the tween duration.

PtzPreset

Describes a preset that may be configured on the device

Field	Type	Label	Description
name	string		Required. The name of the preset, to be used for recall.
title	string		Official human readable name for the preset
description	string
position	PtzVector		Optional position of the preset
writable	bool		Can this preset be stored via the api

PtzSupport

PtzSupport describes the capabilities of devices implementing this trait

Field	Type	Label	Description
resource_support	smartcore.types.ResourceSupport		How a named device supports read/write/pull apis
supports_position	bool		Can we ask the device to move to a specific position
supports_movement	bool		Can we move the device without a target position in mind
presets	PtzPreset	repeated	A list of presets that the device has configured. If the list is empty and supports_custom_presets is false then the device doesn't support presets
supports_custom_presets	bool		If true, custom preset names can be used to store ptz positions. If false only writable presets can be updated.

PtzVector

Defines a value for the pan, tilt, and zoom of the device. This vector can represent a movement in a particular direction or a final position to aim for. If used for movement then the values should be positive or negative to represent the direction of movement. For absolute values the bounds attribute of the device are used as a guide.

All values are relative to the focus of the vector in the real world. For example for a camera, to move right means that the image captured by the camera show more on the right and less on the left of the image.

Field	Type	Label	Description
pan	float		left/right direction for movement or position. Positive values mean right, negative mean left when moving
tilt	float		up/down direction for movement or position. Positive values mean up, negative mean down when moving
zoom	float		in/out direction for movement or zoom level. Positive values mean in, negative mean out when moving

PullPtzRequest

Field	Type	Label	Description
name	string		The device we want to subscribe to
read_mask	google.protobuf.FieldMask		The state fields to fetch
updates_only	bool		When true the device will only send changes to the resource value. The default behaviour is to send the current value immediately followed by any updates as they happen.

PullPtzResponse

Field	Type	Label	Description
changes	PullPtzResponse.Change	repeated

PullPtzResponse.Change

Field	Type	Label	Description
name	string		name for the device that issued the change
change_time	google.protobuf.Timestamp		when the change occurred
ptz	Ptz		The updated state, should be merged with any known state

StopPtzRequest

Field	Type	Label	Description
name	string		the name of the device to stop

UpdatePtzRequest

Field	Type	Label	Description
name	string		the name of the device to update the state of
state	Ptz		The new state
update_mask	google.protobuf.FieldMask		The fields we are intending to update relative to the Ptz

PtzApi

Allows interaction with a pan-tilt-zoom device, typically a camera.

Method Name	Request Type	Response Type	Description
GetPtz	GetPtzRequest	Ptz	Set the target state for the device
UpdatePtz	UpdatePtzRequest	Ptz	Set the target state for the device
Stop	StopPtzRequest	Ptz	Stop the device if it is extending or retracting, returns the current known state after stopping.
CreatePreset	CreatePtzPresetRequest	PtzPreset	Create a preset for the ptz position. If no preset ptz position is specified then use the current position
PullPtz	PullPtzRequest	PullPtzResponse stream	Get notified of changes to the OnOffState of a device

PtzInfo

Describes the capabilities of a specific named device with respect to this trait.

Method Name	Request Type	Response Type	Description
DescribePtz	DescribePtzRequest	PtzSupport	Get information about how a named device implements Ptz features

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)