Debug Your Smart Home Skill

Alexa sends a ReportState directive to request information about the state of an endpoint. When Alexa sends a ReportState directive, you send a StateReport event in response. You also proactively report state to Alexa in ChangeReport events, directive response events, and in error response events. You identify the properties that you proactively report in your discovery response. For more information about state reporting, see Understand State and Change Reporting.

There are two tools that you can use to debug state and other events as you build your smart home skill:

  • State reporting test tool – View the current values of all properties of smart home devices that are associated with your skill and your developer account, and whether the current value came from a StateReport request or proactive reporting such as a ChangeReport.
  • Smart home live debugger – View the ChangeReport, AddOrUpdateReport, and DeleteReport events that Alexa receives from your skill (and any processing errors).

You can see information for the Amazon account that you use to sign in to the Alexa Skills Kit developer console. These tools don't show information from other Amazon accounts.

Prerequisites

To use the State reporting test tool, your smart home skill must send ChangeReport events to Alexa when the properties of your smart device change. Your discovery response must set proactivelyReported to true for all properties defined by the interfaces that your device supports. If your skill supports proactive reporting for only a subset of properties, then you cannot use the State reporting test tool.

To use the Smart home live debugger, your smart home skill must send ChangeReport, AddOrUpdateReport, or DeleteReport events to Alexa.

How to use the state reporting test tool

You can use the state reporting test tool to see the current state of the properties of a smart home device in your developer account, and whether the current property value came from a StateReport or proactive reporting such as a ChangeReport.

Get access to the state reporting test tool

Before you can access the state reporting test tool, you must request access from the Alexa team.

To get access to the state reporting test tool

  1. Sign in to the Amazon developer portal with the developer account for the smart home skill you want to test.
  2. Open the Customer Details page and note your customer ID. You need your customer ID, not your vendor ID.
  3. Open the Alexa Developer Contact Us.
  4. For Type, choose Alexa Skill Building.
  5. For Category, choose Testing & Simulation.
  6. For Subject, enter Requesting access to the state reporting test tool.
  7. For Desciption, enter Requesting access to the state reporting test tool for customer ID <your customer ID>.

Alexa contacts you when you are granted access to the tool, or for more information.

There are some scenarios, such as households with multiple members, where users control the same device from their separate Amazon accounts. To test that you send ChangeReport events for all Amazon accounts that enable your skill for the same device, you need multiple test accounts. Repeat the above procedure to request access for a second account to test this scenario.

Enable your skill in the Alexa app

The state reporting test 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 tool.

To enable your skill in the Alexa app

  1. Log into the web-based Alexa app for your region. The following is the list of regions and the corresponding URLs:

  2. In the app, locate your skill.
    1. Choose Skills, and choose Your Skills in the upper right corner of the skills page.
    2. Scroll to DEV SKILLS and find your skill.
  3. Choose ENABLE to enable the skill. You are directed to account-link the skill to a device cloud account. If you want to remove account linking later, disable your skill in the Skills tab.

View state information

To view state information

  1. In the Alexa app, choose Smart Home and then Devices.
  2. For each device, you see extended debugging information. The information looks like the following.

    Each Capability states line represents a smart device capability interface property. Each line contains the following information:

    • Property name and current value of the property
    • The timestamp for the current value of the property
    • The uncertainty in milliseconds for the current timestamp
    • DeepQuery - True if the value was last set by a StateReport, False if the value was last set by a proactive report such as a ChangeReport

Troubleshoot change reporting problems

If you implement change reporting in your skill, you should see DeepQuery: False for properties in the state reporting test tool to indicate that the values were last set by a ChangeReport.

If you believe you have properly implemented change reporting, but you see DeepQuery: True, check the following:

  • If you are working with a newly-discovered device, Alexa's state cache might be empty. Try refreshing the Alexa app in your browser. If you do not send StateReport events, send a ChangeReport to populate the cache.

  • Make sure you set proactivelyReported to true for all of your device's properties, and that you report all properties in your ChangeReport events.

  • If you implement the EndpointHealth interface, include the connectivity property in your StateReport and ChangeReport events.

  • Make sure you only report properties that are defined by the interfaces that you support. Do not, for example, report directive parameters as properties. For more information, see the documentation for each interface that your device supports.

  • For skills that implement the ThermostatController interface, cycle through the thermostat modes that your device supports so that Alexa can cache the data.

Additional scenario testing

After you confirm that all of your device's properties appear with DeepQuery: False, test all of the scenarios for your device that trigger ChangeReport events. For each scenario, make sure that the expected property values appear in the state reporting test tool.

