Alexa.MotionSensor Interface

The Alexa.MotionSensor interface describes the properties and events used to report the state of an endpoint that senses physical movement in an area. For example, the Alexa.MotionSensor capability can be implemented by a motion sensor.

Discovery

You describe endpoints that supports Alexa.MotionSensor using the standard discovery mechanism described in Alexa.Discovery. For an example discovery response message for sensors, see the discovery example on the Build Smart Home Skills for Sensors page.

Directives

This interface does not define any directives, but sends change reports when a capability property changes and optionally responds to Alexa's ReportState directives.

ReportState

A ReportState directive is sent to request the state of an endpoint.

Example ReportState Request

The following example shows a request for the current state of an endpoint with the ID appliance-001.

{
  "directive": {
    "header": {
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "namespace": "Alexa",
      "name": "ReportState",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "appliance-001",
      "cookie": {},
      "scope":{
            "type":"BearerToken",
            "token":"access-token-from-skill"
      }
    },
    "payload": {
    }
  }
}

Properties and Events

For this interface, you can reply:

  • Synchronously with a StateReport directive from the skill's Lambda function.
  • Asynchronously, which means you send StateReport events to the Alexa event gateway. When you reply asynchronously, you must include a scope with an authorization token to identify the customer, and a correlation token to identify the directive you are responding to.

Properties

Property Name Type Description
detectionState Detection object Indicates whether the motion sensor has detected motion; either DETECTED or NOT_DETECTED. The threshold for motion detection is left to the endpoint manufacturer.

When a motion sensor changes to a DETECTED state, you must wait at least 30 seconds before reporting a change to NOT_DETECTED.

StateReport event

Use a StateReport event to report the value of all of the endpoint properties in response to a ReportState directive.

Example: StateReport

{
  "context": {
    "properties": [
      {
        "namespace": "Alexa.MotionSensor",
        "name": "detectionState",
        "value": "DETECTED",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  },
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "namespace": "Alexa",
      "name": "StateReport",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

ChangeReport event

Use a ChangeReport event to report when the value of one of the endpoint properties changes for any reason. Report additional unchanged property values in the context of the message. Send ChangeReport events to the Alexa event gateway. For more information about how to do this, see Send Events to the Event Gateway.

If the device is low-power and unable to respond to ReportState requests, you must send a ChangeReport event immediately after discovery so the Alexa app can reflect the correct state of the endpoint. Subsequent change reports should be sent only when a change is detected.

Example: ChangeReport

{
  "context": {},
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "namespace": "Alexa",
      "name": "ChangeReport",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "endpoint-001"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.MotionSensor",
            "name": "detectionState",
            "value": "DETECTED",
            "timeOfSample": "2018-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more details.

Alexa.ContactSensor
Describes the capability for an endpoint that senses contact.
Build Smart Home Skills for Sensors
Describes considerations for building a smart home skill that supports sensors.