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

Merge branch 'controller_docs' into 'main'

Browse Source 
docs: Controller docs improvement

See merge request app-frameworks/esp-matter!1222
This commit is contained in:
Shu Chen
2025-10-31 06:56:58 +00:00
parent a91e6ffc24 e8f8b3bbfe
commit c44a241bd2
13 changed files with 712 additions and 593 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/esp_matter_controller/attestation_store/esp_matter_attestation_trust_store.cpp
+9
View File
@@ -307,6 +307,13 @@ cleanup:
}
#endif // CONFIG_DCL_ATTESTATION_TRUST_STORE
static AttestationTrustStore *s_custom_store = nullptr;
void set_custom_attestation_trust_store(AttestationTrustStore *custom_store)
{
s_custom_store = custom_store;
}
const AttestationTrustStore *get_attestation_trust_store()
{
#if CONFIG_TEST_ATTESTATION_TRUST_STORE
@@ -316,6 +323,8 @@ const AttestationTrustStore *get_attestation_trust_store()
return &spiffs_attestation_trust_store::get_instance();
#elif CONFIG_DCL_ATTESTATION_TRUST_STORE
return &dcl_attestation_trust_store::get_instance();
#elif CONFIG_CUSTOM_ATTESTATION_TRUST_STORE
return s_custom_store;
#endif
}
components/esp_matter_controller/attestation_store/esp_matter_attestation_trust_store.h
+2
View File
@@ -92,6 +92,8 @@ private:
};
#endif // CONFIG_DCL_ATTESTATION_TRUST_STORE
void set_custom_attestation_trust_store(AttestationTrustStore *custom_store);
const AttestationTrustStore *get_attestation_trust_store();
} // namespace Credentials
components/esp_matter_controller/core/esp_matter_controller_console.cpp
+8 -6
View File
@@ -631,12 +631,6 @@ esp_err_t controller_register_commands()
"\tcontroller pairing unpair <nodeid>",
.handler = controller_pairing_handler,
},
{
.name = "group-settings",
.description = "Managing the groups and keysets of the controller.\n"
"\tUsage: controller group-settings <sub-commands>",
.handler = controller_group_settings_handler,
},
{
.name = "icd",
.description = "icd client management.\n"
@@ -654,6 +648,14 @@ esp_err_t controller_register_commands()
},
#endif
#endif // CONFIG_ESP_MATTER_COMMISSIONER_ENABLE
#ifndef CONFIG_ESP_MATTER_ENABLE_MATTER_SERVER
{
.name = "group-settings",
.description = "Managing the groups and keysets of the controller.\n"
"\tUsage: controller group-settings <sub-commands>",
.handler = controller_group_settings_handler,
},
#endif // !CONFIG_ESP_MATTER_ENABLE_MATTER_SERVER
{
.name = "open-commissioning-window",
.description =
docs/en/app_guide.rst
+50 -50
View File
@@ -1,8 +1,8 @@
9. Application User Guide
<<<<<<<<<<<<<<<<<<<<<<<<<
Application User Guide
======================
9.1. Delegate Implementation
============================
1. Delegate Implementation
--------------------------
As per the implementation in the connectedhomeip repository, some of the clusters
require an application defined delegate to consume specific data and actions.
@@ -49,8 +49,8 @@ List of clusters with delegate:
- Energy Preference Cluster.
- Commissioner Control Cluster.
9.1.1 Mode Base Cluster
-----------------------
1.1 Mode Base Cluster
~~~~~~~~~~~~~~~~~~~~~
It is a base cluster for ModeEVSE, ModeOven, ModeRVSRun, ModeRVSClean, ModeDishwasher,
ModeWaterHeater, ModeRefrigerator, ModeLaundryWasher and ModeMicrowaveOven.
@@ -67,48 +67,48 @@ ModeWaterHeater, ModeRefrigerator, ModeLaundryWasher and ModeMicrowaveOven.
, `Device Energy Management Mode`_
, `Water Heater Mode`_
9.1.2 Energy Evse Cluster
-------------------------
1.2 Energy Evse Cluster
~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Energy Evse`_, `Energy Evse Delegate`_
9.1.3 Operational State Cluster
-------------------------------
1.3 Operational State Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Operational State`_, `Operational State Delegate`_
9.1.4 Microwave Oven Control Cluster
------------------------------------
1.4 Microwave Oven Control Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Microwave Oven Control`_, `Microwave Oven Control Delegate`_
9.1.5 Fan Control Cluster
-------------------------
1.5 Fan Control Cluster
~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Fan Control`_, `Fan Control Delegate`_
9.1.6 Resource Monitoring Cluster
---------------------------------
1.6 Resource Monitoring Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Resource Monitoring`_, `Resource Monitoring Delegate`_
9.1.7 Laundry Dryer Controls Cluster
------------------------------------
1.7 Laundry Dryer Controls Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
@@ -116,128 +116,128 @@ ModeWaterHeater, ModeRefrigerator, ModeLaundryWasher and ModeMicrowaveOven.
`Laundry Dryer Controls`_, `Laundry Dryer Controls Delegate`_
9.1.8 Valve Configuration And Control Cluster
---------------------------------------------
1.8 Valve Configuration And Control Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Valve Configuration And Control`_, `Valve Configuration And Control Delegate`_
9.1.9 Device Energy Management Cluster
--------------------------------------
1.9 Device Energy Management Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Device Energy Management`_, `Device Energy Management Delegate`_
9.1.10 Door Lock Cluster
------------------------
1.10 Door Lock Cluster
~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Door Lock`_, None
9.1.11 Boolean State Configuration Cluster
------------------------------------------
1.11 Boolean State Configuration Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Boolean State Configuration`_, None
9.1.12 Time Synchronization Cluster
-----------------------------------
1.12 Time Synchronization Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Time Synchronization`_, `Time Synchronization Delegate`_
9.1.13 Application Basic Cluster
--------------------------------
1.13 Application Basic Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Application Basic`_, None
9.1.14 Power Topology Cluster
-----------------------------
1.14 Power Topology Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Power Topology`_, `Power Topology Delegate`_
9.1.15 Electrical Power Measurement Cluster
-------------------------------------------
1.15 Electrical Power Measurement Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Electrical Power Measurement`_, `Electrical Power Measurement Delegate`_
9.1.16 Laundry Washer Controls Cluster
--------------------------------------
1.16 Laundry Washer Controls Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Laundry Washer Controls`_, `Laundry Washer Controls Delegate`_
9.1.17 Window Covering Cluster
------------------------------
1.17 Window Covering Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Window Covering`_, `Window Covering Delegate`_
9.1.18 Dishwasher Alarm Cluster
-------------------------------
1.18 Dishwasher Alarm Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Dishwasher Alarm`_, `Dishwasher Alarm Delegate`_
9.1.19 Keypad Input Cluster
---------------------------
1.19 Keypad Input Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Keypad Input`_, `Keypad Input Delegate`_
9.1.20 Mode Select Cluster
--------------------------
1.20 Mode Select Cluster
~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Mode Select`_, `Mode Select Delegate`_
9.1.21 Water Heater Management Cluster
--------------------------------------
1.21 Water Heater Management Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Water Heater Management`_, `Water Heater Management Delegate`_
9.1.22 Energy Preference Cluster
--------------------------------
1.22 Energy Preference Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
`Energy Preference`_, `Energy Preference Delegate`_
9.1.23 Commissioner Control Cluster
-----------------------------------
1.23 Commissioner Control Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Delegate Class", "Reference Implementation"
docs/en/certification.rst
+36 -36
View File
@@ -1,24 +1,24 @@
3. Matter Certification
=======================
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 <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.
3.1 Introduction to Test Harness (TH)
-------------------------------------
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 <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/>`__.
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.
3.2 Matter Factory Partition Binary
-----------------------------------
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
@@ -43,15 +43,15 @@ A test CD signed by the test CD signing keys in `connectedhomeip <https://github
- 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~
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`_.
3.2.2.1 Generating PAA Certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
@@ -65,8 +65,8 @@ Generate the vendor scoped PAA certificate and key, please make sure to change t
--out-key /path/to/PAA_key \
--out /path/to/PAA_certificate
3.2.2.2 Generating Factory Partition Binary Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 esp-matter-mfg-tool.
@@ -92,8 +92,8 @@ After getting the PAA certificate and key, the factory partition binary files wi
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.
3.2.2.3 Using Vendor's PAA in Test Harness(TH)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2.2.3 Using Vendor's PAA in Test Harness(TH)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Manual Tests (Verified by UI-Manual and Verification Steps Document)
@@ -146,20 +146,20 @@ Make sure to copy your PAA certificates in DER format to the default path ``/va
Run automated chip-tool tests and verify that the pairing commands are using the ``--paa-trust-store-path`` option.
3.2.3 Menuconfig Options
~~~~~~~~~~~~~~~~~~~~~~~~
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.3 Matter OTA Image Generation
-------------------------------
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
@@ -167,8 +167,8 @@ Enable ``Generate Matter OTA image`` in ``→ Component config → CHIP Device L
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
@@ -186,8 +186,8 @@ We should also edit the ``PROJECT_VER`` and the ``PROJECT_VER_NUMBER`` in the pr
The ``-vn`` (version-number) and ``-vs`` (version-string) should match the values in the project's CMakelists.
3.4 PICS files
--------------
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.
@@ -197,15 +197,15 @@ A `PICS-generator tool <https://github.com/espressif/connectedhomeip/tree/master
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
----------------------------------------
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 <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.
3.5.1 Setup Thread BR
~~~~~~~~~~~~~~~~~~~~~
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``.
@@ -244,8 +244,8 @@ The otbr-posix is running on the host now. Open another terminal, start console
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
@@ -296,8 +296,8 @@ Ping the IP address of the Wi-Fi device.
The ping command should be successful.
3.6 FW/SDK configuration notes
------------------------------
6 FW/SDK configuration notes
----------------------------
- ``Enable OTA Requestor`` in ``→ Component config → CHIP Core → System Options``
@@ -315,8 +315,8 @@ The ping command should be successful.
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>`__.
3.7 Appendix FAQs
-----------------
7 Appendix FAQs
---------------
Here are some issues that you might meet in Matter Certification Test and quick solutions for them.
docs/en/controller.rst
+355
View File
@@ -0,0 +1,355 @@
Matter Controller
=================
This section introduces the ``esp_matter_controller`` component, which can be used to build Matter controller and commissioner on Espressif SoCs.
Several controller/commissioner examples are provided.
- `Basic Commissioner <https://github.com/espressif/esp-matter/tree/main/examples/controller>`__
This example implements a basic Matter commissioner which can be used for commissioning Matter commissionees to its Matter Fabric.
- `Controller with Server Instance <https://github.com/espressif/esp-rainmaker/tree/master/examples/matter/matter_controller>`__
This example implements a Matter controller in RainMaker Matter Fabric. It is also a Matter server so it is commissioned to RainMaker Matter Fabic via standard Matter commissioning flow. And it uses a custom Matter cluster to update its Node Operational Credentials (NOC) and obtain the device list of the Matter Fabric.
- `Client-only Controller <https://github.com/espressif/esp-rainmaker/tree/master/examples/matter/client_only_matter_controller>`__
This example implements a Matter controller in RainMaker Matter Fabric without a Matter server instance. It can be provisioned to a Wi-Fi network via `network_provisioning <https://github.com/espressif/idf-extra-components/tree/master/network_provisioning>`_. And it uses a custom RainMaker service to obtain Administer NOC and device list of the Matter Fabric.
Once you have flashed the controller example onto the device, you can use the `device console <./developing.html#device-console>`__ to commission the device and send commands to the end-device. All of the controller commands begin with the prefix ``matter esp controller``.
1 Controller features
----------------------
The controller is the role of a node that has permissions to enable it to control one or more nodes. It has a complete chain of Node Operational Credentials (NOC) and acts as an administer or an operator in its Matter fabric. And the NodeId of the controller or CASE Authenticated Tag (CAT) of the controller's NOC should in the Access Control List of other end-devices with administer/operator privilege.
The controller should support the following features:
- Send Cluster Invoking commands to other nodes.
- Send Read Attribute/Event commands to other nodes.
- Send Write Attribute commands to other nodes
- Send Subscribe Attribute/Event commands to other nodes.
- Join Matter Groups and manage the Group Key Set.
1.1 Cluster Invoking commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``invoke-cmd`` command is used for sending cluster commands to the end-devices. It utilizes a ``cluster_command`` class to establish the sessions and send the command packets. The class constructor function could accept two callback inputs:
- **Success callback**:
This callback will be called upon the reception of the success response. It could be used to handle the response data for the command that requires a reponse. Now the default success callback will print the response data for GroupKeyManagement, Groups, Scenes, Thermostat, and DoorLock clusters. If you want to handle the response data in your example, you can register your success callback when creating the ``cluster_command`` object.
- **Error callback**:
This callback will be called upon the reception of the failure response or reponse timeout.
^^^^^^^^^^^^^^^^
- Send the cluster command:
::
matter esp controller invoke-cmd <node-id | group-id> <endpoint-id> <cluster-id> <command-id> <command-data>
.. note::
- The ``command-data`` should utilize a JSON object string and the name of each item in this object should be ``\"<TagNumber>:<DataType>\"`` or ``\"<TagName>:<TagNumber>:<DataType>\"``. The TagNumber should be the same as the command parameter ID in Matter SPEC and the supported DataTypes are listed in ``$ESP_MATTER_PATH/components/esp_matter/utils/json_to_tlv.h``
- For the DataType ``bytes``, the value should be a Base64-Encoded string.
Here are some examples of the ``command-data`` format.
- For MoveToLevel command in LevelControl cluster, the ``command-data`` (``{"level": 10, "transitionTime": 0, "optionsMask": 0, "optionsOverride": 0}``) should be:
::
matter esp controller invoke-cmd <node-id> <endpoint-id> 8 0 "{\"0:U8\": 10, \"1:U16\": 0, \"2:U8\": 0, \"3:U8\": 0}"
- For KeySetWrite command in GroupKeyManagement cluster, the ``command-data`` (``{"groupKeySet":{"groupKeySetID": 42, "groupKeySecurityPolicy": 0, "epochKey0": d0d1d2d3d4d5d6d7d8d9dadbdcdddedf, "epochStartTime0": 2220000, "epochKey1": null, "epochStartTime1": null, "epochKey2": null, "epochStartTime2": null}}``) should be:
::
matter esp controller invoke-cmd <node-id> <endpoint-id> 63 0 "{\"0:OBJ\": {\"0:U16\": 42, \"1:U8\": 0, \"2:BYT\": \"0NHS09TV1tfY2drb3N3e3w==\", \"3:U64\": 2220000, \"4:NULL\": null, \"5:NULL\": null, \"6:NULL\": null, \"7:NULL\": null}}"
- For AddGroup command in Groups cluster, the ``command-data`` (``{"groupID": 1, "groupName": "grp1"}``) should be:
::
matter esp controller invoke-cmd <node-id> <endpoint-id> 0x4 0 "{\"0:U16\": 1, \"1:STR\": \"grp1\"}"
1.2 Read commands
~~~~~~~~~~~~~~~~~
The ``read_command`` class is used for sending read commands to other end-devices. Its constructor function could accept two callback inputs:
- **Attribute report callback**:
This callback will be called upon the reception of the attribute report for read-attribute commands.
- **Event report callback**:
This callback will be called upon the reception of the event report for read-event commands.
1.2.1 Read attribute commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``read-attr`` commands are used for sending the commands of reading attributes on end-devices.
- Send the read-attribute command:
::
matter esp controller read-attr <node-id> <endpoint-ids> <cluster-ids> <attribute-ids>
.. note::
- endpoint-ids can represent a single or multiple endpoints, e.g. '0' or '0,1'. And the same applies to cluster-ids, attribute-ids, and event-ids below.
1.2.2 Read event commands
^^^^^^^^^^^^^^^^^^^^^^^^^
The ``read-event`` commands are used for sending the commands of reading events on end-devices.
- Send the read-event command:
::
matter esp controller read-event <node-id> <endpoint-ids> <cluster-ids> <event-ids>
1.3 Write attribute commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``write-attr`` command is used for sending the commands of writing attributes on the end-device.
- Send the write-attribute command:
::
matter esp controller write-attr <node-id> <endpoint-id> <cluster-ids> <attribute-ids> <attribute-value>
.. note::
- ``attribute_value`` should utilize a JSON object string. And the format of this string is the same as the ``command_data`` in `cluster commands <./developing.html#cluster-commands>`__. This JSON object should contain only one item that represents the attribute value.
Here are some examples of the ``attribute_value`` format.
For StartUpOnOff attribute of OnOff Cluster, you should use the following JSON structures as the ``attribute_value`` to represent the StartUpOnOff ``2`` and ``null``:
::
matter esp controller write-attr <node_id> <endpoint_id> 6 0x4003 "{\"0:U8\": 2}"
matter esp controller write-attr <node_id> <endpoint_id> 6 0x4003 "{\"0:NULL\": null}"
For Binding attribute of Binding cluster, you should use the following JSON structure as the ``attribute_value`` to represent the binding list ``[{"node":1, "endpoint":1, "cluster":6}]``:
::
matter esp controller write-attr <node_id> <endpoint_id> 30 0 "{\"0:ARR-OBJ\":[{\"1:U64\":1, \"3:U16\":1, \"4:U32\": 6}]}"
For ACL attribute of AccessControl cluster, you should use the following JSON structure as the ``attribute_value`` to represent the AccessControlList ``[{"privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"privilege": 4, "authMode": 3, "subjects": [1], "targets": null}]``:
::
matter esp controller write-attr <node_id> <endpoint_id> 31 0 "{\"0:ARR-OBJ\":[{\"1:U8\": 5, \"2:U8\": 2, \"3:ARR-U64\": [112233], \"4:NULL\": null}, {\"1:U8\": 4, \"2:U8\": 3, \"3:ARR-U64\": [1], \"4:NULL\": null}]}"
To write multiple attributes in one commands, the ``attribute_value`` should be a JSON array. For example, to write the ACL attribute and Binding attribute above, you should use the following JSON structure as the ``attribute_value``:
::
matter esp controller write-attr <node_id> <endpoint_id1>,<endpoint_id2> 31,30 0,0 "[{\"0:ARR-OBJ\":[{\"1:U8\": 5, \"2:U8\": 2, \"3:ARR-U64\": [112233], \"4:NULL\": null}, {\"1:U8\": 4, \"2:U8\": 3, \"3:ARR-U64\": [1], \"4:NULL\": null}]}, {\"0:ARR-OBJ\":[{\"1:U64\":1, \"3:U16\":1, \"4:U32\": 6}]}]"
For attributes of type uint64_t or int64_t, if the absolute value is greater than (2^53), you should use string to represent number in JSON structure for precision
::
matter esp controller write-attr <node_id> <endpoint_id> 42 0 "{\"0:ARR-OBJ\":[{\"1:U64\": \"9007199254740993\", \"2:U8\": 0}]}"
1.4 Subscribe commands
~~~~~~~~~~~~~~~~~~~~~~
The ``subscribe_command`` class is used for sending subscribe commands to other end-devices. Its constructor function could accept four callback
inputs:
- **Attribute report callback**:
This callback will be invoked upon the reception of the attribute report for subscribe-attribute commands.
- **Event report callback**:
This callback will be invoked upon the reception of the event report for subscribe-event commands.
- **Subscribe done callback**:
This callback will be invoked when the subscription is terminated or shutdown.
- **Subscribe failure callback**:
This callback will be invoked upon the failure of establishing CASE session.
1.4.1 Subscribe attribute commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``subs-attr`` commands are used for sending the commands of subscribing attributes on end-devices.
- Send the subscribe-attribute command:
::
matter esp controller subs-attr <node-id> <endpoint-ids> <cluster-ids> <attribute-ids> <min-interval> <max-interval>
1.4.2 Subscribe event commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``subs-event`` commands are used for sending the commands of subscribing events on end-devices.
- Send the subscribe-event command:
::
matter esp controller subs-event <node-id> <endpoint-ids> <cluster-ids> <event-ids> <min-interval> <max-interval>
1.5 Group settings commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``group-settings`` commands are used to set group information of the controller. If the controller wants to send multicast commands to end-devices, it should be in the same group as the end-devices.
- Set group information of the controller:
::
matter esp controller group-settings show-groups
matter esp controller group-settings add-group <group-id> <group-name>
matter esp controller group-settings remove-group <group-id>
matter esp controller group-settings show-keysets
matter esp controller group-settings add-keyset <ketset-id> <policy> <validity-time> <epoch-key-oct-str>
matter esp controller group-settings remove-keyset <ketset-id>
matter esp controller group-settings bind-keyset <group-id> <ketset-id>
matter esp controller group-settings unbind-keyset <group-id> <ketset-id>
2 Commissioner features
-----------------------
The commissioner is an enhanced controller that can perform commissioning which is the sequence of operations to bring a Node into a Fabric by assigning an Operational Node ID and Node Operational credentials.
The commissioner should support the additional features:
- Obtain the onboarding payload (QR code or manual code) and use it to starting commissioning.
- Verify the commissionee's Device Attestation Certificate (DAC) chain and Certificate Declaration (CD) during commissioning.
- Receive the Certificate Signing Request (CSR) and issue NOC for it during commissioning.
2.1 Pairing commands
~~~~~~~~~~~~~~~~~~~~
The ``pairing`` commands are used for commissioning end-devices and are available when the ``Enable matter commissioner`` option is enabled. Here are three standard pairing methods:
- **Onnetwork pairing:** Prior to executing this commissioning method, it is necessary to connect both the controller and the end-device to the same network and ensure that the commissioning window of the end-device is open. To complete this process, you can use the command ``matter esp wifi connect``. After the devices are connected, the pairing process can be initiated.
::
matter esp wifi connect <ssid> <password>
matter esp controller pairing onnetwork <node_id> <setup_passcode>
- **Ble-wifi pairing:** This pairing method is supported for ESP32S3. Before you execute this commissioning method, connect the controller to the Wi-Fi network and ensure that the end-device is in commissioning mode. You can use the command ``matter esp wifi connect`` to connect the controller to your wifi network. Then we can start the pairing.
::
matter esp wifi connect <ssid> <password>
matter esp controller pairing ble-wifi <node_id> <ssid> <password> <pincode> <discriminator>
- **Ble-thread pairing:** This pairing method is supported for ESP32S3. Before you execute this commissioning method, connect the controller to the Wi-Fi network in which there is a Thread Border Router (BR). And please ensure that the end-device is in commissioning mode. You can use the command ``matter esp wifi connect`` to connect the controller to your Wi-Fi network. Get the dataset tlvs of the Thread network of the Thread BR. Then we can start the pairing.
::
matter esp wifi connect <ssid> <password>
matter esp controller pairing ble-thread <node_id> <dataset_tlvs> <pincode> <discriminator>
- **Matter payload based pairing:** This method is similar to the previously mentioned pairing methods, but instead of accepting a PIN code and discriminator, it uses a Matter setup payload as input. The setup payload is parsed to extract the necessary information, which then initiates the pairing process.
For the ``code`` pairing method, commissioner tries to discover the end-device only on the IP network. However, when using ``code-wifi``, ``code-thread``, or ``code-wifi-thread``, and if ``CONFIG_ENABLE_ESP32_BLE_CONTROLLER`` is enabled, controller tries to discover the end-device on both the IP and BLE networks.
Below are supported commands:
::
matter esp controller pairing code <node_id> <setup_payload>
::
matter esp controller pairing code-wifi <node_id> <ssid> <passphrase> <setup_payload>
::
matter esp controller pairing code-thread <node_id> <operationalDataset> <setup_payload>
::
matter esp controller pairing code-wifi-thread <node_id> <ssid> <passphrase> <operationalDataset> <setup_payload>
2.2 Attestation Verification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.2.1 Attestation Trust Storage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The commissioner offers four options for the Attestation Trust Storage which is used to store and utilize the PAA certificates for the Device Attestation verification. This feature is available when the ``Enable matter commissioner`` option is enabled in menuconfig. You can modify this setting in menuconfig ``Components`` -> ``ESP Matter Controller`` -> ``Attestation Trust Store``.
- ``Attestation Trust Store - Test``
Use two hardcoded PAA certificates (Chip-Test-PAA-FFF1-Cert&Chip-Test-PAA-NoVID-Cert) in the firmware.
- ``Attestation Trust Store - Spiffs``
Read the PAA root certificates from the spiffs partition. The PAA der files should be placed in ``paa_cert`` directory so that they can be flashed into the spiffs partition of the controller.
- ``Attestation Trust Store - DCL``
Fetch the PAA root certificates from the DCL MainNet/TestNet. The commissioner will fetch PAA certificates from DCL during commissioning and use the fetched PAA certificates to verifying the DAC chains of commissioned end-devices.
- ``Attestation Trust Store - Custom``
Use the custom Attestation Trust Storage. You should call ``set_custom_attestation_trust_store()`` to set the custom Attestation Trust Store before setting up the commissioner.
2.3 NOC Issuer
~~~~~~~~~~~~~~
In the `esp_matter commissioner <https://github.com/espressif/esp-matter/tree/main/examples/controller>`_ example, the commissioner offers two options to issue the NOC chains for itself and other operational nodes.
- ``Operational Credentials Issuer - Test``
Generate Root CA Certificate (RCAC) and RCAC Private Key and issue a Commissioner NOC when setting up the commissioner, and then issue NOCs for other nodes during commissioning with the generated RCAC Certificate and Key.
- ``Operational Credentials Issuer - Custom``
Obtain the NOC chains for the commissioner and other operational nodes with a custom issuer class. The NOC chains can be issued from the cloud with the custom issuer.
3 Production Considerations
---------------------------
3.1 Controller Production
~~~~~~~~~~~~~~~~~~~~~~~~~
The Matter Controller should always work with a commissioner which is typically a mobile application that assists with its setup and onboarding.
3.1.1 Access Control Privilege
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The controller should possess either Administrator or Operator privileges in order to access other nodes within the same Matter fabric. A common approach is to issue a NOC containing an Administrator/Operator CAT for the controller, and to initialize the Access Control List (ACL) of Matter end devices with the corresponding CATs.
3.1.2 Controller NOC
^^^^^^^^^^^^^^^^^^^^
To access other nodes within a Matter fabric, the controller must be part of the same fabric. Therefore, there must be a mechanism to deliver the NOC chain to the controller. Upon receiving the chain, the controller can add or update it in its Fabric Table.
3.1.3 Device List
^^^^^^^^^^^^^^^^^
The controller should be able to retrieve the list of devices within the same Matter fabric. This list should include the Node IDs and device type information of each node, enabling the controller to determine how to interact with and control the respective Matter end devices.
3.2 Commissioner Production
~~~~~~~~~~~~~~~~~~~~~~~~~~~
3.2.1 Onboarding Payload
^^^^^^^^^^^^^^^^^^^^^^^^
The Matter Commissioner should be able to get the QR Code or Manual Code of Matter end-device so that it can start commissioning that device.
3.2.2 Device Attestation Verification
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Matter Commissioner should be able to process the following DA verification during commissioning:
- Verify that the DAC chain of the commissionee is issued by a trusted Product Attestation Authority (PAA) Certificate in the Connectivity Standards Alliance (CSA) ’s Distributed Compliance Ledger(DCL).
- Verify that the CD of the commissionee is issued by CSA.
- Verify that the DAC or PAI Certificate is not revoked in CSA's DCL.
3.2.3 NOC Issuer
^^^^^^^^^^^^^^^^
The Matter Commissioner should be able to install NOC chain on the commissionee during commissioning. The custom NOC issuer should be implemented so that the Matter Commissioner could generate or otherwise obtain NOC chain after receiving CSRResponse command from the commissionee. In production, the NOC issuer is typically a cloud service: the Commissioner retrieves the CSR from the commissionee and forwards it to the cloud service for signing. The local RCAC is intended for testing only and must not be used in production.
3.2.4 Access Control List Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Matter Commissioner should configure the ACL on the Commissionee over PASE session to grant Administer/Operator privilege over CASE authentication type for all the controllers in the Matter fabric.
docs/en/developing.rst
+134 -389
View File
@@ -1,16 +1,16 @@
2. Developing with the SDK
==========================
Developing with the SDK
=======================
Please refer the :project_file:`Release Notes <RELEASE_NOTES.md>` to know more about
the releases
2.1 ESP-IDF Setup
---------------------
1 ESP-IDF Setup
-------------------
This section talks about setting up ESP-IDF.
2.1.1 Host Setup
~~~~~~~~~~~~~~~~
1.1 Host Setup
~~~~~~~~~~~~~~
You should install drivers and support packages for your development
host. Linux and Mac OS-X are the supported development hosts in Matter, the recommended host versions:
@@ -21,8 +21,8 @@ host. Linux and Mac OS-X are the supported development hosts in Matter, the reco
Additionally, we also support developing on Windows Host using WSL.
2.1.1.1 Windows 10
^^^^^^^^^^^^^^^^^^
1.1.1 Windows 10
^^^^^^^^^^^^^^^^
Development on Windows is supported using Windows Subsystem for Linux (WSL). Please follow the below instructions to set up host.
@@ -45,8 +45,8 @@ For using VSCode for development, please check `Developing in WSL <https://code.
Using CHIP-tool in WSL <using_chip_tool>
2.1.2 Getting the Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.2 Getting the Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Prerequisites for ESP-IDF:
@@ -83,8 +83,8 @@ The Prerequisites for ESP-IDF:
./install.sh
cd ..
2.1.3 Configuring the Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.3 Configuring the Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This should be done each time a new terminal is opened
@@ -93,19 +93,19 @@ This should be done each time a new terminal is opened
cd esp-idf; source ./export.sh; cd ..
2.2 ESP Matter Setup
--------------------
2 ESP Matter Setup
------------------
There are two options to setup esp-matter, you can select one according to demand:
- ESP matter repository, including esp-matter SDK and tools (e.g., CHIP-tool, CHIP-cert, ZAP, ...).
- ESP matter component, including esp-matter SDK.
2.2.1 ESP-Matter Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.1 ESP-Matter Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~
2.2.1.1 Getting the Repository
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2.1.1 Getting the Repository
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Prerequisites for Matter:
@@ -185,8 +185,8 @@ To clone the esp-matter repository with all the submodules, use the following co
It's probably caused by some network connectivity issue, a VPN is required for most of the cases.
2.2.1.2 Configuring the Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2.1.2 Configuring the Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This should be done each time a new terminal is opened
@@ -208,8 +208,8 @@ Ccache caches the previous compilations and speeds up recompilation in subsequen
Above can also be added to your shell’s profile file (.profile, .bashrc, .zprofile, etc.)
to enable ccache every time you open a new terminal.
2.2.2 ESP Matter Component (experimental)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.2 ESP Matter Component (experimental)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can check the component in `Espressif Component Registry <https://components.espressif.com/components/espressif/esp_matter>`__.
@@ -229,8 +229,8 @@ An example with esp_matter component is offered:
Use ``compote version`` to show the version. Use ``pip install 'idf-component-manager~=1.4.0'``
or ``pip install 'idf-component-manager~=2.0.0'`` to install.
2.2.3 Building Applications
~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.3 Building Applications
~~~~~~~~~~~~~~~~~~~~~~~~~
- :project_file:`Light <examples/light/README.md>`
- :project_file:`Light Switch <examples/light_switch/README.md>`
@@ -238,8 +238,8 @@ An example with esp_matter component is offered:
- :project_file:`Zigbee Bridge <examples/bridge_apps/zigbee_bridge/README.md>`
- :project_file:`BLE Mesh Bridge <examples/bridge_apps/blemesh_bridge/README.md>`
2.2.4 Flashing the Firmware
~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.4 Flashing the Firmware
~~~~~~~~~~~~~~~~~~~~~~~~~
Choose IDF target.
@@ -354,8 +354,8 @@ Choose IDF target.
pip install -r $IDF_PATH/requirements.txt
2.3 Commissioning and Control
-----------------------------
3 Commissioning and Control
---------------------------
There are a few implementations of Matter commissioners present in the `connectedhomeip`_ repository.
@@ -368,8 +368,8 @@ Espressif's ESP RainMaker iOS and Android applications support commissioning and
- `ESP-RainMaker iOS App`_
2.3.1 Test Setup (CHIP Tool)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3.1 Test Setup (CHIP Tool)
~~~~~~~~~~~~~~~~~~~~~~~~~~
A host-based chip-tool can be used as a commissioner to commission and control a Matter device. During the previous ``install.sh`` step, the ``chip-tool`` is generated under the folder:
@@ -383,8 +383,8 @@ A host-based chip-tool can be used as a commissioner to commission and control a
Instructions to download the profile can be found in the `profile installation section`_
2.3.1.1 Commissioning
^^^^^^^^^^^^^^^^^^^^^
3.1.1 Commissioning
^^^^^^^^^^^^^^^^^^^
Use ``chip-tool`` in interactive mode to commission the device:
@@ -491,8 +491,8 @@ If you want to use different values for commissioning the device, please use the
`esp-matter-mfg-tool`_ to generate the factory partition which has to be flashed on the device.
It also generates the new pairing code and QR code image using which you can commission the device.
2.3.1.2 Post Commissioning Setup
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3.1.2 Post Commissioning Setup
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The device would need additional configuration depending on the example,
for it to work. Check the "Post Commissioning Setup" section in examples for more information.
@@ -503,8 +503,8 @@ for it to work. Check the "Post Commissioning Setup" section in examples for mor
- :project_file:`Zigbee Bridge <examples/bridge_apps/zigbee_bridge/README.md>`
- :project_file:`BLE Mesh Bridge <examples/bridge_apps/blemesh_bridge/README.md>`
2.3.1.3 Cluster Control
^^^^^^^^^^^^^^^^^^^^^^^
3.1.3 Cluster Control
^^^^^^^^^^^^^^^^^^^^^
Use the cluster commands to control the attributes.
@@ -532,8 +532,8 @@ chip-tool when used in interactive mode uses CASE resumption as against establis
For more details about the commands, please check `chip-tool usage guide`_
2.4 Device console
------------------
4 Device console
----------------
The console on the device can be used to run commands for testing. It is configurable through menuconfig and enabled by default in the firmware. Here are some useful commands:
@@ -631,14 +631,14 @@ Additional Matter specific commands:
matter esp bridge add <parent_endpoint_id> <device_type_id>
2.5 Developing your Product
---------------------------
5 Developing your Product
-------------------------
Understanding the structure before actually modifying and customising
the device is helpful.
2.5.1 Building a Color Temperature Lightbulb
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5.1 Building a Color Temperature Lightbulb
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A device is represented in Matter in terms of its data model. As a first
step of building your product, you will have to define the data model for your
@@ -647,8 +647,8 @@ can use. Please refer to the
`Espressif Matter Blog <https://blog.espressif.com/matter-clusters-attributes-commands-82b8ec1640a0>`__
for clarity on the terms like endpoints, clusters, etc. that are used in this section.
2.5.1.1 Data Model
^^^^^^^^^^^^^^^^^^
5.1.1 Data Model
^^^^^^^^^^^^^^^^
- Typically, the data model is defined in the example's *app_main.cpp*.
First off we start by creating a Matter node, which is the root of
@@ -675,8 +675,8 @@ for clarity on the terms like endpoints, clusters, etc. that are used in this se
endpoints can be created on the same node. Check the following
sections for more info.
2.5.1.2 Attribute Callback
^^^^^^^^^^^^^^^^^^^^^^^^^^
5.1.2 Attribute Callback
^^^^^^^^^^^^^^^^^^^^^^^^
- Whenever a Matter client makes changes to the device, they end up
updating the attributes in the data model.
@@ -703,8 +703,8 @@ for clarity on the terms like endpoints, clusters, etc. that are used in this se
return err;
}
2.5.1.3 Identify Callback
^^^^^^^^^^^^^^^^^^^^^^^^^^
5.1.3 Identify Callback
^^^^^^^^^^^^^^^^^^^^^^^^
- This callback is invoked when clients interact with the Identify Cluster. In the callback implementation,
an endpoint can identify itself. (e.g., by flashing an LED or light).
@@ -717,8 +717,8 @@ for clarity on the terms like endpoints, clusters, etc. that are used in this se
return ESP_OK;
}
2.5.1.4 Device Drivers
^^^^^^^^^^^^^^^^^^^^^^
5.1.4 Device Drivers
^^^^^^^^^^^^^^^^^^^^
- The drivers, depending on the device, are typically initialized and
updated in the example's *app_driver.cpp*.
@@ -777,14 +777,14 @@ for clarity on the terms like endpoints, clusters, etc. that are used in this se
}
2.5.2 Defining your own data model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5.2 Defining your own data model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section demonstrates creating standard endpoints, clusters, attributes,
and commands that are defined in the Matter specification
2.5.2.1 Endpoints
^^^^^^^^^^^^^^^^^
5.2.1 Endpoints
^^^^^^^^^^^^^^^
The device can be customized by editing the endpoint/device_type
creating in the *app_main.cpp* of the example. Examples:
@@ -834,8 +834,8 @@ creating in the *app_main.cpp* of the example. Examples:
Once a ``config_t`` instance has been instantiated, these three values cannot be modified.
2.5.2.2 Clusters
^^^^^^^^^^^^^^^^
5.2.2 Clusters
^^^^^^^^^^^^^^
Additional clusters can also be added to an endpoint. Examples:
@@ -877,8 +877,8 @@ Additional clusters can also be added to an endpoint. Examples:
maximum pressure, maximum speed and maximum flow values. If they aren't set, they will be set to null by default.
Once a ``config_t`` instance has been instantiated, these three values cannot be modified.
2.5.2.3 Attributes and Commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5.2.3 Attributes and Commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Additional attributes and commands can also be added to a cluster.
Examples:
@@ -896,8 +896,14 @@ Examples:
command_t *command = on_off::command::create_toggle(cluster);
2.5.2.4 Features
^^^^^^^^^^^^^^^^^^
- command: move_to_level:
::
command_t *command = level_control::command::create_move_to_level(cluster);
5.2.4 Features
^^^^^^^^^^^^^^
Mandatory features for a device type or endpoint can be configured at endpoint level.
- feature: lighting: On/Off cluster:
@@ -929,15 +935,15 @@ Optional features which are applicable to a cluster can also be added.
cluster_t* cluster = cluster::get(endpoint, Descriptor::Id);
descriptor::feature::tag_list::add(cluster);
2.5.3 Adding custom data model fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5.3 Adding custom data model fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section demonstrates creating custom endpoints, clusters, attributes,
and commands that are not defined in the Matter specification and can be
specific to the vendor.
2.5.3.1 Endpoints
^^^^^^^^^^^^^^^^^
5.3.1 Endpoints
^^^^^^^^^^^^^^^
Non-Standard endpoint can be created, without any clusters.
@@ -947,8 +953,8 @@ Non-Standard endpoint can be created, without any clusters.
endpoint_t *endpoint = endpoint::create(node, ENDPOINT_FLAG_NONE);
2.5.3.2 Clusters
^^^^^^^^^^^^^^^^
5.3.2 Clusters
^^^^^^^^^^^^^^
Non-Standard/Custom clusters can also be created:
@@ -959,8 +965,8 @@ Non-Standard/Custom clusters can also be created:
uint32_t custom_cluster_id = 0x131bfc00;
cluster_t *cluster = cluster::create(endpoint, custom_cluster_id, CLUSTER_FLAG_SERVER);
2.5.3.3 Attributes and Commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5.3.3 Attributes and Commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Non-Standard/Custom attributes can also be created on any cluster:
@@ -986,12 +992,12 @@ Non-Standard/Custom attributes can also be created on any cluster:
uint32_t custom_command_id = 0x0;
command_t *command = command::create(cluster, custom_command_id, COMMAND_FLAG_ACCEPTED, command_callback);
2.5.4 Advanced Setup
~~~~~~~~~~~~~~~~~~~~
5.4 Advanced Setup
~~~~~~~~~~~~~~~~~~
This section explains adding external platforms for Matter. This step is **optional** for most devices. Espressif's SDK for Matter provides support for overriding the default platform layer, so the BLE and Wi-Fi implementations can be customized. Here are the required steps for adding an external platform layer.
2.5.4.1 Creating the external platform directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5.4.1 Creating the external platform directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create a directory ``platform/${NEW_PLATFORM_NAME}`` in your codebase.
You can typically copy
@@ -1001,8 +1007,8 @@ as a start. Note that the new platform name should be something other than
directory must be under ``platform`` folder to meet the Matter include
path conventions.
2.5.4.2 Modifying the BUILD.gn target
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5.4.2 Modifying the BUILD.gn target
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There is an example :project_file:`BUILD.gn <examples/common/external_platform/BUILD.gn>` file for
the ``ESP32_custom`` example platform. It simply compiles the ESP32
@@ -1013,8 +1019,8 @@ platform in Matter without any modifications.
- Multiple build configs must be exported to the build system. See the
``buildconfig_header`` section in the file for the required definitions.
2.5.4.3 Editing Kconfigs
^^^^^^^^^^^^^^^^^^^^^^^^
5.4.3 Editing Kconfigs
^^^^^^^^^^^^^^^^^^^^^^
- Enable ``CONFIG_CHIP_ENABLE_EXTERNAL_PLATFORM``.
- Set ``CONFIG_CHIP_EXTERNAL_PLATFORM_DIR`` to the relative path from
@@ -1034,8 +1040,8 @@ platform in Matter without any modifications.
- If your external platform does not support the *connectedhomeip/connectedhomeip/src/lib/shell/*
provided in the Matter shell library, then disable ``CONFIG_ENABLE_CHIP_SHELL``.
2.5.4.4 Example Usage
^^^^^^^^^^^^^^^^^^^^^
5.4.4 Example Usage
^^^^^^^^^^^^^^^^^^^
As an example, you can build *light* example on ``ESP32_custom`` platform with following steps:
@@ -1048,11 +1054,11 @@ As an example, you can build *light* example on ``ESP32_custom`` platform with f
cp sdkconfig.defaults.ext_plat sdkconfig.defaults
idf.py build
2.6 Factory Data Providers
--------------------------
6 Factory Data Providers
------------------------
2.6.1 Providers Introduction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6.1 Providers Introduction
~~~~~~~~~~~~~~~~~~~~~~~~~~
There are four factory data providers, each with its own implementation, that need to be configured. These providers supply the device with necessary factory data, which is then read by the device according to their respective implementations.
- ``Commissionable Data Provider``
@@ -1071,8 +1077,8 @@ There are four factory data providers, each with its own implementation, that ne
This particular provider is responsible for retrieving device information, which includes fixed-labels, user-labels, supported-locales, and supported-calendar-types.
2.6.2 Configuration Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~
6.2 Configuration Options
~~~~~~~~~~~~~~~~~~~~~~~~~
Different implementations of the four providers can be chosen in meuconfig:
@@ -1144,16 +1150,16 @@ Different implementations of the four providers can be chosen in meuconfig:
Information. ``esp_matter::set_custom_device_info_provider`` should be called before ``esp_matter::start()``
to set the custom provider.
2.6.3 Custom Providers
~~~~~~~~~~~~~~~~~~~~~~
6.3 Custom Providers
~~~~~~~~~~~~~~~~~~~~
In order to use custom providers, you need to define implementations of the four base classes of the providers and override the functions within them. And the custom providers should be set before ``esp_matter::start()`` is called.
2.7 Using esp_secure_cert partition
-----------------------------------
7 Using esp_secure_cert partition
---------------------------------
2.7.1 Configuration Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~
7.1 Configuration Options
~~~~~~~~~~~~~~~~~~~~~~~~~
Build the firmware with below configuration options
@@ -1180,8 +1186,8 @@ Build the firmware with below configuration options
you need to enable the ``CONFIG_ESP_SECURE_CERT_DS_PERIPHERAL=y`` option.
2.7.2 Certification Declaration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7.2 Certification Declaration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you do not have an certification declaration file then you can generate the test CD with the help of below mentioned steps.
We need to generate the new CD because it SHALL match the VID, PID in DAC and the ones reported by basic cluster.
@@ -1206,8 +1212,8 @@ For more info about the arguments, please check `chip-cert's gen-cd command`_ in
-O TEST_CD_FFF1_8001.der
2.7.3 Factory Partition
~~~~~~~~~~~~~~~~~~~~~~~
7.3 Factory Partition
~~~~~~~~~~~~~~~~~~~~~
Factory partition contains basic information like VID, PID, etc.
@@ -1251,8 +1257,8 @@ Factory partition binary will be generated at the below path. Please check for <
[2022-12-02 11:18:12,381] [ INFO] - Generated output files at: out/fff1_8001/e17c95e1-521e-4979-b90b-04da648e21bb
2.7.4 Flashing firmware, secure cert and factory partition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7.4 Flashing firmware, secure cert and factory partition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Flashing secure cert partition. Please check partition table for ``esp_secure_cert`` partition address.
@@ -1279,8 +1285,8 @@ Flash application
idf.py flash
2.7.5 Test commissioning using chip-tool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7.5 Test commissioning using chip-tool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If using the DACs signed by custom PAA that is not present in connectedhomeip repository,
then download the PAA certificate, please make sure it is in DER format.
@@ -1292,16 +1298,16 @@ Run the following command from host to commission the device.
./chip-tool pairing ble-wifi 1234 my_SSID my_PASSPHRASE my_PASSCODE my_DISCRIMINATOR --paa-trust-store-path /path/to/PAA-Certificates/
2.8 Matter OTA
--------------
8 Matter OTA
------------
- Enable the ``CONFIG_ENABLE_OTA_REQUESTOR`` option to enable Matter OTA Requestor functionality.
Please follow the `OTA guide`_
in the connectedhomeip repository for generating a Matter OTA image and performing OTA.
2.8.1 Encrypted Matter OTA
~~~~~~~~~~~~~~~~~~~~~~~~~~
8.1 Encrypted Matter OTA
~~~~~~~~~~~~~~~~~~~~~~~~
The esp-matter SDK supports using a pre-encrypted application image for OTA upgrades.
Please follow the steps below to enable and use encrypted application images for OTA upgrades.
@@ -1331,24 +1337,24 @@ Please follow the steps below to enable and use encrypted application images for
file, or reading it from the NVS. We have demonstrated the use of the private key by embedding it as a text file in the
light example.
2.9 Mode Select
---------------
9 Mode Select
-------------
This cluster provides an interface for controlling a characteristic of a device that can be set to one of several predefined values. For example, the light pattern of a disco ball, the mode of a massage chair, or the wash cycle of a laundry machine.
2.9.1 Attribute Supported Modes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9.1 Attribute Supported Modes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This attribute is the list of supported modes that may be selected for the CurrentMode attribute. Each item in this list represents a unique mode as indicated by the Mode field of the ModeOptionStruct. Each entry in this list SHALL have a unique value for the Mode field.
ESP_MATTER uses factory partition to set the values of Supported Modes attribute.
2.9.2 Generate Factory Partition Using esp-matter-mfg-tool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9.2 Generate Factory Partition Using esp-matter-mfg-tool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use `esp-matter-mfg-tool`_ to generate factory partition of the supported modes attribute.
2.9.2.1 Usage
^^^^^^^^^^^^^
9.2.1 Usage
^^^^^^^^^^^
::
@@ -1364,8 +1370,8 @@ Use `esp-matter-mfg-tool`_ to generate factory partition of the supported modes
--supported-modes mode1/label1/endpointId mode2/label2/endpointId
2.9.3 Build example
~~~~~~~~~~~~~~~~~~~
9.3 Build example
~~~~~~~~~~~~~~~~~
For example we want to use mode_select cluster in light example.
@@ -1390,274 +1396,13 @@ For example we want to use mode_select cluster in light example.
ModeSelect::setSupportedModesManager(&sStaticSupportedModesManager);
}
2.10 Matter Controller
----------------------
This section introduces the Matter controller example. Now this example supports the following features of the standard Matter controller:
- BLE-WiFi pairing
- BLE-Thread pairing
- On-network pairing
- Invoke cluster commands
- Read attributes commands
- Read events commands
- Write attributes commands
- Subscribe attributes commands
- Subscribe events commands
- Group settings command.
2.10.1 Device console
~~~~~~~~~~~~~~~~~~~~~
Once you have flashed the controller example onto the device, you can use the `device console <./developing.html#device-console>`__ to commission the device and send commands to the end-device. All of the controller commands begin with the prefix ``matter esp controller``.
2.10.2 Pairing commands
~~~~~~~~~~~~~~~~~~~~~~~
The ``pairing`` commands are used for commissioning end-devices and are available when the ``Enable matter commissioner`` option is enabled. Here are three standard pairing methods:
- **Onnetwork pairing:** Prior to executing this commissioning method, it is necessary to connect both the controller and the end-device to the same network and ensure that the commissioning window of the end-device is open. To complete this process, you can use the command ``matter esp wifi connect``. After the devices are connected, the pairing process can be initiated.
::
matter esp wifi connect <ssid> <password>
matter esp controller pairing onnetwork <node_id> <setup_passcode>
- **Ble-wifi pairing:** This pairing method is supported for ESP32S3. Before you execute this commissioning method, connect the controller to the Wi-Fi network and ensure that the end-device is in commissioning mode. You can use the command ``matter esp wifi connect`` to connect the controller to your wifi network. Then we can start the pairing.
::
matter esp wifi connect <ssid> <password>
matter esp controller pairing ble-wifi <node_id> <ssid> <password> <pincode> <discriminator>
- **Ble-thread pairing:** This pairing method is supported for ESP32S3. Before you execute this commissioning method, connect the controller to the Wi-Fi network in which there is a Thread Border Router (BR). And please ensure that the end-device is in commissioning mode. You can use the command ``matter esp wifi connect`` to connect the controller to your Wi-Fi network. Get the dataset tlvs of the Thread network that the Thread BR is in. Then we can start the pairing.
::
matter esp wifi connect <ssid> <password>
matter esp controller pairing ble-thread <node_id> <dataset_tlvs> <pincode> <discriminator>
- **Matter payload based pairing:** This method is similar to the previously mentioned pairing methods, but instead of accepting a PIN code and discriminator, it uses a Matter setup payload as input. The setup payload is parsed to extract the necessary information, which then initiates the pairing process.
For the ``code`` pairing method, commissioner tries to discover the end-device only on the IP network.
However, when using ``code-wifi``, ``code-thread``, or ``code-wifi-thread``, and id
``CONFIG_ENABLE_ESP32_BLE_CONTROLLER`` is enabled, controller tries to discover the end-device on both the IP and BLE networks.
Below are supported commands:
::
matter esp controller pairing code <node_id> <setup_payload>
::
matter esp controller pairing code-wifi <node_id> <ssid> <passphrase> <setup_payload>
::
matter esp controller pairing code-thread <node_id> <operationalDataset> <setup_payload>
::
matter esp controller pairing code-wifi-thread <node_id> <ssid> <passphrase> <operationalDataset> <setup_payload>
2.10.3 Cluster commands
~~~~~~~~~~~~~~~~~~~~~~~
The ``invoke-cmd`` command is used for sending cluster commands to the end-devices. It utilizes a ``cluster_command`` class to establish the sessions and send the command packets. The class constructor function could accept two callback inputs:
- **Success callback**:
This callback will be called upon the reception of the success response. It could be used to handle the response data for the command that requires a reponse. Now the default success callback will print the response data for GroupKeyManagement, Groups, Scenes, Thermostat, and DoorLock clusters. If you want to handle the response data in your example, you can register your success callback when creating the ``cluster_command`` object.
- **Error callback**:
This callback will be called upon the reception of the failure response or reponse timeout.
^^^^^^^^^^^^^^^^
- Send the cluster command:
::
matter esp controller invoke-cmd <node-id | group-id> <endpoint-id> <cluster-id> <command-id> <command-data>
.. note::
- The ``command-data`` should utilize a JSON object string and the name of each item in this object should be ``\"<TagNumber>:<DataType>\"`` or ``\"<TagName>:<TagNumber>:<DataType>\"``. The TagNumber should be the same as the command parameter ID in Matter SPEC and the supported DataTypes are listed in ``$ESP_MATTER_PATH/components/esp_matter/utils/json_to_tlv.h``
- For the DataType ``bytes``, the value should be a Base64-Encoded string.
Here are some examples of the ``command-data`` format.
- For MoveToLevel command in LevelControl cluster, the ``command-data`` (``{"level": 10, "transitionTime": 0, "optionsMask": 0, "optionsOverride": 0}``) should be:
::
matter esp controller invoke-cmd <node-id> <endpoint-id> 8 0 "{\"0:U8\": 10, \"1:U16\": 0, \"2:U8\": 0, \"3:U8\": 0}"
- For KeySetWrite command in GroupKeyManagement cluster, the ``command-data`` (``{"groupKeySet":{"groupKeySetID": 42, "groupKeySecurityPolicy": 0, "epochKey0": d0d1d2d3d4d5d6d7d8d9dadbdcdddedf, "epochStartTime0": 2220000, "epochKey1": null, "epochStartTime1": null, "epochKey2": null, "epochStartTime2": null}}``) should be:
::
matter esp controller invoke-cmd <node-id> <endpoint-id> 63 0 "{\"0:OBJ\": {\"0:U16\": 42, \"1:U8\": 0, \"2:BYT\": \"0NHS09TV1tfY2drb3N3e3w==\", \"3:U64\": 2220000, \"4:NULL\": null, \"5:NULL\": null, \"6:NULL\": null, \"7:NULL\": null}}"
- For AddGroup command in Groups cluster, the ``command-data`` (``{"groupID": 1, "groupName": "grp1"}``) should be:
::
matter esp controller invoke-cmd <node-id> <endpoint-id> 0x4 0 "{\"0:U16\": 1, \"1:STR\": \"grp1\"}"
2.10.4 Read commands
~~~~~~~~~~~~~~~~~~~~
The ``read_command`` class is used for sending read commands to other end-devices. Its constructor function could accept two callback inputs:
- **Attribute report callback**:
This callback will be called upon the reception of the attribute report for read-attribute commands.
- **Event report callback**:
This callback will be called upon the reception of the event report for read-event commands.
2.10.4.1 Read attribute commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``read-attr`` commands are used for sending the commands of reading attributes on end-devices.
- Send the read-attribute command:
::
matter esp controller read-attr <node-id> <endpoint-ids> <cluster-ids> <attribute-ids>
.. note::
- endpoint-ids can represent a single or multiple endpoints, e.g. '0' or '0,1'. And the same applies to cluster-ids, attribute-ids, and event-ids below.
2.10.4.2 Read event commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``read-event`` commands are used for sending the commands of reading events on end-devices.
- Send the read-event command:
::
matter esp controller read-event <node-id> <endpoint-ids> <cluster-ids> <event-ids>
2.10.5 Write attribute commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``write-attr`` command is used for sending the commands of writing attributes on the end-device.
- Send the write-attribute command:
::
matter esp controller write-attr <node-id> <endpoint-id> <cluster-ids> <attribute-ids> <attribute-value>
.. note::
- ``attribute_value`` should utilize a JSON object string. And the format of this string is the same as the ``command_data`` in `cluster commands <./developing.html#cluster-commands>`__. This JSON object should contain only one item that represents the attribute value.
Here are some examples of the ``attribute_value`` format.
For StartUpOnOff attribute of OnOff Cluster, you should use the following JSON structures as the ``attribute_value`` to represent the StartUpOnOff ``2`` and ``null``:
::
matter esp controller write-attr <node_id> <endpoint_id> 6 0x4003 "{\"0:U8\": 2}"
matter esp controller write-attr <node_id> <endpoint_id> 6 0x4003 "{\"0:NULL\": null}"
For Binding attribute of Binding cluster, you should use the following JSON structure as the ``attribute_value`` to represent the binding list ``[{"node":1, "endpoint":1, "cluster":6}]``:
::
matter esp controller write-attr <node_id> <endpoint_id> 30 0 "{\"0:ARR-OBJ\":[{\"1:U64\":1, \"3:U16\":1, \"4:U32\": 6}]}"
For ACL attribute of AccessControl cluster, you should use the following JSON structure as the ``attribute_value`` to represent the AccessControlList ``[{"privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"privilege": 4, "authMode": 3, "subjects": [1], "targets": null}]``:
::
matter esp controller write-attr <node_id> <endpoint_id> 31 0 "{\"0:ARR-OBJ\":[{\"1:U8\": 5, \"2:U8\": 2, \"3:ARR-U64\": [112233], \"4:NULL\": null}, {\"1:U8\": 4, \"2:U8\": 3, \"3:ARR-U64\": [1], \"4:NULL\": null}]}"
To write multiple attributes in one commands, the ``attribute_value`` should be a JSON array. For example, to write the ACL attribute and Binding attribute above, you should use the following JSON structure as the ``attribute_value``:
::
matter esp controller write-attr <node_id> <endpoint_id1>,<endpoint_id2> 31,30 0,0 "[{\"0:ARR-OBJ\":[{\"1:U8\": 5, \"2:U8\": 2, \"3:ARR-U64\": [112233], \"4:NULL\": null}, {\"1:U8\": 4, \"2:U8\": 3, \"3:ARR-U64\": [1], \"4:NULL\": null}]}, {\"0:ARR-OBJ\":[{\"1:U64\":1, \"3:U16\":1, \"4:U32\": 6}]}]"
For attributes of type uint64_t or int64_t, if the absolute value is greater than (2^53), you should use string to represent number in JSON structure for precision
::
matter esp controller write-attr <node_id> <endpoint_id> 42 0 "{\"0:ARR-OBJ\":[{\"1:U64\": \"9007199254740993\", \"2:U8\": 0}]}"
2.10.6 Subscribe commands
~~~~~~~~~~~~~~~~~~~~~~~~~
The ``subscribe_command`` class is used for sending subscribe commands to other end-devices. Its constructor function could accept four callback inputs:
- **Attribute report callback**:
This callback will be invoked upon the reception of the attribute report for subscribe-attribute commands.
- **Event report callback**:
This callback will be invoked upon the reception of the event report for subscribe-event commands.
- **Subscribe done callback**:
This callback will be invoked when the subscription is terminated or shutdown.
- **Subscribe failure callback**:
This callback will be invoked upon the failure of establishing CASE session.
2.10.6.1 Subscribe attribute commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``subs-attr`` commands are used for sending the commands of subscribing attributes on end-devices.
- Send the subscribe-attribute command:
::
matter esp controller subs-attr <node-id> <endpoint-ids> <cluster-ids> <attribute-ids> <min-interval> <max-interval>
2.10.6.2 Subscribe event commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``subs-event`` commands are used for sending the commands of subscribing events on end-devices.
- Send the subscribe-event command:
::
matter esp controller subs-event <node-id> <endpoint-ids> <cluster-ids> <event-ids> <min-interval> <max-interval>
2.10.7 Group settings commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``group-settings`` commands are used to set group information of the controller. They are available when the ``Enable matter commissioner`` option is enabled in menuconfig. If the controller wants to send multicast commands to end-devices, it should be in the same group as the end-devices.
- Set group information of the controller:
::
matter esp controller group-settings show-groups
matter esp controller group-settings add-group <group-id> <group-name>
matter esp controller group-settings remove-group <group-id>
matter esp controller group-settings show-keysets
matter esp controller group-settings add-keyset <ketset-id> <policy> <validity-time> <epoch-key-oct-str>
matter esp controller group-settings remove-keyset <ketset-id>
matter esp controller group-settings bind-keyset <group-id> <ketset-id>
matter esp controller group-settings unbind-keyset <group-id> <ketset-id>
2.10.8 Attestation Trust Storage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The controller example offers two options for the Attestation Trust Storage which is used to store and utilize the PAA certificates for the Device Attestation verification. This feature is available when the ``Enable matter commissioner`` option is enabled in menuconfig. You can modify this setting in menuconfig ``Components`` -> ``ESP Matter Controller`` -> ``Attestation Trust Store``
- ``Attestation Trust Store - Test``
Use two hardcoded PAA certificates(Chip-Test-PAA-FFF1-Cert&Chip-Test-PAA-NoVID-Cert) in the firmware.
- ``Attestation Trust Store - Spiffs``
Read the PAA root certificates from the spiffs partition. The PAA der files should be placed in ``paa_cert`` directory so that they can be flashed into the spiffs partition of the controller.
2.11 Custom Cluster
-------------------
10 Custom Cluster
-----------------
Matter enables users to implement custom clusters for unique features. This section introduces how to add a custom cluster.
2.11.1 Cluster XML Template
~~~~~~~~~~~~~~~~~~~~~~~~~~~
10.1 Cluster XML Template
~~~~~~~~~~~~~~~~~~~~~~~~~
Before adding a custom cluster, you should design the attributes, commands, and events it will include, and create the cluster XML template file based on your design.
@@ -1731,13 +1476,13 @@ Run ``zap_regen_all.py`` in Matter virtual environment to generate common code a
The code generation script will create client code for the custom cluster, supporting Android, Darwin, and Python controllers, as well as the chip-tool. It will also generate app-common code for the new custom cluster.
The chip-tool can be used to test the custom cluster after recompiling.
2.11.2 Cluster Implementation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10.2 Cluster Implementation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The custom cluster should be implemented after the app-common code has been generated.
2.11.2.1 Custom Cluster Attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10.2.1 Custom Cluster Attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The attributes in a cluster can be managed with the two following methods. A cluster can utilize both the methods to manage its attributes.
@@ -1753,8 +1498,8 @@ The attributes in a cluster can be managed with the two following methods. A clu
Notes that attributes of complex types(structure or array) cannot be handled by Attribute Accessors and MUST be managed using AAI.
2.11.2.2 Custom Cluster Commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10.2.2 Custom Cluster Commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The commands in a cluster can be handled with one of the two following methods. A cluster can only choose one method to handle its commands.
@@ -1768,21 +1513,21 @@ The commands in a cluster can be handled with one of the two following methods.
If the commands in a cluster are handled by CHI. The cluster should be added to the ``CommandHandlerInterfaceOnlyClusters`` array in the `zap configuration data`_ file.
After modifying the `zap configuration data`_, the code should be regenerated, which will remove the Ember command callback declarations.
2.11.2.3 Custom Cluster Events
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10.2.3 Custom Cluster Events
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All the events are managed by the `EventLogging <https://github.com/project-chip/connectedhomeip/blob/master/src/app/EventLogging.h>`__.
If an event is triggered, ``chip::app::LogEvent()`` can be called to record it. The event will then be reported to the subscriber that has subscribed to it.
2.11.2.4 Custom Cluster Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10.2.4 Custom Cluster Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A custom cluster might requires special funtions to handle initialization, attribute changes, shutdown, and pre-attribute changes.
For instance, the AAI and CHI need to be registered so that they can be accessed by the Matter data model. Therefore, the cluster requires an initialization function to register them.
To enable these functions, the cluster should be added to the appropriate entry in the `zap configuration data`_ file.
2.11.3 Example Usage
~~~~~~~~~~~~~~~~~~~~
10.3 Example Usage
~~~~~~~~~~~~~~~~~~
- Zap Example
docs/en/index.rst
+9 -8
View File
@@ -20,14 +20,15 @@ Table of Contents
1. Introduction <introduction>
2. Developing with the SDK <developing>
3. Matter Certification <certification>
4. Production Considerations <production>
5. Security Considerations <security>
6. RAM and Flash Optimizations <optimizations>
7. API Reference <api-reference/index>
8. Integration with esp-insights <insights>
9. Application User Guide <app_guide>
10. Copyrights and Licenses<COPYRIGHT>
3. Matter Controller <controller>
4. Matter Certification <certification>
5. Production Considerations <production>
6. Security Considerations <security>
7. RAM and Flash Optimizations <optimizations>
8. API Reference <api-reference/index>
9. Integration with esp-insights <insights>
10. Application User Guide <app_guide>
11. Copyrights and Licenses<COPYRIGHT>
A1 Appendix FAQs <faq>
.. _Matter: https://csa-iot.org/all-solutions/matter/
docs/en/introduction.rst
+12 -12
View File
@@ -1,8 +1,8 @@
1. Introduction
===============
Introduction
============
1.1 Espressif Matter Solutions
------------------------------
1 Espressif Matter Solutions
----------------------------
.. figure:: ../_static/solution_architecture.png
:align: center
@@ -15,8 +15,8 @@ Espressif's Matter Solutions consist of:
- Production ready SDK for Matter
- Matter and ESP RainMaker integration
1.1.1 Espressif Matter Platforms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.1 Espressif Matter Platforms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Espressif platform solutions are as shown below:
@@ -30,8 +30,8 @@ Espressif platform solutions are as shown below:
- By efficiently combining ESP32-H and our Wi-Fi SoCs, a **Thread Border Router** can be built to connect the Thread network with the Wi-Fi network. We provide hardware devkits, reference designs and production-ready SDK, which supports the latest Thread 1.3 feature for Matter.
- We also provide Matter-Zigbee and Matter-BLE Mesh bridge solutions that enable non-Matter devices based on Zigbee, Bluetooth LE Mesh and other protocols to connect to the Matter ecosystem. A **Matter-Zigbee Bridge** uses ESP32-H and another Wi-Fi SoC, while a **Matter-BLE Mesh Bridge** can be done on a single SoC with both Wi-Fi and Bluetooth LE interfaces.
1.1.2 Espressif's SDK for Matter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.2 Espressif's SDK for Matter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Espressif's SDK for Matter is built on top of the `open source Matter SDK <https://github.com/project-chip/connectedhomeip/>`__, and provides simplified APIs, commonly used peripherals, tools and utilities for security, manufacturing and production accompanied by exhaustive documentation. It includes rich production references, aimed to simplify the development process of Matter products and enable the users to go to production in the shortest possible time.
@@ -42,16 +42,16 @@ Espressif's SDK for Matter is built on top of the `open source Matter SDK <https
In addition, the SDK also integrates `ESP RainMaker <https://rainmaker.espressif.com/>`__ and `ESP Insights <https://github.com/espressif/esp-insights>`__ for cloud services and remote diagnostics.
1.1.3 Matter and ESP RainMaker Integration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.3 Matter and ESP RainMaker Integration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Espressif's AIoT cloud platform `ESP RainMaker <https://rainmaker.espressif.com/>`__ can provide remote control and enable cloud-based device management for Matter devices.
By combining the above-mentioned Matter hardware and software solutions with ESP RainMaker, this one-stop Matter ecosystem solution provides a full-fledged cloud deployment through your own private account with advanced device management features.
1.2 Try it yourself
-------------------
2 Try it yourself
-----------------
If you want to test Matter on Espressif devices without any additional setup:
docs/en/optimizations.rst
+39 -39
View File
@@ -1,8 +1,8 @@
6. Configuration options to optimize RAM and Flash
==================================================
Configuration options to optimize RAM and Flash
===============================================
6.1 Overview
------------
1 Overview
----------
There are several configuration options available to optimize Flash and RAM storage.
The following list highlights key options that significantly increase the free DRAM, heap, and reduce the flash
@@ -10,11 +10,11 @@ footprint.
For more optimizations, we've also listed the reference links to esp-idf's optimization guide.
6.2 Configurations
------------------
2 Configurations
----------------
6.2.1 Test Environment setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.1 Test Environment setup
~~~~~~~~~~~~~~~~~~~~~~~~~~
All numbers mentioned below are collected in the following environment:
@@ -42,8 +42,8 @@ All numbers mentioned below are collected in the following environment:
allocated as heap. Therefore, a direct increase in the free DRAM will reflect as an increase in free heap.
6.2.2 Default Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.2 Default Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~
We have used the default light example here, and below listed are the static and dynamic sizes.
@@ -76,8 +76,8 @@ We have used the default light example here, and below listed are the static and
Post Commissioning, 101580, --
6.2.3 Disable the chip-shell
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.3 Disable the chip-shell
~~~~~~~~~~~~~~~~~~~~~~~~~~
Console shell is helpful when developing/debugging the application, but may not be necessary in
production. Disabling the shell can save space. Disable the below configuration option.
@@ -115,8 +115,8 @@ production. Disabling the shell can save space. Disable the below configuration
Post Commissioning, 112340, 10760
6.2.4 Adjust the dynamic endpoint count
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.4 Adjust the dynamic endpoint count
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The default dynamic endpoint count and default device type count is 16, which may be excessive for a normal application creating only 2 endpoints.
eg: light, only has two endpoints, one for root endpoint and one for actual light.
@@ -158,8 +158,8 @@ Here, we have set the dynamic endpoint count and device type count to 2. Increas
Post Commissioning, 107984, 6404
6.2.5 Use the newlib nano formatting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.5 Use the newlib nano formatting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This optimization saves approximately 25-50K of flash, depending on the target. In our case, it results in a flash
reduction of 47 KB.
@@ -200,8 +200,8 @@ functions. Fore more details please take a look at esp-idf's `newlib nano format
Post Commissioning, 103500, 1920
6.2.6 BLE Optimizations
~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.6 BLE Optimizations
~~~~~~~~~~~~~~~~~~~~~
Since most devices will primarily operate as BLE peripherals and typically won't need more than one connection
(especially if it's just a Matter app), we can optimize by reducing the maximum allowed connections, thereby
@@ -262,8 +262,8 @@ Below are the configuration options that can be set to achieve these optimizatio
Post Commissioning, 101176, -404
6.2.7 Configuring logging event buffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.7 Configuring logging event buffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Matter events serve as a historical record, stored in chronological order in the logging event buffer.
By reducing the buffer size we can potentially save the DRAM. However, it's important to note that this reduction
@@ -322,8 +322,8 @@ Reduce the chip device event queue size can reduce IRAM size usage, lead to free
Post Commissioning, 108184, 6604
6.2.8 Relocate certain code from IRAM to flash memory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.8 Relocate certain code from IRAM to flash memory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Relocating certain code from IRAM to flash can reduce IRAM usage, so increase available heap size. However, this may increase execution time.
@@ -331,8 +331,8 @@ Relocating certain code from IRAM to flash can reduce IRAM usage, so increase av
The options in this section may impact performance. Please perform thorough testing before using them in production.
6.2.8.1 Reduce BLE IRAM usage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2.8.1 Reduce BLE IRAM usage
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Move most IRAM into flash. This will increase the usage of flash and reduce ble performance.
Because the code is moved to the flash, the execution speed of the code is reduced. To have
@@ -371,8 +371,8 @@ a small impact on performance, you need to enable flash suspend (SPI_FLASH_AUTO_
Post Commissioning, 119608, 18028
6.2.8.2 Place FreeRTOS functions into Flash
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2.8.2 Place FreeRTOS functions into Flash
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When enabled the selected Non-ISR FreeRTOS functions will be placed into Flash memory instead of IRAM.
This saves up to 8KB of IRAM depending on which functions are used.
@@ -410,8 +410,8 @@ This saves up to 8KB of IRAM depending on which functions are used.
Post Commissioning, 111020, 9440
6.2.8.3 Place non-ISR ringbuf functions into flash
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2.8.3 Place non-ISR ringbuf functions into flash
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Place non-ISR ringbuf functions (like xRingbufferCreate/xRingbufferSend) into flash.
This frees up IRAM, but the functions can no longer be called when the cache is disabled.
@@ -449,8 +449,8 @@ This frees up IRAM, but the functions can no longer be called when the cache is
Post Commissioning, 105652, 4072
6.2.8.4 Use esp_flash implementation in ROM
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2.8.4 Use esp_flash implementation in ROM
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Enable this flag to use new SPI flash driver functions from ROM instead of ESP-IDF.
After enable CONFIG_SPI_FLASH_ROM_IMPL, will increase free IRAM.
@@ -491,8 +491,8 @@ But may miss out on some flash features and support for new flash chips.
Post Commissioning, 110512, 8932
6.2.8.5 Force the entire heap component to be placed in flash memory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2.8.5 Force the entire heap component to be placed in flash memory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Enable this flag to save up RAM space by placing the heap component in the flash memory
Note that it is only safe to enable this configuration if no functions from esp_heap_caps.h or
@@ -531,8 +531,8 @@ esp_heap_trace.h are called from IRAM ISR which runs when cache is disabled.
Post Commissioning, 108192, 6612
6.2.9 Reduce Task Stack Size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.9 Reduce Task Stack Size
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Reduce some task stack size can increase free heap size.
@@ -571,8 +571,8 @@ Reduce some task stack size can increase free heap size.
Post Commissioning, 104828, 3248
6.2.10 Excluding Unused Matter Clusters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2.10 Excluding Unused Matter Clusters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the cluster implementation source files use a class derived from another class with virtual functions and instantiate
a global object of this class, the linker may keep all the related symbols that may be used for this class in the vtable.
@@ -686,7 +686,7 @@ The default configuration disables all unused clusters.
.. only:: esp32c2 or esp32c3 or esp32c5 or esp32c6 or esp32h2
6.2.11 Link Time Optimization (LTO)
2.11 Link Time Optimization (LTO)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Link Time Optimization (LTO) helps further optimize both binary size and runtime performance.
@@ -699,8 +699,8 @@ The default configuration disables all unused clusters.
enabling LTO can result in around ~90 KB of flash savings, though it also increases stack usage by ~1700 bytes.
6.3 References for futher optimizations
---------------------------------------
3 References for futher optimizations
-------------------------------------
- `RAM optimization`_
- `Binary size optimization`_
docs/en/production.rst
+24 -24
View File
@@ -1,13 +1,13 @@
4. Production Considerations
============================
Production Considerations
=========================
4.1 Prerequisites
-----------------
1 Prerequisites
---------------
All Matter examples use certain test or evaluation values that enables you to quickly build and test Matter. As you get ready to go to production, these must be replaced with the actual values. These values are typically a part of the manufacturing partition in your device.
4.1.1 Vendor ID and Product ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.1 Vendor ID and Product ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A **Vendor Identifier (VID)** is a 16-bit number that uniquely identifies a particular
product manufacturer or a vendor. It is allocated by the Connectivity Standards
@@ -18,8 +18,8 @@ of a vendor. It is assigned by the vendor (you).
A VID-PID combination uniquely identifies a Matter product.
4.1.2 Certificates
~~~~~~~~~~~~~~~~~~
1.2 Certificates
~~~~~~~~~~~~~~~~
A **Device Attestation Certificate (DAC)** proves the authenticity of the device
manufacturer and the certification status of the device's hardware and software.
@@ -32,16 +32,16 @@ The PAA certificate is an implicitly trusted self-signed root certificate.
Please reach out to your Espressif representative for the details about how to
procure the DAC.
4.1.3 Certification Declaration (CD)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.3 Certification Declaration (CD)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A **Certification Declaration (CD)** is a cryptographic document that allows a Matter
device to assert its protocol compliance. Once your product is certified, the CSA
creates a CD for that device. The CD should then be included in the device firmware
by the device manufacturer.
4.1.4 Setup Passcode, Discriminator and Onboarding Payload
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.4 Setup Passcode, Discriminator and Onboarding Payload
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The unique **setup passcode** serves as the proof of possession and is also used to compute
the shared secret during commissioning. The corresponding SPAKE2+ verifier of the
@@ -56,8 +56,8 @@ The QR code and/or the manual pairing code are generally printed on the packagin
device.
4.1.5 Manufacturing Partition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.5 Manufacturing Partition
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Espressif's SDK for Matter uses a separate manufacturing partition to store all the information
mentioned above. Because the DACs are unique to every device, the manufacturing partition
@@ -73,8 +73,8 @@ images before shipping the modules and provides a manifest (CSV file) along with
bundle.
4.2 Over-the-Air (OTA) Updates
------------------------------
2 Over-the-Air (OTA) Updates
----------------------------
Matter devices must support OTA firmware updates, either by using Matter-based OTA
or vendor specific means.
@@ -89,11 +89,11 @@ on the devices remotely. As opposed to the Matter OTA, ESP RainMaker OTA allows
the flexibility of delivering the OTA upgrades incrementally or to groups of devices.
4.3 Manufacturing
-----------------
3 Manufacturing
---------------
4.3.1 Mass Manufacturing Utility
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3.1 Mass Manufacturing Utility
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For commissioning a device into the Matter Fabric, the device requires the following information:
@@ -109,8 +109,8 @@ When using the utility, by default, the above details will be included in the ge
Details about using the mass manufacturing utility can be found here: `esp-matter-mfg-tool`_
4.3.2 Pre-Provisioned Modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3.2 Pre-Provisioned Modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~
{IDF_TARGET_NAME} modules can be pre-flashed with the manufacturing partition images
during module manufacturing itself and then be shipped to you.
@@ -120,8 +120,8 @@ programming the partition into the device at your end.
Please contact your Espressif contact person for more information.
4.3.3 The esp-matter-mfg-tool Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3.3 The esp-matter-mfg-tool Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In Espressif Matter Prep-provisioning modules, the DAC key pair, DAC and PAI certificates are pre-flashed by default.
docs/en/security.rst
+24 -24
View File
@@ -1,10 +1,10 @@
5. Security Considerations
==========================
Security Considerations
=======================
{IDF_TARGET_RELEASE:default="v5.4.1"}
5.1 Overview
------------
1 Overview
----------
This guide provides an overview of the overall security features that should be considered while designing the products with Matter framework on ESP32 SoCs.
@@ -14,11 +14,11 @@ High level security goals are as follows:
#. Securing device identity (e.g., Matter DAC Private Key)
#. Secure storage for confidential data
5.2 Platform Security
---------------------
2 Platform Security
-------------------
5.2.1 Secure Boot
~~~~~~~~~~~~~~~~~
2.1 Secure Boot
~~~~~~~~~~~~~~~
The Secure Boot feature ensures that only authenticated software can execute on the device. The Secure Boot process forms a chain of trust by verifying all **mutable** software entities involved in the boot-up process. Signature verification happens during both boot-up as well as in OTA updates.
@@ -30,20 +30,20 @@ Please refer to `Secure Boot V2`_ guide for detailed documentation about this fe
.. _flash_enc-guide:
5.2.2 Flash Encryption
~~~~~~~~~~~~~~~~~~~~~~
2.2 Flash Encryption
~~~~~~~~~~~~~~~~~~~~
The Flash Encryption feature helps to encrypt the contents on the off-chip flash memory and thus provides the confidentiality aspect to the software or data stored in the flash memory.
Please refer to `Flash Encryption`_ guide for detailed documentation about this feature in {IDF_TARGET_NAME}.
5.3 Product Security
--------------------
3 Product Security
------------------
.. _secure_storage-guide:
5.3.1 Secure Storage
~~~~~~~~~~~~~~~~~~~~
3.1 Secure Storage
~~~~~~~~~~~~~~~~~~
Secure storage refers to the application-specific data that can be stored in a secure manner on the device, i.e., off-chip flash memory. This is typically a read-write flash partition and holds device specific configuration data, e.g., Wi-Fi credentials.
@@ -51,8 +51,8 @@ ESP-IDF provides the **NVS (Non-volatile Storage)** management component which a
Please refer to the `NVS Encryption`_ for detailed documentation on the working and instructions to enable this feature in {IDF_TARGET_NAME}.
5.3.2 Device Identity
~~~~~~~~~~~~~~~~~~~~~
3.2 Device Identity
~~~~~~~~~~~~~~~~~~~
Matter specification requires a unique Device Attestation Key (DAC) per device. This is a private ECDSA (secp256r1 curve) key that establishes the device identity to the Matter Ecosystem.
DAC private needs to be protected from remote as well as physical attacks in the best possible way.
@@ -81,24 +81,24 @@ Recommended ways for DAC private key protection:
Espressif provides pre-provisioning service to build Matter-Compatible devices. This service also ensures the security of the DAC private key and configuration data. Please contact Espressif Sales for more information.
5.4 More Security Considerations
--------------------------------
4 More Security Considerations
------------------------------
Please refer to the overall ESP-IDF `Security Guide`_ for more considerations related to the debug interfaces, network, transport and OTA updates related security.
5.5 Security Policy
-------------------
5 Security Policy
-----------------
The ESP-Matter GitHub repository has attached `Security Policy Brief`_.
5.5.1 Advisories
~~~~~~~~~~~~~~~~
5.1 Advisories
~~~~~~~~~~~~~~
- Espressif publishes critical `Security Advisories`_, which includes security advisories regarding both hardware and software.
- The specific advisories of the ESP-Matter software components shall be published through the `GitHub repository`_.
5.5.2 Software Updates
~~~~~~~~~~~~~~~~~~~~~~
5.2 Software Updates
~~~~~~~~~~~~~~~~~~~~
Critical security issues in the ESP-Matter components, ESP-IDF components and dependant third-party libraries are fixed as and when we find them or when they are reported to us. Gradually, we make the fixes available in all applicable release branches in ESP-Matter.
examples/controller/README.md
+10 -5
View File
@@ -11,12 +11,17 @@ No additional setup is required.
## 2. Controller Example
See the [docs](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html#controller-example) for more information
about pairing and controling an end-device using this example
See the [docs](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/controller.html) for more information
about pairing and controlling an end-device using this example.
## 3. Controller in Rainmaker Fabric
Matter Controller in Rainmaker Fabric is avaliable in [Rainmaker Matter Examples](https://github.com/espressif/esp-rainmaker/tree/master/examples/matter)
Matter Controller in Rainmaker Fabric is available in [RainMaker Matter Examples](https://github.com/espressif/esp-rainmaker/tree/master/examples/matter).
Two different controller types are provided in RainMaker repository:
- [Matter Server-based Controller](https://github.com/espressif/esp-rainmaker/tree/master/examples/matter/matter_controller): The controller is set up with a Matter server instance. So it can be commissioned to Matter fabric with standard Matter commissioning flow. Then the NOC will be updated to controller's NOC during controller setting up.
- [Matter client-only Controller](https://github.com/espressif/esp-rainmaker/tree/master/examples/matter/client_only_matter_controller): The controller is a client-only Controller. It doesn't have standard Matter data model. And it uses RainMaker provisioning to join a Wi-Fi network.
## 4. OpenThread Border Router (OTBR) feature
@@ -83,7 +88,7 @@ matter esp controller invoke-cmd 1234 1 6 2
I cannot finish the commissioning on the controller example:
- For onnetwork pairing, please make sure that the end-device and the controller are on the same IP-network.
- The controller uses the hard-code test PAA certification so the PAI and DAC on the end-device should be generated by the [test cert](https://github.com/espressif/connectedhomeip/blob/4f7669b052b16bd054227376e1bbadac85419793/credentials/test/attestation/Chip-Test-PAA-NoVID-Cert.pem) and the [test key](https://github.com/espressif/connectedhomeip/blob/4f7669b052b16bd054227376e1bbadac85419793/credentials/test/attestation/Chip-Test-PAA-NoVID-Key.pem)
- The controller uses the hard-code test PAA certificate by default so the PAI and DAC on the end-device should be generated by the [test cert](https://github.com/espressif/connectedhomeip/blob/4f7669b052b16bd054227376e1bbadac85419793/credentials/test/attestation/Chip-Test-PAA-NoVID-Cert.pem) and the [test key](https://github.com/espressif/connectedhomeip/blob/4f7669b052b16bd054227376e1bbadac85419793/credentials/test/attestation/Chip-Test-PAA-NoVID-Key.pem)
- If you are still facing issues, reproduce the issue on the default example for the device and then raise an [issue](https://github.com/espressif/esp-matter/issues). Make sure to share these:
- The complete device logs for both the devices taken over UART.
- The esp-matter and esp-idf branch you are using.
@@ -93,7 +98,7 @@ I cannot finish the commissioning on the controller example:
I cannot send commands to the light from the controller:
- Make sure the pairing command was a success.
- Currently the cluster commands and write-attribute commands are only supported for on-off, level-control, and color-control clusters.
- The command data of cluster invoking command and attribute value data of attribute writing command should be a JSON string that matches the cluster description in Matter SPEC.
- The CASESession will be lost on end-device after reboot. But the controller will still send commands on the previous CASESession. The controller will release previous CASESession after the last command is timeout. So the second command will re-establish a new CASESession in this situation.
- If you are still facing issues, reproduce the issue on the default example for the device and then raise an [issue](https://github.com/espressif/esp-matter/issues). Make sure to share these:
- The complete device logs for both the devices taken over UART.