docs: add more description for platform solutions and H2 examples

2026-04-27 19:13:13 +00:00 · 2022-05-20 10:34:10 +08:00
parent 76d45474f0
commit ab1d30a2cb
10 changed files with 214 additions and 46 deletions
@@ -155,7 +155,7 @@ build_docs:
    script:
        - cd docs
        - pip install -r requirements.txt
-        - build-docs -t esp32c3 esp32 -l en
+        - build-docs -t esp32 esp32c3 esp32h2 -l en

 .deploy_docs_template:
    stage: docs
@@ -22,12 +22,23 @@ host. Linux and Mac OS-X are the supported development hosts in Matter.
 2.1.2 Getting the Repositories
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-::
+.. only:: esp32 or esp32c3

-   git clone --recursive https://github.com/espressif/esp-idf.git
-   cd esp-idf; git checkout v4.4.1; git submodule update --init --recursive;
-   ./install.sh
-   cd ..
+   ::
+
+      git clone --recursive https://github.com/espressif/esp-idf.git
+      cd esp-idf; git checkout v4.4.1; git submodule update --init --recursive;
+      ./install.sh
+      cd ..
+
+.. only:: esp32h2
+
+   ::
+
+      git clone --recursive https://github.com/espressif/esp-idf.git
+      cd esp-idf; git checkout 047903c; git submodule update --init --recursive;
+      ./install.sh
+      cd ..

 ::

@@ -57,24 +68,30 @@ for it to work. Check the example's "Additional Environment Setup" section for m
   RainMaker Light <examples/rainmaker_light>
   Switch <examples/switch>
   Zap Light <examples/zap_light>
-   Zigbee Bridge <examples/bridge_zigbee>
+   ZigBee Bridge <examples/bridge_zigbee>

 2.1.5 Flashing the Firmware
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Choose IDF target.

+.. only:: esp32
+
+   ::
+
+      idf.py set-target esp32
+
 .. only:: esp32c3

   ::

      idf.py set-target esp32c3

-.. only:: esp32
+.. only:: esp32h2

   ::

-      idf.py set-target esp32
+      idf.py --preview set-target esp32h2

 -  If IDF target has not been set explicitly, then ``esp32`` is
   considered as default.
@@ -114,6 +131,9 @@ Choose IDF target.
 2.2 Commissioning and Control
 -----------------------------

+-  For a Wi-Fi device, a Wi-Fi AP which supports IPv6 is required.
+-  For a Thread device, a Thread Border Router is required.
+
 2.2.1 Test Setup (Python Controller Setup)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

@@ -122,7 +142,7 @@ The Python Controller, also referred to as chip-tool can be used as a Matter cli
 2.2.1.1 Environment setup
 ^^^^^^^^^^^^^^^^^^^^^^^^^

-The environment setup should already have been done when the esp-matter/install.sh script was run. If the setup was done without using the script, the below commands can be run to build the chip-tool executable.
+The environment setup should already have been done when the *esp-matter/install.sh* script was run in the 'Getting the Repositories' section. If the setup was done without using the script, the below commands can be run to build the chip-tool executable.

 ::

@@ -136,10 +156,18 @@ The environment setup should already have been done when the esp-matter/install.

 Use ``chip-tool`` to pair the device:

+Pair a Wi-Fi Device over BLE:
+
 ::

   chip-tool pairing ble-wifi 1 <ssid> <password> 20202021 3840

+Pair a Thread Device over BLE:
+
+::
+
+   chip-tool pairing ble-thread 1 hex:<operationalDataset> 20202021 3840
+
 2.2.1.3 Post Commissioning Setup
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

@@ -153,7 +181,7 @@ for it to work. Check the example's "Post Commissioning Setup" section for more
   RainMaker Light <examples/rainmaker_light>
   Switch <examples/switch>
   Zap Light <examples/zap_light>
-   Zigbee Bridge <examples/bridge_zigbee>
+   ZigBee Bridge <examples/bridge_zigbee>


 2.2.1.4 Cluster Control
@@ -1,15 +1,117 @@
-Zigbee Bridge
+ZigBee Bridge
 =============

+The Matter Bridge device is composed of two parts: The RCP running on
+ESP32-H2 and the bridge app running on ESP32.
+
 1. Additional Environment Setup
 -------------------------------

-todo.
+1.1 Hardware connection
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Connect the two SoCs via UART, below is an example setup with ESP32
+DevKitC and ESP32-H2 DevKitC:
+
+.. figure:: ../../_static/zigbee_bridge_hardware_connection.jpg
+    :align: center
+    :alt: ZigBee Bridge Hardware Connection
+    :figclass: align-center
+
+========= ============
+ESP32 Pin ESP32-H2 Pin
+========= ============
+GND       GND
+GPIO4     GPIO7
+GPIO5     GPIO8
+========= ============
+
+1.2 Build and flash the RCP (ESP32-H2)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+   cd ${IDF_PATH}/examples/zigbee/esp_zigbee_rcp/
+   idf.py --preview set-target esp32h2
+   idf.py -p <port> build flash
+
+The Matter Bridge will run on the ESP32 and ZigBee network will be
+formed.

 2. Post Commissioning Setup
 ---------------------------

