Alexa.Commissionable Interface

Implement the Alexa.Commissionable interface in your Alexa skill to help Alexa connect with your endpoints locally on your customer’s home network over a local protocol, such as Matter. After Alexa connects to your endpoints locally, you have an alternate route available for executing control directives. This route makes control of your endpoints faster and more resilient if there are network outages or when your skill isn't available. For details about integrating your Matter devices with Amazon, see Matter on developer.amazon.com.

For the list of locales that the Alexa.Commissionable interface supports, see List of Alexa Interfaces and Supported Languages.

Utterances

The Alexa.Commissionable interface isn't customer-facing, therefore it doesn't support any voice user interactions with Alexa directly.

Workflow

Alexa.Commissionable seamlessly integrates into existing customer and developer workflows. As usual, the customer first registers their device with your app and then enables your smart home skill by account linking your app with their Amazon account. For details about account linking with Alexa, see Set up App-to-App Account Linking for Your Skill. The commissioning of your device with Alexa starts when one of the following activities happens:

  • When a customer asks Alexa to discover their device, Alexa sends a Discover directive to your skill and your skill reports the Discover.Response event with the Alexa.Commissionable capability for the first time for that endpoint. For additional information, see Discovery.
  • When your skill proactively reports your device with the Alexa.Commissionable capability by using the AddOrUpdateReport event. For additional information, see AddOrUpdateReport.

After receiving the Discover.Response event or the AddOrUpdateReport event with the Alexa.Commissionable capability, Alexa sends the ReportCommissioningInformation directive to request commissioning information for the device. After your skill sends a CommissioningInformationReport, Alexa initiates a workflow to trigger a local commissioning.

This diagram illustrates the Discovery workflow when the customer hasn't enabled your skill. Click the image to enlarge.

The Alexa Commissionable Interface Discovery Workflow

This diagram illustrates the AddOrUpdateReport workflow when the customer has already enabled your skill. Click the image to enlarge.

The Alexa Commissionable Interface AddorUpdate Workflow

Matter protocol specific requirements

For Matter devices, apply the following settings in your Alexa.Discovery Discover.Response or AddOrUpdateReport event report:

  • In the Endpoint object, make sure that the friendlyName reported from your skill is also available over the local Matter connection through the NodeLabel field from the Basic Information Cluster of the device. If the customer changes the friendly name on your app, you should update the NodeLabel field to reflect the change.
  • In the AdditionalAttributes object, populate the customIdentifier field with the stable UniqueID field from the Basic Information Cluster of the device. You use this field to deduplicate devices reported through your skill and locally from the Alexa device.
  • In the Connections property, report the type as a MATTER connection. Amazon recommends that you report the matterDiscriminator, macAddress, matterVendorId, matterProductId, and macNetworkInterface of your Matter device if the values are available.

The following pseudocode illustrates how to set certain fields based on values from the Basic Information Cluster of the device.

Copied to clipboard.

endpoint.friendlyName = matter_device.basicInformationCluster.nodeLabel
additional_attributes.customIdentifier = matter_device.basicInformationCluster.uniqueId

network_interfaces_map = { "WIFI": 1, "THREAD": 2, "ETHERNET": 4 }

if (matter_device.networkCommissioningCluster.featureFlag & network_interfaces_map.WIFI) {
    mac_network_interface = "WIFI"
}
else if (matter_device.networkCommissioningCluster.featureFlag & network_interfaces_map.THREAD) {
    mac_network_interface = "THREAD"
}
else if (matter_device.networkCommissioningCluster.featureFlag & network_interfaces_map.ETHERNET) {
    mac_network_interface = "ETHERNET"
}

connections = [{
   "type": "MATTER",
    "macAddress": matter_device.get_mac_address(),
    "macNetworkInterface": mac_network_interface,
    "matterVendorId": matter_device.basicInformationCluster.vendorId,
    "matterProductId": matter_device.basicInformationCluster.productId,
    "matterDiscriminator": matter_device.get_discriminator()
}]

Copied to clipboard.

endpoint.friendlyName = matter_device.basicInformationCluster.nodeLabel
additional_attributes.customIdentifier = matter_device.basicInformationCluster.uniqueId

network_interfaces_map = { "WIFI": 1, "THREAD": 2, "ETHERNET": 4 }

if matter_device.networkCommissioningCluster.featureFlag & network_interfaces_map["WIFI"]:
    mac_network_interface = "WIFI"
elif matter_device.networkCommissioningCluster.featureFlag & network_interfaces_map["THREAD"]:
    mac_network_interface = "THREAD"
elif matter_device.networkCommissioningCluster.featureFlag & network_interfaces_map["ETHERNET"]:
    mac_network_interface = "ETHERNET"

connections = [{
    "type": "MATTER",
    "macAddress": matter_device.get_mac_address(),
    "macNetworkInterface": mac_network_interface,
    "matterVendorId": matter_device.basicInformationCluster.vendorId,
    "matterProductId": matter_device.basicInformationCluster.productId,
    "matterDiscriminator": matter_device.get_discriminator()
}]

Discovery

You describe your device's endpoints that support Alexa.Commissionable by using the standard discovery mechanism described in the Alexa.Discovery Interface and Alexa Discovery Objects / Connections property. When you report the Alexa.Commissionable capability in your discovery response report, Alexa knows that a device is available in your customer's account and is ready to be paired locally with an Echo device.

Apply Matter specific settings as described in Matter protocol specific requirements.

Discovery response example

The following example shows a Discover.Response message for an endpoint that supports Alexa.Commissionable and Alexa.EndpointHealth interfaces.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint",
                "manufacturerName": "the manufacturer name of the endpoint",
                "description": "a description that is shown in the Alexa app",
                "friendlyName": "New Matter device",
                "displayCategories": ["LIGHT"],
                "additionalAttributes": {
                    "manufacturer": "the manufacturer name of the endpoint",
                    "model": "the model of the device",
                    "serialNumber": "the serial number of the device",
                    "firmwareVersion": "the firmware version of the device",
                    "softwareVersion": "the software version of the device",
                    "customIdentifier": "your custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.Commissionable",
                        "version": "1.0"
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ],
             "connections": [{
                "type": "MATTER",
                "macAddress": "00:11:22:AA:BB:33:44:55",
                "macNetworkInterface": "THREAD",
                "matterVendorId": "MatterVendorId",
                "matterProductId": "MatterProductId",
                "matterDiscriminator": "longDiscriminator"
            } ],
            "relationships": {}
            }]
        }
    }
}

AddOrUpdateReport

To commission an existing endpoint or a new Matter endpoint, for example, to Matter-enable an existing endpoint with a firmware update, you can proactively send an Alexa.Discovery.AddOrUpdateReport event. For details, see the AddOrUpdateReport event.

Apply Matter specific settings as described in Matter protocol specific requirements.

AddOrUpdateReport event example

The following example shows an AddOrUpdateReport message for a new endpoint to indicate that an Echo device can commission this device.

Copied to clipboard.


{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "AddOrUpdateReport",
            "payloadVersion": "3",
            "messageId": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the new endpoint",
                "manufacturerName": "the manufacturer name of the endpoint",
                "description": "a description that is shown in the Alexa app",
                "friendlyName": "New Matter device",
                "displayCategories": ["LIGHT"],
                "additionalAttributes": {
                    "manufacturer": "the manufacturer name of the endpoint",
                    "model": "the model of the device",
                    "serialNumber": "the serial number of the device",
                    "firmwareVersion": "the firmware version of the device",
                    "softwareVersion": "the software version of the device",
                    "customIdentifier": "your custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.Commissionable",
                        "version": "1.0"
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ],
            "connections": [{
                "type": "MATTER",
                "macAddress": "00:11:22:AA:BB:33:44:55",
                "macNetworkInterface": "THREAD",
                "matterVendorId": "MatterVendorId",
                "matterProductId": "MatterProductId",
                "matterDiscriminator": "longDiscriminator"
            } ],
            "relationships": {}
            }]
        }
    }
}

