In an Alexa Smart Home skill, users can voice-control their cloud-connected devices. For smart home skills, the voice interaction model is already built by the platform. When a user speaks to Alexa, it interprets the utterance and sends a message to the skill that communicates the request. The skill reacts to the message by changing the state of the device, such as by dimming a light, or by sending information about device state, such as telling the user whether a light is on or off.
Here is an example of a good user experience with the device functionality:
Alexa responds back to the users OK indicating that the device has been turned ON/OFF
Example:
User: Alexa turn on table lamp
Skill: Ok
User: Alexa set thermostat to 50 degrees
Skill: Thermostat set to 50
User: Lock the door
Skill: Locking, hang on. door is locked
User: Turn on Bell
Skill: sorry Bell does not support that.
User: set mode to eco on tom
Skill: I don’t know how to set tom to that Setting.
It is essential that a skill returns a positive response as per user request (responding of device status change or if the respective device does not support the requested command). Let’s have a look at another example for this use case:
User: “Alexa turn on bulb”
Skill: “The bulb is not responding.”/ “I’m not quite sure what went wrong”
This is a bad user experience as the device did not respond with a positive or an error handling response. It is essential that the skill responds to the customer request or it must have an adequate error handling response.
How to fix device functionality issues?
If you can control your devices but Alexa is returning a “<device name> is not responding” message, it’s likely that the Lambda function did not send a confirmation that the directive was handled. As Alexa generally waits 8 seconds for your response before timing out, the 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 request
- 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 will be 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 sent to Alexa at step 7. To resolve this issue, we should ensure that the maximum execution time on the 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.
- 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, we 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.
Below is a quick checklist to check if Alexa confirms the Smart Home API request with a positive response:
- Lambda function must respond to Alexa within 8 seconds. The maximum execution time on the Lambda function must be set to 8 seconds.
- Compare your JSON response to sample documentation.
- Use the Smart Home Test tool which provides automated tests for the following Alexa interfaces: BrightnessController, ColorController, ColorTemperatureController, PowerController and ThermostatController.
- Report all properties required in the StateReport.
Happy skill building!
