Welcome to the Google Home Developer Center, the new destination for learning how to develop smart home actions.

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": false
}

Device STATES

Entities 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

States	Type	Description
`openPercent`	Number	Required. Indicates the percentage that a device is opened, where 0 is closed and 100 is fully open.
`targetOpenPercent`	Number	Level indicating the open percent where the device will go or is moving to as a result of an ongoing change in position.

openPercent

Number

Required.

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

targetOpenPercent

Number

Level indicating the open percent where the device will go or is moving to as a result of an ongoing change in position.

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.
`targetOpenPercent`	Number	Level indicating the open percent where the device will go or is moving to as a result of an ongoing change in position.
`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
}

Simple open-close device currently opening to a new position.

{
  "openPercent": 50,
  "targetOpenPercent": 100
}

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

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

Open device by 30% in down direction, and by 50% in up direction, currently moving to 80% in up direction.

{
  "openState": [
    {
      "openPercent": 30,
      "openDirection": "DOWN"
    },
    {
      "openPercent": 50,
      "targetOpenPercent": 80,
      "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

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.

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

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.

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

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`.

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 false.

This command requires the following attributes:

{
  "commandOnlyOpenClose": false
}

Parameters

Parameters Type Description

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`

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

Sample utterances

de-DE

Bitte öffne die Jalousien auf 30%
Fensterläden um 25 % schliessen
Ist die Jalousie zu?
Mach den Rollladen zu
Mach die Rollos auf
schließe die Rollläden ein bisschen mehr
Öffne die Jalousien um 25%

en-US

Are the blinds in the kitchen open
Close the blinds 25% in my room
Close the door more
Just close the front door
open the blinds in my room
open the blinds to 25%
open the door by 25%

es-ES

abre la ventana del salón
cerrar persianas del dormitorio un 20%
cierra la cortina del salón
cierra mucho más la ventana
está abierta la puerta
quiero que subas la persiana al 25%
sube un 20% las persianas

fr-FR

baisse les stores de 10%
est-ce que la porte d'entrée est ouverte
ferme les stores
ferme un peu les stores
ouvre les stores
ouvre les stores de la chambre de 25%
ouvre les stores à 25%

hi-IN

कृपया 25% पर्दे को खुला रखो
क्या मैंने सामने वाला दरवाजा खुला छोड दिया?
पर्दे को 25% बंद करोगे
पर्दे खोलो
ब्लाइंड 25% खुले पर सेट कर दीजिए
ब्लाइंड को थोड़ा और बंद कर दिजिए
ब्लाइंड बंद करें

it-IT

abbassa un po' di più le tapparelle
apri la serranda
apri la tapparella al 30%
apri le serrande del 30%
chiudi le serrande
chiudi le tende del 25%
è aperta la porta d'ingresso

ja-JP

25% に ブラインド を開けて
25% ブラインド を閉めてください
25% ブラインド 開けて
ブラインド 閉めて
ブラインド 開けて
少し ブラインド を閉じて
玄関のドア は開いてますか

ko-KR

문 살짝만 닫아 줘
블라인드 25% 열어 줘
블라인드 25% 까지 열어 줘
블라인드 30프로 닫아
블라인드 닫아 줘
블라인드 열어 줘
안방 문 열렸어

nl-NL

doe de gordijnen 25% open
doe de jaloezieën voor 25% dicht
doe het raam ietsje meer dicht
is de voordeur open
open de gordijnen
sluit het gordijn
zet de luxaflex voor 50% open

pt-BR

Abrir janela 50%
As cortinas estão abertas?
Fecha a persiana toda
Fechar a janela 10%
a cortina do quarto está aberta?
abra a persiana até 30%
abre as cortinas
abre as cortinas a 50%
abrir as cortinas
abrir as cortinas na sala em 30%
fecha a persiana por favor
fecha um bocado a janela
fechar as cortinas em 25%
fechar um pouco mais as cortinas

sv-SE

Dra upp persiennerna
Dra upp persiennerna till 25%
stäng persiennen i mitt rum 25%
stäng persiennerna
är ytterdörren öppen?
öppna persiennerna med 25%

Device ERRORS

See the full list of errors and exceptions.

Smart Home OpenClose Trait Schema

Device ATTRIBUTES

Examples

Device STATES

Single direction open-close

Multiple direction open-close

Examples

Device COMMANDS

action.devices.commands.OpenClose

Parameters

Examples

Related errors

Follow-up responses

Success

Failure

Examples

action.devices.commands.OpenCloseRelative

Parameters

Examples

Related errors

Sample utterances

de-DE

en-US

es-ES

fr-FR

hi-IN

it-IT

ja-JP

ko-KR

nl-NL

pt-BR

sv-SE

Device ERRORS

`action.devices.commands.OpenClose`

`action.devices.commands.OpenCloseRelative`