How to Use the State Reporting Test Tool
The state reporting test tool enables you to see when your skill is being queried for the current state of endpoint properties, or when Alexa relies on proactive
ChangeReport events to report endpoint properties. You can use this information to debug your smart home skill.
To use the troubleshooting and testing tips in this document, you must:
Implement a smart home skill that sends state updates (ChangeReport) events to the Alexa event gateway.
ChangeReportevents when the properties of an endpoint change. This means your discovery response indicates
proactivelyReported=truefor all capabilities supported by the endpoint. If your implementation only supports proactive reporting for a subset of an endpoint's capabilities you will be unable to use this tool and guide.
For more information see the following topics:
- Steps to Build a Smart Home Skill
- State Reporting in a Smart Home Skill
- Send Events to the Alexa Event Gateway
1. Get access to the tool
To request access to the state reporting test tool, complete the following steps:
- On the Amazon developer portal, sign into your developer account that is associated with the skill you will test.
- Navigate back to the skills portion of the portal and note the Skill ID for the skill you will test.
Navigate to the Developer Support contact form. Provide the following information:
Message: Requesting access to the proactive state test tool for the following skill ID: amzn1.ask.skill-number
You will be contacted when you are granted access or if we need more information.
2. Sign in and enable your skill
The tool is an add-on to the existing web-based Alexa app. Make sure to use the Alexa app for your region and sign in with the same developer account that you used to request access to the testing tool.
Following is a list of regions and the URL for the Alexa app:
- United States: alexa.amazon.com
- United Kingdom: alexa.amazon.co.uk
- Germany: alexa.amazon.de
- Japan: alexa.amazon.co.jp
- Canada: alexa.amazon.ca
- Australia: alexa.amazon.com.au
- India: https://alexa.amazon.in/
If you haven’t already done so, enable and account-link your smart home skill. For more information on how to do this, see Steps to Build a Smart Home Skill.
3. View and understand the state information
In the Alexa app, navigate to Smart Home and then Devices. If the tool has been successfully enabled for your developer account, you should see extended debugging information for each device. The following image shows an example device:
Each Capability states line in the tool output represents an endpoint capability that you marked as proactively reported in your discovery response, the current settings for each property, and whether a query was made for that property.
For example, the Wireless In_wall Dimmer endpoint shown in the image has the following property values:
- connectivity: OK
- brightness: 0
- powerState: OFF
The following image shows a more detailed view of the property reporting.
Pay special attention to the
DeepQuery value. This is a boolean that indicates if your proactive state update events and other event data is being used, or if a query occurred to provide the value.
DeepQuery=True: Indicates Alexa either did not have the value cached or updated the cached value before reporting it by sending a
ReportStatedirective to the skill. The value reported was provided in the
StateReportevent sent by the skill in response.
DeepQuery= False: Indicates that Alexa provided the cached value of the properties for that capability.
If you believe you have properly implemented proactive state updates, but the tool shows
DeepQuery=True, check the following:
- If you are working with a newly discovered endpoint, the state cache might be empty. Try refreshing the Alexa app in your browser. If your capabilities do not respond to
retrievable=false), you will need to send a
ChangeReportto populate the cache.
- Ensure you have indicated
proactivelyReported=truefor all of your endpoint's capabilities, and that you are reporting all property values. This includes the connectivity property defined by EndpointHealth.
- Conversely, ensure that you are only reporting the values of properties defined in your endpoint's capabilities. For example, if your endpoint implements the
BrightnessControllerinterface, you would not report
proactivelyReportedsince this is not a capability property.
- For thermostat devices, you may need to toggle between HEAT/COOL and AUTO modes to ensure we have cached data for all supported set points reported during device discovery.
5. Perform additional tests
After you have confirmed that
DeepQuery=False for all of your capabilities, you should exercise all of the scenarios that can trigger proactive state updates and confirm that expected property values update in the debugging tool.
ReportStatecalls to your skill.
- Manipulate your device state without using Alexa. For example, use another application or the physical device controls to turn a device on or off or change its settings. This should cause your skill to send one or more proactive state updates to the Alexa event gateway. In your browser, refresh the Alexa app to confirm that
DeepQuery=Falseand that the properties show the expected state of the device.
- Make sure to test
EndpointHealthproactive state updates. To do this, remove the power or power source from your device and wait for the device's health polling or heartbeat interval to pass. When the device reports that the connectivity value has changed, refresh your browser and check the Alexa app for the device state. Inversely, restore power to the device and ensure that all properties are correctly updated in the Alexa app.Note: There is a known issue with the test tool that occurs when you are validating
EndpointHealthand the skill response is an error. When the tool receives an
ErrorResponse, it displays Failed to retrieve state with no additional information. Until this issue is resolved, you should validate this scenario by checking your logs to ensure you are sending the appropriate JSON response and error codes.
- Validate that you are sending proactive state updates for all Amazon accounts that have enabled and account-linked the skill; not just the first or more recent accounts to be linked. Commonly, customers in the same household share smart home devices but have their own Amazon accounts associated with the skills for those devices. To test this scenario, enable and account-link the skill from different Amazon accounts using the same device credentials. Then, change the state of the device without using Alexa. Use the debugging tool, logging in as each Amazon user, and confirm the property states are accurate, but that
DeepQueryis false. This helps confirm that you are correctly sending
ChangeReportevents for each user. Note that this test will require that you have enabled at least two Amazon accounts to use the troubleshooting tool. Refer to Section 1 if you need to enable additional accounts. Make sure to login from the account you want to enable before you complete the Contact Us form.Note: If you receive a 403 Forbidden response when you send events to the Alexa event gateway, this indicates that the user has disabled your skill and you can stop sending messages for that user.
- Inspect your log responses to ensure your proactive state updates are being sent correctly to the Alexa event gateway.
Finally if you encounter problems using this debugging approach, please use the Developer Support contact form.