Few documentation fixes

- Added some docs for attribute and identify callback
- mfg_tool: Add the sourcing of esp-idf's export.sh script
- Added the link for getting the repository in top level README.md
- Table for Matter specification version and release branches
- FAQ for stuck at "Solving dependencies requirements"
- Change the link and doc in rainmaker example

README.md

@@ -7,10 +7,24 @@
 
 Espressif's SDK for Matter is the official Matter development framework for ESP32 series SoCs. It 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.
 
-
 [Supported Device Types](SUPPORTED_DEVICE_TYPES.md)
 
 
+## Supported Matter specification versions
+
+| Matter Specification Version |                              Supported Branch                             |
+|:----------------------------:|:-------------------------------------------------------------------------:|
+|             v1.0             | [release/v1.0](https://github.com/espressif/esp-matter/tree/release/v1.0) |
+|             v1.1             | [release/v1.1](https://github.com/espressif/esp-matter/tree/release/v1.1) |
+|     v1.2 (Ongoing effort)    |         [main](https://github.com/espressif/esp-matter/tree/main)         |
+
+
+## Getting the repositories
+
+For efficient cloning of the ESP-Matter repository, please refer
+[Getting the Repositories](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html#getting-the-repositories)
+section in the ESP-Matter Programming Guide.
+
 ## Supported ESP-IDF and connectedhomeip versions
 
 - This SDK currently works with [5b4f800](https://github.com/project-chip/connectedhomeip/commit/5b4f8004662d00bdb111367fec7d3ea978c23372) of connectedhomeip.
@@ -23,7 +37,7 @@ Refer the [Programming Guide](https://docs.espressif.com/projects/esp-matter/en/
 
 
 ## Matter Specifications
-Download the Matter 1.0 specifications from [CSA's official site](https://csa-iot.org/developer-resource/specifications-download-request/)
+Download the Matter specification from [CSA's official site](https://csa-iot.org/developer-resource/specifications-download-request/)
 
 ---
 

components/esp_matter/esp_matter_endpoint.h

@@ -531,6 +531,15 @@ typedef struct config {
     endpoint::root_node::config_t root_node;
 } config_t;
 
+/**
+ * @param[in] config             Configuration of the root node, a pointer to an object of type `node::config_t`.
+ * @param[in] attribute_callback This callback is called for every attribute update. The callback implementation shall
+ *                               handle the desired attributes and return an appropriate error code. If the attribute
+ *                               is not of your interest, please do not return an error code and strictly return ESP_OK.
+ * @param[in] 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).
+ */
 node_t *create(config_t *config, attribute::callback_t attribute_callback,
                identification::callback_t identify_callback);
 

docs/en/faq.rst

@@ -337,3 +337,18 @@ the following configuration options:
 - The software version number of the OTA image must be numerically higher.
 - If you need to perform a functional rollback, the version number in the OTA image must be higher than the current
   version, even though the binary content may match the previous OTA image.
+
+
+A1.13 Stuck at "Solving dependencies requirements ....."
+--------------------------------------------------------
+
+When building an example, if it is stuck at "Solving dependencies requirements..."
+you can resolve this issue by clearing the component manager cache.
+
+    ::
+
+        # On Linux
+        rm -rf ~/.cache/Espressif/ComponentManager
+
+        # On macOS
+        rm -rf ~/Library/Caches/Espressif/ComponentManager

examples/all_device_types_app/main/app_main.cpp

@@ -73,6 +73,8 @@ static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg)
     }
 }
 
+// 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).
 static esp_err_t app_identification_cb(identification::callback_type_t type, uint16_t endpoint_id, uint8_t effect_id,
                                        uint8_t effect_variant, void *priv_data)
 {
@@ -80,6 +82,9 @@ static esp_err_t app_identification_cb(identification::callback_type_t type, uin
     return ESP_OK;
 }
 
+// This callback is called for every attribute update. The callback implementation shall
+// handle the desired attributes and return an appropriate error code. If the attribute
+// is not of your interest, please do not return an error code and strictly return ESP_OK.
 static esp_err_t app_attribute_update_cb(attribute::callback_type_t type, uint16_t endpoint_id, uint32_t cluster_id,
                                          uint32_t attribute_id, esp_matter_attr_val_t *val, void *priv_data)
 {

examples/blemesh_bridge/main/app_main.cpp

@@ -63,6 +63,9 @@ static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg)
     }
 }
 
+// This callback is called for every attribute update. The callback implementation shall
+// handle the desired attributes and return an appropriate error code. If the attribute
+// is not of your interest, please do not return an error code and strictly return ESP_OK.
 static esp_err_t app_attribute_update_cb(callback_type_t type, uint16_t endpoint_id, uint32_t cluster_id,
                                          uint32_t attribute_id, esp_matter_attr_val_t *val, void *priv_data)
 {

examples/esp-now_bridge_light/main/app_main.cpp

@@ -63,6 +63,8 @@ static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg)
     }
 }
 
+// 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).
 static esp_err_t app_identification_cb(identification::callback_type_t type, uint16_t endpoint_id, uint8_t effect_id,
                                        uint8_t effect_variant, void *priv_data)
 {
@@ -70,6 +72,9 @@ static esp_err_t app_identification_cb(identification::callback_type_t type, uin
     return ESP_OK;
 }
 
+// This callback is called for every attribute update. The callback implementation shall
+// handle the desired attributes and return an appropriate error code. If the attribute
+// is not of your interest, please do not return an error code and strictly return ESP_OK.
 static esp_err_t app_attribute_update_cb(attribute::callback_type_t type, uint16_t endpoint_id, uint32_t cluster_id,
                                          uint32_t attribute_id, esp_matter_attr_val_t *val, void *priv_data)
 {

examples/generic_switch/main/app_main.cpp

@@ -66,6 +66,8 @@ static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg)
     }
 }
 
+// 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).
 static esp_err_t app_identification_cb(identification::callback_type_t type, uint16_t endpoint_id, uint8_t effect_id,
                                        uint8_t effect_variant, void *priv_data)
 {
@@ -73,6 +75,9 @@ static esp_err_t app_identification_cb(identification::callback_type_t type, uin
     return ESP_OK;
 }
 
+// This callback is called for every attribute update. The callback implementation shall
+// handle the desired attributes and return an appropriate error code. If the attribute
+// is not of your interest, please do not return an error code and strictly return ESP_OK.
 static esp_err_t app_attribute_update_cb(attribute::callback_type_t type, uint16_t endpoint_id, uint32_t cluster_id,
                                          uint32_t attribute_id, esp_matter_attr_val_t *val, void *priv_data)
 {

examples/light/main/app_main.cpp

@@ -111,6 +111,8 @@ static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg)
     }
 }
 
