espressif/esp-matter
1
0
Fork 0
mirror of https://github.com/espressif/esp-matter.git synced 2026-04-27 19:13:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

update certification process document

Browse Source
This commit is contained in:
liyashuai
2025-12-22 17:38:45 +08:00
parent fb42f3f23d
commit bbbb87dbf2
1 changed files with 370 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/certification.rst
+370 -189
View File
@@ -1,211 +1,397 @@
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.
The Matter Certification denotes compliance to a Connectivity Standards Alliance (CSA) specification for the product and allows the use of Certified Product logos and listing of the product on the Alliance website for verification.
You need to `become a member <https://csa-iot.org/become-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 <https://csa-iot.org/certification/testing-providers/>`__ (must be validated for Matter testing) and submit your product for testing. Here are some tips for the Matter Certification Test.
You need to `become a member <https://csa-iot.org/become-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 <https://csa-iot.org/certification/testing-providers/>`__ (must be validated for Matter testing) and submit your product for testing. Below are the steps for the Matter Certification.
1 Introduction to Test Harness (TH)
-----------------------------------
1 Firmware Development
----------------------
Test Harness on RaspberryPi is used for Matter Certification Test. You can fetch the TH RaspberryPi image from `here <https://groups.csa-iot.org/wg/matter-csg/document/27406>`__ and install the image to a micro SD card with the `Raspberry Pi Imager <https://www.raspberrypi.com/software/>`__.
1.1 Choose an esp-matter branch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 <https://groups.csa-iot.org/wg/matter-csg/document/24838>`__ 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 <https://groups.csa-iot.org/wg/matter-csg/document/26925>`__ step by step.
Use the branch corresponding to the Matter version you plan to certify for firmware development.
2 Matter Factory Partition Binary
---------------------------------
.. list-table:: esp-matter Branches Mapping
:widths: 30 70
:header-rows: 1
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.
* - Matter Version
- esp-matter Branch
* - Matter 1.1
- `release/v1.1 <https://github.com/espressif/esp-matter/tree/release/v1.1>`__
* - Matter 1.2
- `release/v1.2 <https://github.com/espressif/esp-matter/tree/release/v1.2>`__
* - Matter 1.3
- `release/v1.3 <https://github.com/espressif/esp-matter/tree/release/v1.3>`__
* - Matter 1.4
- `release/v1.4 <https://github.com/espressif/esp-matter/tree/release/v1.4>`__
* - Matter 1.4.2
- `release/v1.4.2 <https://github.com/espressif/esp-matter/tree/release/v1.4.2>`__
* - Matter 1.5
- `release/v1.5 <https://github.com/espressif/esp-matter/tree/release/v1.5>`__
2.1 Certification Declaration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.2 Product Attestation Authority (PAA) Generation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 <https://github.com/espressif/connectedhomeip/tree/master/credentials/test/certification-declaration>`__ 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
For Matter certification testing, vendors should generate the test Product Attestation Authority (PAA) certificate, Product Attestation Intermediate (PAI), and Device Attestation Certificate (DAC), rather than using the default test PAA certificate from the connectedhomeip SDK repository. Therefore, you need to generate a PAA certificate and use it to sign the PAI certificate, which is then used to sign the DAC. The PAI certificate, DAC certificate, and DAC private key should be stored in the product under test.
The `chip-cert <https://github.com/project-chip/connectedhomeip/blob/master/src/tools/chip-cert/README.md>`__ tool which is built in `esp-matter setup <https://github.com/espressif/esp-matter/blob/main/docs/en/developing.rst#2-esp-matter-setup>`__ process can be used to generate the PAA certificate and Certification Declaration (CD).
::
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.
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 <https://github.com/espressif/connectedhomeip/tree/master/credentials/test/attestation>`__ SDK repository. So you need to generate a PAA certificate, 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 `esp-matter-mfg-tool`_.
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/
cd $ESP_MATTER_PATH/connectedhomeip/connectedhomeip/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
--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 Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1.3 Certification Declaration (CD) Generation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After getting the PAA certificate and key, the factory partition binary files with PAI certificate, DAC, and DAC keys can be generated using esp-matter-mfg-tool.
- Install the requirements and export the dependent tools path if not done already
Certification Declaration (CD) is a cryptographic document that proves a Matter device complies with protocol standards. For Matter certification testing, users should issue a test CD based on the test CD signing keys in the connectedhomeip SDK repository. This test CD should match the Vendor ID and Product ID in the test DAC, as well as the information in the BasicInformation cluster. During certification testing, the CD's --certification-type should be set to 1 (provisional), while the official CD issued by CSA after passing certification will have --certification-type set to 2 (official).
::
cd path/to/esp_matter
python3 -m pip install -r requirements.txt
export PATH=$PATH:$PWD/connectedhomeip/connectedhomeip/out/host
cd $ESP_MATTER_PATH/connectedhomeip/connectedhomeip/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 $ESP_MATTER_PATH/connectedhomeip/connectedhomeip/credentials/test/certification-declaration/Chip-Test-CD-Signing-Key.pem \
--cert $ESP_MATTER_PATH/connectedhomeip/connectedhomeip/credentials/test/certification-declaration/Chip-Test-CD-Signing-Cert.pem \
--out path/to/test_CD_file
- Generate factory partition binary files
1.4 Factory Bin File Generation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Based on the test PAA and CD generated above, users can use `esp-matter-mfg-tool <https://github.com/espressif/esp-matter-tools?tab=readme-ov-file>`__ to generate the corresponding factory partition bin file. This file contains commissioning information (discriminator, salt, iteration count, and SPAKE2+ verifier), 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.). This information is used to identify the product and ensure secure commissioning.
In the reference command below, the -n option specifies the number of factory bin files to generate. esp-matter-mfg-tool will first generate the PAI certificate and key, then use them to generate the specified number of different DAC certificates and corresponding keys. The tool will use the generated certificates and keys to create multiple factory partition binary files with different DACs, discriminators, and setup pincodes.
::
python3 -m pip install esp-matter-mfg-tool
esp-matter-mfg-tool -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
-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 ``esp-matter-mfg-tool --help``
The option ``-n`` (count) is the number of generated binaries. In the above command, esp-matter-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.
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.
.. only:: esp32 or esp32s3 or esp32c3 or esp32c2 or esp32c6 or esp32c5 or esp32c61
::
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>
.. only:: esp32c6
or
.. only:: esp32h2 or esp32c6 or esp32c5
::
cd path/to/connnectedhomeip/out/host/
./chip-tool pairing ble-thread 0x7283 hex:<thread-dataset> <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:
In Test Harness, you should modify the project configuration to use the vendor's PAA for the DUT that requires a PAA certificate to perform a pairing operation. The flag ``chip_tool_use_paa_certs`` in the ``dut_config`` should be set to ``true`` to configure the Test Harness to use the PAA certificates.
::
"dut_config": {
"discriminator": "3840",
"setup_code": "20202021",
"pairing_mode": "onnetwork",
"chip_tool_timeout": null,
"chip_tool_use_paa_certs": true
}
Make sure to copy your PAA certificates in DER format to the default path ``/var/paa-root-certs/`` on the Raspberry-Pi.
::
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.
2.3 Menuconfig Options
~~~~~~~~~~~~~~~~~~~~~~
Please consult the `factory data providers <./developing.html#factory-data-providers>`__ and adjust the menucofig options accordingly for the certification test.
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.1 Using menuconfig option
1.5 Firmware Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.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
When generating test product firmware, the following configurations can be set in menuconfig to enable accessing the information from the factory bin file generated above:
::
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
CONFIG_ENABLE_ESP32_FACTORY_DATA_PROVIDER=y
CONFIG_ENABLE_ESP32_DEVICE_INSTANCE_INFO_PROVIDER=y
CONFIG_ENABLE_ESP32_DEVICE_INFO_PROVIDER=y
CONFIG_FACTORY_PARTITION_DAC_PROVIDER=y
CONFIG_FACTORY_COMMISSIONABLE_DATA_PROVIDER=y
CONFIG_FACTORY_DEVICE_INSTANCE_INFO_PROVIDER=y
.. note::
1.6 OTA File Generation
~~~~~~~~~~~~~~~~~~~~~~~
The ``-vn`` (version-number) and ``-vs`` (version-string) should match the values in the project's CMakelists.
If the test device supports standard Matter OTA, you need to prepare OTA files for certification testing. (Note: You can add OTA `rollback <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/system/ota.html#app-rollback>`__ functionality to facilitate certification testing)
4 PICS files
------------
In esp-matter projects, change the firmware version number by modifying the PROJECT_VER and PROJECT_VER_NUMBER values in your application's CMakeLists.txt file. When generating OTA files, you need to use firmware with a higher version number than the one currently running on the device.
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.
Use `ota_image_tool.py <https://github.com/project-chip/connectedhomeip/blob/master/src/app/ota_image_tool.py>`__ to generate Matter OTA files, where the ``-vn`` parameter is the software version number, and the ``-vs`` parameter is the software version string:
The `PICS Tool <https://picstool.csa-iot.org/>`__ website is the tool to open, modify, validate, and save the XML PICS files. The `reference XML PICS template files <https://groups.csa-iot.org/wg/matter-csg/document/26122>`__ include all the reference PICS files and each of the XML files defines the features of one or several clusters on the products.
::
A `PICS-generator tool <https://github.com/espressif/connectedhomeip/tree/master/src/tools/PICS-generator>`__ is provided to generate the PICS files with the reference PICS XML template files. The tools will read the supported clusters, attributes, commands, and event from a paired device and generate PICS files for that device. Note that the Base XML file will not be generated with this tool. You still need to modify it in the ``PICS TOOL``.
cd $ESP_MATTER_PATH/connectedhomeip/connectedhomeip/src/app
./ota_image_tool.py create -v <vendor-id> -p <product-id> -vn 2 -vs 1.1 -da sha256 \
/path/to/original_app_bin /path/to/out_ota_bin
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.
1.7 Other Notes
~~~~~~~~~~~~~~~
5 Route Information Option (RIO) notes
--------------------------------------
For products that support the Identify cluster, you need to set the identify type according to the specific product form:
.. list-table:: Presentation Enumeration Values
:widths: 15 20 55 10
:header-rows: 1
* - Value
- Name
- Summary
- Conformance
* - 0x00
- None
- No presentation.
- M
* - 0x01
- LightOutput
- Light output of a lighting product.
- M
* - 0x02
- VisibleIndicator
- Typically a small LED.
- M
* - 0x03
- AudibleBeep
- Audible beep sound.
- M
* - 0x04
- Display
- Presentation will be visible on display screen.
- M
* - 0x05
- Actuator
- Presentation via actuator (e.g., window blind operation or relay).
- M
Implement the corresponding identify command and trigger effect command handlers:
::
esp_err_t app_identification_cb(identification::callback_type_t type, uint16_t endpoint_id, uint8_t effect_id, uint8_t effect_variant, void *priv_data)
{
esp_err_t err = ESP_OK;
ESP_LOGI(TAG, "Identification type: %d, effect_id: %d", type, effect_id);
switch (type) {
case esp_matter::identification::START:
break;
case esp_matter::identification::STOP:
break;
case esp_matter::identification::EFFECT:
switch (effect_id) {
case (int)Identify::EffectIdentifierEnum::kBlink:
break;
case (int)Identify::EffectIdentifierEnum::kBreathe:
break;
case (int)Identify::EffectIdentifierEnum::kOkay:
break;
case (int)Identify::EffectIdentifierEnum::kChannelChange:
break;
case (int)Identify::EffectIdentifierEnum::kFinishEffect:
break;
case (int)Identify::EffectIdentifierEnum::kStopEffect:
break;
default:
break;
}
break;
default:
err = ESP_FAIL;
break;
}
return err;
}
2 Preparation of Files Required for Certification Testing
-----------------------------------------------------------
After preparing the device under test, users need to prepare the following files to submit to the testing organization along with the device.
2.1 PICS File
~~~~~~~~~~~~~~
The PICS file is used to define all Matter features of the product, including endpoints, device types, clusters, attributes, commands, etc. The testing organization will determine the test cases to execute during certification testing based on the PICS file submitted by the user.
The `PICS Tool <https://picstool.csa-iot.org/>`__ website is a tool for opening, modifying, validating, and saving XML format PICS files. `Pics_xml_template_files <https://groups.csa-iot.org/wg/matter-csg/document/40537>`__ contains all PICS file templates, with each XML file defining the feature characteristics of one or more clusters.
The `PICS-generator tool <https://github.com/project-chip/connectedhomeip/tree/master/src/tools/PICS-generator>`__ can generate PICS files based on Pics_xml_template_files. This tool reads the clusters, attributes, commands, features, and events supported by the device under test and outputs a PICS file. Note: This tool cannot automatically generate the Base.xml file, which needs to be opened with PICS TOOL and manually configured. Reference commands are as follows:
::
# WiFi Device:
python3 PICSGenerator.py --pics-template path/to/XML_template --pics-output out_folder --commissioning-method ble-wifi \
--wifi-ssid ssid-name --wifi-passphrase password --passcode setup-pin-code --discriminator discriminator \
--paa-trust-store-path path/to/paa --dm-xml path/to/data_model
# Thread Device:
python3 PICSGenerator.py --pics-template path/to/XML_template --pics-output out_folder --commissioning-method ble-thread \
--thread-dataset-hex thread_dataset --passcode setup-pin-code --discriminator discriminator \
--paa-trust-store-path path/to/paa --dm-xml path/to/data_model
2.2 Test PAA Certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the PAA file generated above.
2.3 OTA File
~~~~~~~~~~~~~
Use the OTA file generated above.
2.4 QR Code for Device Under Test
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the QR code for the device under test.
2.5 Operating Instructions for Device Under Test
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Provide operating instructions for powering the device, performing factory reset, OTA updates, rollback, and other operations.
3 Testing Environment Setup and Testing Methods
-------------------------------------------------
After preparing the device under test, users can perform self-testing using the `Test Harness tool <https://github.com/project-chip/certification-tool>`__.
3.1 Different Matter versions use different `Test Harness tool versions <https://community.csa-iot.org/page/matter-th>`__ for certification.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. list-table:: TH Version Mapping
:widths: 20 35 20
:header-rows: 1
* - Matter Version
- TH Version
- SDK Commit
* - Matter 1.2
- `TH-Fall2023 <https://drive.google.com/file/d/1WTjhc7xbYt18RvpABU3_r47uqOLd7NN1/view?usp=drive_link>`__
- 19771ed
* - Matter 1.3
- v2.10+spring2024
- 11f94c3
* - Matter 1.4
- v2.11+fall2024
- f2e5de7
* - Matter 1.4.1
- v2.12+spring2025
- 91eab26
* - Matter 1.4.2
- v2.13+summer2025
- 1b2b3fd
* - Matter 1.5
- v2.14+fall2025
- ca9d111
3.2 Test Harness Setup
~~~~~~~~~~~~~~~~~~~~~~~
After selecting the Test Harness version according to the table above, refer to the `Matter_TH_User_Guide.pdf <https://groups.csa-iot.org/wg/members-all/document/37522>`__ document for each Matter version setup, for different test harness versions, the Matter_TH_User_Guide.pdf file may be different.
4 Submitting Certification Application Online
---------------------------------------------
After the device under test passes all tests from the testing organization, users can fill out the application on the CSA certification application `website <https://zigbeecertifiedproducts.knack.com/zigbee-certified#home/>`__ . The following explanation uses Add New Product Application as an example.
4.1 Information to Fill In
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. list-table:: Application Parameters Description
:widths: 30 70
:header-rows: 1
* - Parameter Name
- Description
* - Your Company
- Manufacturer name, usually just select from the dropdown list
* - Product Name
- Product name, defined by the manufacturer
* - Product Short Description
- Custom short product description
* - Product Long Description
- Custom long product description
* - Product Link URL
- Optional, product description link
* - Product Image
- Optional, product image
* - Date Product can be Displayed
- Date when the product will be publicly displayed on the CSA website
* - Product Type
- Product certification type, select end device or platform certification. Device manufacturers generally select End Device
* - Completed optional TIS/TRP testing
- Optional, default is No
* - Application Type
- Application protocol type to be certified, select Matter
* - Application Type Version
- Matter protocol version, select Matter 1.1, Matter 1.2, etc. as needed
* - Compliant Platform
- Optional, if applying for certification based on Espressif's certified platform, select ESP32-C-Series or ESP32-H-Series from the dropdown list
* - Firmware Version
- Firmware version number, consistent with software version string in BasicInformation Cluster
* - Hardware Version
- Hardware version number, consistent with hardware version string in BasicInformation Cluster
* - SKU
- Optional, manufacturer-defined, usually the product model
* - Product ID (PID)
- Product ID, consistent with Product ID in BasicInformation Cluster
* - Vendor ID (VID)
- Vendor ID, the ID assigned to the manufacturer by CSA
* - Transport Used
- Check the transport protocols supported by the product. For example, for a WiFi product that supports BLE commissioning, check Wi-Fi and Bluetooth
* - Use 3rd DAC
- Optional, if using a third-party DAC, select Yes and fill in dac_origin_vendor_id and dac_origin_product_id
* - dac_origin_vendor_id
- If using a third-party DAC, fill in the DAC's Vendor ID
* - dac_origin_product_id
- If using a third-party DAC, fill in the DAC's Product ID
* - authorized_paa_list
- Optional, default is empty
* - SoftwareVersion Attribute (integer)
- Software version number, consistent with software version in BasicInformation Cluster
* - Technical Category
- Technical category, select Matter
* - Primary Technical Sub Category
- Primary technical subcategory (device type). If the certified device includes multiple device types, select the primary device type
* - Technical Sub Categories
- Technical subcategories (device types), select all supported device types
* - Parent Functional Categories
- Parent functional category. For end products, select a category that matches the actual functionality
* - Functional Sub Categories
- Functional subcategories. For end products, select one or more categories that match the actual product functionality
* - Submit for processing
- Select submit or save the filled record
* - Declaration of Conformance Document
- Doc document
* - PICS Document
- PICS file in zip format
* - Supplemental PICS Document
- Optional, supplemental PICS file, default is not filled
* - External Certificate
- Can be left blank for Matter certification
* - Transport Attestations
- Transport attestation documents consistent with the transport protocols checked in Transport Used. Can be declared based on Espressif certificates or certificates derived from Espressif certificates
* - Security Attestation
- Security attestation document
4.2 `Declaration of Conformance <https://groups.csa-iot.org/wg/members-all/document/126>`__ (Doc) Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Based on the Doc template provided by Espressif, fill in the relevant content. After the manufacturer signs this document, send it to the certification testing organization. After the testing organization signs it, the manufacturer uploads the signed Doc.
4.3 Transport Attestations (`Bluetooth <https://groups.csa-iot.org/wg/members-all/document/40252>`__, `Wi-Fi <https://groups.csa-iot.org/wg/members-all/document/27435>`__, `Thread <https://groups.csa-iot.org/wg/members-all/document/27434>`__, `Ethernet <https://groups.csa-iot.org/wg/members-all/document/27436>`__) Instructions:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Fill in based on the Transport Attestation template provided by Espressif (version description). Different chip models may have different certificate numbers, which should be verified before filling in. After completion, sign and upload yourself.
4.4 Security Attestation Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Fill in based on the Security Attestation template provided by Espressif. After completion, sign and upload yourself.
4.5 Get the AID and test report
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After completing and submitting the application, you will receive an Application ID (AID). Provide this ID to the certification testing organization, and the testing organization will upload the product test report to the CSA certification body.
4.6 Other steps
~~~~~~~~~~~~~~~~
After completing the application and payment, the CSA certification team will review the application and test report submitted by the manufacturer. If there are issues, the manufacturer will be notified by email. If there are no issues, the certification is passed, and the official CD file will be issued.
5 Filling in Certified Product Information on DCL Website
----------------------------------------------------------
After the product passes certification, manufacturers also need to add Model, Model Version, and Compliance on the `Distributed Compliance Ledger <https://webui.dcl.csa-iot.org/>`__ (DCL). Refer to the documentation: `HowTo - Writing to the DCL.pdf <https://groups.csa-iot.org/wg/members-all/document/27881>`__ .
6 Other notes for some certification test cases
------------------------------------------------
6.1 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 <https://github.com/openthread/ot-br-posix>`__ and `ot-cli-posix <https://github.com/openthread/openthread/tree/main/examples/apps/cli>`__. The `RCP on ESP32-H2 <https://github.com/espressif/esp-idf/tree/master/examples/openthread/ot_rcp>`__ is suggested to be used here. And you can also use other platforms (such as nrf52840, efr32, etc.) as the RCPs.
5.1 Setup Thread BR
~~~~~~~~~~~~~~~~~~~
6.1.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``.
@@ -242,10 +428,10 @@ The otbr-posix is running on the host now. Open another terminal, start console
> 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.
Please record the dataset you get with the last command, it will be used by ot-cli-posix to join the BR's network in the next step.
5.2 Setup Thread End Device
~~~~~~~~~~~~~~~~~~~~~~~~~~~
6.1.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.
@@ -296,8 +482,23 @@ Ping the IP address of the Wi-Fi device.
The ping command should be successful.
6 FW/SDK configuration notes
----------------------------
6.2 TC-CNET-3.11
~~~~~~~~~~~~~~~~~
No response on step 7 is expected (`Related issue <https://github.com/CHIP-Specifications/chip-test-plans/issues/1947>`__).
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.
6.3 TC-RR-1.1
~~~~~~~~~~~~~~
For more application endpoints with group cluster, need more nvs size to store group table, so if the ``TC-RR-1.1`` failed, can try to increase the nvs size. (`Related issue <https://github.com/project-chip/connectedhomeip/issues/32481>`__)
Please note that the minimum NVS size required is 48 KB (0xC000) when using a single endpoint with a group cluster.
7 FW/SDK configuration notes
-----------------------------
- ``Enable OTA Requestor`` in ``→ Component config → CHIP Core → System Options``
@@ -314,23 +515,3 @@ The ping command should be successful.
- ``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 <https://github.com/CHIP-Specifications/chip-test-plans/issues/2332>`__.
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 <https://github.com/CHIP-Specifications/chip-test-plans/issues/1947>`__).
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-RR-1.1``
For more application endpoints with group cluster, need more nvs size to store group table, so if the ``TC-RR-1.1`` failed, can try to increase the nvs size. (`Related issue <https://github.com/project-chip/connectedhomeip/issues/32481>`__`)
Please note that the minimum NVS size required is 48 KB (0xC000) when using a single endpoint with a group cluster.
.. _`esp-matter-mfg-tool`: https://github.com/espressif/esp-matter-tools/tree/main/mfg_tool
.. _`chip-cert`: https://github.com/espressif/connectedhomeip/tree/master/src/tools/chip-cert/README.md