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.

  1. During device discovery, your skill declares support for both the WakeOnLANController and PowerController interfaces.

  2. A customer asks Alexa to turn on a device that implements the WakeOnLANController interface.

  3. Alexa sends a PowerController.TurnOn directive to your skill.

  4. You send three response events from your skill:

    1. You send a DeferredResponse event to Alexa.

    2. 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.

    3. 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.

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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.

StateReport response event example

Copied to clipboard.

{
  "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.

ChangeReport event example

Copied to clipboard.

{  
  "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": {}
}