Merge branch 'update_docs' into 'main'

Minor changes to the documentation See merge request app-frameworks/esp-matter!179
2026-04-27 19:13:13 +00:00 · 2022-08-25 17:40:51 +08:00
parent a7bca54b96 0e1a62d4ee
commit 799174e98b
15 changed files with 52 additions and 45 deletions
@@ -13,7 +13,7 @@
 # http://doxygen.nl/manual/config.html


-PROJECT_NAME = "ESP Matter Programming Guide"
+PROJECT_NAME = "Programming Guide"

 ## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
 ## to automatically generate API reference list files header_file.inc
@@ -1,6 +1,6 @@
 # Documentation Source Folder

-This folder contains source files of **esp matter documentation**.
+This folder contains source files for the documentation of Espressif's SDK for Matter.

 The sources do not render well in GitHub and some information is not visible at all.

@@ -8,7 +8,7 @@ Use actual documentation generated within about 20 minutes on each commit:

 # Hosted Documentation

-* English: https://docs.espressif.com/projects/esp-matter/
+* English: https://docs.espressif.com/projects/esp-matter/en/main/

 The above URL is for the main branch latest version. Click the drop-down in the bottom left to choose a particular version or to download a PDF.

@@ -23,7 +23,7 @@ project_slug = 'esp-matter'

 # Contains info used for constructing target and version selector
 # Can also be hosted externally, see esp-idf for example
-versions_url = '_static/esp_matter_versions.js'
+versions_url = '_static/esp_sdk_matter_versions.js'

 # Final PDF filename will contains target and version
 pdf_file_prefix = u'esp-docs'
@@ -18,9 +18,9 @@ except ImportError:
    from conf_common import *  # noqa: F403,F401

 # General information about the project.
-project = u'ESP Matter'
+project = u'Espressif\'s SDK for Matter'
 copyright = u'2022 - {}, Espressif Systems (Shanghai) Co., Ltd'.format(datetime.datetime.now().year)
-pdf_title = u'ESP Matter Example Guide'
+pdf_title = u'Example Guide'

 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -1,8 +1,8 @@
-2. Developing with ESP Matter
-=============================
+2. Developing with the SDK
+==========================

 Please refer the :project_file:`Release Notes <RELEASE_NOTES.txt>` to know more about
-ESP Matter releases
+the releases

 2.1 Development Setup
 ---------------------
@@ -168,19 +168,24 @@ A host-based chip-tool can be used as a commissioner to commission and control a
 2.2.1.1 Commissioning
 ^^^^^^^^^^^^^^^^^^^^^

-Use ``chip-tool`` to commission the device:
+Use ``chip-tool`` in interactive mode to commission the device:
+
+::
+
+   chip-tool interactive start
+

 .. only:: esp32 or esp32c3

   ::

-      chip-tool pairing ble-wifi 0x7283 <ssid> <passphrase> 20202021 3840
+      pairing ble-wifi 0x7283 <ssid> <passphrase> 20202021 3840

 .. only:: esp32h2

   ::

-      chip-tool pairing ble-thread 0x7283 hex:<operationalDataset> 20202021 3840
+      pairing ble-thread 0x7283 hex:<operationalDataset> 20202021 3840

 In the above commands:

@@ -207,27 +212,29 @@ Use the cluster commands to control the attributes.

 ::

-   chip-tool onoff toggle 0x7283 0x1
+   onoff toggle 0x7283 0x1

 ::

-   chip-tool onoff on 0x7283 0x1
+   onoff on 0x7283 0x1

 ::

-   chip-tool levelcontrol move-to-level 10 0 0 0 0x7283 0x1
+   levelcontrol move-to-level 10 0 0 0 0x7283 0x1

 ::

-   chip-tool levelcontrol move-to-level 100 0 0 0 0x7283 0x1
+   levelcontrol move-to-level 100 0 0 0 0x7283 0x1

 ::

