From 0e1a62d4ee5d9c26a0ba132ac38bee585ce7e082 Mon Sep 17 00:00:00 2001 From: Hrishikesh Dhayagude Date: Mon, 22 Aug 2022 17:44:14 +0530 Subject: [PATCH] Minor changes to the documentation --- docs/Doxyfile | 2 +- docs/README.md | 4 +- ...atform.png => esp_sdk_matter_platform.png} | Bin ..._versions.js => esp_sdk_matter_version.js} | 0 docs/conf_common.py | 2 +- docs/en/conf.py | 4 +- docs/en/developing.rst | 43 ++++++++++-------- docs/en/faq.rst | 2 +- docs/en/index.rst | 8 ++-- docs/en/introduction.rst | 18 ++++---- docs/en/production.rst | 6 +-- examples/blemesh_bridge/main/app_main.cpp | 2 +- examples/light/main/app_main.cpp | 2 +- examples/light_switch/main/app_main.cpp | 2 +- examples/zigbee_bridge/main/app_main.cpp | 2 +- 15 files changed, 52 insertions(+), 45 deletions(-) rename docs/_static/{esp_matter_platform.png => esp_sdk_matter_platform.png} (100%) rename docs/_static/{esp_matter_versions.js => esp_sdk_matter_version.js} (100%) diff --git a/docs/Doxyfile b/docs/Doxyfile index ed981aafd..f53d15e12 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -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 diff --git a/docs/README.md b/docs/README.md index 54abbc353..5aa67ef40 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. diff --git a/docs/_static/esp_matter_platform.png b/docs/_static/esp_sdk_matter_platform.png similarity index 100% rename from docs/_static/esp_matter_platform.png rename to docs/_static/esp_sdk_matter_platform.png diff --git a/docs/_static/esp_matter_versions.js b/docs/_static/esp_sdk_matter_version.js similarity index 100% rename from docs/_static/esp_matter_versions.js rename to docs/_static/esp_sdk_matter_version.js diff --git a/docs/conf_common.py b/docs/conf_common.py index de69d9875..6d2c69435 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -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' diff --git a/docs/en/conf.py b/docs/en/conf.py index 8592aa102..548fecd2a 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -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. diff --git a/docs/en/developing.rst b/docs/en/developing.rst index 0ffd3d8c2..6bedc2674 100644 --- a/docs/en/developing.rst +++ b/docs/en/developing.rst @@ -1,8 +1,8 @@ -2. Developing with ESP Matter -============================= +2. Developing with the SDK +========================== Please refer the :project_file:`Release Notes ` 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 20202021 3840 + pairing ble-wifi 0x7283 20202021 3840 .. only:: esp32h2 :: - chip-tool pairing ble-thread 0x7283 hex: 20202021 3840 + pairing ble-thread 0x7283 hex: 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/faq.rst b/docs/en/faq.rst index ee813b43b..903d4aecf 100644 --- a/docs/en/faq.rst +++ b/docs/en/faq.rst @@ -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 diff --git a/docs/en/index.rst b/docs/en/index.rst index dc3c9b7e2..a7d685e00 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -1,12 +1,12 @@ -ESP Matter Programming Guide -============================ +Programming Guide +================= `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 `__. @@ -18,7 +18,7 @@ Table of Contents :maxdepth: 2 1. Introduction - 2. Developing with ESP Matter + 2. Developing with the SDK 3. Matter Certification 4. Production Considerations 5. API Reference diff --git a/docs/en/introduction.rst b/docs/en/introduction.rst index 5145d1618..69a80663b 100644 --- a/docs/en/introduction.rst +++ b/docs/en/introduction.rst @@ -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 `__, 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 `__, 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 `__ and `ESP Insights `__ for cloud services and remote diagnostics. +In addition, the SDK also integrates `ESP RainMaker `__ and `ESP Insights `__ for cloud services and remote diagnostics. 1.1.3 Matter and ESP RainMaker Integration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/en/production.rst b/docs/en/production.rst index 5d8c79910..b2bd468a6 100644 --- a/docs/en/production.rst +++ b/docs/en/production.rst @@ -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`. 4.3.2 Pre-Provisioned Modules diff --git a/examples/blemesh_bridge/main/app_main.cpp b/examples/blemesh_bridge/main/app_main.cpp index f9774710b..0509252d6 100644 --- a/examples/blemesh_bridge/main/app_main.cpp +++ b/examples/blemesh_bridge/main/app_main.cpp @@ -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); diff --git a/examples/light/main/app_main.cpp b/examples/light/main/app_main.cpp index 82be6fb8a..04b37dafe 100644 --- a/examples/light/main/app_main.cpp +++ b/examples/light/main/app_main.cpp @@ -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); diff --git a/examples/light_switch/main/app_main.cpp b/examples/light_switch/main/app_main.cpp index 2d57e5956..ce25772a4 100644 --- a/examples/light_switch/main/app_main.cpp +++ b/examples/light_switch/main/app_main.cpp @@ -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); diff --git a/examples/zigbee_bridge/main/app_main.cpp b/examples/zigbee_bridge/main/app_main.cpp index 770fe50aa..1cf6b5af6 100644 --- a/examples/zigbee_bridge/main/app_main.cpp +++ b/examples/zigbee_bridge/main/app_main.cpp @@ -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);