Alexa.EventDetectionSensor Interface 3
Implement the Alexa.EventDetectionSensor
interface in your Alexa skill so that you can notify Alexa when your security camera devices detect the presence of a person. When your security camera detects a person, you report that information to Alexa in a change report, and Alexa notifies your user. Users can set up notifications and routines for person detection in the Alexa app. By setting up person detection, users can reduce the number of notifications they receive when tracking all motion detection. For more details about security skills, see Smart Home Security Overview.
For the list of languages that the EventDetectionSensor
interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.
Utterances
The Alexa.EventDetectionSensor
interface doesn't have any user utterances.
Reportable properties
The Alexa.EventDetectionSensor
interface uses the humanPresenceDetectionState
property as the primary property.
The following example shows the humanPresenceDetectionState
object.
{
"value": "DETECTED",
"detectionMethods": ["VIDEO"]
}
The following table shows the definition of the humanPresenceDetectionState
object.
Field | Description | Type | Required |
---|---|---|---|
value |
Indicates whether the endpoint detects presence. Valid values: DETECTED or NOT_DETECTED . |
String | Yes |
detectionMethods |
Methods that the endpoint used to detect the event. Valid values: AUDIO , VIDEO . Default: [ AUDIO , VIDEO ]. |
Array | No |
media
property is deprecated and no longer supported.Discovery
You describe endpoints that support Alexa.EventDetectionSensor
using the standard discovery mechanism described in Alexa.Discovery.
Set proactivelyReported
to true
for the properties that you proactively report to Alexa in a change report.
Use CAMERA
for the display category. For the full list of display categories, see display categories.
Configuration object
In addition to the usual discovery response fields, for EventDetectionSensor
, include a configuration object that contains the following fields.
Field | Description | Type | Required |
---|---|---|---|
detectionMethods |
Methods that the endpoint uses to detect the event. Valid values: AUDIO , VIDEO . Default: [ AUDIO , VIDEO ]. |
Array of strings | No |
detectionModes |
Type of events that the endpoint detects. If you don't specify detectionModes , the default is humanPresence . |
Object | No |
detectionModes[]. humanPresence. featureAvailability |
Indicates whether the human presence detection feature is available. Valid values: ENABLED , DISABLED , SUBSCRIPTION_REQUIRED Default: ENABLED . |
String | No |
detectionModes[]. humanPresence. supportsNotDetected |
Indicates whether the endpoint supports the NOT_DETECTED state. Default: true . |
Boolean | No |
Discover response example
The following example shows a Discover.Response
message for a security camera that supports the Alexa.EventDetectionSensor
and Alexa.EndpointHealth
interfaces.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [
{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Manufacturer of the endpoint",
"description": "Description to be shown in the Alexa app",
"friendlyName": "Device name, displayed in the Alexa app",
"displayCategories": ["CAMERA"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.EventDetectionSensor",
"version": "3",
"properties": {
"supported": [
{
"name": "humanPresenceDetectionState"
}
],
"retrievable": false,
"proactivelyReported": true
},
"configuration": {
"detectionMethods": ["AUDIO", "VIDEO"],
"detectionModes": {
"humanPresence": {
"featureAvailability": "ENABLED",
"supportsNotDetected": false
}
}
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3",
"properties": {
"supported": [
{
"name":"connectivity"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
AddOrUpdateReport
You must proactively send an Alexa.Discovery.AddOrUpdateReport
message if the feature support of your endpoint changes. For example, if human presence detection requires a subscription, your first discovery response indicates that the human presence detection feature is disabled. If the user buys a subscription, send an AddOrUpdateReport
message to indicate that the human presence detection feature is now enabled. Also send an AddOrUpdateReport
message if the user manually disables human presence detection. For more details, see AddOrUpdateReport.
AddOrUpdateReport event example
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [
{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Manufacturer of the endpoint",
"description": "Description to be shown in the Alexa app",
"friendlyName": "Device name, displayed in the Alexa app",
"displayCategories": ["CAMERA"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.EventDetectionSensor",
"version": "3",
"properties": {
"supported": [
{
"name": "humanPresenceDetectionState"
}
],
"retrievable": false,
"proactivelyReported": true
},
"configuration": {
"detectionMethods": ["AUDIO", "VIDEO"],
"detectionModes": {
"humanPresence": {
"featureAvailability": "DISABLED",
"supportsNotDetected": false
}
}
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3",
"properties": {
"supported": [
{
"name":"connectivity"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Change report
You send a ChangeReport
event to report changes proactively in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.
ChangeReport event example with person detected
The following example shows a change report that you send when you detect human presence.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.EventDetectionSensor",
"name": "humanPresenceDetectionState",
"value": {
"value": "DETECTED",
"detectionMethods": ["VIDEO"]
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {
"properties": [
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}