# 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](https://developers.home.google.com/cloud-to-cloud/traits/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](https://developers.home.google.com/cloud-to-cloud/traits/temperaturesetting)).

## 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 |
|---|---|---|
| `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. At least one item with a `lang` value of `en` is required in order to provide language fallback. |
| `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. At least one item with a `lang` value of `en` is required in order to provide language fallback. |
| `lang` | *String* | **Required.** Language code (ISO 639-1). See [supported languages](https://developers.home.google.com/cloud-to-cloud/traits#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](https://developers.home.google.com/cloud-to-cloud/traits#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`](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 |
|---|---|---|
| `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`](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.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

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

- 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](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions).