Matter Certification¶

Matter Certification indicates that a product meets the Connectivity Standards Alliance (CSA) specifications and allows for verification by using the Certified Product Logo and listing the product on the Alliance website.

Before applying for Matter Certification, you need to become a member of the CSA and apply for a Supplier ID code from CSA Certification. You will then need to select an authorised test provider (which must be validated for Matter testing) and submit your product for testing. Here are some tips for Matter Certification testing.

1 Introduction to Test Tools (TH)¶

Test Harness on the RaspberryPi is used for Matter certification testing. You can get the TH RaspberryPi image here and use the Raspberry Pi Imager to install the image on a micro SD card.

Test cases can be validated in four ways, UI-Automated, UI-SemiAutomated, UI-Manual, and Verification Steps Document. website UI is used for the first three methods. You can follow the instructions in the TH User's Guide to use the Website UI. For the last method, you should use the Chip Tool in the path of TH and execute the commands in the Verification Steps Document step by step. ~/apps

2 Matter Factory Partition Binary¶

The Matter factory partition binary file contains delegatable information (discriminator, salt, iteration count, and spake2+ validator) and device attestation information (certification declaration (CD), product attestation intermediate (PAI) certificate, device attestation certificate (DAC), and DAC private key), device instance information (vendor ID, vendor name, product ID, product name, etc.), and device information (fixed labels, supported regional settings, etc.). This information is used to identify the product and ensure commissioning security.

2.1 Certification DECLARATIONS¶

A Certification Declaration (CD) is an encrypted document that allows a Matter device to assert its protocol compliance. It can be generated by following these steps. We need to generate a CD that matches the Vendor ID and Product ID in the DAC and the Vendor ID and Product ID in the Basic Information Cluster.

The Matter certification test requires a test CD signed by a test CD signing key in the connectedhomeip SDK repository, so it's 1 (provisional). CDs in official products that pass the Matter certification test are issued by the CSA and are 2 (official). certification_typecertification_type

Generating Test CD Files

cd path/to/esp_matter/connnectedhomeip/connnectedhomeip
out/host/chip-cert gen-cd --format-version 1 --vendor-id 0x131B --product-id 0x1234 \
                          --device-type-id 0x010c --certificate-id CSA00000SWC00000-01 \
                          --security-level 0 --security-info 0 --version-number 1 \
                          --certification-type 1 \
                          --key credentials/test/certification-declaration/Chip-Test-CD-Signing-Key.pem \
                          --cert credentials/test/certification-declaration/Chip-Test-CD-Signing-Cert.pem \
                          --out path/to/test_CD_file

NOTE: For Matter certification testing, this option must be 1. The --certification-type The option (vendor_id) shall be the Vendor ID (VID) that the vendor receives from the CSA and (product_id) shall be the Product ID (PID) that the vendor selects. They shall be the same as the attribute values in the basic information clustering. --vendor_id --product_id If the product uses DAC and PAI authentication provided by a trusted third-party certification body, the VID and PID in the DAC shall be different from the VID and PID in the Basic Information Clustering. The and option should then be added to the command that generates the test CD file. --dac-origin-vendor-id--dac-origin-product-id

2.2 Certificates and Keys¶

For Matter certification testing, vendors should generate their own Test Product Accreditation Authority (PAA) certificates, Product Accreditation Intermediate (PAI) certificates, and Device Accreditation Certificates (DACs), but cannot use the default test PAA certificates in the connectedhomeip SDK repository. Therefore, you need to generate a PAA certificate, upload it to TestNet as described in the DCL Primer, and use it to sign and certify the PAI certificates that will be used to sign and certify the DACs. the private keys for the PAI certificates, the DACs, and the DACs should be stored in the products you submit for testing.

The following are the steps to generate a certificate and key using chip-cert and mfg_tool.

2.2.1 Generating a PAA certificate¶

Vendor wide PAA certificates are recommended for Matter certificate testing. It can be generated with the help of the above steps.

To generate a vendor-wide PAA certificate and key, make sure to change the (vendor_id) option according to the option being used. --subject-vid

cd path/to/connnectedhomeip/out/host/
./chip-cert gen-att-cert --type a --subject-cn "Example PAA CN" --subject-vid 0x131B \
                         --valid-from "2021-06-28 14:23:43" --lifetime 4294967295 \
                         --out-key /path/to/PAA_key \
                         --out /path/to/PAA_certificate

2.2.2 Generating Factory Partition Binary File¶

After obtaining the PAA certificate and key, you can use mfg_tool to generate a factory partition binary file containing the PAI certificate, DAC and DAC key.

Installation requirements and export dependency tool paths (if not already done)

cd path/to/esp_matter/tools/mfg_tool python3 -m pip install -r requirements.txt export PATH=\(PATH:\)PWD//connectedhomeip/connectedhomeip/out/host

Generate Factory Partition Binary File

./mfg_tool.py -n <count> -cn Espressif --paa -c /path/to/PAA_certificate -k /path/to/PAA_key \
              -cd /path/to/CD_file -v 0x131B --vendor_name Espressif -p 0x1234 \
              --product-name Test-light --hw-ver 1 --hw-ver-str v1.0

Note For more information about the parameters, you can use ./mfg_tool.py --help The option (count) is the number of binaries to generate. In the above command, mfg_tool will generate PAI certificates and keys and then use them to generate different DACs and keys. It will use the generated certificates and keys to generate factory partitioned binaries with different DACs, discriminators and setup pin codes. Flush the factory binaries to the NVS partition of the device. The device will then send the vendor's PAI certificate and DAC to the commissioner during commissioning.-ncountcount

2.2.3 Using the vendor's PAA in the test tool (TH)¶

Manual testing (validation via UI manual and validation step documentation)

This option should be added when using chip-tool pairing for manual testing of devices.--paa-trust-store-path

cd path/to/connnectedhomeip/out/host/ ./chip-tool pairing ble-wifi 0x7283 --paa-trust-store-path

Note that pincode and located in /out/-//-onb_codes.csv. discriminator PAA certificates should be converted to DER format and stored in the chip-certpaa-certificate-path

Automated testing (validated by UI-Automated and UI-SemiAutomated)

The following are the steps to upload a PAA certificate and use it for automated testing:

Enable PAA certificates for chip-tool pairing

cd ~/chip-certification-tool
./scripts/stop.sh
./scripts/pi-setup/update-paa-certs.h
rm .env
./scripts/install-default-env.sh
echo "CHIP_TOOL_USE_PAA_CERTS=true" >> .env
./scripts/start.sh

Copy PAA certificates to /var/paa-root-certs/

sudo cp /path/to/PAA_certificate.der /var/paa-root-certs/

Run the Automated Chip Tool test and verify that the pairing command is using this option. --paa-trust-store-path

2.3 Menuconfig Options¶

Consult your plant data provider and adjust the menucofig options accordingly for certification testing.

3 Matter OTA Image Generation¶

If the product supports Matter's OTA requester functionality, test cases for OTA software updates should be tested. Therefore, you will need to provide an image for OTA testing as well as a method for downgrading.

The following are two ways to generate an OTA image.

3.1 Using the menuconfig option¶

Enable in, set, and in and edit and in the project's CMakelists. For the example build, the OTA image will be generated in the build path containing the application binaries. Generate Matter OTA image→ Component config → CHIP Device Layer → Matter OTA ImageDevice Vendor IdDevice Product Id→ Component config → CHIP Device Layer → Device Identification OptionsPROJECT_VERPROJECT_VER_NUMBER

Caution. Must always be incremental. It must be higher than the version number of the firmware to be updated.PROJECT_VER_NUMBER

3.2 Using the ota_image_tool script¶

When using the script to generate the OTA image, we should also edit and .PROJECT_VERPROJECT_VER_NUMBER in the project's CMakelists.

Build the example and generate the OTA image

cd path/to/example
idf.py build
cd path/to/esp_matter/connectedhomeip/connectedhomeip/src/app
./ota_image_tool.py create -v <vendor-id> -p <product-id> -vn 2 -vs v1.1 -da sha256 \
                           /path/to/original_app_bin /path/to/out_ota_bin

Note that (version-number) and (version-string) should match the values in the project's CMakelists. -vn-vs

4 PICS file¶

The PICS file defines the Matter functionality of the product. The Authorised Test Provider will determine the test cases to be tested in the Matter certification test based on the submitted PICS file.

The PICS Tools website is the tool for opening, modifying, validating, and saving XML PICS files. The reference XML PICS file includes all reference PICS files, each XML file defining the functionality of one or more clusters on the product.

Open the Reference PICS file containing all clusters on the product and select the features supported by the product. At the click of a button, the PICS tool validates all XML files and generates a list of test cases to be tested in the Matter certification test. Validate All

5 Routing Information Option (RIO) Comments¶

For Wi-Fi products using LwIP, TC-SC-4.9 should be tested to verify that the product can receive Router Announcement (RA) messages with RIO and add a routing table indicating whether the prefix can be accessed through the router. It can be tested using a Thread Border Router (BR) that periodically sends RA messages and a Thread Termination Device that is used to verify that the Wi-Fi product can reach the Thread network through the Thread BR. Some Wi-Fi routers may have issues with not being able to forward RA messages sent by Thread-BR, so use a Wi-Fi router that can forward RA messages when testing the TC-SC-4.9.

Below are the steps to set up Thread BR and Thread Terminal Unit. You should have 2 Radio Co-Processors (RCPs) to set up ot-br-posix and ot-cli-posix. it is recommended to use the RCP on the ESP32-H2. you can also use other platforms (e.g., nrf52840, efr32, etc.) as the RCP.

