traits/open_close.proto

Table of Contents

• traits/open_close.proto

  • DescribePositionsRequest

  • GetOpenClosePositionsRequest

  • OpenClosePosition

  • OpenClosePositions

  • OpenClosePositions.Preset

  • PositionsSupport

  • PullOpenClosePositionsRequest

  • PullOpenClosePositionsResponse

  • PullOpenClosePositionsResponse.Change

  • StopOpenCloseRequest

  • UpdateOpenClosePositionsRequest

  • OpenClosePosition.Direction

  • OpenClosePosition.Resistance

  • OpenCloseApi

  • OpenCloseInfo

• Scalar Value Types

Top

traits/open_close.proto

DescribePositionsRequest

Field	Type	Label	Description
name	string		The name of the device

GetOpenClosePositionsRequest

Field	Type	Label	Description
name	string		Name of the device to get the state for
read_mask	google.protobuf.FieldMask		The state fields to fetch

OpenClosePosition

Defines the position of one open close element for the device

Field	Type	Label	Description
open_percent	float		Open percent describes how open the device is in the specified direction. [0-100] where 0 is fully closed and 100 is fully open.
open_percent_tween	smartcore.types.Tween		How the open percent changes or should change over time. On write, only duration should be set.
target_open_percent	float		Read-only, the target open_percent after a transition
direction	OpenClosePosition.Direction		Optional direction for devices that support multiple open/close directions
resistance	OpenClosePosition.Resistance		Resistance reports if there is any resistance preventing the position from being fully achieved. For example if a door is being held open, or a window is jammed closed.

If more than one resistance applies choose the resistance value with the smaller ordinal, for example choose REDUCED_MOTION over SLOW if both apply. |

OpenClosePositions

All open/closable elements for the device

Field	Type	Label	Description
states	OpenClosePosition	repeated	The state of each of the devices open-able elements. Most devices will only have a single value here as they can only be opened from a single direction.
preset	OpenClosePositions.Preset		A preset set of positions (or mode) for the device. For example 'auto' or 'night mode'. During writes the preset takes precedence over the positions in states. During read the device may report either or both the preset and states values.

OpenClosePositions.Preset

A preset position for the device.

Field	Type	Label	Description
name	string		The identifying name of the preset. Required.
title	string		A human readable title for the preset

PositionsSupport

PositionsSupport 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
open_percent_attributes	smartcore.types.FloatAttributes		Define how the value for open percent behave. The bounds for these attributes will be absent and always in the range [0-100] to represent a percentage. Discreet devices, those that only support fully closed or fully open (i.e. a contact closure) should report a step of 100.
directions	OpenClosePosition.Direction	repeated	The supported directions for the device. If none then assume only a single direction is supported
supports_stop	bool		Does the device support the Stop method
presets	OpenClosePositions.Preset	repeated	A description of the supported presets, none means no presets

PullOpenClosePositionsRequest

Request to begin a subscription for open close state changes

Field	Type	Label	Description
name	string		The name of the device we want events from
exclude_tweening	bool		Indicate whether we want to be notified of values while tweening or not. The device may ignore this depending on capabilities
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.

PullOpenClosePositionsResponse

A response as part of the stream of changes to the range value

Field	Type	Label	Description
changes	PullOpenClosePositionsResponse.Change	repeated	The list of changes

PullOpenClosePositionsResponse.Change

A change to a single devices open close state value

Field	Type	Label	Description
name	string		name for the device that issued the change
change_time	google.protobuf.Timestamp		when the change occurred
open_close_position	OpenClosePositions		The new value for the state

StopOpenCloseRequest

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

UpdateOpenClosePositionsRequest

Field	Type	Label	Description
name	string		the name of the device to update the states for
states	OpenClosePositions		target states for each directional element of the device. If you don't want to change an open direction don't include it in the states list.
delta	bool		indicate whether the state change is a delta or absolute value
update_mask	google.protobuf.FieldMask		The state fields to update

OpenClosePosition.Direction

Possible directions the device can open/close

Name	Number	Description
DIRECTION_UNSPECIFIED	0
UP	1
DOWN	2
LEFT	3
RIGHT	4
IN	5
OUT	6

OpenClosePosition.Resistance

Resistance defines types of resistance an OpenClose device may encounter.

Name	Number	Description
RESISTANCE_UNSPECIFIED	0	Resistance is unspecified.
HELD	1	The device is being held in position. For example if someone is holding open a door, or a window is jammed shut.
REDUCED_MOTION	2	The devices motion is reduced. For example if a garage door can't open fully due to a blockage.
SLOW	3	The device is being slow to respond to changes in opening. For example if a window has a rusty hinge.

OpenCloseApi

Applicable to devices that can open or close. Think window contact closure, window blind, or garage door.

Method Name	Request Type	Response Type	Description
GetPositions	GetOpenClosePositionsRequest	OpenClosePositions
UpdatePositions	UpdateOpenClosePositionsRequest	OpenClosePositions
Stop	StopOpenCloseRequest	OpenClosePositions	Stop causes any changes being performed by the underlying device to stop. Will return the current state.
PullPositions	PullOpenClosePositionsRequest	PullOpenClosePositionsResponse stream	Get notified of changes to the OpenCloseState of a device

OpenCloseInfo

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

Method Name	Request Type	Response Type	Description
DescribePositions	DescribePositionsRequest	PositionsSupport	Get information about how a named device implements Positions 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)