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: 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: 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: 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 |
<string> |
String |
Current |
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 |
<string> |
String |
New |
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