Alexa.ToggleController 3.0
The Alexa.ToggleController capability interface comprises the mechanics related to control and reporting on the properties of an endpoint that can be set to on or off.
Alexa.ToggleController is an example of a generic controller, a type of interface that you can implement multiple times for the same device. The instance
field in its capability assertion differentiates between the different functionalities that leverage Alexa.ToggleController.
You can think of Alexa.PowerController as a pre-built, named instance of the Alexa.ToggleController generic controller.
It defines reportable state properties and uses the centralized Alexa interface for state reporting.
Dependencies
An endpoint for which support for Alexa.ToggleController 3.0 is asserted must also have Alexa 3.0 or higher implemented on its behalf.
A device maintaining an HTTP/2 connection that implements the Alexa.ToggleController 3.0 capability on its own behalf or on behalf of other connected endpoints must also implement support for Alexa.Discovery 3.0 or higher.
Capability assertion
To use the Alexa.ToggleController capability, it must be asserted in the capabilities
list of a Discover.Response
or AddOrUpdateReport
event in the Alexa.Discovery interface.
The device maintaining the HTTP/2 connection may implement the Alexa.ToggleController capability both on its own behalf as an endpoint and on behalf of other endpoints. The device must assert support for the Alexa.ToggleController capability and its dependencies in the capabilities
list for each endpoint that leverages it.
Sample Object
{ "type": "AlexaInterface", "interface": "Alexa.ToggleController", "version": "3", "instance": "{{STRING}}", "properties": { "supported": [ { "name": "toggleState" } ], "proactivelyReported": {{BOOLEAN}}, "retrievable": {{BOOLEAN}}, "nonControllable": {{BOOLEAN}} }, "capabilityResources": { "friendlyNames" [ // label objects representing // friendly names for the instance ] }, "semantics": { "actionMappings": [ { "@type": "ActionsToDirective", "actions": ["{{STRING}}", ...], "directive": { "name": "{{STRING}}", "payload": {} } }, ... ], "stateMappings": [ { "@type": "StatesToValue", "states": ["{{STRING}}", ...], "value": "{{STRING}}" }, ... ] } }, { "type": "AlexaInterface", "interface": "Alexa", "version": "3" }
Object Parameters
Parameter | Description | Type |
---|---|---|
instance | The identifier of this instance of Alexa.ToggleController on this endpoint. | string |
properties. proactivelyReported |
Whether changes in values of the reportable state properties for this instance of this capability on this endpoint can be reported by the device through the ChangeReport event. |
boolean |
properties. retrievable |
Whether the values of the reportable state properties for this instance of this capability on this endpoint will be reported by the device through the StateReport event in response the ReportState directive. |
boolean |
properties. nonControllable |
Whether the values of the reportable state properties for this instance of this capability on this endpoint are non-controllable by the end user.false is the default, which allows users to control the properties by voice and through the Alexa app.true allows the endpoint to report the state, but will prevent Alexa from sending the TurnOn and TurnOff directives.
|
boolean |
capabilityResources. friendlyNames |
A list of label objects to describe the possible friendly names for this instance of this capability on this endpoint. Examples are available in the capability resources section of the Smart Home Skills Kit documentation. |
list |
semantics | Semantics that allow mapping user utterances with capability directives and states. | object |
semantics. actionMappings[i]. actions[j] |
The identifiers of the utterances that should trigger the directive. Accepted Values: Alexa.Actions.Open : "open {endpoint}"Alexa.Actions.Close : "close {endpoint}"Alexa.Actions.Raise : "raise {endpoint}"Alexa.Actions.Lower : "lower {endpoint}"
|
string |
semantics. actionMappings[i]. directive. name |
Accepted Values:TurnOn : The identified actions should trigger the TurnOn directive.TurnOff : The identified actions should trigger the TurnOff directive.
|
string |
semantics. actionMappings[i]. directive. payload |
Because the TurnOn and TurnOff directives both have empty payload objects, this will always be an empty object.
|
object |
semantics. stateMappings[i]. states[j] |
The identifiers of the utterances that reflect the specified states. Accepted Values: Alexa.States.Open : "is {endpoint} open"Alexa.States.Closed : "is {endpoint} closed" |
string |
semantics. stateMappings[i]. value |
Accepted Values: ON , OFF
|
string |
Reportable state properties
toggleState
Alexa.ToggleController 3.0 defines the toggleState
property.
Sample Object
{ "namespace": "Alexa.ToggleController", "instance": "{{STRING}}", "name": "toggleState", "value": "{{STRING}}", "timeOfSample": "{{STRING}}", "uncertaintyInMilliseconds": {{LONG}} }
Object Parameters
Parameter | Description | Type |
---|---|---|
instance | The identifier of this instance of Alexa.ToggleController on this endpoint. | string |
value |
The value of the toggleState property.Accepted Values: ON , OFF
|
string |
timeOfSample | The UTC timestamp corresponding to when the property value was recorded, in ISO 8601 YYYY-MM-DDThh:mm:ssZ format. |
string |
uncertaintyInMilliseconds | The number of milliseconds that have elapsed since the property value was last confirmed. For example, if the device sampled the property value from the endpoint 60 seconds ago, the uncertaintyInMilliseconds would be 60000 . |
long |
Directives
TurnOn
AVS will send the TurnOn
directive to instruct the device to send a "turn on" signal to the specified endpoint for the specified instance of Alexa.ToggleController 3.0.
The device must send the Response
event in the Alexa namespace in response. The DeferredResponse
event is not supported as an alternative to sending an immediate Response
event.
If the TurnOn
directive can't run, the device should send the ErrorResponse
event instead.
Sample Message
{ "directive": { "header": { "namespace": "Alexa.ToggleController", "instance": "{{STRING}}, "name": "TurnOn", "payloadVersion": "3", "messageId": "{{STRING}}", "correlationToken": "{{STRING}}" }, "endpoint": { "endpointId": "{{STRING}}" } "payload": { } } }
Message Parameters
Parameter | Description | Type |
---|---|---|
directive. header. instance |
The identifier of this instance of Alexa.ToggleController on this endpoint. | string |
directive. header. messageId |
A universally unique identifier (UUID) generated to the RFC 4122 specification. | string |
directive. header. correlationToken |
An opaque token that must be included in any events responding to this directive. | string |
directive. endpoint. endpointId |
The identifier of the endpoint for which the state is being set. | string |
Note: The payload
is an empty object.
TurnOff
AVS will send the TurnOff
directive to instruct the device to send a "turn off" signal to the specified endpoint for the specified instance of Alexa.ToggleController 3.0.
The device must send the Response
event in the Alexa namespace in response. The DeferredResponse
event is not supported as an alternative to sending an immediate Response
event.
If the TurnOff
directive can't run, the device should send the ErrorResponse
event instead.
Sample Message
{ "directive": { "header": { "namespace": "Alexa.ToggleController", "instance": "{{STRING}}, "name": "TurnOff", "payloadVersion": "3", "messageId": "{{STRING}}", "correlationToken": "{{STRING}}" }, "endpoint": { "endpointId": "{{STRING}}" } "payload": { } } }
Message Parameters
Parameter | Description | Type |
---|---|---|
directive. header. instance |
The identifier of this instance of Alexa.ToggleController on this endpoint. | string |
directive. header. messageId |
A universally unique identifier (UUID) generated to the RFC 4122 specification. | string |
directive. header. correlationToken |
An opaque token that must be included in any events responding to this directive. | string |
directive. endpoint. endpointId |
The identifier of the endpoint for which the state is being set. | string |
Note: The payload
is an empty object.
Events
Alexa.ToggleController does not define any events within its namespace. Instances of Alexa.ToggleController leverage the centralized state change and reporting mechanisms defined in the Alexa interface and must provide the instance
field when including reportable state property objects:
- Responses to Alexa.ToggleController directives use the
Response
andErrorResponse
events. - Changes to Alexa.ToggleController's reportable state properties detected by the device use the
ChangeReport
event. - The device must use the
StateReport
event to respond to the cloud's interrogation of Alexa.ToggleController's reportable state properties' values via theReportState
directive.
Additional resources
The Alexa.ToggleController 3.0 capability has its origins in the Alexa Smart Home Skills API. It is now available directly to AVS devices with an HTTP/2 connection, without requiring an AWS Lambda or maintaining a separate cloud service. The following resources provide additional context and examples:
Last updated: Jan 22, 2021