Directives and events

ReportCommissioningInformation directive

When the Discover.Response or AddOrUpdateReport event includes the Alexa.Commissionable capability, Alexa sends the ReportCommissioningInformation directive to your skill. Using this directive, Alexa asks your device cloud to take necessary actions to enable local commissioning. In the case of the Matter protocol, the follow actions occur. After receiving this directive, your device cloud puts your device in the commissioning mode for a given period and returns commissioning credentials. Also, your device cloud returns the commissioning window expiration timestamp that indicates the duration that the device should stay in the commissioning mode.

ReportCommissioningInformation directive example

The following example shows a ReportCommissioningInformation directive that Alexa sends to your skill.

{
    "directive": {
        "header": {
            "namespace": "Alexa.Commissionable",
            "name": "ReportCommissioningInformation",
            "messageId": "message id",
            "correlationToken": "an opaque correlation token",
            "payloadVersion": "1.0"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2 bearer token"
            },
            "endpointId": "endpoint id",
            "cookie": {}
        },
        "payload": {}
    }
}

ReportCommissioningInformation directive response event

After your skill successfully handles the ReportCommissioningInformation directive and puts the device in commissioning mode, respond with a CommissioningInformationReport event.

CommissioningInformationReport event payload

The following table shows the payload details for the CommissioningInformationReport response event.

Property Description Type Required

CommissioningInformation

An array of protocol objects, which is a list of local protocols over which Alexa can pair with a device. The protocol objects CommissioningInformation.localProtocol and CommissioningInformation.protocolData include the information needed for commissioning over that protocol.

Array of objects

Yes

CommissioningInformation.localProtocol

A string enumeration value that indicates the protocol for commissioning with this device on a local network. The valid value is MATTER, which indicates that Alexa can connect with the device over the Matter protocol.

String

Yes

CommissioningInformation.protocolData

Object containing protocol specific commissioning data, including CommissioningInformation.protocolData.manualPairingCode and CommissioningInformation.protocolData.commissioningWindowExpirationTimestamp.

Object

Yes

CommissioningInformation.protocolData.manualPairingCode

A Matter device generates this code when the current administrator instructs the device to go into the open commissioning window.

String

Yes

CommissioningInformation.protocolData.commissioningWindowExpirationTimestamp

An optional timestamp your skill provides to indicate the commissioning window, after which Alexa can no longer create a local connection. This timestamp helps Alexa limit the retries until a specific time and also troubleshoot when Alexa is unable to create a local connection because the commissioning window has expired. The timestamp represents a specific date and time in Coordinated Universal Time. It's a string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

No

Example response event

The following example shows a successful response event that you send to the ReportCommissioningInformation directive.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Commissionable",
            "name": "CommissioningInformationReport",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token",
            "payloadVersion": "1.0"
        },
        "endpoint": {
            "endpointId": "endpoint id"
        },
        "payload": {
            "commissioningInformation": [{
                    "localProtocol": "MATTER",
                    "protocolData": {
                        "manualPairingCode": "ManualPairingCode",
                        "commissioningWindowExpirationTimestamp": "2021-02-03T16:20:50Z"
                    }
                }
            ]
        }
    }
}

ReportCommissioningInformation directive error handling

If your skill can't handle a ReportCommissioningInformation directive successfully, respond with a ReportCommissioningInformation.ErrorResponse event.

In addition to the ReportCommissioningInformation error types, you can use standard Alexa error types, such as ENDPOINT_BUSY, ENDPOINT_UNREACHABLE, and BRIDGE_UNREACHABLE. For details, see ErrorResponse Events / Error type values.

Matter Frustration-Free Setup

Understand Smart Home Skills