Build Smart Home Skills for Sensors

Smart home skills created for sensors like a motion sensor or contact sensor enable customers to use these devices with Alexa. For example, with the appropriately configured smart home skill, a customer can ask, "Alexa, is the bedroom window open?" and Alexa can respond with the correct answer.

This document provides an overview of the technical requirements as well as specific directives and properties for smart home skills that target sensors.

Get started

If this is your first time creating a smart home skill, you should review the additional documentation as a prerequisite to this document. You will need to be familiar with how to create a smart home skill and write the code for a Lambda function that handles smart home requests from Alexa. For more information, see:

Target v3 and English

In the developer console, when you create a skill for sensors, you need to select v3 (preferred) and English (U.S.) as the target version and language for the skill. This ensures that your skill receives messages for requests related to sensors.

Message format

Alexa first sends a discovery request to your skill's Lambda function and you describe the target sensor in the response. Each sensor is an endpoint described by a list of interface capabilities. Sensor interfaces define the reportable properties that you send in an event to describe the current state of the endpoint. For more details about the messages exchanged, and their format, see Smart Home Skill API Message Reference.

Sensors are slightly different than other types of endpoints in that the capabilities do not define specific directives and utterances that trigger directives, but instead send events in response to a state request from Alexa, or send Alexa change reports when their state changes.

Choose capabilities

As mentioned previously, message formats are defined in interfaces, which are organized by device capability. The table below lists interfaces that you might implement to support sensor capabilities.

Operation Capability Interface
Detect and report contact Alexa.ContactSensor
Detect and report motion Alexa.MotionSensor
Detect and report temperature Alexa.TemperatureSensor
Discover and describe endpoints. Implemented by all smart home skills. Alexa.Discovery
Describe the API message version supported by the skill. Implemented by all smart home skills. Alexa interface
Describe the current state of an endpoint. Implemented by all smart home skills. Alexa.EndpointHealth

Discovery for sensors

You use the standard discovery mechanism to describe sensor endpoints. See Alexa.Discovery for more information.

It's important to note that sensors must send ChangeReport events, so the properties of a sensor must always be proactivelyReported. In addition, an endpoint that supports sensors must also support EndpointHealth.

Identify sensor endpoints

You also should provide the correct displayCategories value for a sensor so that it displays properly in the Alexa app. This could be one of the following for sensors:

CONTACT_SENSOR
Indicates an endpoint that detects and reports contact.
MOTION_SENSOR
Indicates an endpoint that detects and reports motion.
TEMPERATURE_SENSOR
Indicates an endpoint that senses and reports temperature.

For example, for an endpoint that can sense motion, you should set the display category like the following:

"displayCategories":["MOTION_SENSOR"]

Discovery example

The following code example shows how you might describe a sensor that supports motion detection.

Example: Discover.Response for a MotionSensor

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "ff746d98-ab02-4c9e-9d0d-b44711658414"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "sensor-001",
          "manufacturerName": "the manufacturer name of the endpoint",
          "friendlyName": "bedroom sensor",
          "description": "a description that is shown to the customer",
          "displayCategories": [
            "MOTION_SENSOR"
          ],
          "cookie": {
            "key1": "key/value pairs to reference this endpoint.",
            "key2": "There can be multiple entries",
            "key3": "use for reference purposes.",
            "key4": "Do not use to maintain current endpoint state."
          },
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.MotionSensor",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "detectionState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ]
        }
      ]
    }
  }
}

State reporting for sensors

State reporting is very important for sensor endpoints as this is how users are notified when a window is opened, motion is detected by a motion sensor, and more. For sensor endpoints:

  • You must proactively send ChangeReport events whenever an endpoint property value changes, and indicate the time the change was detected (not the time the event is sent) in the ChangeReport.

  • It's recommended that your skill respond to ReportState directives with StateReport events to indicate the current state of the endpoint. However, if the sensor is a low-power sensor, this is not required.

  • If the device is low-power and unable to response to ReportState directives, the endpoint should send a ChangeReport event immediately after discovery completes. This enables the Alexa app to reflect the correct state of the endpoint. Subsequent change reports should be sent only when a property change is detected.

For more information about state reporting, see Understand State Reporting for a Smart Home Skill.

Errors

Errors can occur because the customer asks for something that cannot be completed, or there is a communication issue between the skill and the endpoint. Sensor endpoints should return generic errors as described in the Alexa.ErrorResponse topic.

Learn more

For detailed steps to implement a skill, see Steps to Build a Smart Home Skill.

For more details about message formats for directives sent from Alexa and how to respond, see Smart Home Skill API Message Reference.