Alexa.Commissionable Interface 1.0

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. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

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 shows the Discovery workflow when the customer hasn't enabled your skill. Click the image to enlarge.

The Alexa Commissionable Interface Discovery Workflow

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

The Alexa Commissionable Interface AddorUpdate Workflow

Matter requirements for Alexa discovery

For Matter devices, you must report the following Matter attributes from the Basic Information Cluster to Alexa: VendorID, ProductID, UniqueID, Discriminator ,and NodeLabel. Alexa uses these attributes to identify duplicate devices reported through your skill and locally over Matter. Include these attributes in the Discover.Response and AddOrUpdateReport events from your skill as follows:

  • Enable the Matter UniqueID attribute on your device and populate the endpoint.additionalAttributes.customIdentifier property with the UniqueID.
  • In the endpoint.connections array, report the connection type as MATTER and include the matterVendorId, matterProductId, and matterDiscriminator properties for your Matter device. Also, Amazon recommends that you report the macAddress and macNetworkInterface, if available.
  • In the endpoint.friendlyName property, make sure that the name that your skill reports is available over the local Matter connection in the NodeLabel attribute. If the customer changes the friendly name on your app, make sure that you update the NodeLabel field to reflect the change.

Matter attribute example

The following example shows how to set discovery properties based on values from the Matter Basic Information Cluster.

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. When you report the Alexa.Commissionable capability in your discovery response, 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 in the discovery response properties as described in Matter requirements.

Discovery response example

The following example shows a discovery response for a Matter-enabled endpoint that supports the Alexa.Commissionable and Alexa.EndpointHealth interfaces.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "Unique ID of the endpoint",
                "manufacturerName": "Manufacturer of the endpoint",
                "description": "Description to be shown in the Alexa app",
                "friendlyName": "New Matter device",
                "displayCategories": ["LIGHT"],
                "additionalAttributes": {
                    "manufacturer": "Manufacturer of the endpoint",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Matter UniqueID"
                },
                "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": "Matter VendorID",
                "matterProductId": "Matter ProductID",
                "matterDiscriminator": "longDiscriminator"
            } ],
            "relationships": {}
            }]
        }
    }
}

AddOrUpdateReport

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

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

AddOrUpdateReport event example

The following example shows an AddOrUpdateReport event for a new Matter-enabled endpoint to indicate that an Echo device can commission this endpoint.

Copied to clipboard.


{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "AddOrUpdateReport",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "Unique ID of the new endpoint",
                "manufacturerName": "Manufacturer of the endpoint",
                "description": "Description to be shown in the Alexa app",
                "friendlyName": "New Matter device",
                "displayCategories": ["LIGHT"],
                "additionalAttributes": {
                    "manufacturer": "Manufacturer of the endpoint",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Matter UniqueID"
                },
                "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": "Matter VendorID",
                "matterProductId": "Matter ProductID",
                "matterDiscriminator": "longDiscriminator"
            } ],
            "relationships": {}
            }]
        }
    }
}

Directives and events

The Alexa.Commissionable interface defines the following 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.

For Matter devices, 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": "Unique version 4 UUID",
            "correlationToken": "Opaque correlation token",
            "payloadVersion": "1.0"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2 bearer token"
            },
            "endpointId": "endpoint id",
            "cookie": {}
        },
        "payload": {}
    }
}

ReportCommissioningInformation directive payload

The ReportCommissioningInformation directive doesn't define any payload parameters.

ReportCommissioningInformation directive response

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

ReportCommissioningInformation directive error handling

If your skill can't handle a ReportCommissioningInformation directive successfully and the error is specific to commissioning, respond with an Alexa.ReportCommissioningInformation.ErrorResponse event. For general errors, response with Alexa.ErrorResponse. In addition to the ReportCommissioningInformation error types, you can use general Alexa error types, such as ENDPOINT_BUSY, ENDPOINT_UNREACHABLE, and BRIDGE_UNREACHABLE.

CommissioningInformationReport event

Send the CommissioningInformationReport event to the Alexa event gateway to notify Alexa that you put the device in commissioning mode. You send the CommissioningInformationReport event in response to the ReportCommissioningInformation directive.

CommissioningInformationReport event example

The following example shows a successful CommissioningInformationReport event.

Copied to clipboard.

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

CommissioningInformationReport event payload

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

Property Description Type Required

CommissioningInformation

List of local protocols over which the Echo can pair with a device.

Array of objects

Yes

CommissioningInformation.localProtocol

Indicates the protocol for commissioning with this device on a local network.
Valid value: MATTER.

String

Yes

CommissioningInformation.protocolData

Protocol-specific commissioning information.

Object

Yes

CommissioningInformation.protocolData.manualPairingCode

Code generated by a Matter device when the current Matter administrator instructs the device to go into the open commissioning window.

String

Yes

CommissioningInformation.protocolData.commissioningWindowExpirationTimestamp

Indicates the commissioning date and time window, after which Alexa can no longer create a local connection. This timestamp helps Alexa limit the retries until a specific time. Also, when Alexa is unable to create a local connection because the commissioning window has expired, this timestamp is useful to troubleshoot.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

No

CommissioningInformationReport response

On success, Alexa sends 202 Accepted to indicate that the Alexa service accepted the event for further logical validation and processing. If the event isn't accepted, Alexa sends the appropriate HTTP status code.