Use the Smart Home Debugger for WebRTC Skills

If you implement the Alexa.RTCSessionController interface in your Alexa smart home skill, you can use the smart home debugger to test and debug your skill. For example, when your skill controls a smart home security camera, the user can say "Alexa, show me my front door camera", and the video feed from your camera appears on the user's Alexa device.

While you're developing and testing your Alexa skill, you can use the smart home debugger to see logs from your WebRTC sessions in real-time. You can verify correct behavior, or find problems, such as the following:

  • Incorrect DTLS version
  • Invalid SDP answer
  • Invalid or missing ICE candidates
  • Unsupported codecs
  • Incorrect JSON formatting

For details about debugging problems with Alexa.ChangeReport, Alexa.AddOrUpdateReport, and Alexa.DeleteReport events, see Use the Smart Home Debugger.

Prerequisites

To use the smart home debugger during your WebRTC session, you need the following:

  • Your skill must communicate with a device that's capable of real-time communication (RTC).
  • Your skill must implement the Alexa.RTCSessionController interface.
  • You must have an Alexa device to use to test your skill, such as a Fire TV or any Echo device, such as an Echo Dot, Echo Plus, Echo Show, or Echo Spot.

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, begin testing your skill by interacting with your RTC device. Event information appears in the device log.

Viewing events

The smart home debugger shows logs for the 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.

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

Example event with success

The following example shows the log in the smart home debugger for a SessionDisconnected event that Alexa is able to process successfully. The event field contains the JSON of the event that you sent to Alexa.

{
    "header": {
        "namespace": "SkillDebugger",
        "name": "CaptureDebuggingInfo",
        "messageId": "message ID"
    },
    "payload": {
        "skillId": "skill id",
        "timestamp": "2020-09-29T19:08:14.545Z",
        "dialogRequestId": null,
        "skillRequestId": null,
        "type": "RTCSessionControllerSuccess",
        "content": {
            "eventType": "SessionDisconnectedResponse",
            "event": {}
        }
    }
}

Example event with success on session connected

The following example shows the log in the smart home debugger for a change in connection state that Alexa processes successfully.

{
    "header": {
        "namespace": "SkillDebugger",
        "name": "CaptureDebuggingInfo",
        "messageId": "message ID"
    },
    "payload": {
        "skillId": "skill id",
        "timestamp": "2020-09-29T19:08:14.545Z",
        "dialogRequestId": null,
        "skillRequestId": null,
        "type": "RTCSessionControllerSuccess",
        "content": {
            "eventType": "ConnectionStateEvent",
            "event": {
                "oldState": "DISCONNECTED",
                "newState": "CONNECTED"
            }
        }
    }
}

Example event with success on media flowing

The following example shows the log in the smart home debugger when Alexa is able to process RTC media. The state field can be FLOWING or NOT_FLOWING. The mediaType field can be AUDIO, DATA, or VIDEO.

{
    "header": {
        "namespace": "SkillDebugger",
        "name": "CaptureDebuggingInfo",
        "messageId": "message ID"
    },
    "payload": {
        "skillId": "skill id",
        "timestamp": "2020-09-29T19:08:14.545Z",
        "dialogRequestId": null,
        "skillRequestId": null,
        "type": "RTCSessionControllerSuccess",
        "content": {
            "eventType": "MediaFlowOutStateChangeEvent",
            "event": {
                "state": "FLOWING",
                "mediaType": "VIDEO"
            }
        }
    }
}

Example event with error

The following example shows the log in the smart home debugger for an SessionDisconnected event that Alexa is unable to process successfully. The event field contains the JSON of the event that you sent to Alexa.

{
    "header": {
        "namespace": "SkillDebugger",
        "name": "CaptureDebuggingInfo",
        "messageId": "message ID"
    },
    "payload": {
        "skillId": "skill id",
        "timestamp": "2020-09-29T19:08:14.545Z",
        "dialogRequestId": null,
        "skillRequestId": null,
        "type": "RTCSessionControllerFailure",
        "content": {
            "eventType": "SessionDisconnectedException",
            "errorCode": "LAMBDA_GENERAL_ERROR",
            "errorMessage": "Lambda general error message.",
            "event": null
        }
    }
}

RTCSessionController error codes

The following table lists the error codes that you might see in the smart home debugger for RTCSessionController events.

Error Code Error Message
SETUP_EVENT_ERROR Too many concurrent requests.
NO_VIDEO_ERROR Could not establish connection since timeout occurred waiting on video.
CONNECTION_ERROR Failed to establish the connection.
INTERNAL_ERROR Internal Exception occurred while establishing connection.
Was this page helpful?

Last updated: Nov 22, 2023