Alexa.WakeOnLANController Interface
Implement the Alexa.WakeOnLANController
interface in your Alexa skill for a smart home device that supports the Wake-on-LAN (WoL) or Wake on Wireless LAN (WoWLAN) standard for powering on. This interface is useful for endpoints that can't support powering on with only the Alexa.PowerController interface because a low power mode prevents your cloud from reaching the endpoint over the internet. By using this interface, Alexa sends a Wake-on-LAN message from one of the user's supported Alexa devices to the endpoint over the local network. For more information about entertainment device skills, see Build Smart Home Skills for Entertainment Devices.
For the list of languages that the WakeOnLANController
interface supports, see List of Alexa Interfaces and Supported Languages.
Utterances
When you use the Alexa.WakeOnLANController
interface, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, turn on the TV.
After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.
Overview
You implement the Alexa.WakeOnLANController
interface in conjunction with the Alexa.PowerController interface. To support the WakeOnLANController
interface, follow the specific workflow that follows. The details for each step are explained throughout the rest of this document.
-
During device discovery, your skill declares support for both the
WakeOnLANController
andPowerController
interfaces. -
A customer asks Alexa to turn on a device that implements the
WakeOnLANController
interface. -
Alexa sends a PowerController.TurnOn directive to your skill.
-
You send three response events from your skill:
-
You send a DeferredResponse event to Alexa.
-
You send a WakeOnLANController.WakeUp event to the Alexa event gateway.
Alexa processes the
WakeUp
event and instructs one of the customer's supported devices to broadcast a Wake-on-LAN message to the MAC address provided in the discovery response for the endpoint. Then the Alexa event gateway sends you a success response or an error response. -
You send a final Response or ErrorResponse event to Alexa.
-
Supported Alexa devices
The user of your skill must have an Alexa device connected to the same local network as the device they want to turn on. The following Alexa devices support the Wake-on-LAN functionality:
- Amazon Tap, Echo (all generations)
- Echo Dot (all generations)
- Echo Input
- Echo Plus (all generations)
- Echo Show (all generations)
- Echo Spot
Discovery
You describe endpoints that support Alexa.WakeOnLANController
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 WakeOnLANController
, include a configuration object that contains the following fields.
Field | Description | Type | Required |
---|---|---|---|
MACAddresses |
The MAC address of the device to wake up. | Array | Yes |
Discover response example
The following example shows a Discover.Response
message for an endpoint that supports the WakeOnLANController
and PowerController interfaces.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "<the manufacturer name of the endpoint>",
"description": "<a description that appears in the Alexa app>",
"friendlyName": "<device name, displayed in the Alexa app>",
"displayCategories": ["TV"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.WakeOnLANController",
"version": "3",
"properties": {},
"configuration": {
"MACAddresses": ["00-14-22-01-23-45"]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Directives
The Alexa.WakeOnLANController
interface does not define any directives, but works in conjunction with the TurnOn
directive of the Alexa.PowerController interface as described following.
TurnOn directive
Support the TurnOn
directive of the Alexa.PowerController interface so that customers can turn on devices. When you implement the Alexa.WakeOnLANController
interface, your response to the TurnOn
directive is different than the usual response, as explained following.
TurnOn directive example
The following example illustrates a TurnOn
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.PowerController",
"name": "TurnOn",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {}
}
}
Response events
Normally when you support the TurnOn
directive of the PowerController
interface you send a single response. To implement the Alexa.WakeOnLANController
interface, you send three responses as explained following.
1. DeferredResponse event
The following example shows your first response to the TurnOn
directive. You send a synchronous DeferredResponse
event to Alexa. Optionally include estimatedDeferralInSeconds
, the approximate time before you send your WakeUp
event, in seconds. For more information, see DeferredResponse.
Deferred response example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "DeferredResponse",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"payload": {
"estimatedDeferralInSeconds": 15
}
}
}
2. WakeUp event
The following example shows your second response to the TurnOn
directive. You send your WakeUp
event asynchronously to the Alexa event gateway. For more information, see Send Events to the Event Gateway.
WakeUp event example
{
"event": {
"header": {
"namespace": "Alexa.WakeOnLANController",
"name": "WakeUp",
"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.PowerController",
"name": "powerState",
"value": "OFF",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
3. Response or ErrorResponse event
After you send your WakeUp event to the Alexa event gateway, the event gateway sends you a success response or an error response. Your third response to the TurnOn
directive should be a corresponding Response
event or ErrorResponse
event.
The following example shows a Response
event as your third response to the TurnOn
directive.
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.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
The following example shows an ErrorResponse
event as your third response to the TurnOn
directive. For more information, see Alexa.ErrorResponse.
ErrorResponse event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "<message id>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {
"type": "<error type>",
"message": "<error message>"
}
}
}
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. The response contains the current state of all of the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.
Alexa.WakeOnLANController
interface does not define any retrievable properties. However, if you also implement other interfaces in the skill for your device, you must participate in state reporting for the properties in those interfaces. For example, you must report the properties from the Alexa.PowerController interface.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.PowerController",
"name": "powerState",
"value": "OFF",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Change reporting
You send a ChangeReport
event to proactively report changes in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.
Alexa.WakeOnLANController
interface does not define any proactively reportable properties. However, if you also implement other interfaces in the skill for your device, you must participate in change reporting for the properties in those interfaces. For example, you must report the properties from the Alexa.PowerController interface.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": "VOICE_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {}
}