-todo.
+2.1 Discovering Zigbee Devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can read the parts list from the Bridge to get the number of the bridged devices.
+
+::
+
+   chip-tool descriptor read parts-list 1 0
+
+If there is no other ZigBee device on the ZigBee Network, you will get
+an empty result. Example:
+
+::
+
+   Data = [
+
+   ],
+
+
+2.2 Setup ZigBee Bulb on ESP32-H2
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Build and run ZigBee Bulb app on another ESP32-H2 board.
+
+::
+
+   cd ${IDF_PATH}/examples/zigbee/light_sample/light_bulb
+   idf.py --preview set-target esp32h2
+   idf.py -p <port> build flash monitor
+
+The ZigBee Bulb will be added to the ZigBee Network and a dynamic
+endpoint will be added on the Bridge device. You can read the parts list
+again to get the dynamic endpoint ID.
+
+::
+
+   chip-tool descriptor read parts-list 1 0
+
+The data will now contain the information of the connected ZigBee devices. Example:
+
+::
+
+   Data = [
+      1, 
+   ],
+
+It means that the ZigBee Bulb is added as Endpoint 1 on the Bridge
+device. You can read the cluster servers list on the dynamic endpoint.
+
+::
+
+   chip-tool descriptor read server-list 1 1
+
+This will give the list of supported server clusters. Example:
+
+::
+
+   OnDescriptorServerListListAttributeResponse: 4 entries
+     [1]: 6
+     [2]: 29
+     [3]: 57
+     [4]: 64
+
+2.3 Control the bulb with chip-tool
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now you can control the ZigBee bulb using the chip tool.
+
+::
+
+   chip-tool onoff toggle 1 1

 3. Device Performance
 ---------------------
@@ -16,8 +16,8 @@ also be edited.

 ::

-   $ cd esp-matter/connectedhomeip/connectedhomeip
-   $ ./scripts/tools/zap/run_zaptool.sh <optional_existing_zap_file>
+   cd esp-matter/connectedhomeip/connectedhomeip
+   ./scripts/tools/zap/run_zaptool.sh <optional_existing_zap_file>

 -  If this command fails, run it again.
 -  Once the customization is done, click on 'save' to save the .zap
@@ -28,7 +28,7 @@ command:

 ::

-   $ ./scripts/tools/zap/generate.py /path/to/<saved>.zap -o /path/to/<output_folder>
+   ./scripts/tools/zap/generate.py /path/to/<saved>.zap -o /path/to/<output_folder>

 Now the files in zap_light/main/zap-generated can be replaced with the
 new generated files.
@@ -150,4 +150,4 @@ The LED on my devkit is not working:
   RainMaker Light <examples/rainmaker_light>
   Switch <examples/switch>
   Zap Light <examples/zap_light>
-   Zigbee Bridge <examples/bridge_zigbee>
+   ZigBee Bridge <examples/bridge_zigbee>
@@ -1,43 +1,82 @@
 1. Introduction
 ===============

-1.1 Solution Architecture
-------------------------
+1.1 One-stop Matter Solution
+----------------------------

-The typical solution architecture of the product is shown as below.
+Espressif's **One-stop Matter Solution** consists of:
+
+   - A Full Spectrum of Matter Device Platforms
+   - Production ready ESP Matter SDK
+   - Matter and ESP RainMaker Ecosystem Solution
+
+todo. Add an image similar to the first diagram here: https://rainmaker.espressif.com/ and here: https://github.com/espressif/esp-va-sdk/tree/master#11-solution-architecture?

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

-todo. Add image. Add explanation.
+1.1.1 Espressif Matter Platforms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-1.2 The Software
----------------
+Espressif provides a full spectrum Matter device platforms:

-todo. Add some general explanation.
+.. figure:: ../_static/esp_matter_platform.png
+    :align: center
+    :alt: ESP Matter 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.
+- ESP32-H SoCs and modules integrated with 802.15.4 can be used to build Matter Thread devices.
+- By efficiently combining ESP32-H and Espressif's Wi-Fi SoC, a Thread border router can be built to connect the Thread network with the Wi-Fi network to interconnect devices. Espressif provides hardware devkits, reference design and production-ready SDK, which supports the latest Thread 1.3 feature for Matter, and other features like coexist and OTA.
+- Espressif also provides 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 single SoC with both Wi-Fi and Bluetooth LE interfaces.
+
+1.1.2 ESP Matter SDK
+~~~~~~~~~~~~~~~~~~~~
+
+Espressif's Matter SDK is built on top of `connectedhomeip <https://github.com/project-chip/connectedhomeip/>`__, and integrates ESP Data Model APIs, Tools, Documentation, etc. It is a production ready Matter SDK with rich examples, which can simplify the development process of Matter products.

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

-The above block diagram indicates the various components of the ESP Matter SDK.
+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.

-1.3 Solutions
-------------
+1.1.3 Matter and ESP RainMaker Ecosystem Solution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-1.3.1 Simple Device
+Espressif's AIoT cloud platform `ESP RainMaker <https://rainmaker.espressif.com/>`__ can provide remote control for Matter devices and enable the Cloud-based device management of Matter devices' massive data resources.
+
+todo. Add a supported services diagram similar to the one ad the end of this page https://rainmaker.espressif.com/?
+
+By combining the above-mentioned Matter hardware and software solutions with ESP RainMaker, this one-stop Matter ecosystem solution provides:
+
+   -  Interconnection with Amazon, Google and Apple
+   -  Full-fledged Cloud deployment through own private account
+   -  Privately deployable cloud applications
+   -  Ready-made phone apps supporting all common smart-home scenarios and voice-assistant integrations
+
+Relying on the privatization feature of ESP RainMaker, manufacturers
+can even build their own brand of an IoT ecosystem, and provide more value-added services to end customers
+through their own cloud services.
+
+1.2 Matter Devices
+------------------
+
+1.2.1 Simple Device
 ~~~~~~~~~~~~~~~~~~~

 These are typically basic/simple devices.

+todo. list all supported device types that listed in Matter device library spec.
+
   -  Light Bulb
   -  Switch
   -  Temperature sensor

-1.3.2 Multi-Device
+1.2.2 Multi-Device
 ~~~~~~~~~~~~~~~~~~

 These are a combination of more than one simple devices.
@@ -45,22 +84,22 @@ These are a combination of more than one simple devices.
   -  Fan with Light
   -  Temperature sensor and Proximity sensor

-1.3.3 Bridge
+1.2.3 Bridge
 ~~~~~~~~~~~~

 These devices facilitate using non-Matter devices in a Matter network.

-   -  Zigbee bridge
+   -  ZigBee bridge
   -  BLE mesh bridge

-1.3.4 Thread Border Router
+1.2.4 Thread Border Router
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

 These devices typically connect a Thread network to other IP-based networks, such as Wi-Fi or Ethernet.

   -  https://github.com/espressif/esp-idf/tree/master/examples/openthread/ot_br

-1.3.5 Hub
+1.2.5 Hub
 ~~~~~~~~~

 These can be used to control other Matter devices.
@@ -68,16 +107,16 @@ These can be used to control other Matter devices.
   -  Touch-screen control panel
   -  Hub with internet connectivity for remote control

-1.4 Examples
+1.3 Examples
 ------------

-1.4.1 Light
+1.3.1 Light
 ~~~~~~~~~~~

 This application creates a Color Dimmable Light device using the ESP
 Matter data model.

-1.4.2 RainMaker Light
+1.3.2 RainMaker Light
 ~~~~~~~~~~~~~~~~~~~~~

 This application creates a Color Dimmable Light device using the ESP
@@ -87,7 +126,7 @@ It also initializes ESP RainMaker which enables Device Management and
 OTA using the RainMaker cloud. If user node association is done, it also
 enables Remote Control through RainMaker.

-1.4.3 Switch
+1.3.3 Switch
 ~~~~~~~~~~~~

 This application creates an On/Off Light Switch device using the ESP Matter
@@ -96,21 +135,21 @@ data model.
 It creates the On/Off client and other devices can be binded to the
 switch and then controlled from the switch.

-1.4.4 Zap Light
+1.3.4 Zap Light
 ~~~~~~~~~~~~~~~

 This application creates a Color Dimmable Light device using the Zap
 data model instead of the ESP Matter data model.

-1.4.5 Zigbee Bridge
+1.3.5 ZigBee Bridge
 ~~~~~~~~~~~~~~~~~~~

-todo.
+This application demonstrates a Matter-ZigBee Bridge that bridges ZigBee devices to Matter fabric.

-1.5 Try it yourself
+1.4 Try it yourself
 -------------------

-1.5.1 ESP Launchpad
+1.4.1 ESP Launchpad
 ~~~~~~~~~~~~~~~~~~~

 This allows you to quickly try out Matter on Espressif devices through a web browser.
@@ -1,9 +1,7 @@
-# Bridge Example
+# Zigbee Bridge Example

 ## Building and Flashing the Firmware

-This example should be built on IDF commit [b05b70c7f3](https://github.com/espressif/esp-idf/tree/b05b70c7f39a45b9bb8d09498b45edbe3b7bfc22)
-
 See the [README.md](../../README.md) file for more information about building and flashing the firmware.

 The Matter Bridge device is composed of two parts: The RCP running on ESP32-H2 and the bridge app
@@ -12,6 +10,7 @@ running on ESP32.
 ### Hardware connection

 Connect the two SoCs via UART, below is an example setup with ESP32 DevKitC and ESP32-H2 DevKitC:
+![zigbee_bridge](../docs/_static/esp32-esp32h2.jpg)

  ESP32 Pin  | ESP32-H2 Pin
 -------------|--------------