The following are examples of some scenarios that you could test.

  • Change 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 ChangeReport events to Alexa. In your browser, refresh the Alexa app to confirm that DeepQuery: False and that the expected property values appear.

  • If you implement the EndpointHealth interface, verify that you are reporting the connectivity property correctly in your ChangeReport events. Remove the power or power source from your device and wait for the device's health polling or heartbeat interval to pass. When your skill reports that the connectivity has changed, refresh your browser and check the Alexa app. Then restore power to the device and check the Alexa app again.

  • Make sure that you send ChangeReport events for all Amazon accounts that have enabled and account-linked your skill, not just the first, or most recent accounts. Commonly, customers in the same household share smart home devices but have their own Amazon accounts associated with the skills for those devices.

    The state reporting test tool enables you to see information about the smart home devices associated with your skill only in the Amazon account that you use to sign in to the Alexa Skills Kit developer console. The tool doesn't show information from other Amazon accounts. 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. Sign in with each Amazon account, then use the state reporting test tool to confirm that the property states are accurate and that DeepQuery: False. This helps confirm that your skill is correctly sending ChangeReport events for each Amazon account.

  • Inspect your log responses to make sure that you are sending ChangeReport events to Alexa correctly.

If you encounter problems with the state reporting test tool, use the Alexa Developer Contact Us page to let us know.

How to use the smart home live debugger

The smart home live debugger enables you to see the ChangeReport, AddOrUpdateReport, and DeleteReport events associated with your smart home devices. You can see the following information:

  • The events that Alexa receives, including the JSON for your request.
  • Processing errors (if any) for the events.

Accessing the smart home live debugger

To view the smart home live debugger

  1. Sign in to the Amazon developer portal with the developer account for the smart home skill you want to test.

  2. Open the Alexa Skills Kit developer console.

  3. Open the smart home skill associated with your smart home device.

  4. Open the Test page.

  5. Enable testing for the skill.

  6. At the top of the page, select Device Log and Alexa Smart Home (Beta).

  7. In the Smart Home (Beta) section, enable Smart Home live debugger.

After you complete the procedure, when you send a ChangeReport, AddOrUpdateReport, or DeleteReport event to Alexa, the event information is added to the device log.

Viewing events

The smart home live debugger shows the ChangeReport, AddOrUpdateReport, and DeleteReport events that Alexa receives from your skill, for the Amazon account that you used to sign in to the Alexa Skills Kit developer console. Each event in the device log contains a JSON document with details about the event that Alexa received. The following image shows the smart home live debugger.

The smart home live debugger
The smart home live debugger

If you encounter problems with the smart home live debugger, use the Alexa Developer Contact Us page to let us know.

Example ChangeReport event with success

The following example shows the log in the smart home live debugger for a ChangeReport event that Alexa is able to process successfully.

