mirror of
https://github.com/espressif/esp-matter.git
synced 2026-04-27 19:13:13 +00:00
docs: Minor docs changes
readme: Replacing the example rst files in the docs with the readme files in the example directories.
This commit is contained in:
Chirag Atal
Shu Chen
@@ -1,105 +1,3 @@
|
||||
# ESP Matter
|
||||
|
||||
[Matter](https://buildwithmatter.com/) is the unified IP-based connectivity protocol built on proven technologies, helping connect and build reliable, secure IoT ecosystems. This new technology and royalty-free connectivity standard enables communications among a wide range of smart devices.
|
||||
|
||||
ESP Matter is the official Matter development framework for the Espressif's ESP32 series SoCs.
|
||||
|
||||
## Development Setup
|
||||
|
||||
This sections talks about setting up your development host, fetching the git repositories, and instructions to build and flash.
|
||||
|
||||
### Host Setup
|
||||
|
||||
You should install drivers and support packages for your development host. Windows, Linux and Mac OS-X, are supported development hosts. Please see [Get Started](https://docs.espressif.com/projects/esp-idf/en/v4.3/esp32/index.html) for the host setup instructions.
|
||||
|
||||
### Getting the Repositories
|
||||
|
||||
This only needs to be done once:
|
||||
```
|
||||
$ git clone --recursive https://github.com/espressif/esp-idf.git
|
||||
$ cd esp-idf
|
||||
$ git checkout release/v4.4
|
||||
$ git submodule update --init --recursive
|
||||
$ ./install.sh
|
||||
$ cd ..
|
||||
|
||||
$ git clone --recursive https://glab.espressif.cn/esp-matter-preview/esp-matter.git
|
||||
$ cd esp-matter/connectedhomeip/connectedhomeip
|
||||
$ source scripts/bootstrap.sh
|
||||
```
|
||||
|
||||
### Configuring the environment
|
||||
|
||||
This needs to be done everytime a new terminal is opened:
|
||||
```
|
||||
$ cd /path/to/esp-idf
|
||||
$ . export.sh
|
||||
$ cd /path/to/esp-matter/
|
||||
$ . export.sh
|
||||
$ cd examples/light/
|
||||
|
||||
$ export ESPPORT=/dev/cu.SLAB_USBtoUART (or /dev/ttyUSB0 or /dev/ttyUSB1 on Linux or COMxx on MinGW)
|
||||
```
|
||||
|
||||
### Building and Flashing the Firmware
|
||||
|
||||
Choose IDF target.
|
||||
```
|
||||
idf.py set-target esp32c3 (or esp32 or other supported targets)
|
||||
```
|
||||
|
||||
* If IDF target has not been set explicitly, then `esp32` is considered as default.
|
||||
* The default device for `esp32`/`esp32c3` is `esp32-devkit-c`/`esp32c3-devkit-m`. If you want to use another device, you can export `ESP_MATTER_DEVICE_PATH` after choosing correct target, e.g for `m5stack` device:
|
||||
```
|
||||
$ export ESP_MATTER_DEVICE_PATH=/path/to/esp_matter/device_hal/device/m5stack
|
||||
```
|
||||
* If the device that you have is of a different revision, and is not working as expected, you can create a new device and export your device path.
|
||||
* The other peripheral components like led_driver, button_driver, etc are selected based on the device selected.
|
||||
* The configuration of the peripheral components can be found in `$ESP_MATTER_DEVICE_PATH/esp_matter_device.cmake`.
|
||||
|
||||
Build and flash:
|
||||
```
|
||||
$ idf.py build
|
||||
$ idf.py flash monitor
|
||||
```
|
||||
|
||||
* Note: If you are getting build errors like:
|
||||
```
|
||||
ERROR: This script was called from a virtual environment, can not create a virtual environment again
|
||||
```
|
||||
Run:
|
||||
```
|
||||
pip install -r $IDF_PATH/requirements.txt
|
||||
```
|
||||
|
||||
## Test Setup (Python Controller Setup)
|
||||
|
||||
### Environment setup
|
||||
|
||||
```
|
||||
$ cd esp-matter/connectedhomeip/connectedhomeip
|
||||
$ source ./scripts/activate.sh
|
||||
$ gn gen out/debug
|
||||
$ ninja -C out/debug
|
||||
|
||||
```
|
||||
|
||||
### Commissioning
|
||||
|
||||
Use `chip-tool` to pair the device:
|
||||
|
||||
```
|
||||
$ ./out/debug/chip-tool pairing ble-wifi 12344321 TESTSSID TESTPASSWD 0 20202021 3840
|
||||
```
|
||||
|
||||
### Cluster Control
|
||||
|
||||
Use the cluster commands to control the attributes.
|
||||
```
|
||||
$ ./out/debug/chip-tool onoff on 12344321 1
|
||||
$ ./out/debug/chip-tool levelcontrol move-to-level 10 0 0 0 12344321 1
|
||||
$ ./out/debug/chip-tool levelcontrol move-to-level 100 0 0 0 12344321 1
|
||||
$ ./out/debug/chip-tool colorcontrol move-to-saturation 200 0 0 0 12344321 1
|
||||
$ ./out/debug/chip-tool colorcontrol move-to-hue 150 0 0 0 0 12344321 1
|
||||
$ ./out/debug/chip-tool onoff toggle 12344321 1
|
||||
```
|
||||
See the [docs](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/index.html) for more information.
|
||||
|
||||
+29
-30
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+6
-9
@@ -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>`
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
+25
-49
@@ -1,62 +1,38 @@
|
||||
# Light Example
|
||||
# Light
|
||||
|
||||
## Building and Flashing the Firmware
|
||||
This example creates a Color Dimmable Light device using the ESP
|
||||
Matter data model.
|
||||
|
||||
See the [README.md](../../README.md) file for more information about building and flashing the firmware.
|
||||
See the [docs](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html) for more information about building and flashing the firmware.
|
||||
|
||||
## 1. Additional Environment Setup
|
||||
|
||||
## What to expect in this example?
|
||||
No additional setup is required.
|
||||
|
||||
The example provides a minimal implementation to build a Matter light device on ESP32 series SoCs.
|
||||
## 2. Post Commissioning Setup
|
||||
|
||||
Supported features:
|
||||
- Matter Commissioning
|
||||
- On/Off, Brightness and Color (on ESP32-C3 for now) control
|
||||
- (Optional) Interactive shell
|
||||
No additional setup is required.
|
||||
|
||||
### Useful shell commands
|
||||
## 3. Device Performance
|
||||
|
||||
- BLE commands
|
||||
### 3.1 Memory usage
|
||||
|
||||
```
|
||||
> matter ble <start|stop|state>
|
||||
```
|
||||
The following is the Memory and Flash Usage.
|
||||
|
||||
Set and get the BLE advertisement state.
|
||||
- `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)
|
||||
|
||||
- Wi-Fi commands
|
||||
| | Bootup | After Commissioning |
|
||||
|:- |:-: |:-: |
|
||||
|**Free Internal Memory** |109KB |105KB |
|
||||
|
||||
```
|
||||
> matter wifi mode [disable|ap|sta]
|
||||
```
|
||||
**Flash Usage**: Firmware binary size: 1.26MB
|
||||
|
||||
Set and get the Wi-Fi mode.
|
||||
|
||||
```
|
||||
> matter wifi connect <ssid> <psk>
|
||||
```
|
||||
|
||||
Connect to Wi-Fi network.
|
||||
|
||||
- Device configuration
|
||||
|
||||
```
|
||||
> matter config
|
||||
```
|
||||
|
||||
Dump the device static configuration
|
||||
|
||||
|
||||
- Factory reset
|
||||
|
||||
```
|
||||
> matter device factoryreset
|
||||
```
|
||||
|
||||
- On-boarding codes
|
||||
|
||||
```
|
||||
> matter onboardingcodes
|
||||
```
|
||||
|
||||
Dump the on-boarding pairing code payloads.
|
||||
This should give you a good idea about the amount of free memory that is
|
||||
available for you to run your application's code.
|
||||
|
||||
@@ -54,8 +54,6 @@ static esp_err_t app_attribute_update_cb(callback_type_t type, uint16_t endpoint
|
||||
if (type == PRE_UPDATE) {
|
||||
/* Driver update */
|
||||
err = app_driver_attribute_update(endpoint_id, cluster_id, attribute_id, val);
|
||||
} else if (type == POST_UPDATE) {
|
||||
/* Other ecosystems update */
|
||||
}
|
||||
|
||||
return err;
|
||||
|
||||
@@ -1,59 +1,120 @@
|
||||
# Light Switch Example
|
||||
# Light Switch
|
||||
|
||||
## Building and Flashing the Firmware
|
||||
This example creates an On/Off Light Switch device using the ESP Matter
|
||||
data model.
|
||||
|
||||
See the [README.md](../../README.md) file for more information about building and flashing the firmware.
|
||||
It creates the On/Off client and other devices can be bound to the
|
||||
switch and then controlled from the switch.
|
||||
|
||||
## What to expect in this example?
|
||||
See the [docs](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html) for more information about building and flashing the firmware.
|
||||
|
||||
Supported features:
|
||||
- Matter Commissioning
|
||||
- Switch will connect to light when Bind command is sent
|
||||
- CLIs to control remote light from switch
|
||||
## 1. Additional Environment Setup
|
||||
|
||||
## Bind light to switch
|
||||
No additional setup is required.
|
||||
|
||||
Update the light's acl attribute which adds entry of remote device (switch) in the access control list:
|
||||
## 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 0x7283 (29315 in decimal)
|
||||
- Node Id of light used during commissioning is 0x5164 (20836 in decimal)
|
||||
- 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:
|
||||
```
|
||||
./out/debug/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [ 112233, 12344321 ], "targets": null}]' 12344322 0
|
||||
chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [ 112233, 29315 ], "targets": null}]' 0x5164 0x0
|
||||
```
|
||||
|
||||
Update the switch's binding attribute which adds entry of remote device (light) in binding table:
|
||||
Update the switch's binding attribute to add the entry of remote device
|
||||
(light) in the binding table:
|
||||
```
|
||||
./out/debug/chip-tool binding write binding '[{"fabricIndex": 1, "node":12344322, "endpoint":1, "cluster":6}]' 12344321 1
|
||||
chip-tool binding write binding '[{"fabricIndex": 1, "node":20836, "endpoint":1, "cluster":6}]' 0x7283 0x1
|
||||
```
|
||||
|
||||
note:
|
||||
- 12344321 : node Id of switch used during commissioning
|
||||
- 12344322 : node Id of light used during commissioning
|
||||
- Cluster Id for OnOff cluster is 6
|
||||
- Binding cluster is currently present on endpoint 1
|
||||
### 2.2 Device console
|
||||
|
||||
### Useful shell commands
|
||||
Switch specific console commands:
|
||||
|
||||
After the binding is successful you can send the following command to control light from switch
|
||||
- Send command to all the bound devices on the specified cluster:
|
||||
(The IDs are in hex):
|
||||
```
|
||||
matter esp bound invoke <endpoint_id> <cluster_id> <command_id>
|
||||
```
|
||||
|
||||
```
|
||||
> matter esp bound invoke <endpoint_id> <cluster_id> <command_id>
|
||||
```
|
||||
here, endpoint_id, cluster_id, command_id of switch must be given in hex format
|
||||
- Example: Off:
|
||||
```
|
||||
matter esp bound invoke 0x1 0x6 0x0
|
||||
```
|
||||
|
||||
e.g.
|
||||
- Example: On:
|
||||
```
|
||||
matter esp bound invoke 0x1 0x6 0x1
|
||||
```
|
||||
|
||||
- Power Off command
|
||||
- Example: Toggle:
|
||||
```
|
||||
matter esp bound invoke 0x1 0x6 0x2
|
||||
```
|
||||
|
||||
```
|
||||
> matter esp bound invoke 0x0001 0x0006 0x0000
|
||||
```
|
||||
## 3. Device Performance
|
||||
|
||||
- Power On command
|
||||
### 3.1 Memory usage
|
||||
|
||||
```
|
||||
> matter esp bound invoke 0x0001 0x0006 0x0001
|
||||
```
|
||||
The following is the Memory and Flash Usage.
|
||||
|
||||
- Toggle command
|
||||
- `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)
|
||||
|
||||
```
|
||||
> matter esp bound invoke 0x0001 0x0006 0x0002
|
||||
```
|
||||
| | Bootup | After Commissioning |
|
||||
|:- |:-: |:-: |
|
||||
|**Free Internal Memory** |113KB |110KB |
|
||||
|
||||
**Flash Usage**: Firmware binary size: 1.24MB
|
||||
|
||||
This should give you a good idea about the amount of 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 bound 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 0x5164 0x0`.
|
||||
- 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 bound.
|
||||
- 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.
|
||||
|
||||
@@ -54,8 +54,6 @@ static esp_err_t app_attribute_update_cb(callback_type_t type, uint16_t endpoint
|
||||
if (type == PRE_UPDATE) {
|
||||
/* Driver update */
|
||||
err = app_driver_attribute_update(endpoint_id, cluster_id, attribute_id, val);
|
||||
} else if (type == POST_UPDATE) {
|
||||
/* Other ecosystems update */
|
||||
}
|
||||
|
||||
return err;
|
||||
|
||||
@@ -1,78 +1,142 @@
|
||||
# RainMaker Light Example
|
||||
# RainMaker Light
|
||||
|
||||
## Building and Flashing the Firmware
|
||||
This example creates a Color Dimmable Light device using the ESP
|
||||
Matter data model.
|
||||
|
||||
See the [README.md](../../README.md) file for more information about building and flashing the firmware.
|
||||
It also initializes [ESP RainMaker](https://rainmaker.espressif.com/) which enables Device Management and
|
||||
OTA using the RainMaker cloud. If user node association is done, it also
|
||||
enables Remote Control through RainMaker.
|
||||
|
||||
## What to expect in this example?
|
||||
See the [docs](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html) for more information about building and flashing the firmware.
|
||||
|
||||
This example showcases integration of ESP RainMaker with a Matter light device. ESP RainMaker is an end-to-end solution offered by Espressif to enable remote control and monitoring for ESP32 based products without any configuration required in the Cloud. Please refer the ESP RainMaker documentation [here](https://rainmaker.espressif.com/docs/get-started.html) for more details.
|
||||
## 1. Additional Environment Setup
|
||||
|
||||
Supported features:
|
||||
- Matter Commissioning
|
||||
- RainMaker Claiming and User-Node Association
|
||||
- On/Off, Brightness and Color (on ESP32-C3 for now) control over RainMaker app as well as Matter Controller
|
||||
- Updates through RainMaker reflected over Matter and vice versa
|
||||
### 1.1 Getting the Repositories
|
||||
|
||||
Make sure to follow these additional steps along with the steps in the top level README.
|
||||
|
||||
### Getting the Repositories
|
||||
|
||||
This only needs to be done once:
|
||||
```
|
||||
$ git clone --recursive https://github.com/espressif/esp-rainmaker.git
|
||||
git clone --recursive https://github.com/espressif/esp-rainmaker.git
|
||||
```
|
||||
|
||||
Setup the RainMaker CLI from here: https://rainmaker.espressif.com/docs/cli-setup.html
|
||||
|
||||
### Configuring the environment
|
||||
### 1.2 Configuring the Environment
|
||||
|
||||
This needs to be done everytime a new terminal is opened:
|
||||
```
|
||||
cd esp-matter/examples/rainmaker_light/
|
||||
|
||||
export ESP_RMAKER_PATH=/path/to/esp-rainmaker
|
||||
```
|
||||
|
||||
### RainMaker Claiming
|
||||
### 1.3 RainMaker Claiming
|
||||
|
||||
If self-claiming is not enabled/supported, this need to be done before flashing the firmware.
|
||||
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
|
||||
cd $ESP_RMAKER_PATH/cli
|
||||
rainmaker.py claim --addr 0x3E0000 $ESPPORT
|
||||
```
|
||||
|
||||
### RainMaker User-Node Association
|
||||
## 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):
|
||||
```
|
||||
$ ./out/debug/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.
|
||||
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 0x7283 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 0x7283 0x0
|
||||
```
|
||||
|
||||
RainMaker CLI:
|
||||
|
||||
Get the details: This will print the user_id and secret_key (do not close this):
|
||||
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 <node-id>
|
||||
rainmaker.py test --addnode <rainmaker-node-id>
|
||||
|
||||
>> add-user <user-id> <secret-key>
|
||||
```
|
||||
|
||||
Prepare the command payload: Use the above details.
|
||||
Prepare the command payload using the above details:
|
||||
|
||||
```
|
||||
payload: <user_id>::<secret_key>
|
||||
payload: <user-id>::<secret-key>
|
||||
```
|
||||
|
||||
Now use the payload to run the RainMaker configuration command from chip-tool:
|
||||
Now use the payload to run the RainMaker configuration command from
|
||||
chip-tool:
|
||||
|
||||
```
|
||||
$ ./out/debug/chip-tool any command-by-id 0x131B0000 0x0 '"<user_id>::<secret_key>"' 0x1 0x0
|
||||
chip-tool any command-by-id 0x131b0000 0x0 '"<user-id>::<secret-key>"' 0x7283 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 Memory usage
|
||||
|
||||
The following is the Memory and Flash 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 |
|
||||
|
||||
**Flash Usage**: Firmware binary size: 1.52MB
|
||||
|
||||
This should give you a good idea about the amount of 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 0x7283 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.
|
||||
|
||||
@@ -55,7 +55,7 @@ static esp_err_t app_attribute_update_cb(callback_type_t type, uint16_t endpoint
|
||||
/* Driver update */
|
||||
err = app_driver_attribute_update(endpoint_id, cluster_id, attribute_id, val);
|
||||
} else if (type == POST_UPDATE) {
|
||||
/* Other ecosystems update */
|
||||
/* Rainmaker update */
|
||||
err = app_rainmaker_attribute_update(endpoint_id, cluster_id, attribute_id, val);
|
||||
}
|
||||
|
||||
|
||||
@@ -1,62 +1,88 @@
|
||||
# Light Example
|
||||
# Zap Light
|
||||
|
||||
## Building and Flashing the Firmware
|
||||
This example creates a Color Dimmable Light device using the Zap
|
||||
data model instead of the ESP Matter data model.
|
||||
|
||||
See the [README.md](../../README.md) file for more information about building and flashing the firmware.
|
||||
See the [docs](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html) for more information about building and flashing the firmware.
|
||||
|
||||
## 1. Additional Environment Setup
|
||||
|
||||
## What to expect in this example?
|
||||
### 1.1 Customization
|
||||
|
||||
The example provides a minimal implementation to build a Matter light device on ESP32 series SoCs.
|
||||
|
||||
Supported features:
|
||||
- Matter Commissioning
|
||||
- On/Off, Brightness and Color (on ESP32-C3 for now) control
|
||||
- (Optional) Interactive shell
|
||||
|
||||
### Useful shell commands
|
||||
|
||||
- BLE commands
|
||||
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.
|
||||
|
||||
```
|
||||
> matter ble <start|stop|state>
|
||||
cd esp-matter/connectedhomeip/connectedhomeip
|
||||
./scripts/tools/zap/run_zaptool.sh <optional_existing_zap_file>
|
||||
```
|
||||
|
||||
Set and get the BLE advertisement state.
|
||||
- If this command fails, run it again.
|
||||
- Once the customization is done, click on 'save' to save the .zap
|
||||
file.
|
||||
|
||||
- Wi-Fi commands
|
||||
The other zap-generated files can be generated using the generate
|
||||
command:
|
||||
|
||||
```
|
||||
> matter wifi mode [disable|ap|sta]
|
||||
./scripts/tools/zap/generate.py /path/to/<saved>.zap -o /path/to/<output_folder>
|
||||
```
|
||||
|
||||
Set and get the Wi-Fi mode.
|
||||
Now the files in zap_light/main/zap-generated can be replaced with the
|
||||
new generated files.
|
||||
|
||||
```
|
||||
> matter wifi connect <ssid> <psk>
|
||||
```
|
||||
## 2. Post Commissioning Setup
|
||||
|
||||
Connect to Wi-Fi network.
|
||||
No additional setup is required.
|
||||
|
||||
- Device configuration
|
||||
## 3. Device Performance
|
||||
|
||||
```
|
||||
> matter config
|
||||
```
|
||||
### 3.1 Memory usage
|
||||
|
||||
Dump the device static configuration
|
||||
The following is the Memory and Flash 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)
|
||||
|
||||
- Factory reset
|
||||
| | Bootup | After Commissioning |
|
||||
|:- |:-: |:-: |
|
||||
|**Free Internal Memory** |121KB |118KB |
|
||||
|
||||
```
|
||||
> matter device factoryreset
|
||||
```
|
||||
**Flash Usage**: Firmware binary size: 1.24MB
|
||||
|
||||
- On-boarding codes
|
||||
This should give you a good idea about the amount of free memory that is
|
||||
available for you to run your application's code.
|
||||
|
||||
```
|
||||
> matter onboardingcodes
|
||||
```
|
||||
## A2 Appendix FAQs
|
||||
|
||||
Dump the on-boarding pairing code payloads.
|
||||
### 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.
|
||||
|
||||
@@ -52,8 +52,6 @@ static esp_err_t app_attribute_update_cb(callback_type_t type, uint16_t endpoint
|
||||
if (type == PRE_UPDATE) {
|
||||
/* Driver update */
|
||||
err = app_driver_attribute_update(endpoint_id, cluster_id, attribute_id, val);
|
||||
} else if (type == POST_UPDATE) {
|
||||
/* Other ecosystems update */
|
||||
}
|
||||
|
||||
return err;
|
||||
|
||||
@@ -1,100 +1,130 @@
|
||||
# Zigbee Bridge Example
|
||||
# ZigBee Bridge
|
||||
|
||||
## Building and Flashing the Firmware
|
||||
This example demonstrates a Matter-ZigBee Bridge that bridges ZigBee devices to Matter fabric.
|
||||
|
||||
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 running on ESP32.
|
||||
|
||||
The Matter Bridge device is composed of two parts: The RCP running on ESP32-H2 and the bridge app
|
||||
running on ESP32.
|
||||
See the [docs](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html) for more information about building and flashing the firmware.
|
||||
|
||||
### Hardware connection
|
||||
## 1. Additional Environment Setup
|
||||
|
||||
Connect the two SoCs via UART, below is an example setup with ESP32 DevKitC and ESP32-H2 DevKitC:
|
||||
|
||||
### 1.1 Hardware connection
|
||||
|
||||
ESP32 Pin | ESP32-H2 Pin
|
||||
-------------|--------------
|
||||
GND | GND
|
||||
GPIO4 | GPIO7
|
||||
GPIO5 | GPIO8
|
||||
Connect the two SoCs via UART, below is an example setup with ESP32
|
||||
DevKitC and ESP32-H2 DevKitC:
|
||||
|
||||
### Build and flash the RCP (ESP32-H2)
|
||||
|
||||
|
||||
| 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
|
||||
cd ${IDF_PATH}/examples/zigbee/esp_zigbee_rcp/
|
||||
idf.py --preview set-target esp32h2
|
||||
idf.py -p <port> build flash
|
||||
```
|
||||
|
||||
The Matter Bridge app will run on the ESP32 and ZigBee network will be formed.
|
||||
The Matter Bridge will run on the ESP32 and ZigBee network will be
|
||||
formed.
|
||||
|
||||
## Build chip-tool and provision the Matter Bridge device
|
||||
## 2. Post Commissioning Setup
|
||||
|
||||
Open a new terminal window and active matter environment
|
||||
### 2.1 Discovering Zigbee Devices
|
||||
|
||||
You can read the parts list from the Bridge to get the number of the
|
||||
bridged devices.
|
||||
|
||||
```
|
||||
$ cd esp-matter/connectedhomeip/connectedhomeip/examples/chip-tool
|
||||
$ gn gen out
|
||||
$ ninja -C out
|
||||
chip-tool descriptor read parts-list 0x7283 0x0
|
||||
```
|
||||
|
||||
Now you can provision the Matter Bridge device with `./out/chip-tool` (Please ensure that your PC
|
||||
and the bridge device are on the same local network).
|
||||
If there is no other ZigBee device on the ZigBee Network, you will get
|
||||
an empty result. Example:
|
||||
|
||||
```
|
||||
$ ./out/chip-tool pairing ble-wifi 12344321 {wifi-ssid} {wifi-password} 20202021 3840
|
||||
Data = [
|
||||
|
||||
],
|
||||
```
|
||||
|
||||
After Provisioning success, you can read the parts list in Bridge app to get the number of the bridged devices.
|
||||
### 2.2 Setup ZigBee Bulb on ESP32-H2
|
||||
|
||||
Build and run ZigBee Bulb app on another ESP32-H2 board.
|
||||
|
||||
```
|
||||
$ ./out/chip-tool descriptor read parts-list 12344321 0
|
||||
cd ${IDF_PATH}/examples/zigbee/light_sample/light_bulb
|
||||
idf.py --preview set-target esp32h2
|
||||
idf.py -p <port> build flash monitor
|
||||
```
|
||||
|
||||
If there is no other ZigBee device on the ZigBee Network, you will get an empty result.
|
||||
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.
|
||||
|
||||
```
|
||||
[1639378931.513638][1808055:1808060] CHIP:DMG: Data = [
|
||||
[1639378931.513641][1808055:1808060] CHIP:DMG:
|
||||
[1639378931.513645][1808055:1808060] CHIP:DMG: ],
|
||||
chip-tool descriptor read parts-list 0x7283 0x0
|
||||
```
|
||||
|
||||
## Setup ZigBee Bulb on ESP32-H2
|
||||
|
||||
Build and run ZigBee Bulb app on another ESP32-H2 board. Open another terminal window and repeat Step 2 again.
|
||||
The data will now contain the information of the connected ZigBee
|
||||
devices. Example:
|
||||
|
||||
```
|
||||
$ cd ${IDF_PATH}/examples/zigbee/light_sample/light_bulb
|
||||
$ idf.py --preview set-target esp32h2
|
||||
$ idf.py -p <port> build flash monitor
|
||||
Data = [
|
||||
1,
|
||||
],
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
```
|
||||
$ ./out/chip-tool descriptor read parts-list 12344321 0
|
||||
...
|
||||
[1639379769.737877][1809119:1809124] CHIP:DMG: Data = [
|
||||
[1639379769.737881][1809119:1809124] CHIP:DMG: 1,
|
||||
[1639379769.737885][1809119:1809124] CHIP:DMG: ],
|
||||
chip-tool descriptor read server-list 0x7283 0x1
|
||||
```
|
||||
|
||||
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.
|
||||
This will give the list of supported server clusters. Example:
|
||||
|
||||
```
|
||||
$ ./out/chip-tool descriptor read server-list 12344321 1
|
||||
...
|
||||
[1639380020.748687][1809427:1809432] CHIP:TOO: OnDescriptorServerListListAttributeResponse: 4 entries
|
||||
[1639380020.748695][1809427:1809432] CHIP:TOO: [1]: 6
|
||||
[1639380020.748699][1809427:1809432] CHIP:TOO: [2]: 29
|
||||
[1639380020.748703][1809427:1809432] CHIP:TOO: [3]: 57
|
||||
[1639380020.748706][1809427:1809432] CHIP:TOO: [4]: 64
|
||||
OnDescriptorServerListListAttributeResponse: 4 entries
|
||||
[1]: 6
|
||||
[2]: 29
|
||||
[3]: 57
|
||||
[4]: 64
|
||||
```
|
||||
|
||||
## Control the bulb with chip-tool
|
||||
### 2.3 Control the bulb with chip-tool
|
||||
|
||||
Now you can control the ZigBee bulb using the chip tool.
|
||||
|
||||
Now you can control the ZigBee bulb on chip tool.
|
||||
```
|
||||
$ ./out/chip-tool onoff toggle 12344321 1
|
||||
chip-tool onoff toggle 0x7283 0x1
|
||||
```
|
||||
|
||||
## 3. Device Performance
|
||||
|
||||
### 3.1 Memory usage
|
||||
|
||||
The following is the Memory and Flash 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 |
|
||||
|
||||
**Flash Usage**: Firmware binary size: 1.26MB
|
||||
|
||||
This should give you a good idea about the amount of free memory that is
|
||||
available for you to run your application's code.
|
||||
|
||||
Reference in New Issue
Block a user