+// 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).
 static esp_err_t app_identification_cb(identification::callback_type_t type, uint16_t endpoint_id, uint8_t effect_id,
                                        uint8_t effect_variant, void *priv_data)
 {
@@ -118,6 +120,9 @@ static esp_err_t app_identification_cb(identification::callback_type_t type, uin
     return ESP_OK;
 }
 
+// This callback is called for every attribute update. The callback implementation shall
+// handle the desired attributes and return an appropriate error code. If the attribute
+// is not of your interest, please do not return an error code and strictly return ESP_OK.
 static esp_err_t app_attribute_update_cb(attribute::callback_type_t type, uint16_t endpoint_id, uint32_t cluster_id,
                                          uint32_t attribute_id, esp_matter_attr_val_t *val, void *priv_data)
 {

examples/light_switch/main/app_main.cpp

@@ -63,6 +63,8 @@ static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg)
     }
 }
 
+// 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).
 static esp_err_t app_identification_cb(identification::callback_type_t type, uint16_t endpoint_id, uint8_t effect_id,
                                        uint8_t effect_variant, void *priv_data)
 {
@@ -70,6 +72,9 @@ static esp_err_t app_identification_cb(identification::callback_type_t type, uin
     return ESP_OK;
 }
 
+// This callback is called for every attribute update. The callback implementation shall
+// handle the desired attributes and return an appropriate error code. If the attribute
+// is not of your interest, please do not return an error code and strictly return ESP_OK.
 static esp_err_t app_attribute_update_cb(callback_type_t type, uint16_t endpoint_id, uint32_t cluster_id,
                                          uint32_t attribute_id, esp_matter_attr_val_t *val, void *priv_data)
 {

examples/rainmaker/README.md

@@ -0,0 +1,4 @@
+# RainMaker
+
+RainMaker Matter examples are available in
+[esp-rainmaker](https://github.com/espressif/esp-rainmaker/tree/master/examples/matter) repository.

examples/rainmaker_light/README.md

@@ -1,3 +0,0 @@
-# RainMaker Light
-
-Matter Light with RainMaker will be soon available in [RainMaker Examples](https://github.com/espressif/esp-rainmaker/tree/master/examples).

examples/refrigerator/main/app_main.cpp

@@ -65,6 +65,8 @@ static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg)
     }
 }
 
+// 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).
 static esp_err_t app_identification_cb(identification::callback_type_t type, uint16_t endpoint_id, uint8_t effect_id,
                                        uint8_t effect_variant, void *priv_data)
 {
@@ -72,6 +74,9 @@ static esp_err_t app_identification_cb(identification::callback_type_t type, uin
     return ESP_OK;
 }
 
+// This callback is called for every attribute update. The callback implementation shall
+// handle the desired attributes and return an appropriate error code. If the attribute
+// is not of your interest, please do not return an error code and strictly return ESP_OK.
 static esp_err_t app_attribute_update_cb(callback_type_t type, uint16_t endpoint_id, uint32_t cluster_id,
                                          uint32_t attribute_id, esp_matter_attr_val_t *val, void *priv_data)
 {

examples/room_air_conditioner/main/app_main.cpp

@@ -103,6 +103,8 @@ static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg)
     }
 }
 