{
  "header": {
    "customerId": "<customer id>",
    "skillId": "<skill id>",
    "skillStage": "development",
    "eventType": "SmartHomeChangeReportSuccess",
    "messageId": "<message id>",
    "applianceId": "ALL"
  },
  "payload": {
    "request": {
      "event": {
        "header": {
          "namespace": "Alexa",
          "name": "ChangeReport",
          "messageId": "<message id>",
          "payloadVersion": "3"
        },
        "endpoint": {
          "scope": {
            "type": "BearerToken",
            "token": "<an OAuth2 bearer token>"
          },
          "endpointId": "<endpoint id>"
        },
        "payload": {
          "change": {
            "cause": {
              "type": "PHYSICAL_INTERACTION"
            },
            "properties": [
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 75,
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              }
            ]
          }
        }
      },
      "context": {
        "properties": [
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-07-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 60000
          },
          {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
              "value": "OK"
            },
            "timeOfSample": "2017-07-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

Example ChangeReport event with error

The following example shows the log in the smart home live debugger for a ChangeReport event that Alexa is unable to process successfully, because the request contains errors. For more information, see understanding event errors.

{
  "header": {
    "customerId": "<customer id>",
    "skillId": "<skill id>",
    "skillStage": "development",
    "eventType": "SmartHomeChangeReportFailure",
    "messageId": "<message id>",
    "applianceId": "ALL"
  },
  "payload": {
    "errors": [
      {
        "code": "Duplicate_Payload_Property",
        "message": "duplicate property in the payload for brightness property"
      }
    ],
    "proactiveStateRequest": {
      "event": {
        "header": {
          "namespace": "Alexa",
          "name": "ChangeReport",
          "messageId": "<message id>",
          "payloadVersion": "3"
        },
        "endpoint": {
          "scope": {
            "type": "BearerToken",
            "token": "<an OAuth2 bearer token>"
          },
          "endpointId": "<endpoint id>"
        },
        "payload": {
          "change": {
            "cause": {
              "type": "PHYSICAL_INTERACTION"
            },
            "properties": [
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 75,
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              },
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 75,
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              }
            ]
          }
        }
      },
      "context": {
        "properties": [
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-07-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 60000
          },
          {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
              "value": "OK"
            },
            "timeOfSample": "2017-07-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

Understanding event errors

When your skill sends a ChangeReport, AddOrUpdateReport, or DeleteReport event to the Alexa event gateway, you receive an HTTP response from the gateway. For the full list of possible HTTP response codes, see Send Events to the Event Gateway.

When your skill receives a 202 Accepted response from the gateway, it means that Alexa received your event request successfully. However, there might be errors in the event that prevent Alexa from processing it correctly. In that case, the live debugger log contains a SmartHomeChangeReportFailure, SmartHomeAddOrUpdateReportFailure, or SmartHomeDeleteReportFailure event that contains an array of errors in the payload.

SmartHomeChangeReportFailure error codes

The following table lists the error codes that you might see in the smart home live debugger for a SmartHomeChangeReportFailure.

Error Code Description
BEARER_TOKEN_NULL_OR_EMPTY The bearer token is missing or empty.
CAUSE_NULL The cause object in the payload is missing.
CAUSE_TYPE_NULL_OR_EMPTY The cause object is missing a cause type, or the type is empty.
CLIENT_ID_NOT_AVAILABLE The client ID (customer ID) is missing.
CONTEXT_NULL The context object is missing.
CONTEXT_PROPERTIES_EMPTY The properties object in the context is empty.
CONTEXT_PROPERTIES_NULL The properties object in the context is missing.
CONTEXT_PROPERTY_NULL A property in the properties object in the context is missing.
DIRECTED_USER_ID_NULL_OR_EMPTY The directed user ID is missing or empty.
DUPLICATE_CONTEXT_PROPERTY The context contains two identical properties.
DUPLICATE_PAYLOAD_PROPERTY The payload contains two identical properties.
DUPLICATE_PROPERTY_MISMATCHED_VALUE A single property is reported twice, each with different values.
ENDPOINT_ID_BLANK The endpoint ID is empty.
ENDPOINT_ID_NULL The endpoint ID is missing.
ENDPOINT_SCOPE_NULL The endpoint scope is missing.
EVENT_ENDPOINT_NULL The event endpoint is missing.
EVENT_HEADER_NULL The event header is missing.
EVENT_NULL The event object is missing.
EVENT_PAYLOAD_NULL The event payload is missing.
HEADER_NAME_NULL The header name in the event object is null.
HEADER_NAMESPACE_NULL The header namespace in the event object is null.
HEADER_PAYLOAD_VERSION_NULL The payload version in the header in the event object is null.
INVALID_ASYNC_EVENT The asynchronous response is missing a correlation token.
INVALID_CHANGE_REPORT The ChangeReport contains a correlation token. A ChangeReport must not contain a correlation token.
INVALID_HEADER_NAMESPACE The header namespace must contain the value Alexa.
INVALID_PAYLOAD The payload could not be processed.
INVALID_PAYLOAD_VERSION The payload could not be processed.
INVALID_PROPERTY A property is invalid.
MISSING_TIME_OF_SAMPLE The timeOfSample field in the properties object is missing.
MISSING_UNCERTAINTY_IN_MILLIS The uncertaintyInMilliseconds field in the properties object is missing.
NEGATIVE_TIME_OF_SAMPLE_DIFFERENCE The timeOfSample field contains a time that is after the ChangeReport was received.
NEGATIVE_UNCERTAINTY_IN_MILLIS The uncertaintyInMilliseconds field contains a negative number. This number must be positive.
PAYLOAD_PROPERTIES_EMPTY The properties object in the payload is empty.
PAYLOAD_PROPERTIES_NULL The properties object in the payload is missing.
PAYLOAD_PROPERTY_NULL A property in the properties object in the payload is missing.
REQUEST_NULL The body of the request is missing.
SCOPE_INVALID The endpoint scope is invalid.
TIME_OF_SAMPLE_LARGER_THAN_THRESHOLD The timeOfSample field contains a time that is more than three seconds after the ChangeReport was received.
UNCERTAINTY_IN_MILLIS_LARGER_THAN_THRESHOLD The uncertaintyInMilliseconds field contains a number larger than 14,400,000.
UNKNOWN_PAYLOAD_VERSION The payload version is unsupported.
USER_IDENTIFIER_NULL_OR_EMPTY The user ID is missing or empty.

SmartHomeAddOrUpdateReportFailure error codes

The following table lists the error codes that you might see in the smart home live debugger for a SmartHomeAddOrUpdateReportFailure.

Error Code Description
INVALID_REQUEST_EXCEPTION The request is invalid for one of the following reasons:
  • Unsupported event type.
  • The payload version is missing.
  • The payload version is unsupported.
  • The endpoint ID is missing.
  • The friendly name is missing.
  • A parsing error occurred.

SmartHomeDeleteReportFailure error codes

The following table lists the error codes that you might see in the smart home live debugger for a SmartHomeDeleteReportFailure.

Error Code Description
INVALID_REQUEST_EXCEPTION The request is invalid for one of the following reasons:
  • Unsupported event type.
  • The payload version is missing.
  • The payload version is unsupported.
  • A parsing error occurred.