3. Matter Certification

The Matter Certification denotes compliance to a Connectivity Standards Alliance (CSA) specification for the product and allow the use of Certified Product logos and listing of the product on the Alliance website for verification.

You need to become a member of CSA and request a Vendor ID code from CSA Certification before you apply for a Matter Certification. Then you need to choose an authorized test provider (must be validated for Matter testing) and submit your product for testing. Here are some tips for the Matter Certification Test.

3.1 Introduction to Test Harness (TH)

Test Harness on RaspberryPi is used for Matter Certification Test. You can fetch the TH RaspberryPi image from here and install the image to a micro SD card with the Raspberry Pi Imager.

Test cases can be verified with TH by 4 methods including UI-Automated, UI-SemiAutomated, UI-Manual, and Verification Steps Document. A website UI is used for the first three methods. You can follow the instructions in TH User Guide to use the website UI. For the last method, you should use the chip-tool in path ~/apps of the TH and execute the commands in the Verification Steps Document step by step.

3.2 Matter Factory Partition Binary

Matter factory partition binary files contains the commissionable information (discriminator, salt, iteration count, and spake2+ verifier) 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 label, supported locales, etc.). These informations are used to identify the product and ensure the security of commissioning.

3.2.1 Certification Declaration

A Certification Declaration (CD) is a cryptographic document that allows a Matter device to assert its protocol compliance. It can be generated with following steps. We need to generate the CD which matches the vendor id and product id in DAC and the ones in basic information cluster.

A test CD signed by the test CD signing keys in connectedhomeip SDK repository is required for Matter Certification Test, so the certification_type of it is 1 (provisional). The CD in official products passing the Matter Certification Test is issued by CSA and the certification_type is 2 (official).

  • Generate the Test CD file

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

  • The option --certification-type must be 1 for the Matter Certification Test.

  • The options --vendor_id (vendor_id) should be the Vendor ID (VID) that the vendor receives from CSA, and --product_id (product_id) could be the Product ID (PID) choosed by the vendor. They should be the same as the attributes’ value in basic information cluster.

  • If the product uses the DACs and PAI certifications provided by a trusted third-party certification authority, the VID and PID in DAC are different from the ones in basic information cluster. Then the --dac-origin-vendor-id and --dac-origin-product-id options should be added in the command generating the test CD file.

3.2.2 Certificates and Keys

For Matter Certification Test, vendors should generate their own test Product Attestation Authority (PAA) certificate, Product Attestation Intermediate (PAI) certificate, and Device Attestation Certificate (DAC), but not use the default test PAA certificate in connectedhomeip SDK repository. So you need to generate a PAA certificate, upload it to TestNet following the instruction in DCL Primer, and use it to sign and attest PAI certificates which will be used to sign and attest the DACs. The PAI certificate, DAC, and DAC’s private key should be stored in the product you submit to test.

Here are the steps to generate the certificates and keys using chip-cert and mfg_tool.

3.2.2.1 Generating PAA Certificate

Vendor scoped PAA certificate is suggested for the Matter Certificate Test. It can be generated with the help of blow mentioned steps.

Generate the vendor scoped PAA certificate and key, please make sure to change the --subject-vid (vendor_id) option base on the one that is being used.

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

3.2.2.2 Generating Factory Partition Binary Files

After getting the PAA certificate and key, the factory partition binary files with PAI certificate, DAC, and DAC keys can be generated using mfg_tool.

  • Install the requirements and export the dependent tools path if not done already

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 files

./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 arguments, you can use ./mfg_tool.py --help

The option -n (count) is the number of generated binaries. In the above command, mfg_tool will generate PAI certificate and key and then use them to generate count different DACs and keys. It will use the generated certificates and keys to generate count factory partition binaries with different DACs, discriminators, and setup pincodes. Flash the factory binary to the device’s NVS partition. Then the device will send the vendor’s PAI certificate and DAC to the commissioner during commissioning.

3.2.2.3 Using Vendor’s PAA in Test Harness(TH)

  • Manual Tests (Verified by UI-Manual and Verification Steps Document)

The option --paa-trust-store-path should be added when using chip-tool to pair the device for manual tests.

cd path/to/connnectedhomeip/out/host/
./chip-tool pairing ble-wifi 0x7283 <ssid> <passphrase> <setup-pin-code> <discriminator> --paa-trust-store-path <paa-certificate-path>

Note

  • pincode and discriminator are in the /out/<vid>-<pid>/<UUID>/<uuid>-onb_codes.csv.

  • PAA certificate should be converted to DER format using chip-cert and stored in paa-certificate-path.

  • Automated Tests (Verified by UI-Automated and UI-SemiAutomated)

Here are the steps to upload the PAA certificate and use it for automated tests:

Enable PAA certificates using 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 your PAA certificate to /var/paa-root-certs/

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

Run automated chip-tool tests and verify that the pairing commands are using the --paa-trust-store-path option.

3.3 Matter OTA Image Generation

If the product supports OTA Requestor features of Matter, the test cases of OTA Software Update should be tested. So you need to provide the image for OTA test and also the way to downgrade.

