Smart Home Modes Trait Schema

action.devices.traits.Modes - This trait covers all available modes and mode-specific settings for a device.

This trait belongs to any devices with an arbitrary number of "n-way" modes in which the modes and settings for each mode are arbitrary and unique to each device or device type. Each mode has multiple possible settings, but only one can be selected at a time; a dryer cannot be in "delicate," "normal," and "heavy duty" mode simultaneously. A setting that simply can be turned on or off belongs in the Toggles trait.

For instance, a washing machine can have settings for load size and temperature. These would both be modes because they are independent of each other, but each can be in only one state at a time. The user can set a mode such as temperature explicitly with a command like Set the washer’s temperature to cold.

Some modes are "ordered" and can also be adjusted with up/down, increase/decrease verbiage. For example, load size (small, medium, large) and temperature are clearly ordered (note that temperature is not an actual thermostat with a numeric target, as on other devices), but load type (delicates, normal, wool, etc) may not be.

This trait covers one or more individual modes which users can set. In general, these modes should be used for functionality that is unlinked from other device behavior. Linked behavior, such as turning the device itself on or off, should use more specific traits (for example, the thermostatMode in the trait TemperatureSetting).

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
availableModes Array

Required.

List of available modes.
[item, ...] Object

Available mode.
name String

Required.

Internal name of the mode, which will be used in commands and states. This can be non-user-friendly, and will be shared across all languages.
name_values Array

Required.

Synonyms of the mode in each supported languages.
[item, ...] Object

Synonyms of the mode in a given language.
name_synonym Array

Required.

Synonyms of the mode. The first string in this list is used as the canonical name of the level in that language.
[item, ...] String

Synonym name.
lang String

Required.

Language code (ISO 639-1). See supported languages.
settings Array

Required.

Supported settings for this mode.
[item, ...] Object

Supported setting.

Requires at least 2 items.
setting_name String

Required.

Internal name of the mode setting, which will be used in commands and states. This can be non-user-friendly, and will be shared across all languages.
setting_values Array

Required.

Synonyms of the setting in each supported languages.
[item, ...] Object

Synonyms of the setting in a given language.
setting_synonym Array

Required.

Synonyms of the setting. The first string in this list is used as the canonical name of the level in that language.
[item, ...] String

Synonym name.
lang String

Required.

Language code (ISO 639-1). See supported languages.
ordered Boolean

(Default: false)

If this is set to true, additional grammar for increase/decrease logic will apply, in the order (increasing) of the settings array.
commandOnlyModes 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.
queryOnlyModes Boolean

(Default: false)

Required if the device supports query-only execution. This attribute indicates if the device can only be queried for state information, and cannot be controlled.

Examples

Device with multiple mode and settings.

{
  "availableModes": [
    {
      "name": "load_mode",
      "name_values": [
        {
          "name_synonym": [
            "Load",
            "Size",
            "Load size"
          ],
          "lang": "en"
        }
      ],
      "settings": [
        {
          "setting_name": "small_load",
          "setting_values": [
            {
              "setting_synonym": [
                "Small",
                "Half"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "setting_name": "medium_load",
          "setting_values": [
            {
              "setting_synonym": [
                "Medium",
                "Normal"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "setting_name": "large_load",
          "setting_values": [
            {
              "setting_synonym": [
                "Large",
                "Full"
              ],
              "lang": "en"
            }
          ]
        }
      ],
      "ordered": true
    },
    {
      "name": "temp_mode",
      "name_values": [
        {
          "name_synonym": [
            "Temperature",
            "Temp"
          ],
          "lang": "en"
        }
      ],
      "settings": [
        {
          "setting_name": "hot_temp",
          "setting_values": [
            {
              "setting_synonym": [
                "Hot",
                "White"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "setting_name": "warm_temp",
          "setting_values": [
            {
              "setting_synonym": [
                "Warm",
                "Color"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "setting_name": "cold_temp",
          "setting_values": [
            {
              "setting_synonym": [
                "Cold",
                "Delicate"
              ],
              "lang": "en"
            }
          ]
        }
      ],
      "ordered": false
    }
  ]
}

Device with command-only modes.

{
  "availableModes": [
    {
      "name": "light_mode",
      "name_values": [
        {
          "name_synonym": [
            "Light",
            "Lighting"
          ],
          "lang": "en"
        }
      ],
      "settings": [
        {
          "setting_name": "day_light",
          "setting_values": [
            {
              "setting_synonym": [
                "Day",
                "Bright"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "setting_name": "night_light",
          "setting_values": [
            {
              "setting_synonym": [
                "Night",
                "Dark"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "setting_name": "reading_light",
          "setting_values": [
            {
              "setting_synonym": [
                "Reading",
                "Ambiant"
              ],
              "lang": "en"
            }
          ]
        }
      ],
      "ordered": false
    }
  ],
  "commandOnlyModes": true,
  "queryOnlyModes": false
}

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
currentModeSettings Object

Required.

Key/value pair with the mode name of the device as the key, and the current setting_name as the value.
<string> String

Current setting_name.

Examples

What mode is the device in?

{
  "currentModeSettings": {
    "load_mode": "small_load",
    "temp_mode": "cold_temp"
  }
}

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

Update mode settings.

Parameters

Parameters Type Description
updateModeSettings Object

Required.

Key/value pair with the mode name of the device as the key, and the new setting_name as the value.
<string> String

New setting_name.

Examples

Set to large load.

{
  "command": "action.devices.commands.SetModes",
  "params": {
    "updateModeSettings": {
      "load_mode": "large_load"
    }
  }
}

Sample utterances

de-DE

  • Stelle den Staubsauger auf Ruhemodus

en-US

  • set the vacuum to energy saver mode

es-ES

  • pon la lavadora en modo frío

fr-FR

  • mets l'aspirateur en silencieux

hi-IN

  • वैक्यूम पर कार्पेट मोड लगाएं

it-IT

  • imposta l'aspirapolvere su silenzioso

ja-JP

  • 掃除機 を 静音 モードに設定して

ko-KR

  • 세탁기 세탁량 많음 으로 설정해

pt-BR

  • acionar a função autolimpeza do aspirador
  • ligar o modo de aquecimento

Device ERRORS

See the full list of errors and exceptions.