Use the Smart Home Debugger

If your smart home add-on proactively reports state to Alexa in Alexa.ChangeReport events, you can use the smart home debugger to test and debug your smart home add-on. By using the smart home debugger, you can view the Alexa.ChangeReport, Alexa.AddOrUpdateReport, and Alexa.DeleteReport events that Alexa receives from your add-on, including your JSON, and any processing errors. If you implement the Alexa.RTCSessionController interface in your Alexa add-on, also see Use the Smart Home Debugger for WebRTC Add-ons. For details about other test tools, see Test and Debug Your Smart Home Add-on.

Prerequisites

To use the smart home debugger, your smart home add-on 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

Sign in to the Alexa developer console.
Open the smart home add-on associated with your smart home device.
Open the Test page.
Enable testing for the add-on.
At the top of the page, select Device Log and Smart Home Debugger.
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 add-on, 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.

Alexa simulator, device log and associated JSON in the smart home debugger. — Smart Home Debugger

If you encounter problems with the smart home debugger, contact Alexa developer support with the details.

ChangeReport event with success example

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": "Unique version 4 UUID",
    "applianceId": "ALL"
  },
  "payload": {
    "request": {
      "event": {
        "header": {
          "namespace": "Alexa",
          "name": "ChangeReport",
          "messageId": "Unique version 4 UUID",
          "payloadVersion": "3"
        },
        "endpoint": {
          "scope": {
            "type": "BearerToken",
            "token": "OAuth2.0 bearer token"
          },
          "endpointId": "Unique ID of the endpoint"
        },
        "payload": {
          "change": {
            "cause": {
              "type": "PHYSICAL_INTERACTION"
            },
            "properties": [
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 75,
                "timeOfSample": "2017-07-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              }
            ]
          }
        }
      },
      "context": {
        "properties": [
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-07-03T10:00:00.02Z",
            "uncertaintyInMilliseconds": 60000
          },
          {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
              "value": "OK"
            },
            "timeOfSample": "2017-07-03T16:00:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

ChangeReport event with error example

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": "Unique version 4 UUID",
    "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": "Unique version 4 UUID",
          "payloadVersion": "3"
        },
        "endpoint": {
          "scope": {
            "type": "BearerToken",
            "token": "OAuth2.0 bearer token"
          },
          "endpointId": "Unique ID of the endpoint"
        },
        "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-02-03T10:00:00.02Z",
            "uncertaintyInMilliseconds": 60000
          },
          {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
              "value": "OK"
            },
            "timeOfSample": "2017-02-03T16:00:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

Understanding event errors

When your add-on 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 Alexa Event Gateway. When your add-on 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.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Prerequisites

Accessing the smart home debugger

Viewing events

ChangeReport event with success example

ChangeReport event with error example

Understanding event errors

Change report errors

AddOrUpdate report errors

Delete report errors

​Prerequisites

​Accessing the smart home debugger

​Viewing events

​ChangeReport event with success example

​ChangeReport event with error example

​Understanding event errors

​Change report errors

​AddOrUpdate report errors

​Delete report errors

​Related topics

Prerequisites

Accessing the smart home debugger

Viewing events

ChangeReport event with success example

ChangeReport event with error example

Understanding event errors

Change report errors

AddOrUpdate report errors

Delete report errors

Related topics