Alexa.WakeOnLANController Interface 3

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 details about entertainment device skills, see Build Smart Home Skills for Entertainment Devices.

For the list of languages that the Alexa.WakeOnLANController interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.WakeOnLANController interface uses the pre-built voice interaction model. 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.

Directive workflow

You implement the Alexa.WakeOnLANController interface in conjunction with the Alexa.PowerController interface. To support the WakeOnLANController interface, follow these steps.

  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-enabled 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

Reportable properties

The Alexa.WakeOnLANController interface doesn't define any reportable properties.

Discovery

You describe endpoints that support Alexa.WakeOnLANController by using the standard discovery mechanism described in Alexa.Discovery.

Set retrievable to true for all 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 Alexa.WakeOnLANController, include a configuration object that contains the following fields.

Property 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": "Unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "Unique ID of the endpoint",
          "manufacturerName": "Manufacturer of the endpoint",
          "description": "Description to be shown 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.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },            
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

The Alexa.WakeOnLANController interface doesn't define any directives, but works in conjunction with the TurnOn directive of the Alexa.PowerController interface.

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.

TurnOn directive example

The following example shows a TurnOn directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerController",
      "name": "TurnOn",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {}
  }
}

TurnOn directive responses

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.

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 details, see DeferredResponse.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 15
    }
  }
}
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 details, see Send Events to the Event Gateway.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.WakeOnLANController",
      "name": "WakeUp",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}
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.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

TurnOn directive error handling

If you can't handle an TurnOn directive successfully, respond with an Alexa.ErrorResponse event as your third response to the TurnOn directive.

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 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 example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 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 report changes proactively 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": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 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": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2017-02-03T16:20:50.52Z",
    "uncertaintyInMilliseconds": 0
  }
}