# Smart Home LockUnlock Trait Schema

`action.devices.traits.LockUnlock` - This trait belongs to any devices that support locking and unlocking, and/or reporting a locked state.

> [!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

None.

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

| States | Type | Description |
|---|---|---|
| `isLocked` | *Boolean* | Whether the device is currently locked. |
| `isJammed` | *Boolean* | Whether the device is currently jammed and therefore its locked state cannot be determined. |

#### Examples

*Device that is locked*

```
{
  "isLocked": true
}
```

*Device that is jammed*

```
{
  "isJammed": true
}
```

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

Lock or unlock the device.

#### Parameters

| Parameters | Type | Description |
|---|---|---|
| `lock` | *Boolean* | **Required.** True when command is to lock, false to unlock. |
| `followUpToken` | *String* | Google-provided token for follow-up response. |

#### Examples

*Lock the front door.*

```
{
  "command": "action.devices.commands.LockUnlock",
  "params": {
    "lock": true,
    "followUpToken": "123"
  }
}
```

*Unlock the front door.*

```
{
  "command": "action.devices.commands.LockUnlock",
  "params": {
    "lock": false,
    "followUpToken": "567"
  }
}
```

#### Related errors

An error occurred locking or unlocking the device.

Supported values:

`remoteSetDisabled`
`deviceJammingDetected`
`notSupported`
`alreadyLocked`
`alreadyUnlocked`

#### 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: Locked

| Fields | Type | Description |
|---|---|---|
| `followUpToken` | *String* | **Required.** Token provided in the original EXECUTE request. |
| `status` | *String* | **Required.** Result of the request. Supported values: `SUCCESS` |
| `isLocked` | *Boolean* | **Required.** Indicates whether the device is locked. |

#### 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, `deviceJammingDetected`. |

#### Examples

*Lock the front door. (follow-up response for success case)*

```
{
  "LockUnlock": {
    "priority": 0,
    "followUpResponse": {
      "status": "SUCCESS",
      "isLocked": true,
      "followUpToken": "1234"
    }
  }
}
```

*Unlock the front door. (follow-up response for success case)*

```
{
  "LockUnlock": {
    "priority": 0,
    "followUpResponse": {
      "status": "SUCCESS",
      "isLocked": false,
      "followUpToken": "1234"
    }
  }
}
```

*Lock the front door. (follow-up response for failure case)*

```
{
  "LockUnlock": {
    "priority": 0,
    "followUpResponse": {
      "status": "FAILURE",
      "errorCode": "deviceJammingDetected",
      "followUpToken": "1234"
    }
  }
}
```

## 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 *Eingangstür* abschließen
- Bitte schließ *die Eingangstür* auf

### en-US

- lock *my doors*
- unlock *study room*

### es-ES

- cierra *la puerta* con llave
- quitar *el cerrojo de la puerta de entrad* a

### fr-FR

- déverrouille *la porte d'entrée*
- verrouille *la porte d'entrée*

### hi-IN

- *फ़्रंट डोर* अनलॉक करो
- *सामने के दरवाजे* को लॉक करो

### it-IT

- apri *la porta d'ingresso*
- puoi chiudere *la porta d'ingresso* a chiave

### ja-JP

- *玄関のドア* を施錠して
- *玄関* 開錠して

### ko-KR

- *도어락* 잠가 줘
- *현관 도어락* 열어 줄래

### nl-NL

- Ontgrendel *de voordeur*
- doe *de voordeur* op slot

### pt-BR

- Tranca *a porta do quarto* .
- destranca *a porta da cozinha*
- destrancar *a porta da frente*
- trancar *a porta da frente*

### sv-SE

- lås upp *ytterdörren*
- lås *ytterdörren*

## Device ERRORS

See the full list of [errors and exceptions](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions).