Commission ACK-based Matter Devices

To commission your device to the Matter network, you use the Matter chip-tool. Commissioning uses the Product Attestation Intermediate (PAI) certificate and private key to establish the authenticity of a new device. The device uses its certification declaration (CD) to prove its compliance with the Matter protocol.

Prerequisites

Before you start, make sure that you have the following items:

Alexa app on a mobile device.
In Settings on your mobile device, allow the Alexa app to access the camera.
Matter-compatible Amazon Echo device. For a list of devices, see Compatible Echo and eero devices.
Connect the Echo device to the same Amazon developer account as the Alexa app.
Connect the Echo device to a 2.4 GHz Wi-Fi network.
Connect the development kit to a USB port on your host machine.

Before you can run commands on the development kit, connect your host machine to the kit. If your host machine is an Ubuntu VM or a Mac, use the screen command in a terminal window. For Windows, use PuTTY.

Complete the following instructions to connect your host machine to the serial console on the development kit. Select the tab for Ubuntu, Windows, or Mac based on your host machine type.

To connect your Ubuntu VM to the development kit

Navigate to VM settings, and then enable USB support.
Depending on your virtualization software, add a USB filter to select the USB device.
Connect a USB cable from your host machine to the debug port on the development kit.
Select the USB device to connect it to the VM.
In an Ubuntu terminal window, at the command prompt, enter the following command to add the user to the dialout group for access to the serial port.

Copied to clipboard.

    sudo usermod -a -G dialout $USER

To identify the serial port, enter the following command.

Copied to clipboard.

    dmesg | grep tty

In a convenient place, such as Notepad on Windows or TextEdit on Mac, paste the port number.
To connect to the development kit with a baud rate of 115200, enter the following command in an Ubuntu VM terminal window. Use the port number that you saved in the previous step.
This command opens a new terminal window on the development kit.

Copied to clipboard.

screen /dev/tty<port number> 115200

To verify your Ubuntu VM connects to the development kit, enter ? in the terminal window.
The command displays the list of available commands on the development kit.

Tip: For the Ubuntu VM to recognize the USB port, you must unplug and reconnect the USB cable every time you reboot the VM.

To connect your Windows host machine to the development kit

Connect a USB cable from your host machine to the debug port on the development kit.
Tip: In the steps that follow, if you aren't sure which port is the development kit, disconnect and then reconnect the USB cable to see the entry that disappears and then reappears.
To identify the port on your host machine to which the development kit connects, from the Start menu, search for and open Device Manager.
In Device Manager, expand Ports (COM & LPT), and then find the USB serial connection. For example, the connection might be Silicon Labs CP210x USB to UART Bridge.
In a convenient place, such as Notepad, paste the port number.
Install PuTTY on your Windows machine.
From the Windows start menu, open PuTTY, and then under Category, select Session.
Under Connection type, select Serial, and then for Serial line, enter the port number you saved in Step 4. For Speed, enter 115200.
To save the configuration, in Saved Sessions, enter Development Kit, and then choose Save.
Next time, to select the saved configuration, next to Development Kit, choose Load. (Or, double-click Development Kit.)
To connect to the development kit with a baud rate of 115200, select Open.
A PuTTY terminal window opens. To see the command prompt, press the Enter key.
To verify your host machine connects to the development kit, enter ? in the terminal window.
The command displays the list of available commands on the development kit.

To connect your Mac host machine to the development kit

Connect a USB cable from your host machine to the debug port on the development kit.
Tip: In the steps that follow, if you aren't sure which port is the development kit, disconnect and then reconnect the USB cable to see the entry that disappears and then reappears.
To identify the port on your host machine to which the development kit connects, open the Finder icon in your Dock.
In Finder, choose Applications > Utilities, open System Information, and then in the sidebar, choose USB.
In a convenient place, such as TextEdit, paste the port number. For example, /dev/tty.usbserial-1420.
To connect to the development kit with a baud rate of 115200, enter the following command in a terminal window. Use the port number that you saved in the previous step.
This command opens a new terminal window on the development kit.

Copied to clipboard.

screen /dev/tty.usbserial-<port number> 115200

To verify your host machine connects to the development kit, enter ? in the terminal window.
The command displays the list of available commands on the development kit.

Create a new device discriminator (Optional)

To test multiple devices, generate a new discriminator for each device so that the Matter commissioner can distinguish between each device advertising to join the network.

To generate a new discriminator

In a terminal window on your development kit, enter the following command to generate a new discriminator.
Set <discrimator-value> to a value between 0000 and 4095, inclusive.

Copied to clipboard.

    mack set-attr discriminator=<discrimator-value>

To apply the discriminator, enter the following command to reboot the development kit.

Copied to clipboard.

    reset reboot

Commission the device with Alexa

Using the Alexa app, you commission the device to the Matter network using Wi-Fi over Bluetooth Low Energy (BLE). Make sure that you sign in to the Alexa app with your Amazon developer account.

To add your ACK-based device to the Alexa app

