Alexa.ModeController Interface
The Alexa.ModeController interface enables your skill to model components of an endpoint that can be set to one of a list of values. The list can be ordered, but that's not required. Use ModeController to model components of a device that have more than one setting. You can include multiple instances of a ModeController on a single endpoint, as long as they have unique values in the instance and friendlyNames fields.
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, 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 one of these utterances, Alexa sends a corresponding directive to your skill.
Discovery response
All smart home skills must send a discovery response (Discover.Response) that describes the devices associated with the customer's account.
Example discovery response
The following example shows a discovery response for a smart home skill that implements the ModeController interface.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c"
},
"payload": {
"endpoints": [
{
"endpointId": "Washer-001",
"friendlyName": "Washer",
"description": "Smart Washer by Washer Maker Plus",
"manufacturerName": "Washer Maker Plus",
"displayCategories": [
"OTHER"
],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.ModeController",
"version": "3",
"instance": "Washer.WashCycle",
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Wash Cycle",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Wash Setting",
"locale": "en-US"
}
}
]
},
"properties": {
"supported": [
{
"name": "mode"
}
],
"retrievable": true,
"proactivelyReported": true
},
"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",
"instance": "Washer.WashTemperature",
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Wash Temperature",
"locale": "en-US"
}
},
{
"@type": "asset",
"value": {
"assetId": "Alexa.Setting.WaterTemperature"
}
}
]
},
"properties": {
"supported": [
{
"name": "mode"
}
],
"retrievable": true,
"proactivelyReported": true
},
"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"
}
}
]
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Discovery response fields
The following table describes the fields that are specific to the discovery response for devices that implement the ModeController interface. All fields are required.
| Field | Description | Type |
|---|---|---|
instance |
A unique identifier for this instance of the ModeController interface. |
string that contains letters or numbers, spaces or the following special characters: _ - = # ; : ? @ & |
capabilityResources |
A capabilityResources object specifying the names that customers can use for VUI and GUI interactions. |
object |
supportedModes |
An array of Mode objects that specify the modes supported by this instance of the ModeController |
array of Mode objects |
ordered |
Specifies whether the modes have an order. Only ordered modes support the adjustMode directive. Ordered mode values should be configured in increasing order. |
Boolean |
Mode object
The following table describes the fields in a Mode object. All fields are required.
| Field | Description | Type |
|---|---|---|
value |
Specifies a unique identifier for each possible mode value. | string |
modeResources |
An object that contains all localizable resources for the mode. | ModeResources object |
ModeResources and capabilityResources objects
For more information on ModeResources and capabilityResources objects, see Resources and Assets.
Directives
The ModeController interface supports directives to set and adjust the mode, and to query the current mode. The following example is a query utterance:
User: Alexa, what is the wash setting on the washer?
SetMode
Customers can request to set the mode. For example:
User: Alexa, set the wash cycle to cottons.
User: Alexa, set the wash setting on the washer to normal.
The following example shows a SetMode directive.
{
"directive": {
"header": {
"namespace": "Alexa.ModeController",
"name": "SetMode",
"instance": "Washer.WashCycle",
"messageId": "a3c0e1e3-c924-469d-bb46-78d3fd3f2bfe",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "Washer-001",
"cookie": {}
},
"payload": {
"mode": "WashCycle.Normal"
}
}
}
Payload fields
The following table describes the fields in the payload of a SetMode directive.
| Field | Description | Type |
|---|---|---|
mode |
The mode value to set for the component. | string |
AdjustMode
For modes that are ordered, customers can increase or decrease the mode by the specified delta. The default delta is 1. 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.
For example:
User: Alexa, increase the water temperature on the washer.
The following example shows an AdjustMode directive.
{
"directive": {
"header": {
"namespace": "Alexa.ModeController",
"name": "AdjustMode",
"instance": "Washer.WashTemperature",
"messageId": "c5c5bb3b-039b-4a29-bc1c-e74abf69a981",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<the identifier of the target endpoint>",
"cookie": {}
},
"payload": {
"modeDelta": 1
}
}
}
Payload fields
The following table describes the fields in the payload of an AdjustMode directive.
| Field | Description | Type |
|---|---|---|
modeDelta |
Indicates the value of the adjustment. Can be a positive or negative. | number |
Properties and events
When the state of a mode value changes, send a state report with a mode property. You must also include the instance to specify which ModeController of the endpoint you are reporting state for.
When a mode value is not currently set (for example, the device is off), report a mode value of null.
| Property name | Description | Type |
|---|---|---|
mode |
The current value of the ModeController. |
string |
For example:
{
"name": "mode",
"value": "WashCycle.Normal"
}
ErrorResponse
You should respond with an error when you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more information.