Use the Smart Home Debugger

If your skill proactively reports state to Alexa in Alexa.ChangeReport events, you can use the smart home debugger to test and debug your smart home skill. By using the smart home debugger, you can view the Alexa.ChangeReport, Alexa.AddOrUpdateReport, and Alexa.DeleteReport events that Alexa receives from your skill, including your JSON, and any processing errors.

If you implement the Alexa.RTCSessionController interface in your Alexa skill, also see Use the Smart Home Debugger for WebRTC Skills.

For details about other test tools, see Test and Debug Your Smart Home Skill.

Prerequisites

To use the smart home debugger, your smart home skill must send Alexa.ChangeReport, Alexa.AddOrUpdateReport, or Alexa.DeleteReport events to Alexa. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.

Accessing the smart home debugger

To access the smart home debugger, you use the Alexa developer console.

To view the smart home debugger

  1. Sign in to the Alexa developer console.

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

  3. Open the Test page.

  4. Enable testing for the skill.

  5. At the top of the page, select Device Log and Smart Home Debugger.

  6. In the Smart Home Debugger section of the page, use the toggle to enable Smart Home debugger.

After you complete the procedure, when you send an Alexa.ChangeReport, Alexa.AddOrUpdateReport, or Alexa.DeleteReport event to Alexa, you see the event information in the device log.

Viewing events

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

smart home debugger
The smart home debugger

If you encounter problems with the smart home debugger, send the details to Amazon by using the Alexa Developer Contact Us page.

Example ChangeReport event with success

The following example shows the log in the smart home debugger for an Alexa.ChangeReport event that Alexa processes 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 debugger for an Alexa.ChangeReport event that Alexa is unable to process successfully, because the request contains errors. For details, 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 an Alexa.ChangeReport, Alexa.AddOrUpdateReport, or Alexa.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 message that prevent Alexa from processing the event correctly. In that case, the debugger log contains a SmartHomeChangeReportFailure, SmartHomeAddOrUpdateReportFailure, or SmartHomeDeleteReportFailure event that contains an array of errors in the payload.

Change report errors

The following table lists the error codes that you might see in the smart home 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 Alexa.ChangeReport contains a correlation token. An Alexa.ChangeReport must not contain a correlation token.
INVALID_HEADER_NAMESPACE The header namespace must contain the value Alexa.
INVALID_PAYLOAD The payload couldn't be processed.
INVALID_PAYLOAD_VERSION The payload couldn't 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's after the Alexa.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's more than three seconds after the Alexa.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.

AddOrUpdate report errors

The following table lists the error codes that you might see in the smart home 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 isn't supported.
  • The endpoint ID is missing.
  • The friendly name is missing.
  • A parsing error occurred.

Delete report errors

The following table lists the error codes that you might see in the smart home 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.