Your Alexa Consoles
登录
登录
感谢您的访问。此页面目前仅提供英语版本。我们正在开发中文版本。谢谢您的理解。

Debug Your Smart Home Skill

As you build your smart home skill, you have the following options for debugging it:

  • State reporting test tool – This tool enables you to view the properties of the smart home devices associated with your skill, and whether your skill is queried for these properties or it proactively reports them to Alexa.
  • Smart home live debugger – This feature enables you to see the ChangeReport events that Alexa receives for the smart home devices associated with your skill, including processing errors.

These tools enable you to see information about the smart home devices associated with your skill in 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.

For more information about building a smart home skill with state reporting, see the following topics:

 

Overview

Your smart home skill should notify Alexa when a property of your smart device changes. Your skill notifies Alexa by sending a ChangeReport event to the Alexa event gateway. For more information, see Send Events to the Event Gateway. Sometimes Alexa sends ReportState directives to your skill, in which case your skill should respond with a StateReport.

The state reporting test tool and the smart home live debugger help you understand what Alexa knows about the state of your smart home devices, and why. Specifically, these tools can help you understand the following information:

State reporting test tool

  • The current state of the smart device's properties.
  • Whether Alexa received the state in the response to a ReportState directive.

Smart home live debugger

  • The ChangeReport events that Alexa receives.
  • Processing errors (if any) for the received ChangeReport events.
  • Whether the state of the smart device's properties were sent in the payload or the context of the ChangeReport.

You can use these tools together to see a more complete picture of how your skill interacts with Alexa.

Prerequisites

To use the tools, testing tips, and troubleshooting ideas in this topic, you must have a smart home skill that sends state update (ChangeReport) events to the Alexa event gateway when the properties of your smart device change. This means that your discovery response (Discover.Response) indicates "proactivelyReported": true for all capabilities supported by the smart device. If your skill supports proactive reporting for only a subset of the smart device's properties, then you cannot use the tools described in this topic.

How to use the state reporting test tool

The state reporting test tool enables you to see when your skill is queried for the current state of your smart device's properties, or when Alexa relies on the proactive ChangeReport events that your skill sends. The following sections explain how to use it.

Step 1: Get access to the tool

To request access to the state reporting test tool, complete the following steps:

  1. On the Amazon developer portal, sign in with the developer account that is associated with 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 Developer Support contact page. Use the contact form to send the following information. Replace customer ID with your customer ID from the previous step.

    Subject: Alexa

    Message: Requesting access to the state reporting test tool for the following customer ID: customer ID

You will be contacted when you are granted access to the tool, or if we need more information.

Step 2: Sign in and enable your skill

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.

The following is a list of regions and the corresponding URL for the web-based Alexa app:

If you haven't already done so, enable and account-link your smart home skill. For more information about how to do this, see Steps to Build a Smart Home Skill.

Step 3: View and understand the state information

In the Alexa app, navigate to Smart Home and then Devices. If the tool is enabled for your developer account, you see extended debugging information for each device. The following image shows an example device:

Each Capability states line in the tool represents a smart device capability (property) that you marked as proactively reported in your discovery response. It also shows the current state for each property, and whether Alexa queried your skill to determine that state.

For example, in the preceding image the Wireless In-wall Dimmer device has the following property states:

  • connectivity: OK
  • brightness: 0
  • powerState: OFF

The following image explains each part of the capability states line.

Pay special attention to the DeepQuery value. This is a boolean that indicates whether your proactive state update (ChangeReport) events and other event data are being used, or Alexa queried to obtain the value.

  • DeepQuery: False: Indicates that Alexa used your proactive state update (ChangeReport) events to determine this property's value.

  • DeepQuery: True: Indicates that Alexa sent a ReportState directive to the skill. The property's value was received in the StateReport event sent by the skill in response.

Step 4: Troubleshoot

If you believe you have properly implemented proactive state updates (ChangeReport events), but the tool shows 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 your device's properties are not sent in the response to a ReportState directive (if "retrievable": false), you need to send a ChangeReport to populate the cache.
  • Make sure you indicate "proactivelyReported": true for all of your device's properties, and that you report all property values. This includes the connectivity property of the EndpointHealth interface.
  • Make sure you only report the values of properties that are defined and reportable for your device. For example, if your device implements the BrightnessController interface, do not report brightnessDelta as proactivelyReported because this is not a reportable property.
  • For thermostat devices, you might need to toggle between HEAT/COOL and AUTO modes to make sure that Alexa has cached data for all the supported set points that were reported during device discovery.

