espressif/esp-matter
1
0
Fork 0
mirror of https://github.com/espressif/esp-matter.git synced 2026-04-27 19:13:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add more description for platform solutions and H2 examples

Browse Source
This commit is contained in:
Shu Chen
2022-05-20 10:34:10 +08:00
parent 76d45474f0
commit ab1d30a2cb
10 changed files with 214 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/_static/esp_matter_platform.png
Vendored
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 150 KiB

docs/_static/software_components.png
Vendored
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 79 KiB

docs/_static/zigbee_bridge_hardware_connection.jpg
Vendored
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 331 KiB

docs/en/developing.rst
+38 -10
View File
@@ -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
docs/en/examples/bridge_zigbee.rst
+105 -3
View File
@@ -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
---------------------
docs/en/examples/zap_light.rst
+3 -3
View File
@@ -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.
docs/en/faq.rst
+1 -1
View File
@@ -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>
docs/en/introduction.rst
+64 -25
View File
@@ -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.