Alexa.WakeOnLANController Interface

Implement the Alexa.WakeOnLANController interface for a smart home device endpoint that supports the Wake-on-LAN (WoL) or Wake on Wireless LAN (WoWLAN) standard for powering on. This interface is useful for endpoints that cannot support powering on with the PowerController interface because a low power mode prevents your cloud from reaching the endpoint over the internet. With this interface, a supported Alexa device sends a Wake-on-LAN message directly to the endpoint over the local network.

For the list of locales that are supported for the WakeOnLANController interface, see List of Capability Interfaces and Supported Locales.

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 this interface in conjunction with the Alexa.PowerController interface. The following is a typical flow:

  1. During discovery, your skill provides a response that defines the WakeOnLANController and PowerController interfaces for the endpoint. In the WakeOnLANController configuration object, provide the endpoint's MAC address.
  2. A customer asks Alexa to turn on the endpoint that implements WakeOnLANController. For example:

User: Alexa, turn on the TV.

  1. Alexa sends a TurnOn directive (defined in the PowerController interface) to your skill.
  2. Your skill sends a DeferredResponse event to indicate that a message will be sent to the event gateway, and the response will be delayed. For more information, see Alexa.Response Interface.

  3. Your skill sends a WakeUp event to the Alexa event gateway. Send this event any time after the TurnOn directive, but before the Response event. For more information about sending events to the event gateway, see:

  4. 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.
  5. After your skill receives a success or error response from the Alexa event gateway (in response to the WakeUp event), send a Response event to the Alexa event gateway. For more information about the response, see Response in the PowerController documentation.
  6. Your skill monitors the endpoint and sends a change report event to the Alexa event gateway when the power state changes.

Both the DeferredResponse (step 4) and Response (step 7) events must include the correlation token of the original TurnOn request (step 3).

Supported Alexa devices

The following Alexa devices support the Wake-on-LAN functionality. To successfully power on an endpoint with Wake-on-LAN, your skill's user must have one of these devices connected to the same local network as the endpoint that supports Wake-on-LAN.

  • Amazon Tap
  • Echo (all generations)
  • Echo Dot (all generations)
  • Echo Input
  • Echo Plus (all generations)
  • Echo Show (all generations)
  • Echo Spot

Discovery

When you send a discover response that describes an endpoint that implements WakeOnLANController, you must specify the endpoint's MAC address as shown in the following example.

Example

The following example discover response shows how to specify the MAC address for an endpoint that implements the WakeOnLANController interface.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "appliance-tv-001",
          "friendlyName": "Living Room TV",
          "description": "Smart TV by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "TV"
          ],
          "cookie": {
            "extraDetail1": "optionalDetailForSkillAdapterToReferenceThisDevice",
            "extraDetail2": "There can be multiple entries",
            "extraDetail3": "but they should only be used for reference purposes",
            "extraDetail4": "This is not a suitable place to maintain current device state"
          },
          "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
              }
            }
          ]
        }
      ]
    }
  }
}

Directives

TurnOn directive

Support the TurnOn directive so that customers can turn on their devices. The TurnOn directive is defined in the Alexa.PowerController interface. For more information, see TurnOn directive.

Properties and events

Properties

There are no reportable properties currently defined for this interface.

WakeUp

When your skill receives a TurnOn directive for an endpoint that's in low-power mode and supports the Wake-on-LAN capability, send a WakeUp event to the Alexa event gateway. For more information, see Send Events to the Event Gateway. Alexa processes this 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.

Example WakeUp event

{
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  },
  "event": {
    "header": {
      "namespace": "Alexa.WakeOnLANController",
      "name": "WakeUp",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more details.

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment