Alexa.WakeOnLANController Interface

Use the WakeOnLANController interface for an endpoint (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 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.

Overview

You implement this interface in conjunction with the 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.

  3. Alexa sends a TurnOn directive (defined in the PowerController interface) to your skill.
  4. Your skill sends a DeferredResponse event to indicate that a message will be sent to the event gateway, and the response will be delayed.
  5. 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:

  6. 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.
  7. 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.
  8. 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

The TurnOn directive is defined in the PowerController interface, but is duplicated here for completeness.

TurnOn

Request to turn on an endpoint.

User: Alexa, turn on device
User: Alexa, schalte Smart Home-Gerät ein
User: deviceをつけて
User: allume device s'il te plaît

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerController",
      "name": "TurnOn",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

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.

See the Alexa.PowerController interface, which defines messages to change the power state for an endpoint.