Smart Home Modes Trait Schema
action.devices.traits.Modes
- This trait covers all available modes and
mode-specific settings for a device.
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
Attribute | Definition |
---|---|
availableModes |
Each mode has a name and at least 2 settings:
|
ordered | If is set to true, additional grammar
for increase/decrease logic will apply, in the order (increasing) of the
settings array. |
{ "availableModes": [{ "name": "load", "name_values": [{ "name_synonym": ["load", "size", "load size"], "lang": "en" }], "settings": [{ "setting_name": "small", "setting_values": [{ "setting_synonym": ["small", "half"], "lang": "en" }] }, { "setting_name": "large", "setting_values": [{ "setting_synonym": ["large", "full"], "lang": "en" }] }], "ordered": true }] }
Sample SYNC Request and Response
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.SYNC", }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "agentUserId": "1836.15267389", "devices": [{ "id": "123", "type": "action.devices.types.WASHER", "traits": [ "action.devices.traits.Modes" ], "name": { "defaultNames": ["AAA Cybernetics Corporation Washer 3421"], "name": "Washer", "nicknames": ["clothes washer"] }, "willReportState": false, "attributes": { "availableModes": [{ "name": "load", "name_values": [{ "name_synonym": ["load", "size", "load size"], "lang": "en" }], "settings": [{ "setting_name": "small", "setting_values": [{ "setting_synonym": ["small", "half"], "lang": "en" }] }, { "setting_name": "large ", "setting_values": [{ "setting_synonym": ["large", "full"], "lang": "en" }] }], "ordered": true }] }, "deviceInfo": { "manufacturer": "AAA Cybernetics Corporation", "model": "233451", "hwVersion": "3.2", "swVersion": "11.4" }, "customData": { "fooValue": 74, "barValue": true, "bazValue": "lambtwirl" } }] } }
Device STATES
State | Definition |
---|---|
currentModeSettings |
Object containing a string for each mode defined on the object, representing setting_name.
For example:
"currentModeSettings": { "temperature": "hot", "load": "large" } |
Sample QUERY Request and Response
What mode is the dryer in?{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.QUERY", "payload": { "devices": [{ "id": "123", "customData": { "fooValue": 74, "barValue": true, "bazValue": "lambtwirl" } }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": { "123": { "on": true, "online": true, "currentModeSettings": { "drytype": "permpress", "load": "large" } }, "456": { "on": true, "online": true, "isPaused": true, "isRunning": false, "currentModeSettings": { "temperature": "hot", "load": "large" } } } } }
Device COMMANDS
Command | Parameters/Definition |
---|---|
action.devices.commands.SetModes |
updateModeSettings Object containing the new string value
(setting_name ) for each mode that's being set.
|
Sample EXECUTE Request and Response
Set the dryer to permanent press.{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123", "customData": { "fooValue": 74, "barValue": true, "bazValue": "lambtwirl" } }], "execution": [{ "command": "action.devices.commands.SetModes", "params": { "updateModeSettings": { "drytype": "permpress" } } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["123"], "status": "SUCCESS", "states": { "currentModeSettings": { "drytype": "permpress", "load": "large" } } }] } }