-   chip-tool colorcontrol move-to-saturation 200 0 0 0 0x7283 0x1
+   colorcontrol move-to-saturation 200 0 0 0 0x7283 0x1

 ::

-   chip-tool colorcontrol move-to-hue 150 0 0 0 0 0x7283 0x1
+   colorcontrol move-to-hue 150 0 0 0 0 0x7283 0x1
+
+chip-tool when used in interactive mode uses CASE resumption as against establishing CASE for cluster control commands. This results into shorter execution times, thereby improving the overall experience.

 For more details on chip-tool usage, check https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool

@@ -272,7 +279,7 @@ The console on the device can be used to run commands for testing. It is configu

      matter onboardingcodes

-Additional ESP Matter specific commands:
+Additional Matter specific commands:

 -  Get attribute: (The IDs are in hex):

@@ -459,16 +466,16 @@ creating in the *app_main.cpp* of the example. Examples:

   ::
   
-      fan::config_t light_config;
-      endpoint_t *endpoint = fan::create(node, &light_config, ENDPOINT_FLAG_NONE);
+      fan::config_t fan_config;
+      endpoint_t *endpoint = fan::create(node, &fan_config, ENDPOINT_FLAG_NONE);


 -  door_lock:

   ::

-      door_lock::config_t light_config;
-      endpoint_t *endpoint = door_lock::create(node, &light_config, ENDPOINT_FLAG_NONE);
+      door_lock::config_t door_lock_config;
+      endpoint_t *endpoint = door_lock::create(node, &door_lock_config, ENDPOINT_FLAG_NONE);


 2.4.2.2 Clusters
@@ -581,7 +588,7 @@ Non-Standard/Custom attributes can also be created on any cluster:

 2.4.4 Advanced Setup
 ~~~~~~~~~~~~~~~~~~~~
-This section explains adding external platforms for Matter. This step is **optional** for most devices. ESP 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.
+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.4.4.1 Creating the external platform directory
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -60,7 +60,7 @@ My device is crashing:

 -  Given the tight footprint requirements of the device, please make
   sure any issues in your code have been ruled out. If you believe the
-   issue is with the ESP Matter SDK itself, please recreate the issue on
+   issue is with the Espressif SDK itself, please recreate the issue on
   the default example application (without any changes) and go through
   the following steps:
 -  Make sure you are on the correct esp-idf branch. Run ``git submodule
@@ -1,12 +1,12 @@
-ESP Matter Programming Guide
-============================
+Programming Guide
+=================

 `Matter <https://csa-iot.org/all-solutions/matter/>`__ is a unified IP-based
 connectivity protocol that is designed to connect and build open, reliable
 and secure IoT ecosystems. This new technology and connectivity standard enables
 communication among a wide range of smart devices. Matter supports IP connectivity over Wi-Fi, Thread and Ethernet.

-ESP Matter is the official Matter development framework for
+Espressif's SDK for Matter is the official Matter development framework for
 Espressif's ESP32 series SoCs.

 We have put together a series of blog posts that introduces various aspects of Matter. We recommend that you go through this `Espressif Matter Blog <https://blog.espressif.com/matter-38ccf1d60bcd>`__.
@@ -18,7 +18,7 @@ Table of Contents
   :maxdepth: 2

   1. Introduction <introduction>
-   2. Developing with ESP Matter <developing>
+   2. Developing with the SDK <developing>
   3. Matter Certification <certification>
   4. Production Considerations <production>
   5. API Reference <api-reference/index>
@@ -6,13 +6,13 @@

 .. figure:: ../_static/solution_architecture.png
    :align: center
-    :alt: ESP Matter Solution Architecture
+    :alt: Solution Architecture
    :figclass: align-center

 Espressif's Matter Solutions consist of:

   - A full spectrum of Matter device platforms
-   - Production ready ESP Matter SDK
+   - Production ready SDK for Matter
   - Matter and ESP RainMaker integration

 1.1.1 Espressif Matter Platforms
