Home > Alexa > Alexa Skills Kit

Providing Scenes in a Smart Home Skill

Introduction

Overview

An Alexa smart home skill enables a customer to control their cloud-connected devices with their voice. To create a smart home skill, you provide some configuration and skill information in the Amazon developer portal, and provide code, called a skill adapter, which is hosted as an AWS Lambda function. The skill adapter responds to requests, called directives, from the Smart Home Skill API, and communicates with connected devices, turning them on and off and adjusting their settings according to customer requests to their Alexa-enabled device.

With the scene feature, a customer can use their voice to set multiple devices to previously configured settings. For example, a customer could say, “Alexa, turn on bedtime” and the lights would dim and the temperature decrease for the room. Typically a customer edits and creates scenes with an Alexa-compatible hub or through a device manufacturer’s app. A customer can then discover these scenes with their Alexa-enabled device.

Providing a scene is very similar to how you provide a smart home skill for any other connected device, however there are some special requirements for your skill adapter. To enable the scene functionality for a smart home skill, your skill adapter code must:

  • Enable discovery of a scene that affects settings on allowed devices only
  • Ensure certain properties of the discovery response are formatted correctly for a scene
  • Expose 12 or less scenes in the discovery process

Prerequisites

If you haven’t created a smart home skill in the past, you should review the existing documentation as a prerequisite to this document.

Scene Discovery and Allowed Devices

You enable discovery of a scene similar to discovery of a device. However, you must only enable the discovery of scenes with devices that do not represent a security or safety risk to the customer. This means that if a scene contains disallowed devices, it should not be included in a discovery response.

Following are examples of allowed and disallowed devices.

Allowed Devices

The following device types are allowed to be incorporated as part of a scene:

  • Light bulbs
  • Thermostats
  • Switched electrical outlets
  • Fans
  • Window blinds

Devices that are not allowed

Device types that have security or safety considerations are prohibited. The following list contains examples of devices that are not allowed. If we determine that your smart home skill allows the discovery of scenes that affect disallowed devices, it will not pass the certification process.

  • Door locks
  • Garage doors
  • Security systems
  • Security sensors
  • Cooking appliances
  • Cameras

In addition, your skill adapter should return an error if a customer adds a disallowed device to a discovered scene, and then tries to interact with that scene. For example, if a customer adds a door lock to their bedtime scene, and then asks Alexa to turn that scene on, your skill adapter should return an UnsupportedOperationError. Alexa will then tell the customer that the request cannot be completed.

DiscoverAppliancesResponse Requirements to Describe a Scene

The Smart Home Skill API sends a discovery request and your skill adapter describes a scene similar to device in the DiscoverAppliancesResponse. However, there are special requirements for some of the response properties when you describe a scene.

  • The friendlyDescription must be present and include the word “scene” as well as how the scene is connected. For example: “scene connected via vendor name”. The friendly description should not exceed 128 characters.

  • A friendlyName is the name that customers use to interact with your scene and must be present. The goal is to enable customers to interact with a scene in a way that is natural and easy. A friendlyName should follow these guidelines:

    • Preferred option includes only the scene name. This provides the simplest and most natural way for a customer to interact with a scene
    • Optionally includes the room name, if a similar scene is offered in different rooms
    • Optionally includes “scene”
    • Optionally includes the preposition “in” between the scene name and a room name
    • Should not include special characters or punctuation
    • Should not exceed 128 characters

The following table lists some example friendly names and the utterance a customer would use to turn on that scene.

Friendly Name Format Friendly Name Example Customer utterance
scene name bedtime "Alexa, turn on bedtime"
scene name + scene bedtime scene "Alexa, turn on bedtime scene"
scene name + in + room name bedtime in nursery "Alexa, turn on bedtime in nursery"
  • The actions array should contain actions that the scene can respond to.
    • turnOn must be an included action.
    • Do not list the actions for each device in a scene.
    • Only include the turnOff action if a scene if you handle the TurnOffRequest directive for the scene in the skill adapter implementation.
  • The modelName property must include the model name of the device that provides the scene. The device is typically a hub, but can be any allowable device type.
  • The applianceTypes property can include one of two different values for a scene:
applianceTypes Description
ACTIVITY_TRIGGER Describes combination of devices set to a specific state when the state change must occur in a specific order. For example, a "watch Neflix" scene might require the 1) TV to be powered on 2) Input set to HDMI1.
SCENE_TRIGGER Describes a combination of devices set to a specific state, when the order of the state change is not important. For example a "bedtime" scene might include turning off lights and lowering the thermostat, but the order is unimportant.

DiscoverAppliancesResponse with scenes

A DiscoverAppliancesResponse returns all of the devices or scenes assoicated with the customer’s device cloud account and is the expected response for the skill adapter to the Smart Home Skill API for a DiscoverAppliancesRequest directive. For more information about response properties, see DiscoverAppliancesResponse in the Smart Home Skill API Reference documentation.

When you provide discovery information for a scene, you should accurately describe the device types in the scene. To do this, use the applianceType entry.

The following code shows a DiscoverAppliancesResponse from a skill adapter that includes scenes.

{
    "header": {
    "messageId": "ff746d98-ab02-4c9e-9d0d-b44711658414",
    "name": "DiscoverAppliancesResponse",
    "namespace": "Alexa.ConnectedHome.Discovery",
    "payloadVersion": "2"
    },
    "payload": {
    "discoveredAppliances": [
      {
        "actions": [
          "turnOn"
        ],
        "additionalApplianceDetails": {
          "extraDetail1": "detail about the scene",
          "extraDetail2": "another detail about scene",
          "extraDetail3": "only be used for reference purposes."
        },
        "applianceId": "uniqueDeviceId",
        "friendlyDescription": "Scene connected via vendor name",
        "friendlyName": "Kitchen Cooking Scene",
        "isReachable": true,
        "manufacturerName": "yourManufacturerName",
        "modelName": "Model of device providing scene",
        "version": "your software version number here."
      },
      {
        "actions": [
          "turnOn",
          "turnOff"
        ],
        "applianceTypes":[
          "SCENE_TRIGGER"
        ],
        "additionalApplianceDetails": {
          "extraDetail1":  "detail about the scene",
          "extraDetail2": "another detail about scene",
          "extraDetail3": "only be used for reference purposes."

        },
        "applianceId": "uniqueDeviceId",
        "friendlyDescription": "Scene connected by vendorName",
        "friendlyName": "Reading Scene",
        "isReachable": true,
        "manufacturerName": "yourManufacturerName",
        "modelName": "Model of device providing scene",
        "version": "your software version number here."
      }
     ]
    }
}


Scene Discovery Limit

Once discovered, every appliance and scene that your skill adapter provides in the discovery process displays to the customer in the Alexa app. To keep a customer-friendly experience, you should not describe more than 12 default scenes in your DiscoverAppliancesResponse. A customer can configure as many custom scenes as they want.

TurnOnRequest for scenes

A scene must support a turnOn action, which means that your skill adapter must handle the TurnOnRequest directive, and respond with a TurnOnConfirmation directive or an error message if the request could not be completed. A turnOnRequest that specifies a scene looks very similar to a turnonRequest directive for a device. The deviceId in the request will specify the scene to turn on. For more information see, TurnOnRequest and TurnOnConfirmation.

Example Utterance: “Alexa, turn on scene friendly name

TurnOnRequest example for a scene:

{
  "header": {
    "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
    "name": "TurnOnRequest",
    "namespace": "Alexa.ConnectedHome.Control",
    "payloadVersion": "2"
  },
  "payload": {
    "accessToken": "[OAuth Token here]",
    "appliance": {
      "additionalApplianceDetails": {
        "extraDetail1": "detail about the scene"
      },
      "applianceId": "[Device ID for the Scene]"
    }
  }
}


Additional Documentation