Step 5: Perform additional tests

After you confirm that all of your device's properties show DeepQuery: False, you should test all of the scenarios for your device that trigger proactive state updates. For each scenario, make sure that the expected property values are shown in the state reporting test tool.

The following are examples of some scenarios that you might want to 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 proactive state updates to the Alexa event gateway. In your browser, refresh the Alexa app to confirm that DeepQuery: False and that the device's properties show the expected state.

  • Test EndpointHealth proactive 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 your skill reports that the connectivity value has changed, refresh your browser and check the Alexa app for the device state. Then restore power to the device and make sure that all properties are correctly updated in the Alexa app.

  • Make sure 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. 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.

    To test this scenario, you must have at least two Amazon accounts that are enabled to use the tool. Refer to Step 1 if you need to enable additional accounts. Make sure to log in from the account you want to enable before you send the contact form.

  • Inspect your log responses to make sure that your proactive state updates are sent correctly to the Alexa event gateway.

If you encounter problems with the state reporting test tool, use the Developer Support contact form to let us know.

How to use the smart home live debugger

The smart home live debugger enables you to see the ChangeReport events associated with your smart home devices.

Step 1: Access the tool

To view the ChangeReport events for your smart home devices, complete the following steps.

  1. Open the Alexa Skills Kit developer console.

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

  3. Open the Test page.

  4. At the top of the page, make sure that Device Log and Alexa Smart Home (Beta) are selected.

  5. In the Smart Home (Beta) section of the page, make sure the Smart Home live debugger is enabled toggle is on.

When Alexa receives a ChangeReport event for a smart home device associated with your smart home skill, the event information is added to the device log. For example, see the following image.

The smart home live debugger
The smart home live debugger

For help understanding ChangeReport events in the device log, see the following sections.

If you encounter problems with the smart home live debugger, use the Developer Support contact form to let us know.

Step 2: Understand ChangeReport events

After you complete the steps in the preceding section, the device log shows the ChangeReport events that Alexa receives for the smart home devices associated with your smart home skill in the Amazon account that you use to sign in to the Alexa Skills Kit developer console. You don't see ChangeReport events for devices in other Amazon accounts. Each event in the device log contains a JSON document with details about the ChangeReport that Alexa received.

When your skill sends a ChangeReport event to the Alexa event gateway, you receive an HTTP response from the gateway. For the full list of possible HTTP response codes, see Success and Errors in the Send Events to the Event Gateway topic.

Even when your skill receives a 202 Accepted response from the gateway, there might be errors with the ChangeReport that prevent Alexa from processing it correctly. You can see these processing errors (if any) in the device log. For a complete list of potential errors, see the following section.

ChangeReport processing errors

The following table lists the processing errors that you might see in the smart home live debugger and the reason why. For more information about the ChangeReport event schema, see ChangeReport.

Error Code Reason
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.

Example ChangeReport events in the smart home live debugger

The following are examples of ChangeReport events that you might see in the live debugger.

Example ChangeReport event (success)
{
  "header": {
    "customerId": "A1E2P2455A5NYT",
    "skillId": "amzn1.ask.skill.awer45bc-f5f7-6f9b-5f24-c3d5f6821d4f",
    "skillStage": "development",
    "eventType": "SmartHomeChangeReportSuccess",
    "messageId": "89bb25e2-9f6c-42b8-8982-ff1dc038c58c",
    "applianceId": "ALL"
  },
  "payload": {
    "request": {
      "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
          }
        ]
      },
      "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": "2017-07-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              }
            ]
          }
        }
      }
    }
  }
}
Example ChangeReport event (processing error)
{
  "header": {
    "customerId": "A1E2P2455A5NYT",
    "skillId": "amzn1.ask.skill.awer45bc-f5f7-6f9b-5f24-c3d5f6821d4f",
    "skillStage": "development",
    "eventType": "SmartHomeChangeReportFailure",
    "messageId": "89bb25e2-9f6c-42b8-8982-ff1dc038c58c",
    "applianceId": "ALL"
  },
  "payload": {
    "errors": [
      {
        "code": "Duplicate_Payload_Property",
        "message": "duplicate property in the payload for brightness property"
      }
    ],
    "proactiveStateRequest": {
      "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
          }
        ]
      },
      "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": "2017-07-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              },
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 85,
                "timeOfSample": "2017-07-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              }
            ]
          }
        }
      }
    }
  }
}