Best Practices to Commission Matter Devices with Alexa

Customers often struggle to commission their Matter-enabled devices to their home network. Follow these best practices for Matter commissioning to improve device setup success and enable device discovery across all Alexa-supported setup journeys.

Customer challenges

Customers face the following challenges when commissioning Matter devices:

• Pairing mode confusion – Customers often can't determine how to activate commissioning mode on their devices. Manufacturers implement different activation methods. Some devices require button presses or power cycling, and others provide menu-based approaches through on-device interfaces or manufacturer apps. Further, the commissioning window closes after several minutes, and customers often miss this deadline, resulting in setup failures.

• Multi-step complexity – The commissioning process requires multiple sequential steps that vary depending on the device manufacturer. These steps include scanning a QR code or entering a numeric code, Bluetooth Low Energy (BLE) discovery, secure channel establishment, device attestation, and credential provisioning. Any step can fail without clear customer guidance and consistent UI flows across different smart home administrators.

• Factory reset uncertainty – When commissioning fails or requires a device restart, customers can't determine how or when to reset their device to factory settings.

• Multi-Admin setup challenge – Multi-Admin support is a key feature of Matter. However, adding an already-configured Matter device to a second Matter administrator creates challenges. Most customers don't realize they must first open the original administrator app to generate a temporary pairing code. Additionally, each app places this code generation feature in a different location, making customers struggle to find the right place. Customers must then copy that code and enter it in the new app, a multi-step process that feels unfamiliar and frequently leads to customer frustration or failure.

Understand commissioning

The Matter specification defines three commissioning flows, each designed for different product architectures. The flows differ based on device characteristics, pre-configuration requirements, and manufacturer preferences. In all setup paths, the Matter-enabled device advertises that it's in commissioning (pairing) mode, so that Alexa, acting as the commissioner, can discover and commission the device to the Alexa Matter fabric (a logical network of Matter devices managed by Alexa).

The following diagram shows initial and secondary commissioning of a Matter-enabled device to the Alexa Matter fabric.

The following table shows the ways a customer can put a device into commissioning mode.

Initial commissioning

A Matter-enabled device enters commissioning mode by using one of the commissioning flows and begins advertising to the Matter fabric, typically over Bluetooth Low-Energy (BLE).

Initial commissioning creates the out-of-the-box experience that occurs when a customer sets up a Matter device for the first time. To identify and authenticate their device, the customer scans the QR code printed on the device or product packaging, enters a numeric code, or follows instructions in the manufacturer app or service. The Matter commissioner can then identify the device by the advertisement data, such as the discriminator, and establish a secure channel by using a shared secret derived from the QR code. The commissioner then proceeds with device attestation and credential provisioning to join the device to the fabric.

Secondary commissioning

Customers can commission Matter-enabled devices to multiple Matter fabrics. Secondary commissioning occurs when a customer commissions a device already set up on one Matter fabric to a new Matter fabric.

Matter supports two methods for secondary commissioning:

• Basic Commissioning Method (BCM) – This method uses the original QR code or numeric pairing code from the device or product packaging. If the current Matter administrator and the device support this method, customers follow device-specific manual steps to put the device into commissioning mode. Customers then use the original QR code or numeric pairing code to pair the device with the new administrator. Device manufacturers and commissioners can choose whether to implement this optional method.

• Enhanced Commissioning Method (ECM) – This method requires a new QR or numeric pairing code. The current administrator sends an OpenCommissioningWindow command to the device to generate a new, random passcode for the pairing window. The current administrator presents the new, temporary 11-digit manual pairing code or dynamically generated QR code in an app or on screen. The customer uses the new code to commission the device onto the new fabric. The Matter specification requires all Matter devices and commissioners to implement this method.

A Matter device can support both ECM and BCM. During network discovery, the device advertises its commissioning method so Alexa knows which pairing code to expect.

Implementation best practices

A common cause of commissioning failures is that the device isn't in pairing mode when Alexa attempts discovery. Depending on the commissioning flow the device supports, putting the device into pairing mode might require a power cycle, a button press, or retrieving a pairing code from a manufacturer app. Sometimes, a factory reset is required.

The Alexa guided setup begins with initial commissioning and falls back to secondary commissioning based on customer input, providing contextual guidance throughout the process. For devices that require physical interaction, describe these steps in the Distributed Compliance Ledger (DCL) as parameterized instructions. When you provide structured, product-specific instructions in the DCL, Alexa can guide customers through setup without requiring them to search for manufacturer documentation.

Configure commissioning-related metadata

The DCL contains specific device information, including commissioning data and links to product information. Alexa relies on the DCL to provide manufacturer and product-specific instructions to the customer.

Without the information in the DCL, Alexa falls back to generic verbiage. When you populate pairing instructions in the DCL, Alexa can give relevant guidance to the customer.

Carefully configure these fields for every Product ID in your portfolio. When you provide clear, product-specific commissioning data in the DCL, you can reduce setup failures, improve customer satisfaction, and lower support costs.

Device model schema

The following table shows the commissioning-related data contained in the DCL device model schema.

Pairing hint bitmap

The pairing hint bitmap provides hints to the commissioner about the steps the customer must take to put the device in commissioning mode or factory reset. The pairing hint represents a base-10 numeric value for a bitmap of pairing methods supported by the device. Some pairing hints require additional pairing instructions (PI).

The following table shows the bits relevant for commissioning and factory reset.

Enable secondary commissioning for your device

Make sure your device supports both the ECM and BCM methods for secondary commissioning. Provide a way to put the device into secondary commissioning via BCM through physical interaction, allowing customers to conveniently reuse the original fixed passcode typically printed on the device or its packaging.

Customers can physically interact with the device to activate secondary commissioning mode. For example, pressing a setup button or power cycling until visual indication appears. Describe these sequences in the DCL to enable Alexa to provide contextual guidance to customers. When you put a device into commissioning mode this way, or when you use the OpenBasicCommissioningWindow command, the device advertises a Commissioning Mode state value of CM=1 which tells Alexa that the device requires the original passcode.

Define a factory reset sequence for your device

A device might appear as "Available" or "Ready to pair," but still fail with errors, such as "Pairing failed" or "This device is already commissioned." Common failure reasons include:

• Hidden "bound" state due to prior commissioning
• BLE advertising failures
• Misconfigured network settings
• Expired commissioning window

To resolve these issues, support a factory reset sequence with some form of physical interaction with your device and describe that sequence in the DCL. Alexa can display the instructions from the DCL so that the customers don't have to search through printed manuals or online support pages for instructions to factory reset the device.

Implement Extended Discovery

For a Matter device already connected to an IP network, such as Wi-Fi or Ethernet, but not in active commissioning mode (CM=0), Extended Discovery allows the device to advertise its presence by using DNS-based Service Discovery (DNS-SD) for longer periods or permanently. DNS-SD enables Alexa to discover the device even when the device isn't actively seeking to be commissioned.

The Matter specification defines Extended Discovery as "commissionable node discovery over IP," and it serves two primary scenarios:

• Initial Commissioning – When a device connects to your local Wi-Fi network through a manufacturer app or cloud connection, such as a smart home skill, but hasn't yet connected to the Alexa Matter fabric, it's not in active commissioning mode (CM=0). The device uses Extended Discovery to advertise its presence, enabling Alexa to discover the device and use the Pairing Hint (PH) to guide the customer in putting the device into commissioning mode for its initial Matter setup.

• Secondary Commissioning – Devices already commissioned to a fabric and operating on the network can use Extended Discovery to continuously advertise themselves. Extended Discovery supports the "Discover My Devices" Alexa customer journey. When a customer opens the Alexa app, Alexa can detect the device and guide the customer through the steps to open a secondary commissioning window for the Alexa Matter fabric.

To enable Extended Discovery, your device firmware must meet the following requirements:

• Connect to the IP network (Wi-Fi or Ethernet)
• Advertise a DNS-SD service of type _matterc._udp on the local network
• Populate the required TXT records in the DNS-SD advertisement

TXT configuration

Matter defines the following TXT record keys for the matterc._udp service advertisement. Alexa reads these keys during Extended Discovery.

Implement extended discovery in firmware

If you use the open source Matter SDK connectedhomeip, you manage Extended Discovery in the DnssdServer and CommissioningWindowManager.

To configure Extended Discovery in the Matter SDK, include the following definitions in src/include/platform/CHIPDeviceConfig.h:

#define CHIP_DEVICE_CONFIG_ENABLE_EXTENDED_DISCOVERY 1 // Enable extended DNS-SD
#define CHIP_DEVICE_CONFIG_ENABLE_COMMISSIONABLE_DEVICE_TYPE 1 // Advertise the device type in DNS-SD messages
#define CHIP_DEVICE_CONFIG_EXTENDED_DISCOVERY_TIMEOUT_SECS -1  // Advertise continuously (no timeout)
#define CHIP_DEVICE_CONFIG_DEVICE_VENDOR_ID 0xFFF1  // Your VID (Example: 65521)
#define CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID 0x007B  // Your PID (Example: 123)

In addition, define the following pairing instructions in the Basic Information cluster or the commissioning data set.

chip::DeviceLayer::ConfigurationMgr().StorePairingHint(257);
chip::DeviceLayer::ConfigurationMgr().StorePairingInstruction("5");

Test all setup journeys across multiple administrators

The Matter specification enables interoperability between devices from different manufacturers, but interoperability in specification doesn't always translate to a great customer experience in practice. Testing your device with every smart home system your customers might use is essential because each system implements its own commissioning flows, fabric management behaviors, and directive handling.

Alexa, in particular, supports multiple setup journeys. Validate your product for each of the following setup experiences:

• Initial commissioning
• Secondary commissioning
• Zero-touch commissioning with Matter Simple Setup
• Automatic commissioning using the Alexa.Commissionable interface for Alexa skill-connected devices

