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

> [!NOTE]
> **Note:** You should use [secondary user verification](https://developers.home.google.com/cloud-to-cloud/enhancements/secondary-user-verification) for this trait with the `DOOR`, `GARAGE`, `GATE`, or `WINDOW` device type.

## Device ATTRIBUTES

Devices with this trait may report the following
attributes as part of the [`SYNC`](https://developers.home.google.com/cloud-to-cloud/intents/sync) operation. To learn
more about handling `SYNC` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/sync).

| 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`](https://developers.home.google.com/cloud-to-cloud/intents/query) operation. To learn
more about handling `QUERY` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute).

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. Value must be between `0` and `100`. |
| `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. Value must be between `0` and `100`. |

#### 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. Value must be between `0` and `100`. |
| `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. Value must be between `0` and `100`. |
| `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

> [!NOTE]
> **Note:** This trait supports providing additional state with a secondary user verification challenge response. See [supported challenge types](https://developers.home.google.com/cloud-to-cloud/enhancements/secondary-user-verification#supported_challenge_types) for more details.

Devices with this trait may respond to the following
commands as part of the [`EXECUTE`](https://developers.home.google.com/cloud-to-cloud/intents/execute) operation. To learn
more about handling `EXECUTE` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute#handle_execute_intents).

### `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. Value must be between `0` and `100`. |
| `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"
  }
}
```

#### Related errors

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](https://developers.home.google.com/cloud-to-cloud/integration/notifications).

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. Value must be between `0` and `100`. |

#### 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](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions#error_list) 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 `discreteOnlyOpenClose` is set to `false`.
This command requires the following attributes:

```
{
  "discreteOnlyOpenClose": 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%"). Value must be between `-100` and `100`. |
| `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"
  }
}
```

#### Related errors

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

Supported values:

`lockedState`
`deviceJammingDetected`

## Sample utterances

> [!NOTE]
> This is a sample of the utterances supported by this device trait, make sure to also review other [supported languages](https://developers.home.google.com/cloud-to-cloud/traits#supported-languages).

### 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](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions).