# Smart Home ArmDisarm Trait Schema

`action.devices.traits.ArmDisarm` - This trait supports arming and disarming as used in, for example, security systems.

For devices with multiple levels of security levels, these levels should be reported with the
`availableArmLevels` attribute.

> [!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 |
|---|---|---|
| `availableArmLevels` | *Object* | Describes the supported security levels of the device. If this attribute is not reported, the device only supports one level. |
| `levels` | *Array* | **Required.** List of the available security levels supported by the device. |
| `[*item, ...*]` | *Object* | Security level. |
| `level_name` | *String* | **Required.** The internal name of the security level that is used in commands and states. This name can be non-user-friendly and is shared across all languages. |
| `level_values` | *Array* | **Required.** Contains `level_synonym` and `lang`. |
| `[*item, ...*]` | *Object* | Level synonym for a given language. At least one item with a `lang` value of `en` is required in order to provide language fallback. |
| `level_synonym` | *Array* | **Required.** User-friendly names for the level in each supported language. The first item is treated as the canonical name. |
| `[*item, ...*]` | *String* | Synonym name. At least one item with a `lang` value of `en` is required in order to provide language fallback. |
| `lang` | *String* | **Required.** Language code for the level synonyms. See [Supported languages](https://developers.home.google.com/cloud-to-cloud/traits#supported-languages). |
| `ordered` | *Boolean* | **Required.** If set to true, additional grammar for increase/decrease logic applies, in the order of the levels array. For example, "Hey Google, increase my security level by 1", results in the Assistant determining the current security level and then increasing that security level by one. If this value is set to false, additional grammar for increase/decrease logic is not supported. |

#### Examples

*Security system with two distinct arm levels*

```
{
  "availableArmLevels": {
    "levels": [
      {
        "level_name": "L1",
        "level_values": [
          {
            "level_synonym": [
              "Home and Guarding",
              "SL1"
            ],
            "lang": "en"
          },
          {
            "level_synonym": [
              "Zuhause und Bewachen",
              "SL1"
            ],
            "lang": "de"
          }
        ]
      },
      {
        "level_name": "L2",
        "level_values": [
          {
            "level_synonym": [
              "Away and Guarding",
              "SL2"
            ],
            "lang": "en"
          },
          {
            "level_synonym": [
              "Weg und Bewachen",
              "SL2"
            ],
            "lang": "de"
          }
        ]
      }
    ],
    "ordered": true
  }
}
```

## 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 |
|---|---|---|
| `isArmed` | *Boolean* | **Required.** Indicates if the device is currently armed. |
| `currentArmLevel` | *String* | **Required.** Required if the `availableArmLevels` attribute is specified. If multiple security levels exist, indicates the name of the current security level. |
| `exitAllowance` | *Integer* | Indicates the time, in seconds, the user has to leave before `currentArmLevel` takes effect. |

#### Examples

*Security system that reports distinct arm level*

```
{
  "isArmed": true,
  "currentArmLevel": "L1"
}
```

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

Set the alarm level of this device.

#### Parameters

The payload contains one of the following:

#### Cancel the arm or disarm operation

| Parameters | Type | Description |
|---|---|---|
| `followUpToken` | *String* | Google-provided token for follow-up response. |
| `arm` | *Boolean* | **Required.** True when command is to arm. False to disarm. |
| `cancel` | *Boolean* | **Required.** True when command is to cancel the `arm` value. |

#### Arm or disarm the device, with an optional security level.

| Parameters | Type | Description |
|---|---|---|
| `followUpToken` | *String* | Google-provided token for follow-up response. |
| `arm` | *Boolean* | **Required.** True when command is to arm. False to disarm. |
| `armLevel` | *String* | The `level_name` to arm to. |

#### Examples

*Arm the system*

```
{
  "command": "action.devices.commands.ArmDisarm",
  "params": {
    "arm": true,
    "followUpToken": "123"
  }
}
```

*Set the system to arm level L1*

```
{
  "command": "action.devices.commands.ArmDisarm",
  "params": {
    "arm": true,
    "armLevel": "L1",
    "followUpToken": "456"
  }
}
```

*Cancel the arming operation*

```
{
  "command": "action.devices.commands.ArmDisarm",
  "params": {
    "arm": true,
    "cancel": true
  }
}
```

#### Related errors

An error occurred arming or disarming the device.

Supported values:

`alreadyInState`
`deviceTampered`
`passphraseIncorrect`
`pinIncorrect`
`securityRestriction`
`tooManyFailedAttempts`
`userCancelled`

## Device ERRORS

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