Here are two ways to generate the OTA image.

3.3.1 Using menuconfig option

Enable Generate Matter OTA image in → Component config → CHIP Device Layer → Matter OTA Image, set Device Vendor Id and Device Product Id in → Component config → CHIP Device Layer → Device Identification Options, and edit the PROJECT_VER and the PROJECT_VER_NUMBER in the project’s CMakelists. Build the example and the OTA image will be generated in the build path with the app binary file.

Note

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

3.3.2 Using ota_image_tool script

We should also edit the PROJECT_VER and the PROJECT_VER_NUMBER in the project’s CMakelists when using the script to generate the OTA image.

  • 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

The -vn (version-number) and -vs (version-string) should match the values in the project’s CMakelists.

3.4 PICS files

The PICS files define the Matter features for the product. The authorized test provider will determine the test cases to be tested in Matter Certification Test according to the PICS files submitted.

The PICS Tool website is the tool to open, modify, validate, and save the XML PICS files. The reference XML PICS files include all the reference PICS files and each of the XML files defines the features of one or several clusters on the products.

Open the reference PICS files that include all the clusters of the product, and select the features supported by the product. Clicking the button Validate All, the PICS Tool will validate all the XML files and generate a list of test cases to be tested in Matter Certification Test.

3.5 Route Information Option (RIO) notes

For Wi-Fi products using LwIP, TC-SC-4.9 should be tested in order to verify that the product can receive Router Advertisement (RA) message with RIO and add route table that indicates whether the prefix can be reached by way of the router. It can be tested with a Thread Border Router (BR) which sends RA message periodically and a Thread End Device that is used to verify the Wi-Fi product can reach the Thread network via Thread BR. Some Wi-Fi Routers might have the issue that they cannot forward RA message sent by the Thread BR, so please use a Wi-Fi Router that can forward RA message when you are testing TC-SC-4.9.

Here are the steps to set up the Thread BR and Thread End Device. You should prepare 2 Radio Co-Processors (RCP) to set up the ot-br-posix and ot-cli-posix. The RCP on ESP32-H2 is suggested to be used here. And you can also use other platforms (such as nrf52840, efr32, etc.) as the RCPs.

3.5.1 Setup Thread BR

The otbr-posix can be run on RaspberryPi or Ubuntu machine. Connecting an RCP to the host, the port RCP_PORT1 for it will be /dev/ttyUSBX or /dev/ttyACMX.

  • Build the otbr-posix on the host

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

Then the otbr-posix will be built and a service named otbr-agent will be created on the host. You can disable the service and start the 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 commands:

  • wpan0 is the infra network interface. The network interface named wpan0 will be created on the host as the thread network interface.

  • eth0 is the backbone network interface, which is always the ethernet or wifi network interface on the host, please ensure that the backbone network interface is connected to the AP which the Wi-Fi product is also connected to.

  • RCP_PORT1 is the port of RCP for Thread BR.

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

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

Please record the dataset you get with the last command, it will be used by otcli-posix to join the BR’s network in the next step.

3.5.2 Setup Thread End Device

We use the Posix Thread Command-Line Interface (CLI) as the Thread End Device. Connect another RCP to the host and get the port RCP_PORT2 for it.

  • Build the 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 the ot-cli will be started. Connect the ot-cli to the otbr’s Thread network with the dataset you got in the above step.

> 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 console of ot-cli, 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

Note

177AC531F48BE736-0000000000000190 can be get with command avahi-browse -rt _matter._tcp. 177AC531F48BE736 is the fabric ID and 0000000000000190 is the node ID.

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.

3.6 FW/SDK configuration notes

  • Enable OTA Requestor in → Component config → CHIP Core → System Options

    The option to enable OTA requestor. This option should be enabled if the OTA requestor feature is selected in PICS files.

  • Enable Extended discovery Support in → Component config → CHIP Device Layer → General Options

    This option should be enabled if the PICS option MCORE.DD.EXTENDED_DISCOVERY is selected.

  • Enable Device type in commissionable node discovery in → Component config → CHIP Device Layer → General Options

    This option should be enabled if the PICS option MCORE.SC.EXTENDED_DISCOVERY is selected.

  • LOG_DEFAULT_LEVEL in → Component config → Log output

    It is suggested to set log level to No output for passing the test cases of OnOff, LevelControl, and ColorControl clusters. Here is related issue.

3.7 Appendix FAQs

Here are some issues that you might meet in Matter Certification Test and quick solutions for them.

  • TC-CNET-3.11

    No response on step 7 is expected (Related issue).

    Step 17 might return Timeout for the examples before commit 85abe2c. You can update the esp-matter or cherry-pick commit d7cd5aa to the connectedhomeip repository.

    All the NetworkCommissioning commands are fail-safe required. If the commands fail with a FAILSAFE_REQUIRED status code. You need to send arm-fail-safe command and then send the NetworkCommissioning commands.

  • TC-SU-2.7

    The StateTransition event Applying might be missed because the OTA reboot time is too short. You can cherry-pick the commit from the fixing Pull Request to fix the issue.