@@ -20,9 +20,9 @@ Espressif's Matter Solutions consist of:

 Espressif platform solutions are as shown below:

-.. figure:: ../_static/esp_matter_platform.png
+.. figure:: ../_static/esp_sdk_matter_platform.png
    :align: center
-    :alt: ESP Matter Platform
+    :alt: Platform
    :figclass: align-center

 - The Wi-Fi-enabled SoCs and modules, such as ESP32, ESP32-C and ESP32-S series can be used to build **Matter Wi-Fi devices**.
@@ -30,17 +30,17 @@ 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 ESP Matter SDK
-~~~~~~~~~~~~~~~~~~~~
+1.1.2 Espressif's SDK for Matter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-Espressif's Matter SDK 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.
+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.

 .. figure:: ../_static/software_components.png
    :align: center
-    :alt: ESP Matter Software Components
+    :alt: Software Components
    :figclass: align-center

-In addition, ESP Matter SDK also integrates `ESP RainMaker <https://rainmaker.espressif.com/>`__ and `ESP Insights <https://github.com/espressif/esp-insights>`__ for cloud services and remote diagnostics.
+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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -59,7 +59,7 @@ device.
 4.1.5 Manufacturing Partition
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-The ESP Matter SDK uses a separate manufacturing partition to store all the information
+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
 will also be unique per device. Thus by moving all the typical per device unique fields into
 the manufacturing partition, the rest of the components like the bootloader, firmware image
@@ -80,7 +80,7 @@ Matter devices must support OTA firmware updates, either by using Matter-based O
 or vendor specific means.

 In case of Matter OTA, there's an *OTA provider* that
-assists an *OTA requestor* to get upgraded. ESP Matter examples support Matter OTA
+assists an *OTA requestor* to get upgraded. The SDK examples support Matter OTA
 requestor role out of the box. The OTA provider could be a manufacturer specific
 phone app or any Matter node that has internet connectivity.

@@ -106,7 +106,7 @@ on a per-device basis for mass manufacturing purposes.

 When using the utility, by default, the above details will be included in the generated manufacturing partition image. The utility also has a provision to include additional details in the same image by using CSV files.

-Details about using the ESP Matter mass manufacturing utility can be found here:
+Details about using the mass manufacturing utility can be found here:
 :project_file:`mfg_tool<tools/mfg_tool/README.md>`.

 4.3.2 Pre-Provisioned Modules
@@ -63,7 +63,7 @@ extern "C" void app_main()
    /* Initialize the ESP NVS layer */
    nvs_flash_init();

-    /* Create a Matter node */
+    /* Create a Matter node and add the mandatory Root Node device type on endpoint 0 */
    node::config_t node_config;
    node_t *node = node::create(&node_config, app_attribute_update_cb, NULL);

@@ -79,7 +79,7 @@ extern "C" void app_main()
    app_driver_handle_t button_handle = app_driver_button_init();
    app_reset_button_register(button_handle);

-    /* Create a Matter node */
+    /* Create a Matter node and add the mandatory Root Node device type on endpoint 0 */
    node::config_t node_config;
    node_t *node = node::create(&node_config, app_attribute_update_cb, app_identification_cb);

@@ -77,7 +77,7 @@ extern "C" void app_main()
    app_driver_handle_t switch_handle = app_driver_switch_init();
    app_reset_button_register(switch_handle);

-    /* Create a Matter node */
+    /* Create a Matter node and add the mandatory Root Node device type on endpoint 0 */
    node::config_t node_config;
    node_t *node = node::create(&node_config, app_attribute_update_cb, app_identification_cb);

@@ -62,7 +62,7 @@ extern "C" void app_main()
    /* Initialize the ESP NVS layer */
    nvs_flash_init();

-    /* Create a Matter node */
+    /* Create a Matter node and add the mandatory Root Node device type on endpoint 0 */
    node::config_t node_config;
    node_t *node = node::create(&node_config, app_attribute_update_cb, NULL);