Alexa.ModeController Interface
The Alexa.ModeController interface describes messages used to control the mode settings of an endpoint. You can use the ModeController interface to model properties of an endpoint that can be set to one of a list of values, such as the wash cycle mode of a washing machine. The list of values can be ordered, but that's not required.
The Alexa.ModeController interface is highly configurable and enables you to model many different kinds of settings for many different kinds of devices. Use one of the following more specific interfaces if it's appropriate for your device:
- Alexa.Cooking and CookingMode
- Alexa.EqualizerController and EqualizerMode
- Alexa.LockController and LockState
- Alexa.ThermostatController and ThermostatMode
For the list of locales that are supported for the ModeController interface, see List of Capability Interfaces and Supported Locales.
Utterances
When you use the Alexa.ModeController interface, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, what is the wash setting on the washer?
Alexa, set the wash cycle to cottons.
Alexa, set the wash setting on the washer to normal.
Alexa, increase the water temperature on the washer.
After the customer says an utterance, Alexa sends a corresponding directive to your skill.
Properties and Objects
The mode property
The Alexa.ModeController interface uses the mode property as the primary property. An endpoint can support multiple modes, such as a washing machine that supports a wash cycle mode and a wash temperature mode. Because an endpoint can support multiple modes, you must always include the instance attribute for a mode property. You identify your instance names, in your discovery response.
Mode property example
{
"namespace": "Alexa.ModeController",
"name": "mode",
"instance": "Washer.WashTemperature",
"value": "WashTemperature.Cold"
}
The mode object
The mode object represents an acceptable value for a mode.
Mode object details
| Field | Description | Type |
|---|---|---|
value |
The name of the mode value. | String |
modeResources |
Friendly names that customers can use to interact with the mode value. | A modeResources object. |
Mode object example
{
"value": "WashCycle.Normal",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Normal",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Cottons",
"locale": "en-US"
}
}
]
}
}
The modeResources object
Use the modeResources object to provide a set of friendly names that customers can use to interact with mode values. The first friendly name is the name that is displayed in the Alexa mobile app. For more information, see Resources and Assets.
ModeResources object example
The following example shows the mode resources for the night mode of a fan. The skill provides 2 friendly names: Alexa.Setting.Night as an asset, and White Noise as text. Customers say phrases like "Alexa, set the fan speed to night mode" or "Alexa, set the fan to white noise."
"modeResources":
{
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Setting.Night"
}
},
{
"@type": "text",
"value": {
"text": "White Noise",
"locale": "en-US"
}
}
]
}
Discovery
You describe endpoints that support Alexa.ModeController using the standard discovery mechanism described in Alexa.Discovery.
Set retrievable to true for all of the interfaces and properties that you report when Alexa sends your skill a state report request. Set proactivelyReported to true for interfaces and properties that you proactively report to Alexa in a change report.
For the full list of display categories, see display categories.
In addition to the usual discovery response fields, for each ModeController entry in the capabilities array, include the following fields.
| Field | Description | Type |
|---|---|---|
instance |
The name of the mode, for example Washer.WashCycle or Washer.WashTemperature. |
String |
capabilityResources |
Friendly names that customers can use to interact with the mode. | A CapabilityResources object. |
configuration.ordered |
True if the mode values have an order; otherwise, false. For example, a wash temperature mode could have values ordered from cold, to warm, to hot. Only modes that are ordered support the adjustMode directive. |
Boolean |
configuration.supportedModes |
The values that are accepted for the mode. Ordered mode values should be listed in increasing order. | An array of mode objects. |
Discover response example
The following example shows a Discover.Response message for a washing machine endpoint that supports the Alexa.ModeController interface.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "Washer Maker Plus",
"description": "Smart Washer by Washer Maker Plus",
"friendlyName": "Washer",
"displayCategories": [
"OTHER"
],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.ModeController",
"version": "3",
"properties": {
"supported": [
{
"name": "mode"
}
],
"retrievable": true,
"proactivelyReported": true
},
"instance": "Washer.WashCycle",
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Wash Cycle",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Wash Setting",
"locale": "en-US"
}
}
]
},
"configuration": {
"ordered": false,
"supportedModes": [
{
"value": "WashCycle.Normal",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Normal",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Cottons",
"locale": "en-US"
}
}
]
}
},
{
"value": "WashCycle.Delicates",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Delicates",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Knits",
"locale": "en-US"
}
}
]
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.ModeController",
"version": "3",
"properties": {
"supported": [
{
"name": "mode"
}
],
"retrievable": true,
"proactivelyReported": true
},
"instance": "Washer.WashTemperature",
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Wash Temperature",
"locale": "en-US"
}
},
{
"@type": "asset",
"value": {
"assetId": "Alexa.Setting.WaterTemperature"
}
}
]
},
"configuration": {
"ordered": true,
"supportedModes": [
{
"value": "WashTemperature.Cold",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Cold",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Cool",
"locale": "en-US"
}
}
]
}
},
{
"value": "WashTemperature.Warm",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Warm",
"locale": "en-US"
}
}
]
}
},
{
"value": "WashTemperature.Hot",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Hot",
"locale": "en-US"
}
}
]
}
}
]
}
}
]
}
]
}
}
}
Directives
SetMode directive
Support the SetMode directive so that customers can set the mode of a device.
The following example shows a customer utterance:
Alexa, set the wash cycle to cottons.
Alexa, set the wash setting on the washer to normal.
SetMode directive payload details
| Field | Description | Type |
|---|---|---|
mode |
The mode to set for the device. | String |
SetMode directive example
{
"directive": {
"header": {
"namespace": "Alexa.ModeController",
"name": "SetMode",
"instance": "Washer.WashCycle",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"mode": "WashCycle.Normal"
}
}
}
SetMode response event
If you handle a SetMode directive successfully, respond with an Alexa.Response event. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.
In the context object, include the values of all properties that changed. You must include the instance for each mode property that you are reporting.
SetMode response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {},
"context": {
"properties": [
{
"namespace": "Alexa.ModeController",
"name": "mode",
"instance": "Washer.WashCycle",
"value": "WashCycle.Normal",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
}
SetMode directive error handling
If you can't handle a SetMode directive successfully, respond with an Alexa.ErrorResponse event.
AdjustMode directive
Support the AdjustMode directive so that customers can adjust the mode of a device.
For modes that are ordered, customers can increase or decrease the mode by a specified delta. This directive does not restrict requests based on the current mode. That means you can support wrapped modes by appropriately handling requests to increase and decrease the mode.
The following example shows a customer utterance:
Alexa, increase the water temperature on the washer.
AdjustMode directive payload details
| Field | Description | Type |
|---|---|---|
modeDelta |
The amount by which to change the mode. The default is 1. | Integer |
AdjustMode directive example
{
"directive": {
"header": {
"namespace": "Alexa.ModeController",
"name": "AdjustMode",
"instance": "Washer.WashTemperature",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"modeDelta": 1
}
}
}
AdjustMode response event
If you handle an AdjustMode directive successfully, respond with an Alexa.Response event. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.
In the context object, include the values of all properties that changed. You must include the instance for each mode property that you are reporting.
AdjustMode response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {},
"context": {
"properties": [
{
"namespace": "Alexa.ModeController",
"name": "mode",
"instance": "Washer.WashTemperature",
"value": "WashTemperature.Warm",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
}
AdjustMode directive error handling
If you can't handle an AdjustMode directive successfully, respond with an Alexa.ErrorResponse event.
State reporting
Alexa sends a ReportState directive to request information about the state of an endpoint. When Alexa sends a ReportState directive, you send a StateReport event in response. For more information about state reports, see Understand State Reporting.
The response contains the current state of all of the retrievable properties in the context object. You must include the instance for each mode property that you are reporting. You identify your retrievable properties, and your instance names, in your discovery response.
When a mode is not set, for example when the device is off, report null for the mode property.
StateReport response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ModeController",
"name": "mode",
"instance": "Washer.WashCycle",
"value": "WashCycle.Delicates",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Change reporting
You send a ChangeReport event to proactively report changes in the state of an endpoint. For more information about change reports, see Understand State Reporting.
The ChangeReport contains the value of all properties that changed in the payload object. You must include the instance for each mode property that you are reporting. You identify the properties that you proactively report, and your instance names, in your discovery response.
ChangeReport event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "<message id>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.ModeController",
"name": "mode",
"instance": "Washer.WashTemperature",
"value": "WashTemperature.Hot",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {}
}