Smart Home OpenClose Trait Schema

action.devices.traits.OpenClose - This trait belongs to devices that support opening and closing, and in some cases opening and closing partially or potentially in more than one direction.

Device ATTRIBUTES

Devices with this trait may report the following attributes as part of the SYNC operation. To learn more about handling SYNC intents, see Intent fulfillment.

Attributes Type Description
discreteOnlyOpenClose Boolean

(Default: false)

When set to true, this indicates that the device must either be fully open or fully closed (that is, it does not support values between 0% and 100%).
openDirection Array

List of supported directions in which the device can open or close. Include this attribute if the device supports opening and closing in more than one direction.
[item, ...] String

Supported direction.

Supported values:

UP
DOWN
LEFT
RIGHT
IN
OUT
commandOnlyOpenClose Boolean

(Default: false)

Indicates if the device supports using one-way (true) or two-way (false) communication. Set this attribute to true if the device cannot respond to a QUERY intent or Report State for this trait.
queryOnlyOpenClose Boolean

(Default: false)

Indicates if the device can only be queried for state information and cannot be controlled. Sensors that can only report open state should set this field to true.

Examples

Simple open-close device.

{
  "discreteOnlyOpenClose": true
}

Top-down bottom-up device. Can be opened in either direction.

{
  "openDirection": [
    "UP",
    "DOWN"
  ]
}

Command-only device.

{
  "commandOnlyOpenClose": true
}

Device STATES

Devices with this trait may report the following states as part of the QUERY operation. To learn more about handling QUERY intents, see Intent fulfillment.

The payload contains one of the following:

Single direction open-close

States Type Description
openPercent Number

Required.

Indicates the percentage that a device is opened, where 0 is closed and 100 is fully open.

Multiple direction open-close

States Type Description
openState Array

Required.

List of states for each supported open direction.
[item, ...] Object

Current state for the given open direction.
openPercent Number

Required.

Indicates the percentage that a device is opened, where 0 is closed and 100 is fully open.
openDirection String

Required.

Direction in which the device is opened.

Supported values:

UP
DOWN
LEFT
RIGHT
IN
OUT

Examples

Simple open-close device.

{
  "openPercent": 100
}

Open device by 30% in down direction, and by 50% in up direction.

{
  "openState": [
    {
      "openPercent": 30,
      "openDirection": "DOWN"
    },
    {
      "openPercent": 50,
      "openDirection": "UP"
    }
  ]
}

Device COMMANDS

Devices with this trait may respond to the following commands as part of the EXECUTE operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

action.devices.commands.OpenClose

Set the open-close state of the device.

Parameters

Parameters Type Description
openPercent Number

Required.

Indicates the percentage that a device is opened, where 0 is closed and 100 is fully open.
openDirection String

Direction in which to open. Only present if device supports multiple directions, as indicated by the openDirection attribute, and a direction is specified by the user.

Supported values:

UP
DOWN
LEFT
RIGHT
IN
OUT
followUpToken String

Google-provided token for follow-up response.

Examples

Open the device.

{
  "command": "action.devices.commands.OpenClose",
  "params": {
    "openPercent": 100,
    "followUpToken": "123"
  }
}

Open device 50 percent down.

{
  "command": "action.devices.commands.OpenClose",
  "params": {
    "openPercent": 50,
    "openDirection": "DOWN",
    "followUpToken": "456"
  }
}

An error occurred setting the open-close state of the device.

Supported values:

lockedState
deviceJammingDetected

Follow-up responses

Devices with this trait may return the following follow-up response payload as part of the EXECUTE operation. To learn more about implementing follow-up responses, see Notifications for smart home Actions.

The payload contains one of the following:

Success

Fields Type Description
followUpToken String

Required.

Token provided in the original EXECUTE request.
status String

Required.

Result of the request.

Supported values:

SUCCESS
openPercent Number

Required.

Indicates the percentage that a device is opened where 0 is closed and 100 is fully open.

Failure

Fields Type Description
followUpToken String

Required.

Token provided in the original EXECUTE request.
status String

Required.

Result of the request.

Supported values:

FAILURE
errorCode String

Required.

The value can be any error code for this trait, for example, lockedState.

Examples

Open the garage door. (follow-up response for success case)

{
  "OpenClose": {
    "priority": 0,
    "followUpResponse": {
      "openPercent": 100,
      "status": "SUCCESS",
      "followUpToken": "1234"
    }
  }
}

Open the garage door. (follow-up response for failure case)

{
  "OpenClose": {
    "priority": 0,
    "followUpResponse": {
      "errorCode": "lockedState",
      "status": "FAILURE",
      "followUpToken": "1234"
    }
  }
}

action.devices.commands.OpenCloseRelative

Adjust the open-close state of the device relative to the current state. This command is only available if commandOnlyOpenClose is set to true.

This command requires the following attributes: 
{
  "commandOnlyOpenClose": true
}

Parameters

Parameters Type Description
openRelativePercent Number

Required.

The exact percentage to change open-close state. Ambigous relative commands will be converted to an exact percentage parameter (for example, "Open the blinds a little more" vs "Open the blinds by 5%").
openDirection String

Direction in which to open. Only present if device supports multiple directions, as indicated by the openDirection attribute, and a direction is specified by the user.

Supported values:

UP
DOWN
LEFT
RIGHT
IN
OUT

Examples

Open the device a little more

{
  "command": "action.devices.commands.OpenCloseRelative",
  "params": {
    "openRelativePercent": 5
  }
}

Close the device 10% more

{
  "command": "action.devices.commands.OpenCloseRelative",
  "params": {
    "openRelativePercent": -10
  }
}

Open device 50% more, downward.

{
  "command": "action.devices.commands.OpenCloseRelative",
  "params": {
    "openRelativePercent": 50,
    "openDirection": "DOWN"
  }
}

An error occurred setting the open-close state of the device.

Supported values:

lockedState
deviceJammingDetected

Device ERRORS

See the full list of errors and exceptions.