4 Tips for Implementing Device Discovery in Your Smart Home Skills
Building an Alexa smart home skill enables you to link Alexa with your existing smart home device cloud. This gives your customers the ability to control and query their compatible devices through Alexa. When creating a smart home skill, one of the first steps is to implement the Alexa.Discovery interface.The Device Discovery process allows you to send Alexa a list of your customer’s devices and capabilities, so that they can interact with them through voice or the Alexa app.
When testing your implementation of the Alexa.Discovery interface, you first need to check that you've enabled the skill on your Alexa account and successfully performed account linking. The next step is to run device discovery from your Alexa account. If no endpoints are found from your skill, then you may have encountered a device discovery error. Here are four common culprits you can look into to resolve these errors.
1. Consider the Location of Your Customers, Your AWS Lambda Functions, and Supported Languages
In order for your customers to successfully discover devices in their Alexa accounts, the following three regional factors will need to align:
Languages Available on the Skill
When creating a smart home skill, like other skill types, you first choose the default language. Additional languages can be added to the skill, later.
Regions the Skill’s AWS Lambda Functions Are Deployed To
For each language that you add to the skill, you will need to ensure that you have an AWS Lambda Function deployed to the corresponding region. For a full list of these mappings, please see the table in the following tech doc: Deploy Your Lambda Function to Multiple Regions.
Region of the Customer’s Amazon Account
Amazon accounts are associated with a particular region that determines the skills that are available within the Alexa Skills Store. For example, if an Amazon account is of the US region, then the skills available from the Alexa Skills Store for that account will be those with an English (US) locale.
Avoiding Availability Issues When Testing
When testing the development version of your smart home skill, you will need to take note of the region of the Amazon account that you are testing with, as this can determine whether or not device discovery will be successful. Please note: When developing a skill, the development version will be available for testing on your corresponding Amazon account, regardless of the languages of the model.
If your Amazon account’s region is different from what your skill’s current configuration supports, then the Device Discovery request will not make it to your skill’s Lambda function. In this case, the skill’s Lambda function would not have received the discovery request, thus no corresponding request log will be found in Amazon CloudWatch. This will not be an issue once the skill is live in the Alexa Skills Store, as it will only be available to Amazon accounts that are set to the corresponding region.
CloudWatch Logs Tip: Availability issues = no discover request logged
2. Check the Latency of Your Skill’s Lambda Function, and Related Async Calls
Once your skill’s Lambda function has received a device discovery request, the skill has a maximum of 8 seconds with which to return a response. However, we recommended that responses are sent as quickly as possible.
When first creating a Lambda function, the default timeout is set to 3 seconds. Updating this timeout to 7 seconds will help avoid the potential for the lambda function to time out before returning the final Discover.Response within Alexa's timeout window. If you are planning on building a smart home camera skill, then please note that they have a timeout window of 6 seconds. Please see the Build Smart Home Camera Skills documentation for additional information. For changing the default timeout of a Lambda function, please take a look at Basic AWS Lambda Function Configuration.
CloudWatch Logs Tip: Lambda Timeout Issues = discover request logged, 'task timed out' Message Logged
Another common culprit of timeout issues are any asynchronous calls being made within your skill code. Is your device cloud taking too long to return a response to your skill's Lambda function? Logging any asynchronous requests and responses made within your skill’s Lambda function is very important in helping to pinpoint the source of the latency.
3. Ensure That Your Skill Is Not Returning Malformed JSON
Another common issue regarding device discovery failures is malformed Discover.Response JSON. The first step in troubleshooting this is to copy the complete JSON response that your skill returned from your Amazon CloudWatch logs and check it with a JSON validator to ensure that it is valid.
If valid JSON was returned, the next step would be to compare it with a known working sample. A general Discover.Response sample that includes various types of endpoints can be found in the Alexa smart home Github, here.
For more specific examples, please see the device templates in our Get Started with Device Templates documentation.
CloudWatch Logs Tip: Malformed JSON Response = discover request and return response both logged.
4. Check Access Token Refresh Requests From Your Authorization Server
If you've successfully completed device discovery, and then notice that later discover requests are failing, the culprit could be that the Alexa service could not successfully refresh and retrieve a valid access token from the skill's authorization service. You can check the logs of your authorization service to ensure that refresh requests are successfully completing.
CloudWatch Logs Tip: Apparent when first discovery flow after account linking completes successfully, and subsequent device discovery requests are not logged.
Conclusion
Come join the discussion in the Alexa Smart Home Skill API Forum. New to the forum and smart home skill building? Check out our welcome post, which has helpful links to get you started. You can also find me over on Twitter @roycodes.