Alexa.ModeController Interface 3
Implement the Alexa.ModeController
interface in your Alexa skill so that users can control the mode settings of a device. You can use the Alexa.ModeController
interface to model properties of a device that the user can set to one of a list of values, such as the wash cycle mode of a washing machine. The list of values can have an order, but that's not required. The Alexa.ModeController
interface is a generic controller interface.
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 Mode
- Alexa.LockController and LockState
- Alexa.ThermostatController and ThermostatMode
For the list of languages that the Alexa.ModeController
interface supports, see List of Alexa Interfaces and Supported Languages.
de-DE
, en-GB
, en-US
, es-ES
, fr-FR
, and it-IT
.For the definitions of the message properties, see Alexa Interface Message and Property Reference.
Utterances
The Alexa.ModeController
interface uses the pre-built voice interaction model. The following examples show some user utterances:
Alexa, what's 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.
アレクサ、扇風機は何に設定されている?
アレクサ、洗濯機をデリケートモードにして
アレクサ、洗濯モードをドライに設定して
アレクサ、洗濯機の水位を上げて
You can enable additional utterances by using semantics. The following examples show user utterances enabled with semantics:
Alexa, open the garage door.
Alexa, close the garage door.
Alexa, raise the bedroom blinds.
Alexa, lower the living room blinds.
Alexa, fahre das Rollo in der Küche hoch.
Alexa, fahre das Küchenrollo hoch.
Alexa, fahr das Wohnzimmer-Rollo runter.
Alexa, fahre die Rollläden im Wohnzimmer runter.
アレクサ、ゴミ箱のふたを開けて
アレクサ、ブラインドを閉めて
アレクサ、シェードを上げて
アレクサ、プロジェクタースクリーンを下げて
After the user says an utterance, Alexa sends a corresponding directive to your skill.
Properties and objects
Mode property
The Alexa.ModeController
interface uses the mode
property as the primary property. The property values are strings. The Mode
object defines the acceptable values for the mode.
An endpoint can support multiple modes. To distinguish modes, you must always include the instance
attribute. This attribute defines the name of the mode. You identify your instance
names in your discovery response.
Mode property example
{
"namespace": "Alexa.ModeController",
"name": "mode",
"instance": "Washer.WashTemperature",
"value": "WashTemperature.Cold"
}
Mode object
The Mode
object represents an acceptable value for a mode. You include at least two Mode
objects in the supportedModes
array in your discovery response.
The following example shows two Mode
objects in a supportedModes
array.
"supportedModes": [
{
"value": "WashCycle.Normal",
"modeResources": {
}
},
{
"value": "WashCycle.Delicates",
"modeResources": {
}
}
]
The following table shows the properties of the Mode
object.
Field | Description | Type |
---|---|---|
value |
Name of the mode value. | String |
modeResources |
Friendly names that users can use to interact with the mode value. | ModeResources object |
ModeResources object
Use the ModeResources
object to provide a set of friendly names that users can use to interact with mode values. The first friendly name is the name that appears in the Alexa app. For details, see Resources and Assets.
The following example shows the mode resources for the delicate wash cycle of a washing machine. Users can say phrases like "Alexa, set the wash cycle to knits."
"modeResources":
{
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Delicate"
}
},
{
"@type": "text",
"value": {
"text": "Delicates",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Knits",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Ciclo delicado",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Cycle délicat",
"locale": "fr-CA"
}
}
]
}
Semantics
Use semantics to enable additional features, such as additional user utterances and announcements when your device requires attention. To use semantics, include a semantics object in your discover response as described in the discovery section.
Use semantics to enable additional utterances
When you use the Alexa.ModeController
interface, the voice interaction model is already built for you. Users can interact with your device by saying the standard Alexa.ModeController
utterances. For details, see utterances.
You can optionally enable additional utterances by using semantics. When you use semantics, you manually map the phrases "open", "close", "raise", and "lower" to the Alexa.ModeController
directives SetMode and AdjustMode. For example, if you have a controller for a garage door opener, you can map the phrase "open" to the SetMode
directive.
open
on a Alexa.ModeController
instance, you can't map the phrase open
on any other Alexa.ModeController
instances, any Alexa.RangeController
instances, or any Alexa.ToggleController
instances.Use semantics to enable announcements
You can use semantics to enable announcements to the user when your device requires attention.
Announcements take the form, Your <device friendly name> is <state>
.
For example, when their automatic vacuum cleaner gets stuck, Alexa notifies the user with the following announcement: "Your vacuum is stuck."
To enable announcements, implement the Alexa.ProactiveNotificationSource
interface in your Alexa skill. To indicate the states that you support, include a semantics object in your discovery response to map the mode
property to one of the Alexa.States
values, such as Alexa.States.Stuck
. You trigger announcements by sending an Alexa.ChangeReport
to report a change in the device state. For more details about announcement text, see Alexa.ProactiveNotificationSource.
Discovery
You describe endpoints that support Alexa.ModeController
by using the standard discovery mechanism described in Alexa.Discovery.
Set retrievable
to true for the properties that you report when Alexa sends your skill a state report request. Set proactivelyReported
to true for the properties that you proactively report to Alexa in a change report.
For connected vehicles that use Alexa user identification, include directiveConfigurations
in your discovery response to configure the authentication confidence level and policy name. For details, see directiveConfigurations.
You can model properties of an endpoint that users can't change by setting nonControllable
to true. For example, when a washing machine automatically goes from wash, to rinse, to spin, you can report the current wash cycle to the user without allowing them to change it.
For each Alexa.ModeController
entry in the capabilities
array, you can optionally include a semantics object. For details, see use semantics to enable additional utterances and use semantics to enable announcements.
For the full list of display categories, see display categories.
Capabilities array
In addition to the usual discovery response fields, for each Alexa.ModeController
entry in the capabilities
array, include the following fields.
Field | Description | Type |
---|---|---|
instance |
Name of the mode, for example Washer.WashCycle or Washer.WashTemperature . |
String |
capabilityResources |
Friendly names that users can use to interact with the mode. If you enable announcements for the instance friendly name, include @type set to text . |
CapabilityResources object |
configuration.ordered |
Set to true , if the mode values have an order; otherwise, set to false . For example, a wash temperature mode could have values ordered from cold, to warm, to hot. Modes that have an order support the AdjustMode directive. |
Boolean |
configuration. supportedModes |
Specifies the list of accepted mode values. You must include a minimum of two mode objects. List ordered mode values in increasing order in the array. |
Array of Mode objects |
Discovery response examples
Washing machine example
The following example shows a Discover.Response
message for a washing machine that supports three modes defined by three instances: Washer.WashCycle
, Washer.CurrentWashCycle
, and Washer.WashTemperature
.
Semantics for blinds example
The following example shows a Discover.Response
message for blinds that support the Alexa.ModeController
interface and uses semantics. Use the Alexa.ModeController
interface for blinds that only fully open and fully close. If your blinds can raise and lower to a range of positions, use the RangeController interface instead.
You can use the Alexa.ModeController
interface for your skills that control blinds in the following locales: de-DE
, en-AU
, en-GB
, en-IN
, en-US
, es-ES
, es-MX
, es-US
, it-IT
, ja-JP
.
Semantics for a garage door opener example
The following example shows a Discover.Response
message for a garage door opener that supports the Alexa.ModeController
interface and uses semantics. If your device is a garage door opener, you must use both the Alexa.ModeController
interface and the GARAGE_DOOR
display category.
For a garage door device, after the user asks to open the garage door, Alexa asks "What is your voice code?" before opening the garage door.
You can use the Alexa.ModeController
interface for your skills that control a garage door in the following locales: de-DE
, en-GB
, en-US
, es-ES
, fr-FR
, it-IT
.
Directives
Alexa sends the following Alexa.ModeController
interface directives to your skill.
SetMode directive
Support the SetMode
directive so that users can set the mode of a device.
The following example shows a user utterance:
Alexa, set the wash cycle to cottons.
Alexa, set the wash setting on the washer to normal.
アレクサ、洗濯機をデリケートモードにして
アレクサ、洗濯モードをドライに設定して
SetMode directive example
The following example shows a SetMode
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.ModeController",
"instance": "Washer.WashCycle",
"name": "SetMode",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID",
"cookie": {}
},
"payload": {
"mode": "WashCycle.Normal"
}
}
}
SetMode directive payload
Property | Description | Type | Required |
---|---|---|---|
|
Mode to set for the device. |
String |
Yes |
SetMode response
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 report.
The following example reports that the Washer.WashCycle
mode value changed.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ModeController",
"instance": "Washer.WashCycle",
"name": "mode",
"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. If your error is safety related, respond with an Alexa.Safety.ErrorResponse.
AdjustMode directive
For modes that have an order, support the AdjustMode
directive so that users can adjust the mode of a device.
When you set configuration.ordered
to true
in the discovery response, with this directive, users can increase or decrease the mode by a specified delta. This directive doesn't 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 user utterance:
Alexa, increase the water temperature on the washer.
アレクサ、洗濯機の水温を上げて
AdjustMode directive example
The following example shows an AdjustMode
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.ModeController",
"instance": "Washer.WashTemperature",
"name": "AdjustMode",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID",
"cookie": {}
},
"payload": {
"modeDelta": 1
}
}
}
AdjustMode directive payload
Property | Description | Type | Required |
---|---|---|---|
|
The amount by which to change the mode. The default is 1. |
Integer |
No |
AdjustMode response
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're reporting.
The following example shows an AdjustMode
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ModeController",
"instance": "Washer.WashTemperature",
"name": "mode",
"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. If your error is safety related, respond with an Alexa.Safety.ErrorResponse.
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 details about state reports, see Understand State and Change Reporting.
The response contains the current state of all the retrievable properties in the context object. You must include the instance
for each mode property that you report. You identify the retrievable properties and instance
names in your discovery response.
When a mode isn't set, for example, when the device is off, report null
for the mode
property.
Support the ReportState
directive so that users can ask about the features of their devices.
The following examples show some user utterances:
Alexa, what's the current washer cycle?
アレクサ、洗濯機のモードは何にセットされている?
StateReport response example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ModeController",
"instance": "Washer.WashCycle",
"name": "mode",
"value": "WashCycle.Delicates",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Change reporting
You send a ChangeReport
event to report changes proactively in the state of an endpoint. For details about change reports, see Understand State and Change 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 report. You identify the properties that you proactively report and the instance
names in your discovery response.
ChangeReport event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.ModeController",
"instance": "Washer.WashTemperature",
"name": "mode",
"value": "WashTemperature.Hot",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
}