Today we are excited to announce live debugging for smart home devices (beta). With this new functionality, you can now view device change reports sent to Alexa and examine their content for errors and reliability.

For developers building skills for smart home devices, the live debugging feature in the Alexa Developer Console provides visibility to change reports and any processing errors encountered with them in near real time. Access the new debugging tool, in addition to other testing and validation features, from the Alexa Simulator panel of the developer console. You’ll also find enhanced documentation showing different change report errors and how to handle them.

Using this tool, you can improve the accuracy and reliability of submitted change reports. Device change report integrity is critical in building the right experience for customers and supporting the accuracy of smart home features. By enabling you to publish accurate change reports to Alexa, you ultimately provide customers with improved functionality and experiences on their smart home devices.

How to Use Live Debugging for Smart Home Devices (Beta)

Enabling the ‘Alexa Smart Home (Beta)’ checkbox, shown below, displays a smart home widget where developers can turn on live debugging.

Once live debugging is enabled, change reports for devices associated with the developer account will automatically appear in the Device Log panel. Change reports are displayed as the actual JSON payload and include device details, what was changed, the previous state of the device, and any processing errors encountered. As device changes continue to occur, new change reports appear in the Device Log, allowing you to get insights into change report behaviors so you can make appropriate corrections as errors are identified.

Below is an example of a device log entry for a successful change report:

    {
        "header": {
            "namespace": "SkillDebugger",
            "name": "CaptureDebuggingInfo",
            "messageId": "89bb25e2-9f6c-42b8-8982-ff1dc038c58c"
        },
        "payload": {
            "skillId": "amzn1.ask.skill.1a2e7f2e-e949-4504-9c20-77163e497c12",
            "timestamp": "2018-08-16T22:20:21.687Z",
            "dialogRequestId": null,
            "skillRequestId": null,
            "type": "SmartHomeChangeReportSuccess",
            "content": {
                "changeReport": {
                    "context": {
                        "properties": [
                            {
                                "namespace": "Alexa.PowerController",
                                "name": "powerState",
                                "value": "ON",
                                "timeOfSample": "2018-08-16T22:20:50.52Z",
                                "uncertaintyInMilliseconds": 60000
                            },
                            {
                                "namespace": "Alexa.EndpointHealth",
                                "name": "connectivity",
                                "value": {
                                    "value": "OK"
                                },
                                "timeOfSample": "2018-08-16T22:20:50.52Z",
                                "uncertaintyInMilliseconds": 0
                            }
                        ]
                    },
                    "event": {
                        "header": {
                            "messageId": "abc-123-def-456",
                            "namespace": "Alexa",
                            "name": "ChangeReport",
                            "payloadVersion": "3"
                        },
                        "endpoint": {
                            "endpointId": "endpoint-001",
                            "cookie": {
                                "path": "path/for/this/endpoint"
                            }
                        },
                        "payload": {
                            "change": {
                                "cause": {
                                    "type": "PHYSICAL_INTERACTION"
                                },
                                "properties": [
                                    {
                                        "namespace": "Alexa.BrightnessController",
                                        "name": "brightness",
                                        "value": 85,
                                        "timeOfSample": "2018-08-16T22:20:50.52Z",
                                        "uncertaintyInMilliseconds": 0
                                    },
                                    {
                                        "namespace": "Alexa.BrightnessController",
                                        "name": "brightness",
                                        "value": 85,
                                        "timeOfSample": "2018-08-16T22:20:50.52Z",
                                        "uncertaintyInMilliseconds": 0
                                    }
                                ]
                            }
                        }
                    }
                }
            }
        }
    }

With the new live debugging tool, you can debug issues with change reports and view the actual JSON payload received by Alexa. The new tool also provides clear error codes and messages related to processing the change report.

Live debugging is accessible to all developers building a skill using smart home APIs. Once enabled, change reports for devices associated with the developer’s account will automatically appear. If you are creating skills for smart home devices and would benefit from live debugging, review the documentation and join the community in the Alexa Smart Home Skill Developer Forum. We look forward to seeing what you create with this new capability. To learn more, check out these resources:

• Smart Home Live Debugging
• Smart Home Development with Alexa
• Smart Home Skill API Documentation
• Steps to Create a Smart Home Skill
• Understanding State Reporting for Smart Home Skills