diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 0130bcffe..389c3e916 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -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 diff --git a/docs/_static/esp_matter_platform.png b/docs/_static/esp_matter_platform.png new file mode 100644 index 000000000..9196d7a77 Binary files /dev/null and b/docs/_static/esp_matter_platform.png differ diff --git a/docs/_static/software_components.png b/docs/_static/software_components.png index 7bda8a71a..4da02fd8b 100644 Binary files a/docs/_static/software_components.png and b/docs/_static/software_components.png differ diff --git a/docs/_static/zigbee_bridge_hardware_connection.jpg b/docs/_static/zigbee_bridge_hardware_connection.jpg new file mode 100644 index 000000000..91f67f5a8 Binary files /dev/null and b/docs/_static/zigbee_bridge_hardware_connection.jpg differ diff --git a/docs/en/developing.rst b/docs/en/developing.rst index 0c0e48c3d..b8edb9e5f 100644 --- a/docs/en/developing.rst +++ b/docs/en/developing.rst @@ -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 Switch Zap Light - Zigbee Bridge + ZigBee Bridge 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 20202021 3840 +Pair a Thread Device over BLE: + +:: + + chip-tool pairing ble-thread 1 hex: 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 Switch Zap Light - Zigbee Bridge + ZigBee Bridge 2.2.1.4 Cluster Control diff --git a/docs/en/examples/bridge_zigbee.rst b/docs/en/examples/bridge_zigbee.rst index caa4590c5..2027a5500 100644 --- a/docs/en/examples/bridge_zigbee.rst +++ b/docs/en/examples/bridge_zigbee.rst @@ -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 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 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 --------------------- diff --git a/docs/en/examples/zap_light.rst b/docs/en/examples/zap_light.rst index 4ba8b530b..cdfffbc4a 100644 --- a/docs/en/examples/zap_light.rst +++ b/docs/en/examples/zap_light.rst @@ -16,8 +16,8 @@ also be edited. :: - $ cd esp-matter/connectedhomeip/connectedhomeip - $ ./scripts/tools/zap/run_zaptool.sh + cd esp-matter/connectedhomeip/connectedhomeip + ./scripts/tools/zap/run_zaptool.sh - 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/.zap -o /path/to/ + ./scripts/tools/zap/generate.py /path/to/.zap -o /path/to/ Now the files in zap_light/main/zap-generated can be replaced with the new generated files. diff --git a/docs/en/faq.rst b/docs/en/faq.rst index ab6dd5722..8e6547cda 100644 --- a/docs/en/faq.rst +++ b/docs/en/faq.rst @@ -150,4 +150,4 @@ The LED on my devkit is not working: RainMaker Light Switch Zap Light - Zigbee Bridge + ZigBee Bridge diff --git a/docs/en/introduction.rst b/docs/en/introduction.rst index 928bf24f0..ec5c1d10b 100644 --- a/docs/en/introduction.rst +++ b/docs/en/introduction.rst @@ -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 `__, 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 `__ and `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 `__ 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. diff --git a/examples/bridge_zigbee/README.md b/examples/bridge_zigbee/README.md index 70b2035db..236a93f42 100644 --- a/examples/bridge_zigbee/README.md +++ b/examples/bridge_zigbee/README.md @@ -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 -------------|--------------