+// 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).
 static esp_err_t app_identification_cb(identification::callback_type_t type, uint16_t endpoint_id, uint8_t effect_id,
                                        uint8_t effect_variant, void *priv_data)
 {
@@ -110,6 +112,9 @@ static esp_err_t app_identification_cb(identification::callback_type_t type, uin
     return ESP_OK;
 }
 
+// This callback is called for every attribute update. The callback implementation shall
+// handle the desired attributes and return an appropriate error code. If the attribute
+// is not of your interest, please do not return an error code and strictly return ESP_OK.
 static esp_err_t app_attribute_update_cb(attribute::callback_type_t type, uint16_t endpoint_id, uint32_t cluster_id,
                                          uint32_t attribute_id, esp_matter_attr_val_t *val, void *priv_data)
 {

examples/zap_light/main/app_main.cpp

@@ -62,6 +62,9 @@ static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg)
     }
 }
 
+// This callback is called for every attribute update. The callback implementation shall
+// handle the desired attributes and return an appropriate error code. If the attribute
+// is not of your interest, please do not return an error code and strictly return ESP_OK.
 static esp_err_t app_attribute_update_cb(callback_type_t type, uint16_t endpoint_id, uint32_t cluster_id,
                                          uint32_t attribute_id, esp_matter_attr_val_t *val, void *priv_data)
 {

examples/zigbee_bridge/main/app_main.cpp

@@ -62,6 +62,9 @@ static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg)
     }
 }
 
+// This callback is called for every attribute update. The callback implementation shall
+// handle the desired attributes and return an appropriate error code. If the attribute
+// is not of your interest, please do not return an error code and strictly return ESP_OK.
 static esp_err_t app_attribute_update_cb(callback_type_t type, uint16_t endpoint_id, uint32_t cluster_id,
                                          uint32_t attribute_id, esp_matter_attr_val_t *val, void *priv_data)
 {

tools/mfg_tool/README.md

@@ -16,6 +16,7 @@
 ### Install python dependencies
 ```
 cd path/to/esp-matter/tools/mfg_tool
+source path/to/esp-idf/export.sh
 python3 -m pip install -r requirements.txt
 ```