Troubleshooting Common Issues with Alexa Smart Home Skills
Most issues that arise while developing a smart home skill can be easily resolved by testing and troubleshooting. This blog will cover issues regarding unsuccessful device discovery, devices not responding to directives, and supported utterances for different devices.
If a customer enables your skill and starts the discovery process by saying, “Alexa, discover my smart home devices” or clicking “Discover Devices” on the Alexa app but no devices are discovered, it’s likely that your skill’s response to the Discover directive is incorrectly formatted. Here are some tips on troubleshooting the discovery response:
- Check the documentation for the exact formatting for each interface. Make sure to confirm the formatting of your current response to the Discover directive and compare it to the samples on the documentation. For example, when testing discovery for thermostats, compare your response to the sample discover response from the ThermostatController documentation. Any diff tool or code editor that can show the between JSON responses will allow you to compare your response with the samples for any typos or incorrect formatting.
- Test one endpoint at a time. By testing one at a time, as opposed to discovering multiple devices all at once, you will be able to determine which device or controller is causing issues during discovery. Using the same ThermostatController example as above, first confirm that you can discover a single thermostat using the sample response. Once your thermostat can be discovered, try changing the parameters that matches your smart device functions - for example, if you are creating a single-setpoint thermostat, try removing or replacing the lowerSetpoint and upperSetpoint properties with targetSetpoint. From there, add other relevant controllers based on the functionality provided by your device by also using the sample responses from other controllers. Once you have confirmed that the device implementing multiple controllers can be successfully discovered, you can add multiple devices to a single discovery response.
You may encounter an issue where you have successfully tested discovery for your multi-locale skill, but the skill fails certification due to devices not being able to be discovered in a specific region. If the skill is unable to discover any devices for a specific region, this could be the result of one of the following:
- One or more of the endpoints for your other regions are not returning devices. When you run discovery for a smart home skill or control a device using your smart home skill, the Lambda function that is called depends on the region of the customer account that you are testing with. For example, if the region associated with your customer account is set to the U.S., regardless of what language you use, the Lambda function associated with the us-east-1 region will be called. Testing a different locale with the same account will still result in a request sent to the us-east-1 region Lambda. In order to test for different regions, make sure to test for all regions where you intend to release the skill. Check out the documentation on Lambda regions for the supported regions in smart home skills.
- Some interfaces are only available in certain regions. If your discovery response is returning devices using interfaces that are not available in certain regions, this can cause discovery to fail. Review the list of Alexa interfaces and their supported languages to check if your interfaces are supported in all regions.
If you are able to control your devices but Alexa is returning a “<device name> is not responding” message, it’s likely that your Lambda function did not send a confirmation that the directive was handled. As Alexa generally waits 8 seconds for your response before timing out, your Lambda function must also respond to Alexa within 8 seconds. Here is an example of a request where a customer hears the error message, but the light turns on:
- Customer asks to turn off light
- Alexa receives requests
- Alexa sends TurnOff directive to Lambda function
- Lambda function receives request
- Lambda function tells device cloud to turn off light
- Device cloud handles request and responds to Lambda function
- Lambda function sends response to Alexa confirming request has been handled
If steps 4-7 takes more than 8 seconds, the customer will hear the “Sorry, <device name> is not responding” message, even though the light is turned off. If the Lambda function's execution time is set to the default 3 seconds and step 6 takes more than 3 seconds, the device cloud will have controlled the device but the Lambda function will have timed out, resulting in no response send to Alexa at step 7. To resolve this issue, ensure that the maximum execution time on your Lambda function is set to 8 seconds, while also checking that your device cloud is responding promptly and not causing the Lambda function to respond to Alexa after 8 seconds.
Compare your JSON response to sample documentation. Depending on the controller, the formatting of the payload may be slightly different - ensure that spelling and case of each payload parameter, the structure of the objects within the payload object, as well as the spelling of the namespace and name parameters within the header object matches the documentation. Copying the sample and modifying it so that it works for your device is the simplest way to ensure the correct format.
For example, a sample format for the AdjustTargetTemperature from the ThermostatController can be found here, which shows the exact format of the payload, which includes the targetSetpointDelta object.
{
"directive": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "AdjustTargetTemperature",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"targetSetpointDelta": {
"value": -2.0,
"scale": "CELSIUS"
}
}
}
}Use the Smart Home Test tool which provides automated tests for the following Alexa interfaces:
- BrightnessController
- ColorController
- ColorTemperatureController
- PowerController
- ThermostatController
Report all properties required in the StateReport. For example, In a thermostat that implements the TemperatureSensor and ThermostatController, you would want to report the “temperature” property of the TemperatureSensor as well as all of the properties defined in discovery for the ThermostatController such as: thermostatMode, targetSetpoint, lowerSetpoint and upperSetpoint.
You may find that certain utterances can be used to control a device that has implemented a specific interface, but similar sounding utterances might not. The Utterances section listed on the documentation for each controller should be used when testing your smart home skill. As long as you have implemented the interface correctly, those utterances should work for your device. For example, in the ThermostatController documentation, Utterances section lists various utterances that will work for controlling a thermostat.
These troubleshooting tips should help you get your smart home skill back on track to certification. Feel free to reach out over on the smart home skill API forum for any further questions.