5.1 Setting up threads BR¶

otbr-posix can be run on a RaspberryPi or Ubuntu machine. When connecting RCP to a host, its port will be or . RCP_PORT1/dev/ttyUSBX/dev/ttyACMX

Build otbr-posix on hosts

git clone https://github.com/openthread/ot-br-posix
cd ot-br-posix
./script/bootstrap
./script/setup

Then, otbr-posix will be built and a service named otbr-agent will be created on the host. You can disable this service and start otbr-posix manually.

sudo systemctl disable otbr-agent.service
sudo ./build/otbr/src/agent/otbr-agent -I wpan0 -B eth0 -v spinel+hdlc+uart://{RCP_PORT1}

In the above command:

wpan0 is the infrastructure network interface. A network interface named wpan0 will be created on the host as the thread network interface.
eth0 is the backbone interface and is always the Ethernet or WiFi network interface on the host. make sure that the backbone interface is connected to an AP to which the Wi-Fi product is also connected.
RCP_PORT1 is the RCP port for Thread BR.

The otbr-posix is now running on the host. Open another terminal and start the otbr-posix console to form a Thread network and get the dataset.

sudo ot-ctl
> ifconfig up
> thread start
> dataset active -x

Make a note of the dataset you obtained with the last command, otcli-posix will use it in the next step to join the BR's network.

5.2 Setting Up the Threaded Terminal Device¶

We use the Posix Threaded Command Line Interface (CLI) as the threaded terminal device. Connect another RCP to the host and get its port RCP_PORT2.

Building otcli on the host

git clone --recursive https://github.com/openthread/openthread.git
cd openthread/
./script/bootstrap
./bootstrap
./script/cmake-build posix
./build/posix/src/posix/ot-cli 'spinel+hdlc+uart:///dev/{RCP_PORT2}?uart-baudrate=115200' -v

The console for ot-cli will start. Connect ot-cli to otbr's Thread network using the dataset you obtained in the above steps.

> dataset set active <PROVIDE THE DATASET OF THE BR THAT YOU NEED TO JOIN>
> dataset commit active
> ifconfig up
> thread start
> srp client autostart enable

In the ot-cli console, discover the product IP address.

> dns service 177AC531F48BE736-0000000000000190 _matter._tcp.default.service.arpa.
DNS service resolution response for 177AC531F48BE736-0000000000000190 for service _matter._tcp.default.service.arpa.
Port:5540, Priority:0, Weight:0, TTL:6913
Host:72FF282E7739731F.default.service.arpa.
HostAddress:fd11:66:0:0:22ae:27fe:13ac:54df TTL:6915
TXT:[SII=35303030, SAI=333030, T=30] TTL:6913

Attention. 177AC531F48BE736-0000000000000190 can be obtained with the command. It is the structure ID and also the node ID. avahi-browse -rt _matter._tcp177AC531F48BE7360000000000000190

Ping the IP address of the Wi-Fi device.

> ping fd11:66:0:0:22ae:27fe:13ac:54df
16 bytes from fd11:66:0:0:22ae:27fe:13ac:54df : icmp_seq=2 hlim=64 time=14ms
1 packets transmitted, 1 packets received. Packet loss = 0.0%. Round-trip min/avg/max = 14/14.0/14 ms.
Done

The ping command should be successful.

6 Firmware/SDK configuration instructions¶

Enable OTA Requestor in → Component config → CHIP Core → System Options
Option to enable the OTA Requestor. This option should be enabled if the OTA Requestor feature is selected in the PICS file.
Enable Extended discovery Support in → Component config → CHIP Device Layer → General Options Option to enable the OTA requestor functionality if it is selected in the PICS file.MCORE.DD.EXTENDED_DISCOVERY
Enable Device type in commissionable node discovery in → Component config → CHIP Device Layer → General Options This option should be enabled if the PICS option is selected.MCORE.SC. EXTENDED_DISCOVERY
LOG_DEFAULT_LEVEL in → Component config → Log output It is recommended that test cases for OnOff, LevelControl and ColorControl clusters be set to log level. this is a related issue. no output

7 Appendix Frequently Asked Questions¶

Below are some of the problems you may encounter during your Matter certification test and quick solutions to those problems.

TC-CNET-3.11

No response to Step 7 is expected (related issue).

Step 17 may return the example Timeout before commit 85abe2c. you can update esp-matter or cherry-pick commit d7cd5aa to the connectedhomeip repository.

All NetworkCommissioning commands are fail-safe. If the command fails and a status code is displayed. You need to send the command and then send the NetworkCommissioning command.FAILSAFE_REQUIREDarm-fail-safe

TC-SU-2.7.

The StateTransition event may be missed because the OTA restart time is too short. You can fix the problem by picking a commit from the fix pull request. Applying