Home > Alexa > Alexa Skills Kit

Building Smart Home Skills for Entertainment Devices

intro

Smart home skills created for home entertainment/AV devices give customers voice access to their smart TV, cable boxes and other entertainment devices. For example, with the appropriately-configured smart home skill, a customer can say, “Alexa, increase the volume on the TV” and hear the volume increase on their TV.

This document provides a overview of the technical requirements as well as specific directives and error messages for smart home skills that target entertainment devices.

Get Started

If this is your first time creating a smart home skill, you should review the existing documentation as a prerequisite to this document. You will need to be familiar how to create a smart home skill and write the code for a skill adapter that handles requests from the Smart Home Skill API. For more information see:

Skill Implementation

The next sections provide details about implementing a smart home skill for entertainment devices.

Smart Home Skills for Entertainment Devices in the Developer Portal

When you create a skill for entertainment devices, you need to make sure you receive messages for the entertainment device control in the Smart Home Skill API. To do this, you will select payload version 3 in the developer portal when you create your skill.

For more information and detailed steps, see Steps to Create a Smart Home Skill.

Message Format

Alexa sends your skill a directive as a result of a customer request and you send back an event indicating the request was successful or an error message. Alexa can then respond appropriately to the customer. Entertainment device control in the Smart Home Skill API leverages new message formats defined by payload version 3 of the API. Each device for is an endpoint described by a list of interface capabilities in the discovery response. Each interface provides directives that are sent by Alexa to the skill and events that can be sent from the skill back to Alexa. An interface also defines reportable properties that you might send in a response event to describe the current state of the entertainment device. For example, for a device that can change channels, you would implement the the Alexa.Discovery interface and the Alexa.ChannelController interface, which defines channel as a reportable property.

Discovery for Entertainment Devices

When you describe devices, you will also describe the capabilities associated with each device. Note that there are slight differences between the payload versions 2 and 3 fields and how you describe devices. See the following table to understand how you describe an entertainment device. For reference, the table includes how the same fields are described in the payload version 2 format.

Purpose payload v2 field payload v3 field
Device appliance object endpoint object
Device identifier applianceId endpointId
Manufacture name manufacturerName manufacturerName
Name assigned by customer friendlyName friendlyName
Description of the device such as now it is connected friendlyDescription description
Array of key/value pairs to store information about the device additionalApplianceDetails cookie
The cookie property expects the same key/value pair format as additionalApplianceDetails so you can copy entries over as-is.
Describe requests that a device can respond to actions array capabilities array
Device model name modelName None
Describes whether a device is currently reachable isReachable None
Category the device displays under in Alexa app applianceTypes displayCategories - Leave this array blanks for entertainment devices.

The following code example shows how you might describe an entertainment device. For more information on device discovery messages, see Alexa.Discovery

Example Discovery Response for an Entertainment Device

{
   "event":{
      "header":{
         "namespace":"Alexa.Discovery",
         "name":"Discover.Response",
         "payloadVersion":"3",
         "messageId":"5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4},
      "payload":{
         "endpoints":[
            {
               "endpointId":"appliance-001",
               "friendlyName":"Living Room Entertainment System",
               "description":" Entertainment System by Sample Manufacturer",
               "manufacturerName":"Sample Manufacturer",
               "displayCategories":[

               ],
               "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.Speaker",
                     "version":"1.0",
                     "properties":{
                        "supported":[
                           {
                              "name":"volume"
                           },
                           {
                              "name":"muted"
                           }
                        ]
                     }
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.ChannelController",
                     "version":"1.0",
                     "properties":{
                        "supported":[
                           {
                              "name":"channel"
                           }
                        ]
                     }
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.PlaybackController",
                     "version":"1.0",
                     "properties":{

                     }
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.InputController",
                     "version":"1.0",
                     "properties":{
                        "supported":[
                           {
                              "name":"input"
                           }
                        ]
                     }
                  }
               ]
            }
         ]
      }
   }
}

Interfaces for Entertainment Devices

To act on customer requests, you will need to parse Alexa request messages and compose Alexa.Response events to respond. If an error occurs, you will need to return the correct error message. Messages are defined in interfaces, which are organized by device capability. The interfaces that describe entertainment device capabilities are described in the following table.

Operation Capability Interface
Turn things on and off Alexa.PowerController
Change the channel on a device Alexa.ChannelController
Change the input of a playback device Alexa.InputController
Control the playback of device; fast forward, rewind and pause Alexa.PlaybackController
Change the volume in incremental steps Alexa.StepSpeaker
Change the volume to anywhere on a continuous range Alexa.Speaker
Indicate an error has occurred Alexa.ErrorResponse

See Steps to Create a Smart Home Skill for detailed steps to create a skill for entertainment devices.

Additional Resources