Welcome to the Google Home Developer Center, the new destination for learning how to develop smart home actions. Note: You'll continue building actions in the Actions console.
Stay organized with collections Save and categorize content based on your preferences.

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

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

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

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.