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

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.