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: Minor docs changes

Browse Source 
readme: Replacing the example rst files in the docs with the readme files in the example directories.
This commit is contained in:
Chirag Atal
2022-05-24 14:37:18 +05:30
committed by Shu Chen
parent a14fb95d08
commit 2e91ab095f
19 changed files with 412 additions and 923 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/developing.rst
+29 -30
View File
@@ -1,7 +1,7 @@
2. Developing with ESP Matter
=============================
Please refer to :project_file:`CHANGELOG.md` to track release changes
Please refer to :project_file:`Changelog <CHANGELOG.md>` to track release changes
and known-issues.
2.1 Development Setup
@@ -61,14 +61,11 @@ host. Linux and Mac OS-X are the supported development hosts in Matter.
The device would need additional configuration depending on the example,
for it to work. Check the example's "Additional Environment Setup" section for more information.
.. toctree::
:maxdepth: 1
Light <examples/light>
Light Switch <examples/light_switch>
RainMaker Light <examples/rainmaker_light>
Zap Light <examples/zap_light>
ZigBee Bridge <examples/zigbee_bridge>
- :project_file:`Light <examples/light/README.md>`
- :project_file:`Light Switch <examples/light_switch/README.md>`
- :project_file:`RainMaker Light <examples/rainmaker_light/README.md>`
- :project_file:`Zap Light <examples/zap_light/README.md>`
- :project_file:`ZigBee Bridge <examples/zigbee_bridge/README.md>`
2.1.5 Flashing the Firmware
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -160,13 +157,19 @@ Pair a Wi-Fi Device over BLE:
::
chip-tool pairing ble-wifi 1 <ssid> <password> 20202021 3840
chip-tool pairing ble-wifi 0x7283 <ssid> <password> 20202021 3840
Pair a Thread Device over BLE:
::
chip-tool pairing ble-thread 1 hex:<operationalDataset> 20202021 3840
chip-tool pairing ble-thread 0x7283 hex:<operationalDataset> 20202021 3840
In the above commands:
- ``0x7283`` is the randomly generated ``node_id``
- ``20202021`` is the ``setup_pin_code``
- ``3840`` is the ``discriminator``
2.2.1.3 Post Commissioning Setup
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -174,15 +177,11 @@ Pair a Thread Device over BLE:
The device would need additional configuration depending on the example,
for it to work. Check the example's "Post Commissioning Setup" section for more information.
.. toctree::
:maxdepth: 1
Light <examples/light>
Light Switch <examples/light_switch>
RainMaker Light <examples/rainmaker_light>
Zap Light <examples/zap_light>
ZigBee Bridge <examples/zigbee_bridge>
- :project_file:`Light <examples/light/README.md>`
- :project_file:`Light Switch <examples/light_switch/README.md>`
- :project_file:`RainMaker Light <examples/rainmaker_light/README.md>`
- :project_file:`Zap Light <examples/zap_light/README.md>`
- :project_file:`ZigBee Bridge <examples/zigbee_bridge/README.md>`
2.2.1.4 Cluster Control
^^^^^^^^^^^^^^^^^^^^^^^
@@ -191,27 +190,27 @@ Use the cluster commands to control the attributes.
::
chip-tool onoff toggle 1 1
chip-tool onoff toggle 0x7283 0x1
::
chip-tool onoff on 1 1
chip-tool onoff on 0x7283 0x1
::
chip-tool levelcontrol move-to-level 10 0 0 0 1 1
chip-tool levelcontrol move-to-level 10 0 0 0 0x7283 0x1
::
chip-tool levelcontrol move-to-level 100 0 0 0 1 1
chip-tool levelcontrol move-to-level 100 0 0 0 0x7283 0x1
::
chip-tool colorcontrol move-to-saturation 200 0 0 0 1 1
chip-tool colorcontrol move-to-saturation 200 0 0 0 0x7283 0x1
::
chip-tool colorcontrol move-to-hue 150 0 0 0 0 1 1
chip-tool colorcontrol move-to-hue 150 0 0 0 0 0x7283 0x1
For more chip-tool usage, check https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool
@@ -315,7 +314,7 @@ the terms like endpoints, clusters, etc. that are used in this section.
node_t *node = node::create(&node_config, app_attribute_update_cb, NULL);
- We will use the ``color_dimmable_light`` standard device type in this
case. All standard device types are available in :project_file:`components/esp_matter/esp_matter_endpoint.h` header file.
case. All standard device types are available in :project_file:`esp_matter_endpoint.h <components/esp_matter/esp_matter_endpoint.h>` header file.
Each device type has a set of default configuration that can be
specific as well.
@@ -585,7 +584,7 @@ path conventions.
2.4.4.2 Modifying the BUILD.gn target
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There is an example :project_file:`examples/common/external_platform/BUILD.gn` file for
There is an example :project_file:`BUILD.gn <examples/common/external_platform/BUILD.gn>` file for
the ``ESP32_custom`` example platform. It simply compiles the ESP32
platform in Matter without any modifications.
@@ -664,7 +663,7 @@ If the Button driver that you wish to use is not part of Espressif's
supported list, you can write a driver for it yourself.
A reference hollow_button is available within the SDK at
:project_file:`device_hal/button_driver/hollow_button/button_driver.c`. This includes all
:project_file:`hollow_button/button_driver.c <device_hal/button_driver/hollow_button/button_driver.c>`. This includes all
the skeletal code and the empty APIs that the button driver is supposed
to implement to plug into the SDK.
@@ -708,7 +707,7 @@ If the LED driver that you wish to use is not part of Espressif's
supported list, you can write a driver for it yourself.
A reference hollow_led is available within the SDK at
:project_file:`device_hal/led_driver/hollow_led/led_driver.c`. This includes all the
:project_file:`hollow_led/led_driver.c <device_hal/led_driver/hollow_led/led_driver.c>`. This includes all the
skeletal code and the empty APIs that the LED driver is supposed to
implement to plug into the SDK.
docs/en/examples/light.rst
-39
View File
@@ -1,39 +0,0 @@
Light
=====
1. Additional Environment Setup
-------------------------------
No additional setup is required.
2. Post Commissioning Setup
---------------------------
No additional setup is required.
3. Device Performance
---------------------
3.1 CPU and Memory usage
~~~~~~~~~~~~~~~~~~~~~~~~
The following is the CPU and Memory Usage.
- ``Bootup`` == Device just finished booting up. Device is not
commissionined or connected to wifi yet.
- ``After Commissioning`` == Device is conneted to wifi and is also
commissioned and is rebooted.
- device used: esp32c3_devkit_m
- tested on: `bd951b8 <https://github.com/espressif/esp-matter/commit/bd951b84993d9d0b5742872be4f51bb6c9ccf15e>`__ (2022-05-05)
======================== =========== ===================
\ Bootup After Commissioning
======================== =========== ===================
**Free Internal Memory** 109KB 105KB
**CPU Usage** \- \-
======================== =========== ===================
**Flash Usage**: Firmware binary size: 1.26MB
This should give you a good idea about the amount of CPU and free memory
that is available for you to run your application's code.
docs/en/examples/light_switch.rst
-130
View File
@@ -1,130 +0,0 @@
Light Switch
============
1. Additional Environment Setup
-------------------------------
No additional setup is required.
2. Post Commissioning Setup
---------------------------
2.1 Bind light to switch
~~~~~~~~~~~~~~~~~~~~~~~~
Using the chip-tool, commission 2 devices, the switch and a light. Then
use the below commands to bind the light to the switch.
For the commands below:
- Node Id of switch used during commissioning is 1
- Node Id of light used during commissioning is 2
- Cluster Id for OnOff cluster is 6
- Binding cluster is currently present on endpoint 1 on the switch
Update the light's acl attribute to add the entry of remote device
(switch) in the access control list:
::
chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [ 112233, 1 ], "targets": null}]' 2 0
Update the switch's binding attribute to add the entry of remote device
(light) in the binding table:
::
chip-tool binding write binding '[{"fabricIndex": 1, "node":2, "endpoint":1, "cluster":6}]' 1 1
2.2 Device console
~~~~~~~~~~~~~~~~~~
Switch specific console commands:
- Send command to all the binded devices on the specified cluster: (The IDs are in hex):
::
matter esp bound invoke <endpoint_id> <cluster_id> <command_id>
- Example: Off:
::
matter esp bound invoke 0x1 0x6 0x0
- Example: On:
::
matter esp bound invoke 0x1 0x6 0x1
- Example: Toggle:
::
matter esp bound invoke 0x1 0x6 0x2
3. Device Performance
---------------------
3.1 CPU and Memory usage
~~~~~~~~~~~~~~~~~~~~~~~~
The following is the CPU and Memory Usage.
- ``Bootup`` == Device just finished booting up. Device is not
commissionined or connected to wifi yet.
- ``After Commissioning`` == Device is conneted to wifi and is also
commissioned and is rebooted.
- device used: esp32c3_devkit_m
- tested on: `bd951b8 <https://github.com/espressif/esp-matter/commit/bd951b84993d9d0b5742872be4f51bb6c9ccf15e>`__ (2022-05-05)
======================== =========== ===================
\ Bootup After Commissioning
======================== =========== ===================
**Free Internal Memory** 113KB 110KB
**CPU Usage** \- \-
======================== =========== ===================
**Flash Usage**: Firmware binary size: 1.24MB
This should give you a good idea about the amount of CPU and free memory
that is available for you to run your application's code.
A2 Appendix FAQs
----------------
A2.1 Binding Failed
~~~~~~~~~~~~~~~~~~~
My light is not getting binded to my switch:
- Make sure the light's acl is updated. You can read it again to make
sure it is correct:
``chip-tool accesscontrol read acl 2 0``.
- If you are still facing issues, reproduce the issue on the default
example for the device and then raise an `issue <https://github.com/espressif/esp-matter/issues>`. Make sure
to share these:
- The complete device logs for both the devices taken over UART.
- The complete chip-tool logs.
- The esp-matter and esp-idf branch you are using.
A2.2 Command Send Failed
~~~~~~~~~~~~~~~~~~~~~~~~
I cannot send commands to the light from my switch:
- Make sure the binding command was a success.
- Make sure you are passing the local endpoint_id, and not the remote
endpoint_id, to the cluster_update() API.
- If using device console, make sure you are running the ``bound invoke``
command and not the ``client invoke`` command. The client commands are for devices
which have not been binded.
- If you are still facing issues, reproduce the issue on the default
example for the device and then raise an `issue <https://github.com/espressif/esp-matter/issues>`. Make sure
to share these:
- The complete device logs for both the devices taken over UART.
- The complete chip-tool logs.
- The esp-matter and esp-idf branch you are using.
docs/en/examples/rainmaker_light.rst
-147
View File
@@ -1,147 +0,0 @@
RainMaker Light
===============
1. Additional Environment Setup
-------------------------------
1.1 Getting the Repositories
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
git clone --recursive https://github.com/espressif/esp-rainmaker.git
Setup the RainMaker CLI from here:
https://rainmaker.espressif.com/docs/cli-setup.html
1.2 Configuring the Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
export ESP_RMAKER_PATH=/path/to/esp-rainmaker
1.3 RainMaker Claiming
~~~~~~~~~~~~~~~~~~~~~~
If self-claiming is not enabled/supported, this need to be done before
flashing the firmware.
RainMaker CLI:
::
cd $ESP_RMAKER_PATH/cli
rainmaker.py claim --addr 0x3E0000 $ESPPORT
2. Post Commissioning Setup
---------------------------
2.1 RainMaker User-Node Association
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This needs to be done after commissioning.
Check if the device already has user node association done, using the
custom RainMaker cluster (cluster_id: 0x131b0000):
::
chip-tool any read-by-id 0x131b0000 0x0 0x1 0x0
- If the above custom status attribute (attribute_id: 0x0) returns
true, the association has already been done.
- If the attribute returns false, the association has not been done.
And the below custom configuration command (command_id: 0x0) can be
used to do the association.
Get the RainMaker node id (attribute_id: 0x1):
::
chip-tool any read-by-id 0x131b0000 0x1 0x1 0x0
RainMaker CLI:
Trigger user-node association using the above rainmaker-node-id: This will print the user-id and secret-key (do not close this):
::
rainmaker.py test --addnode <rainmaker-node-id>
>> add-user <user-id> <secret-key>
Prepare the command payload using the above details:
::
payload: <user-id>::<secret-key>
Now use the payload to run the RainMaker configuration command from
chip-tool:
::
chip-tool any command-by-id 0x131b0000 0x0 '"<user-id>::<secret-key>"' 0x1 0x0
The device/node should now be associated with the user.
2.2 Device console
~~~~~~~~~~~~~~~~~~
RainMaker specific console commands:
- User Node Association:
::
matter esp rainmaker add-user <user-id> <secret-key>
3. Device Performance
---------------------
3.1 CPU and Memory usage
~~~~~~~~~~~~~~~~~~~~~~~~
The following is the CPU and Memory Usage.
- ``Bootup`` == Device just finished booting up. Device is not
commissionined or connected to wifi yet.
- ``After Commissioning`` == Device is conneted to wifi and is also
commissioned and is rebooted.
- device used: esp32c3_devkit_m
- tested on: `bd951b8 <https://github.com/espressif/esp-matter/commit/bd951b84993d9d0b5742872be4f51bb6c9ccf15e>`__ (2022-05-05)
======================== =========== ===================
\ Bootup After Commissioning
======================== =========== ===================
**Free Internal Memory** 87KB 65KB
**CPU Usage** \- \-
======================== =========== ===================
**Flash Usage**: Firmware binary size: 1.52MB
This should give you a good idea about the amount of CPU and free memory
that is available for you to run your application's code.
A2 Appendix FAQs
----------------
A2.1 User Node association is failing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
User Node association is failing on my device:
- Make sure the device has been claimed.
- If the device prints “This command has reached a limit”, reboot the
device to run the command again.
- Read the status attribute:
``chip-tool any read-by-id 0x131b0000 0x0 0x1 0x0``. If
this custom status attribute (attribute_id: 0x0) returns true, the
association has already been done.
- If you are still facing issues, reproduce the issue on the default
example for the device and then raise an `issue <https://github.com/espressif/esp-matter/issues>`. Make sure
to share these:
- The complete device logs taken over UART.
- The esp-matter, esp-idf and esp-rainmaker branch you are using.
docs/en/examples/zap_light.rst
-97
View File
@@ -1,97 +0,0 @@
Zap Light
=========
1. Additional Environment Setup
-------------------------------
This example uses the Zap data model from zap-generated instead of using
the ESP Matter data model.
1.1 Customization
~~~~~~~~~~~~~~~~~
For customizing the 'device', the zap-tool can be used to create the
``.zap`` file, if you don't already have one. An existing .zap file can
also be edited.
::
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
file.
The other zap-generated files can be generated using the generate
command:
::
./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.
2. Post Commissioning Setup
---------------------------
No additional setup is required.
3. Device Performance
---------------------
3.1 CPU and Memory usage
~~~~~~~~~~~~~~~~~~~~~~~~
The following is the CPU and Memory Usage.
- ``Bootup`` == Device just finished booting up. Device is not
commissionined or connected to wifi yet.
- ``After Commissioning`` == Device is conneted to wifi and is also
commissioned and is rebooted.
- device used: esp32c3_devkit_m
- tested on: `bd951b8 <https://github.com/espressif/esp-matter/commit/bd951b84993d9d0b5742872be4f51bb6c9ccf15e>`__ (2022-05-05)
======================== =========== ===================
\ Bootup After Commissioning
======================== =========== ===================
**Free Internal Memory** 121KB 118KB
**CPU Usage** \- \-
======================== =========== ===================
**Flash Usage**: Firmware binary size: 1.24MB
This should give you a good idea about the amount of CPU and free memory
that is available for you to run your application's code.
A2 Appendix FAQs
----------------
A2.1 Zaptool is not working
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The run_zaptool.py command is failing:
- Check that the connectedhomeip submodule is updated.
- Revert any modifications in any of te files in the connectedhomeip
submodule, or any submodules in connectedhomeip, and try again.
- If you are still facing issues, reproduce the issue on the default
example for the device and then raise an `issue <https://github.com/espressif/esp-matter/issues>`. Make sure
to share these:
- The complete logs for the command.
- The esp-matter and esp-idf branch you are using.
A2.2 Missing files in zap-generated
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some files are not generated on running the generate command
(generate.py):
- This can happen depending on your zap configuration, and it should be
okay to use the file which was already present in zap-generated.
- We have observed that af-gen-event.h does not get generated on
running the generate command.
- If the file is missing from the zap-generated folder, there might be
other compilation errors of the file not being found.
docs/en/examples/zigbee_bridge.rst
-143
View File
@@ -1,143 +0,0 @@
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
-------------------------------
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
---------------------------
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
---------------------
3.1 CPU and Memory usage
~~~~~~~~~~~~~~~~~~~~~~~~
The following is the CPU and Memory Usage.
- ``Bootup`` == Device just finished booting up. Device is not
commissionined or connected to wifi yet.
- ``After Commissioning`` == Device is conneted to wifi and is also
commissioned and is rebooted.
- device used: esp32c3_devkit_m
- tested on: `bd951b8 <https://github.com/espressif/esp-matter/commit/bd951b84993d9d0b5742872be4f51bb6c9ccf15e>`__ (2022-05-05)
======================== =========== ===================
\ Bootup After Commissioning
======================== =========== ===================
**Free Internal Memory** 109KB 105KB
**CPU Usage** \- \-
======================== =========== ===================
**Flash Usage**: Firmware binary size: 1.26MB
This should give you a good idea about the amount of CPU and free memory
that is available for you to run your application's code.
todo. Update the values.
docs/en/faq.rst
+6 -9
View File
@@ -43,7 +43,7 @@ Bluetooth/BLE does not work on by device:
- Run the device console command:
``matter wifi connect <ssid> <password>``.
- Run the chip-tool command for commissioning over ip:
``chip-tool pairing onnetwork 1 20202021``.
``chip-tool pairing onnetwork 0x7283 20202021``.
- If you are still facing issues, reproduce it on the default
example for the device and then raise it `here <https://github.com/espressif/esp-matter/issues>`__. Make sure
@@ -142,11 +142,8 @@ The LED on my devkit is not working:
**Also check the "Appendix FAQs" sections of the respective examples.**
.. toctree::
:maxdepth: 1
Light <examples/light>
Light Switch <examples/light_switch>
RainMaker Light <examples/rainmaker_light>
Zap Light <examples/zap_light>
ZigBee Bridge <examples/zigbee_bridge>
- :project_file:`Light <examples/light/README.md>`
- :project_file:`Light Switch <examples/light_switch/README.md>`
- :project_file:`RainMaker Light <examples/rainmaker_light/README.md>`
- :project_file:`Zap Light <examples/zap_light/README.md>`
- :project_file:`ZigBee Bridge <examples/zigbee_bridge/README.md>`
docs/en/introduction.rst
+1 -1
View File
@@ -137,7 +137,7 @@ enables Remote Control through RainMaker.
This application creates an On/Off Light Switch device using the ESP Matter
data model.
It creates the On/Off client and other devices can be binded to the
It creates the On/Off client and other devices can be bound to the
switch and then controlled from the switch.
1.3.4 Zap Light
docs/en/production.rst
+1 -1
View File
@@ -33,7 +33,7 @@ per device. ESP-Matter provides a utility (mfg_tool.py) to create instances of t
When using the utility, by default, the above details will be included in the generated NVS partition image. The utility also has provision to include additional details in the same NVS image by using the config and value CSV files.
Details about using the ESP Matter mass manufacturing utility can be found here:
:project_file:`tools/mfg_tool/README.md`.
:project_file:`mfg_tool<tools/mfg_tool/README.md>`.
4.3.2 Pre-Provisioned Modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~