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.

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
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.
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.
lang String

Required.

Language code for the level synonyms. See 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 operation. To learn more about handling QUERY intents, see Intent fulfillment.

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

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

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.