Alexa.MotionSensor Interface

Implement the Alexa.MotionSensor capability interface for endpoints that sense physical movement in an area. For example, a motion sensor attached to a front door.

If your motion sensors are components of a larger security system, your skill can also implement the Alexa.SecurityPanelController interface for a unified customer experience.

For the list of locales that are supported for the MotionSensor interface, see List of Capability Interfaces and Supported Locales.

Properties

The Alexa.MotionSensor interface uses detectionState as the primary property. You can use the following values for detectionState.

Value Description
DETECTED Motion is detected. Your device and user settings determine the threshold for detecting motion.
NOT_DETECTED Motion is not detected.

Discovery

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

Set retrievable to true for the properties that you report when Alexa sends your skill a state report request. Set proactivelyReported to true for the properties that you proactively report to Alexa in a change report.

Use MOTION_SENSOR for the display category. For the full list of display categories, see display categories.

Discover response example

The following example shows a Discover.Response message for an endpoint that supports the Alexa.MotionSensor interface.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name of the endpoint>",
          "description": "Smart Sensor by Sensor Maker",
          "friendlyName": "Front door",
          "displayCategories": ["MOTION_SENSOR"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.MotionSensor",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "detectionState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

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 retrievable properties in the context object. You identify your retrievable properties in your discovery response. For more information about state reports, see Understand State Reporting.

StateReport response event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.MotionSensor",
        "name": "detectionState",
        "value": "NOT_DETECTED",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

Change reporting

You send a ChangeReport event to proactively report changes in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For more information about change reports, see Understand State Reporting.

When a motion sensor changes to DETECTED, and then changes to NOT_DETECTED, you must wait at least 30 seconds before sending the second change report.

ChangeReport event example

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.MotionSensor",
            "name": "detectionState",
            "value": "DETECTED",
            "timeOfSample": "2018-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {}
}