After your product receives Matter certification, apply for Works With Alexa (WWA) certification. The WWA badge assures customers that your product meets a high-quality bar for a fully tested Alexa setup experience.

Examples for common device types

The following examples show how to configure the DCL for common device types across each commissioning flow. Use these as a reference when configuring your own device.

Standard commissioning

The following examples show common device types, their supported commissioning mode options, and the associated DCL configuration.

Smart plug with button

The following example shows a smart plug with a button press to enter commissioning mode.

Smart plug  

CommissioningCustomFlow = 0

CommissioningModeInitialStepsHint = 1  // bit 0 = 1
CommissioningModeInitialStepsInstruction = <empty>
CommissioningModeSecondaryStepsHint = 32772 // bit 15 + bit 2 = 32768 + 4
CommissioningModeSecondaryStepsInstruction = 5
FactoryResetStepsHint = 32768  // bit 15
FactoryResetStepsInstruction = 10 // 10 seconds

Smart bulb with fixed number of power cycles

The following example shows a smart bulb that supports power cycle a specific number of times to enter commissioning mode.

Smart bulb with power cycle N times  

CommissioningCustomFlow = 0

CommissioningModeInitialStepsHint = 1  // bit 0 = 1
CommissioningModeInitialStepsInstruction = <empty>
CommissioningModeSecondaryStepsHint = 1048580  // bit 20 + bit 2 = 1048576 + 4
CommissioningModeSecondaryStepsInstruction = 5,1,10,3 // Formatted as N,X,Y,Z where N=number of cycles, X=minimum seconds ON, Y=time window, Z=blink confirmation
FactoryResetStepsHint = 1048576 // bit 20 = 1048576
FactoryResetStepsInstruction = 8,2,15,3 // Formatted as N,X,Y,Z where N=number of cycles, X=minimum seconds ON, Y=time window, Z=blink confirmation

Smart bulb with power cycle indicator

The following example shows a smart bulb that supports power cycle until a color indicator confirms the device is in commissioning mode.

Smart bulb with power cycle until indicated  

CommissioningCustomFlow = 0

CommissioningModeInitialStepsHint = 1  // bit 0 = 1
CommissioningModeInitialStepsInstruction = <empty>
CommissioningModeSecondaryStepsHint = 4194308  // bit 22 + bit 2 = 4194304 + 4
CommissioningModeSecondaryStepsInstruction = 0,0,0,sequence // Formatted as X,Y,Z,M,N where X=number of seconds in ON state, Y=number of seconds in OFF state, Z=blink confirmation, M=color name of the light blink (sequence for rainbow sequence), N=initial state of device, with default of ON state when not specified
FactoryResetStepsHint = 4194304 // bit 22 = 4194304
FactoryResetStepsInstruction = 1,2,3,blue,OFF // Formatted as X,Y,Z,M,N where X=number of seconds in ON state, Y=number of seconds in OFF state, Z=blink confirmation, M=color name of the light blink (white, red, green, blue, orange, yellow, purple, cool white, warm white), N=initial state of device, with default of ON state when not specified

User-intent commissioning

The following example shows a smart thermostat that supports button press until an indicator confirms the bulb is in commissioning mode.

Smart thermostat  

CommissioningCustomFlow = 1

CommissioningModeInitialStepsHint = 65536  // bit 16 = 65536
CommissioningModeInitialStepsInstruction = blue
CommissioningModeSecondaryStepsHint = 2097156   // bit 21 + bit 2 = 2097152 + 4
CommissioningModeSecondaryStepsInstruction = 10,,0x01 // Formatted as N,Z,A where N=number of seconds, Z=number of blinks, A=CEC keycodes in hexadecimal notation for buttons, separated by ‘|’ (OR) and ‘&’ (AND) as applicable for secondary commissioning
FactoryResetStepsHint = 2097152  // bit 21 = 2097152
FactoryResetStepsInstruction = ,,0x01|0x02 // Formatted as Formatted as N,Z,A where N=number of seconds, Z=number of blinks, A=CEC keycodes in hexadecimal notation for buttons, separated by ‘|’ (OR) and ‘&’ (AND) as applicable for factory reset

Custom commissioning

The following example shows a smart hub that supports commissioning in a Matter administrator app.

Smart hub  

CommissioningCustomFlow = 2
CommissioningCustomFlowUrl = <https://example.com>  // HTTPS or deep-link to manufacturer portal or app

CommissioningModeInitialStepsHint = 2  // bit 1 = 2
CommissioningModeInitialStepsInstruction = <empty>
CommissioningModeSecondaryStepsHint = 4   // bit 2 = 4
CommissioningModeSecondaryStepsInstruction = <empty>
FactoryResetStepsHint = 256  // bit 8 = 256
FactoryResetStepsInstruction = 10 // 10 seconds

Related topics

• Connect Your Device to Alexa with Matter
• Works with Alexa Local Connection Requirements / Matter

Last updated: frontmatter-missing