On your mobile device, open the Alexa app.
On the Alexa app, navigate to the Devices page, and then tap the plus sign (+).
Tap Add Device, and then from list of devices, select Other.
For Which logo is on your device?, tap Matter, and then for Does your device have a Matter logo, tap Yes.
For Is your device powered on?, tap Yes.
Connect your host machine to the development kit.
For details, see Connect your host machine to the development kit.
To get the QR code for the setup, enter the following command in a terminal window.
The command displays a QR code link similar to Sample QR.

Copied to clipboard.

    mack show

Click the link to the QR code.
In the Alexa app, tap Scan QR Code.
For Allow permission, tap Allow for access to the camera, and then scan the QR code with your camera.
If you see This device isn't Matter compatible, that's OK. For Do you want to set up this device anyway?, tap Yes.
For Connect device to Wi-Fi, select your Wi-Fi network, and then tap Next.
For Device setup and ready to use, tap Done.
Alexa indicates that the setup succeeded.
Test the device controls in the Alexa app and by voice.

Commission the device with the CHIP tool (Optional)

You can also commission the device into the Matter network by using the chip-tool as the Matter controller. The commissioning process begins with communication over BLE between the chip-tool and the device. The process ends with confirmation sent from device to chip-tool over Wi-Fi. For more details, see Working with the CHIP Tool.

Tip: To commission the device, make sure your host machine is on the same network as the device.

In the following steps, use these command options with chip-tool.

Option	Description
`<node-id>`	User-defined ID to assign to the device that you're commissioning. Set to a decimal number or a 0x-prefixed hexidecimal number.
`<wifi-ssid>`	Name of the Wi-Fi network to which to connect the device. Set to a string or 0xXXXXXXXX hexidecimal string, encoded as two-digit hexidecimal numbers.
`<wifi-password>`	Credentials for the Wi-Fi network. Set to the Wi-Fi password for your Wi-Fi network, formatted as a string or 0xXXXXXXXX hexidecimal string, encoded as two-digit hexidecimal numbers.
`<setup-pin-code>`	Device-specific 27-bit unsigned integer used to discover and authenticate the device. The setup PIN code is randomly generated and then flashed to the device during manufacturing. You can find this value in the logging terminal window when the device boots up or by running `mack show` on the device. For prototyping, use the test value of `20202021`.
`<device-discriminator>`	Device-specific12-bit unsigned integer used to distinguish between multiple devices advertising on the Matter network. The discriminator is randomly generated and then flashed to the device during manufacturing. You can find this value in the logging terminal when the device boots up or by running `mack show` on the device. For prototyping, use the test value of `3840`.

To commission the device

In a new Ubuntu terminal window, at the command prompt, enter the following command.

Copied to clipboard.

source ./setup.sh

Navigate to the Matter tools directory to find the chip-tool. You defined the directory name when you installed Matter tools.
To commission the device onto the Matter network, enter the following command at the command prompt.

Copied to clipboard.

./chip-tool pairing ble-wifi <node-id> <wifi-ssid> <wifi-password> <setup-pin-code> <device-discriminator>

After several seconds of log output on both the device and host running the chip-tool, you should see the following output from the chip-tool.
```
CHIP:TOOL: Device commissioning completed with success
```
Test the device controls with the chip-tool.

Test with the CHIP tool (Optional)

You can also test device control with the chip-tool. For more details, see Working with the CHIP Tool.

For each invocation, set the <node-id> to 12345, the same value that you used when you commissioned the device with the chip-tool.

The following table shows the chip-tool commands to test lighting features.

Command	Description
`chip-tool onoff on <node-id> 1`	Turn on the light.
`./chip-tool onoff off <node-id> 1`	Turn off the light.
`./chip-tool onoff toggle <node-id> 1`	Toggle the light on and off.
`./chip-tool levelcontrol move-to-level 98 0 0 0 <node-id> 1`	Change the brightness of the light.
`./chip-tool colorcontrol move-to-hue 225 0 0 0 0 <node-id> 1`	Change the hue.
`./chip-tool colorcontrol move-to-saturation 55 0 0 0 <node-id> 1`	Change the saturation.
`./chip-tool colorcontrol move-to-hue-and-saturation 225 55 0 0 0 <node-id> 1`	Change the hue and saturation.
`./chip-tool [onoff\|levelcontrol\|colorcontrol]`	Help for lighting clusters.

Troubleshooting

If you encounter an error during commissioning, try the following tips:

To monitor device logs during commissioning, enter the following command in your VM terminal window: idf.py monitor.
If the Wi-Fi communication fails, make sure that the Wi-Fi router and all clients have IPv6 enabled and confirm that they can ping each other. Also, make sure the firewall setting in the router isn't blocking communication.
If the chip-tool doesn't receive confirmation from the device, the chip-tool reports an error, but the device thinks that commissioning succeeded. To start the commissioning process again, you must do a factory reset on the device, or erase the flash and then re-flash the image to the device. For more details, see Erase flash memory.

Was this page helpful?

Provide feedback

Last updated: frontmatter-missing

Commission ACK-based Matter Devices

Prerequisites

Create a new device discriminator (Optional)

Commission the device with Alexa

Commission the device with the CHIP tool (Optional)

Test with the CHIP tool (Optional)

Troubleshooting

Related topics