Build Smart Home Skills for Locks
Smart home skills created for security devices gives customers voice access to their door locks. For example, a customer can say, "Alexa, lock the front door" and the door will lock. These skills also enable customers to see the status of their cloud-connected locks in the Alexa app.
This document provides an overview of the concepts as well as specific directives and error messages for smart home skills that target lock devices.
To create a smart home skill, you provide configuration information in the Amazon Developer Portal and code, which is hosted as an AWS Lambda function (an Amazon Web Services offering). The skill responds to directives from Alexa, and communicates with connected devices, such as a door lock, and sends response events back to Alexa.
You should be familiar with the steps to create a smart home skill. For more information see:
Identify a lock endpoint
Alexa sends a discovery request when your skill is enabled, and in the response, you describe a locking endpoint by providing the capabilities associated with the device, and properties that you support for each capability. You also should identify the category of device, which for a locking device is SMARTLOCK.
Example discovery response for a locking device
The following code example shows how you might describe a locking device.
{
"event":{
"header":{
"namespace":"Alexa.Discovery",
"name":"Discover.Response",
"payloadVersion":"3",
"messageId":"5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
},
"payload":{
"endpoints":[
{
"endpointId":"appliance-003",
"friendlyName":"Front Door",
"description":"Smart Lock by Sample Manufacturer",
"manufacturerName":"Sample Manufacturer",
"displayCategories":[
"SMARTLOCK"
],
"cookie":{
},
"capabilities":[
{
"type":"AlexaInterface",
"interface":"Alexa.LockController",
"version":"3",
"properties":{
"supported":[
{
"name":"lockState"
}
],
"proactivelyReported":true,
"retrievable":true
}
},
{
"type":"AlexaInterface",
"interface":"Alexa",
"version":"3"
}
]
}
]
}
}
}
Slow and fast locking hardware
In order to create a smart home skill that works and reports the status of a locking device properly, you need to determine how quickly your devices respond to a request. This will determine the details of your skill implementation.
- A fast lock can lock or unlock in 5 seconds or less
- A slow lock is a lock that takes over 5 seconds to lock or unlock
Fast locks
If your locking hardware can respond to a request in 5 seconds or less, then you can implement synchronous or asynchronous responses. This means when you receive a lock or unlock directive, you respond with an Alexa response or error message that indicates the request completed successfully or that an error occurred.
Slow locks
If your locking hardware is slow to respond to a request, then you must implement asynchronous responses to lock directives. This means when you receive a directive, you:
- Send a synchronous DeferredResponse event for the skill's Lambda function that indicates when the response should occur.
- Send an asynchronous Response or ErrorResponse event to the Alexa event gateway with the status of the lock directive
Both events should contain a correlation token that corresponds to the directive making the request.
Choose capabilities
To act on customer requests to lock or unlock an endpoint, you will need to choose the correct capabilities. Capability interfaces that describe locking devices are described in the following table.
| Operation | Capability Interface |
|---|---|
| Get or set the lock status of an endpoint | Alexa.LockController |
| Indicate an error has occurred | Alexa.ErrorResponse (Alexa interface) |
Note that an endpoint that supports unlocking by voice will require extra security precautions and configuration by the user in the Alexa app. See the Unlocking or Disarming section of Security Testing for more details.
