mirror of
https://github.com/espressif/esp-matter.git
synced 2026-04-27 19:13:13 +00:00
docs: Add matter docs
This commit is contained in:
Chirag Atal
Shu Chen
@@ -8,3 +8,5 @@ dependencies.lock
|
||||
managed_components/
|
||||
__pycache__/
|
||||
out/
|
||||
_build/
|
||||
tools/chip-tool/
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
stages:
|
||||
- build
|
||||
- docs
|
||||
|
||||
variables:
|
||||
IDF_PATH: "$CI_PROJECT_DIR/esp-idf"
|
||||
@@ -139,3 +140,59 @@ build_upstream_examples:
|
||||
- *setup_idf
|
||||
- *setup_matter
|
||||
- *build_matter_examples
|
||||
|
||||
build_docs:
|
||||
stage: build
|
||||
image: $CI_DOCKER_REGISTRY/esp-idf-doc-env:v4.4-1-v4
|
||||
tags:
|
||||
- matter_build
|
||||
artifacts:
|
||||
when: always
|
||||
paths:
|
||||
- docs/_build/*/*/*.txt
|
||||
- docs/_build/*/*/html/*
|
||||
expire_in: 1 days
|
||||
script:
|
||||
- cd docs
|
||||
- pip install -r requirements.txt
|
||||
- build-docs -t esp32c3 esp32 -l en
|
||||
|
||||
.deploy_docs_template:
|
||||
stage: docs
|
||||
image: $CI_DOCKER_REGISTRY/esp-idf-doc-env:v4.4-1-v4
|
||||
tags:
|
||||
- docs
|
||||
needs:
|
||||
- build_docs
|
||||
script:
|
||||
- source ${CI_PROJECT_DIR}/docs/utils.sh
|
||||
- add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER
|
||||
- export GIT_VER=$(git describe --always)
|
||||
- pip install -r ${CI_PROJECT_DIR}/docs/requirements.txt
|
||||
- deploy-docs
|
||||
|
||||
deploy_docs_preview:
|
||||
extends:
|
||||
- .deploy_docs_template
|
||||
when: manual
|
||||
variables:
|
||||
TYPE: "preview"
|
||||
DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/"
|
||||
DOCS_DEPLOY_PRIVATEKEY: "$DOCS_DEPLOY_KEY"
|
||||
DOCS_DEPLOY_SERVER: "$DOCS_SERVER"
|
||||
DOCS_DEPLOY_SERVER_USER: "$DOCS_SERVER_USER"
|
||||
DOCS_DEPLOY_PATH: "$DOCS_PATH"
|
||||
DOCS_DEPLOY_URL_BASE: "https://$DOCS_PREVIEW_SERVER_URL/docs/esp-matter"
|
||||
|
||||
deploy_docs_production:
|
||||
extends:
|
||||
- .deploy_docs_template
|
||||
when: manual
|
||||
variables:
|
||||
TYPE: "preview"
|
||||
DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/"
|
||||
DOCS_DEPLOY_PRIVATEKEY: "$DOCS_PROD_DEPLOY_KEY"
|
||||
DOCS_DEPLOY_SERVER: "$DOCS_PROD_SERVER"
|
||||
DOCS_DEPLOY_SERVER_USER: "$DOCS_PROD_SERVER_USER"
|
||||
DOCS_DEPLOY_PATH: "$DOCS_PROD_PATH"
|
||||
DOCS_DEPLOY_URL_BASE: "https://docs.espressif.com/projects/esp-matter"
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
# Changelog
|
||||
|
||||
## 2022-05-18 (github release)
|
||||
|
||||
GitHub release for ESP Matter: https://github.com/espressif/esp-matter
|
||||
|
||||
**Enhancements**
|
||||
* todo.
|
||||
|
||||
**API Changes**
|
||||
* todo.
|
||||
|
||||
**Bug Fixes**
|
||||
* todo.
|
||||
|
||||
**Known Issues**
|
||||
* todo.
|
||||
-63
@@ -1,63 +0,0 @@
|
||||
# 2021-12-07 (esp_matter: New data model)
|
||||
|
||||
This commit creates the dynamic ESP Matter data model and uses that instead of the
|
||||
static data model in zap-generated.
|
||||
|
||||
The examples create the ESP Matter data model using the new APIs and default configs.
|
||||
These APIs add the mandatory clusters and the corresponding attributes and commands for the
|
||||
device type (endpoint) created.
|
||||
```
|
||||
esp_matter_node_config_t node_config = NODE_CONFIG_DEFAULT();
|
||||
esp_matter_node_t *node = esp_matter_node_create(&node_config, app_attribute_update_cb, NULL);
|
||||
|
||||
esp_matter_endpoint_color_dimmable_light_config_t light_config = ENDPOINT_CONFIG_COLOR_DIMMABLE_LIGHT_DEFAULT();
|
||||
esp_matter_endpoint_t *endpoint = esp_matter_endpoint_create_color_dimmable_light(node, &light_config, ESP_MATTER_ENDPOINT_FLAG_NONE);
|
||||
```
|
||||
|
||||
The examples have also been restructured and the matter submodule specific initialisations have
|
||||
been moved to the esp_matter component and are called from the application with the new API.
|
||||
```
|
||||
typedef void (*esp_matter_event_callback_t)(const ChipDeviceEvent *event, intptr_t arg);
|
||||
|
||||
esp_err_t esp_matter_start(esp_matter_event_callback_t callback);
|
||||
```
|
||||
|
||||
There is now just one attribute update callback which calls the other callbacks in the application.
|
||||
The application receives this callback twice, once before updating the value in the data model (pre_attribute)
|
||||
and once after updating the value (post_attribute).
|
||||
```
|
||||
esp_err_t app_attribute_update_cb(esp_matter_callback_type_t type, int endpoint_id, int cluster_id, int attribute_id, esp_matter_attr_val_t *val, void *priv_data);
|
||||
```
|
||||
|
||||
The app_driver component has been moved to the application itself and it now uses the endpoint_id,
|
||||
cluster_id, attribute_id for setting/getting the values. The application calls the the attribute_update
|
||||
for drivers first when it gets the pre_attribute callback. If this returns success, i.e. ESP_OK, only then
|
||||
the data model value is updated and the application receives the post_attribute callback.
|
||||
```
|
||||
esp_err_t app_driver_attribute_update(int endpoint_id, int cluster_id, int attribute_id, esp_matter_attr_val_t *val);
|
||||
```
|
||||
|
||||
The rainmaker example creates its data model dynamically based on the ESP Matter data model. New
|
||||
params can be easily supported in the rainmaker example by adding to the app_rainmaker_get_* APIs.
|
||||
The application calls the attribute_update for rainmaker and other ecosystems when it gets the post_attribute
|
||||
callback.
|
||||
```
|
||||
/* Create a device and add the relevant parameters to it */
|
||||
app_rainmaker_device_create();
|
||||
|
||||
esp_err_t app_rainmaker_attribute_update(int endpoint_id, int cluster_id, int attribute_id, esp_matter_attr_val_t *val);
|
||||
```
|
||||
|
||||
Non-mandatory endpoints, clusters, attributes or commands can also be easily added by using the
|
||||
low level APIs. New device types (endpoints) and supporting clusters can be added from the spec
|
||||
by looking at the existing APIs for reference.
|
||||
```
|
||||
esp_matter_node_t *esp_matter_node_create_raw();
|
||||
esp_matter_endpoint_t *esp_matter_endpoint_create_raw(esp_matter_node_t *node, uint8_t flags);
|
||||
esp_matter_cluster_t *esp_matter_cluster_create(esp_matter_endpoint_t *endpoint, int cluster_id, uint8_t flags);
|
||||
esp_matter_attribute_t *esp_matter_attribute_create(esp_matter_cluster_t *cluster, int attribute_id, uint8_t flags, esp_matter_attr_val_t val);
|
||||
esp_matter_command_t *esp_matter_command_create(esp_matter_cluster_t *cluster, int command_id, uint8_t flags, esp_matter_command_callback_t callback);
|
||||
```
|
||||
|
||||
Another zap_light example has been added for backward compatibility, which uses the static data model
|
||||
and the default zap-generated.
|
||||
@@ -0,0 +1,61 @@
|
||||
# This is Doxygen configuration file
|
||||
#
|
||||
# Doxygen provides over 260 configuration statements
|
||||
# To make this file easier to follow,
|
||||
# it contains only statements that are non-default
|
||||
#
|
||||
# NOTE:
|
||||
# It is recommended not to change defaults unless specifically required
|
||||
# Test any changes how they affect generated documentation
|
||||
# Make sure that correct warnings are generated to flag issues with documented code
|
||||
#
|
||||
# For the complete list of configuration statements see:
|
||||
# http://doxygen.nl/manual/config.html
|
||||
|
||||
|
||||
PROJECT_NAME = "ESP Matter Programming Guide"
|
||||
|
||||
## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
|
||||
## to automatically generate API reference list files header_file.inc
|
||||
## These files are placed in '_inc' directory
|
||||
## and used to include in API reference documentation
|
||||
|
||||
INPUT = \
|
||||
$(PROJECT_PATH)/components/esp_matter/esp_matter_endpoint.h \
|
||||
$(PROJECT_PATH)/components/esp_matter/esp_matter_cluster.h \
|
||||
$(PROJECT_PATH)/components/esp_matter/esp_matter_attribute.h \
|
||||
$(PROJECT_PATH)/components/esp_matter/esp_matter_command.h \
|
||||
$(PROJECT_PATH)/components/esp_matter/esp_matter_core.h \
|
||||
$(PROJECT_PATH)/components/esp_matter/esp_matter_event.h \
|
||||
$(PROJECT_PATH)/components/esp_matter/esp_matter_client.h \
|
||||
|
||||
## Get warnings for functions that have no documentation for their parameters or return value
|
||||
##
|
||||
WARN_NO_PARAMDOC = YES
|
||||
|
||||
## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files
|
||||
##
|
||||
ENABLE_PREPROCESSING = YES
|
||||
MACRO_EXPANSION = YES
|
||||
EXPAND_ONLY_PREDEF = YES
|
||||
PREDEFINED = \
|
||||
$(ENV_DOXYGEN_DEFINES)
|
||||
|
||||
## Do not complain about not having dot
|
||||
##
|
||||
HAVE_DOT = NO
|
||||
|
||||
## Generate XML that is required for Breathe
|
||||
##
|
||||
GENERATE_XML = YES
|
||||
XML_OUTPUT = xml
|
||||
|
||||
GENERATE_HTML = NO
|
||||
HAVE_DOT = NO
|
||||
GENERATE_LATEX = NO
|
||||
GENERATE_MAN = YES
|
||||
GENERATE_RTF = NO
|
||||
|
||||
## Skip distracting progress messages
|
||||
##
|
||||
QUIET = YES
|
||||
@@ -0,0 +1,17 @@
|
||||
# Documentation Source Folder
|
||||
|
||||
This folder contains source files of **esp matter documentation**.
|
||||
|
||||
The sources do not render well in GitHub and some information is not visible at all.
|
||||
|
||||
Use actual documentation generated within about 20 minutes on each commit:
|
||||
|
||||
# Hosted Documentation
|
||||
|
||||
* English: https://docs.espressif.com/projects/esp-matter/
|
||||
|
||||
The above URL is for the master branch latest version. Click the drop-down in the bottom left to choose a particular version or to download a PDF.
|
||||
|
||||
# Building Documentation
|
||||
|
||||
The documentation is built using the python package `esp-docs`, which can be installed by running `pip install esp-docs`. Running `build-docs --help` will give a summary of available options. For more information see the `esp-docs` documentation at https://github.com/espressif/esp-docs/blob/master/README.md
|
||||
Vendored
+15
@@ -0,0 +1,15 @@
|
||||
var DOCUMENTATION_VERSIONS = {
|
||||
DEFAULTS: { has_targets: false,
|
||||
supported_targets: [ "esp32" ]
|
||||
},
|
||||
VERSIONS: [
|
||||
{ name: "latest", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32c3", "esp32s3", "esp32h2" ] },
|
||||
],
|
||||
IDF_TARGETS: [
|
||||
{ text: "ESP32", value: "esp32" },
|
||||
{ text: "ESP32-S2", value: "esp32s2" },
|
||||
{ text: "ESP32-S3", value: "esp32s3" },
|
||||
{ text: "ESP32-C3", value: "esp32c3" },
|
||||
{ text: "ESP32-H2", value: "esp32h2" },
|
||||
]
|
||||
};
|
||||
Vendored
BIN
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 5.5 KiB |
@@ -0,0 +1,29 @@
|
||||
from esp_docs.conf_docs import * # noqa: F403,F401
|
||||
|
||||
languages = ['en']
|
||||
idf_targets = ['esp32', 'esp32s2', 'esp32s3', 'esp32c3', 'esp32h2']
|
||||
|
||||
extensions += ['sphinx_copybutton',
|
||||
# Needed as a trigger for running doxygen
|
||||
'esp_docs.esp_extensions.dummy_build_system',
|
||||
'esp_docs.esp_extensions.run_doxygen',
|
||||
]
|
||||
|
||||
# link roles config
|
||||
github_repo = 'espressif/esp-matter'
|
||||
|
||||
# context used by sphinx_idf_theme
|
||||
html_context['github_user'] = 'espressif'
|
||||
html_context['github_repo'] = 'esp-matter'
|
||||
|
||||
html_static_path = ['../_static']
|
||||
|
||||
# Extra options required by sphinx_idf_theme
|
||||
project_slug = 'esp-matter'
|
||||
|
||||
# Contains info used for constructing target and version selector
|
||||
# Can also be hosted externally, see esp-idf for example
|
||||
versions_url = '_static/esp_matter_versions.js'
|
||||
|
||||
# Final PDF filename will contains target and version
|
||||
pdf_file_prefix = u'esp-docs'
|
||||
@@ -1,47 +0,0 @@
|
||||
# Adding External Platforms for Matter
|
||||
|
||||
esp-matter provides support for overriding the device layer in Matter. Here are the required steps for adding an external platform.
|
||||
|
||||
## Creating the external platform directory
|
||||
|
||||
Create a directory `platform/${NEW_PLATFORM_NAME}` in your codebase. You can typically copy `${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/src/platform/ESP32` as a start. Note that the new platform name shall be different with name `ESP32`. In this article we'll use `ESP32_custom` as an example. The directory must be under `platform` folder to meet the Matter include path conventions.
|
||||
|
||||
## Modifying the BUILD.gn target
|
||||
|
||||
We've provided an example BUILD.gn file for the `ESP32_custom` example platform. It simply compiles the ESP32 platform in Matter without any modifications.
|
||||
|
||||
The new platform directory must be added to the Matter include path. See the `ESP32_custom_include` config in the [BUILD.gn](./BUILD.gn).
|
||||
|
||||
Multiple build configs must be exported to the build system. See the `buildconfig_header` section in the [BUILD.gn](./BUILD.gn) for the required definitions.
|
||||
|
||||
## Required Kconfigs
|
||||
|
||||
The config `CONFIG_CHIP_ENABLE_EXTERNAL_PLATFORM` shall be enabled.
|
||||
The config `CONFIG_CHIP_EXTERNAL_PLATFORM_DIR` shall be the relative path from `${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/config/esp32` to the external platform directory.
|
||||
For instance, if your source tree is:
|
||||
|
||||
```
|
||||
my_project
|
||||
├── esp-matter
|
||||
└── platform
|
||||
└── ESP32_custom
|
||||
```
|
||||
|
||||
Then `CONFIG_CHIP_EXTERNAL_PLATFORM_DIR` will be `../../../../../platform/ESP32_custom`.
|
||||
|
||||
The config `CONFIG_BUILD_CHIP_TESTS` shall be disabled.
|
||||
|
||||
If your external platform does not support the [shell interface](../../connectedhomeip/connectedhomeip/src/lib/shell) provided in the Matter shell library, then `CONFIG_ENABLE_CHIP_SHELL` shall also be disabled.
|
||||
|
||||
## Example
|
||||
|
||||
As an example, you can build [light](../../examples/light) example on `ESP32_custom` platform with following steps:
|
||||
|
||||
```
|
||||
$ mkdir $ESP_MATTER_PATH/../platform
|
||||
$ cp -r $ESP_MATTER_PATH/connectedhomeip/connectedhomeip/src/platform/ESP32 $ESP_MATTER_PATH/../platform/ESP32_custom
|
||||
$ cp $ESP_MATTER_PATH/docs/custom_platform_guide/BUILD.gn $ESP_MATTER_PATH/../platform/ESP32_custom
|
||||
$ cd $ESP_MATTER_PATH/examples/light
|
||||
$ cp sdkconfig.defaults.ext_plat_ci sdkconfig.defaults
|
||||
$ idf.py build
|
||||
```
|
||||
@@ -0,0 +1,9 @@
|
||||
Attribute
|
||||
=========
|
||||
|
||||
This has the high level APIs for Attributes.
|
||||
|
||||
API reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_matter_attribute.inc
|
||||
@@ -0,0 +1,9 @@
|
||||
Client
|
||||
=======
|
||||
|
||||
This has the APIs for Clients such as connect() and send_command().
|
||||
|
||||
API reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_matter_client.inc
|
||||
@@ -0,0 +1,9 @@
|
||||
Cluster
|
||||
=======
|
||||
|
||||
This has the high level APIs for Clusters.
|
||||
|
||||
API reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_matter_cluster.inc
|
||||
@@ -0,0 +1,9 @@
|
||||
Command
|
||||
=======
|
||||
|
||||
This has the high level APIs for Commands.
|
||||
|
||||
API reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_matter_command.inc
|
||||
@@ -0,0 +1,9 @@
|
||||
Core Low Level
|
||||
==============
|
||||
|
||||
This has the Core Low Level APIs.
|
||||
|
||||
API reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_matter_core.inc
|
||||
@@ -0,0 +1,9 @@
|
||||
Endpoint/Device Type
|
||||
====================
|
||||
|
||||
This has the high level APIs for Endpoint/Device Type.
|
||||
|
||||
API reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_matter_endpoint.inc
|
||||
@@ -0,0 +1,9 @@
|
||||
Event
|
||||
=======
|
||||
|
||||
This has the APIs for Events.
|
||||
|
||||
API reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_matter_event.inc
|
||||
@@ -0,0 +1,13 @@
|
||||
5. API Reference
|
||||
================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
esp_matter_endpoint.rst
|
||||
esp_matter_cluster.rst
|
||||
esp_matter_attribute.rst
|
||||
esp_matter_command.rst
|
||||
esp_matter_core.rst
|
||||
esp_matter_event.rst
|
||||
esp_matter_client.rst
|
||||
@@ -0,0 +1,5 @@
|
||||
3. Matter Certification
|
||||
=======================
|
||||
|
||||
todo. Get your product certified. also mention about dcl.
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# English Language RTD & Sphinx config file
|
||||
#
|
||||
# Uses ../conf_common.py for most non-language-specific settings.
|
||||
|
||||
# Importing conf_common adds all the non-language-specific
|
||||
# parts to this conf module
|
||||
|
||||
import datetime
|
||||
|
||||
try:
|
||||
from conf_common import * # noqa: F403,F401
|
||||
except ImportError:
|
||||
import os
|
||||
import sys
|
||||
sys.path.insert(0, os.path.abspath('../'))
|
||||
from conf_common import * # noqa: F403,F401
|
||||
|
||||
# General information about the project.
|
||||
project = u'ESP Matter'
|
||||
copyright = u'2022 - {}, Espressif Systems (Shanghai) Co., Ltd'.format(datetime.datetime.now().year)
|
||||
pdf_title = u'ESP Matter Example Guide'
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
language = 'en'
|
||||
@@ -0,0 +1,694 @@
|
||||
2. Developing with ESP Matter
|
||||
=============================
|
||||
|
||||
Please refer to :project_file:`CHANGELOG.md` to track release changes
|
||||
and known-issues.
|
||||
|
||||
2.1 Development Setup
|
||||
---------------------
|
||||
|
||||
This section talks about setting up your development host, fetching the
|
||||
git repositories, and instructions for build and flash.
|
||||
|
||||
2.1.1 Host Setup
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
You should install drivers and support packages for your development
|
||||
host. Linux and Mac OS-X are the supported development hosts in Matter.
|
||||
|
||||
- Please see `Prerequisites <https://docs.espressif.com/projects/esp-idf/en/v4.4.1/esp32/get-started/index.html#step-1-install-prerequisites>`__ for ESP IDF.
|
||||
- Please get the `Prerequisites <https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/BUILDING.md#prerequisites>`__ for Matter.
|
||||
|
||||
2.1.2 Getting the Repositories
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
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-matter.git
|
||||
cd esp-matter
|
||||
./install.sh
|
||||
cd ..
|
||||
|
||||
2.1.3 Configuring the Environment
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
cd esp-idf; . ./export.sh; cd ..
|
||||
cd esp-matter; . ./export.sh; cd ..
|
||||
|
||||
2.1.4 Additional Environment Setup
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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>
|
||||
RainMaker Light <examples/rainmaker_light>
|
||||
Switch <examples/switch>
|
||||
Zap Light <examples/zap_light>
|
||||
Zigbee Bridge <examples/bridge_zigbee>
|
||||
|
||||
2.1.5 Flashing the Firmware
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Choose IDF target.
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
::
|
||||
|
||||
idf.py set-target esp32c3
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
::
|
||||
|
||||
idf.py set-target esp32
|
||||
|
||||
- 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``.
|
||||
|
||||
(When flashing the SDK for the first time, it is recommended to do
|
||||
``idf.py erase_flash`` to wipe out entire flash and start out fresh.)
|
||||
|
||||
::
|
||||
|
||||
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
|
||||
|
||||
2.2 Commissioning and Control
|
||||
-----------------------------
|
||||
|
||||
2.2.1 Test Setup (Python Controller Setup)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Python Controller, also referred to as chip-tool can be used as a Matter client to commission and control the device.
|
||||
|
||||
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.
|
||||
|
||||
::
|
||||
|
||||
cd esp-matter/connectedhomeip/connectedhomeip
|
||||
scripts/examples/gn_build_example.sh examples/chip-tool examples/chip-tool/out/
|
||||
export PATH=$PATH:$ESP_MATTER_PATH/connectedhomeip/connectedhomeip/examples/chip-tool/out/
|
||||
cd ../../
|
||||
|
||||
2.2.1.2 Commissioning
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Use ``chip-tool`` to pair the device:
|
||||
|
||||
::
|
||||
|
||||
chip-tool pairing ble-wifi 1 <ssid> <password> 20202021 3840
|
||||
|
||||
2.2.1.3 Post Commissioning Setup
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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>
|
||||
RainMaker Light <examples/rainmaker_light>
|
||||
Switch <examples/switch>
|
||||
Zap Light <examples/zap_light>
|
||||
Zigbee Bridge <examples/bridge_zigbee>
|
||||
|
||||
|
||||
2.2.1.4 Cluster Control
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Use the cluster commands to control the attributes.
|
||||
|
||||
::
|
||||
|
||||
chip-tool onoff toggle 1 1
|
||||
|
||||
::
|
||||
|
||||
chip-tool onoff on 1 1
|
||||
|
||||
::
|
||||
|
||||
chip-tool levelcontrol move-to-level 10 0 0 0 1 1
|
||||
|
||||
::
|
||||
|
||||
chip-tool levelcontrol move-to-level 100 0 0 0 1 1
|
||||
|
||||
::
|
||||
|
||||
chip-tool colorcontrol move-to-saturation 200 0 0 0 1 1
|
||||
|
||||
::
|
||||
|
||||
chip-tool colorcontrol move-to-hue 150 0 0 0 0 1 1
|
||||
|
||||
For more chip-tool usage, check https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool
|
||||
|
||||
2.3 Device console
|
||||
------------------
|
||||
|
||||
The console on the device can be used to run commands for testing. It is enabled by default in the firmware. Here are some useful commands:
|
||||
|
||||
- BLE commands: Set and get the BLE advertisement state:
|
||||
|
||||
::
|
||||
|
||||
matter ble [start|stop|state]
|
||||
|
||||
- Wi-Fi commands: Set and get the Wi-Fi mode:
|
||||
|
||||
::
|
||||
|
||||
matter wifi mode [disable|ap|sta]
|
||||
|
||||
- Wi-Fi connect:
|
||||
|
||||
::
|
||||
|
||||
matter wifi connect <ssid> <password>
|
||||
|
||||
- Device configuration: Dump the device static configuration:
|
||||
|
||||
::
|
||||
|
||||
matter config
|
||||
|
||||
- Factory reset:
|
||||
|
||||
::
|
||||
|
||||
matter device factoryreset
|
||||
|
||||
- On-boarding codes: Dump the on-boarding pairing code payloads:
|
||||
|
||||
::
|
||||
|
||||
matter onboardingcodes
|
||||
|
||||
Additional ESP Matter specific commands:
|
||||
|
||||
- Get attribute: (The IDs are in hex):
|
||||
|
||||
::
|
||||
|
||||
matter esp attribute get <endpoint_id> <cluster_id> <attribute_id>
|
||||
|
||||
- Example: on_off::on_off:
|
||||
|
||||
::
|
||||
|
||||
matter esp attribute get 0x1 0x6 0x0
|
||||
|
||||
- Set attribute: (The IDs are in hex):
|
||||
|
||||
::
|
||||
|
||||
matter esp attribute set <endpoint_id> <cluster_id> <attribute_id> <attribute value>
|
||||
|
||||
- Example: on_off::on_off:
|
||||
|
||||
::
|
||||
|
||||
matter esp attribute set 0x1 0x6 0x0 1
|
||||
|
||||
- Diagnostics:
|
||||
|
||||
::
|
||||
|
||||
matter esp diagnostics mem-dump
|
||||
|
||||
2.4 Developing your Product
|
||||
---------------------------
|
||||
|
||||
Understanding the structure before actually modifying and customising
|
||||
the device is helpful.
|
||||
|
||||
2.4.1 Building a Dimmable Lightbulb
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A device is represented in Matter in terms of its data model. As a first
|
||||
step of building your product you will define the data model for your
|
||||
device. Matter has a standard set of device types already defined that you can preferably use. Please refer to the `Espressif Matter Blog <https://blog.espressif.com/matter-clusters-attributes-commands-82b8ec1640a0>`__ for clarity on
|
||||
the terms like endpoints, clusters, etc. that are used in this section.
|
||||
|
||||
2.4.1.1 Data Model
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Typically, the data model is defined in the example's *app_main.cpp*.
|
||||
First off we start by creating the Matter node, which is the root of
|
||||
the Data Model.
|
||||
|
||||
::
|
||||
|
||||
node::config_t node_config;
|
||||
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.
|
||||
Each device type has a set of default configuration that can be
|
||||
specific as well.
|
||||
|
||||
::
|
||||
|
||||
color_dimmable_light::config_t light_config;
|
||||
light_config.on_off.on_off = DEFAULT_POWER;
|
||||
light_config.level_control.current_level = DEFAULT_BRIGHTNESS;
|
||||
light_config.color_control.hue_saturation.current_hue = DEFAULT_HUE;
|
||||
light_config.color_control.hue_saturation.current_saturation = DEFAULT_SATURATION;
|
||||
endpoint_t *endpoint = color_dimmable_light::create(node, &light_config, ENDPOINT_FLAG_NONE);
|
||||
|
||||
In this case, we create the light using the ``color_dimmable_light::create()`` function. Similarly, multiple
|
||||
endpoints can be created on the same endpoint. Check the following
|
||||
sections for more info.
|
||||
|
||||
2.4.1.2 Attribute Callback
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Whenever a Matter client makes changes to the device, they end up
|
||||
updating the attributes in the data model.
|
||||
|
||||
- When an attribute is updated, the attribute_update callback is used
|
||||
to notify the application of this change. You would typically call
|
||||
device driver specific APIs for executing the required action. Here,
|
||||
if the callback type is ``PRE_UPDATE``, the driver is updated first.
|
||||
If that is a success, only then the attribute value is actually
|
||||
updated in the database.
|
||||
|
||||
::
|
||||
|
||||
esp_err_t app_attribute_update_cb(callback_type_t type, int endpoint_id, int cluster_id, int attribute_id,
|
||||
esp_matter_attr_val_t *val, void *priv_data)
|
||||
{
|
||||
esp_err_t err = ESP_OK;
|
||||
|
||||
if (type == PRE_UPDATE) {
|
||||
/* Driver update */
|
||||
err = app_driver_attribute_update(endpoint_id, cluster_id, attribute_id, val);
|
||||
}
|
||||
|
||||
return err;
|
||||
}
|
||||
|
||||
2.4.1.3 Device Drivers
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- The drivers, depending on the device, are typically initialized and
|
||||
updated in the example's *app_driver.cpp*.
|
||||
|
||||
::
|
||||
|
||||
esp_err_t app_driver_init()
|
||||
{
|
||||
ESP_LOGI(TAG, "Initialising driver");
|
||||
|
||||
/* Initialize button */
|
||||
button_config_t button_config = button_driver_get_config();
|
||||
button_handle_t handle = iot_button_create(&button_config);
|
||||
iot_button_register_cb(handle, BUTTON_PRESS_DOWN, app_driver_button_toggle_cb);
|
||||
app_reset_button_register(handle);
|
||||
|
||||
/* Initialize led */
|
||||
led_driver_config_t led_config = led_driver_get_config();
|
||||
led_driver_init(&led_config);
|
||||
|
||||
app_driver_attribute_set_defaults();
|
||||
return ESP_OK;
|
||||
}
|
||||
|
||||
- The driver's attribute update API just handles the attributes that
|
||||
are actually relevant for the device. For example, a
|
||||
color_dimmable_light handles the power, brightness, hue and
|
||||
saturation.
|
||||
|
||||
::
|
||||
|
||||
esp_err_t app_driver_attribute_update(int endpoint_id, int cluster_id, int attribute_id, esp_matter_attr_val_t *val) {
|
||||
esp_err_t err = ESP_OK;
|
||||
if (endpoint_id == light_endpoint_id) {
|
||||
if (cluster_id == OnOff::Id) {
|
||||
if (attribute_id == OnOff::Attributes::OnOff::Id) {
|
||||
err = app_driver_light_set_power(val);
|
||||
}
|
||||
} else if (cluster_id == LevelControl::Id) {
|
||||
if (attribute_id == LevelControl::Attributes::CurrentLevel::Id) {
|
||||
err = app_driver_light_set_brightness(val);
|
||||
}
|
||||
} else if (cluster_id == ColorControl::Id) {
|
||||
if (attribute_id == ColorControl::Attributes::CurrentHue::Id) {
|
||||
err = app_driver_light_set_hue(val);
|
||||
} else if (attribute_id == ColorControl::Attributes::CurrentSaturation::Id) {
|
||||
err = app_driver_light_set_saturation(val);
|
||||
}
|
||||
}
|
||||
}
|
||||
return err;
|
||||
}
|
||||
|
||||
2.4.1.4 Matter Device Ready
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
With the few lines of code that we've written above, your
|
||||
full-certifiable Matter device is now ready.
|
||||
|
||||
2.4.2 Defining your own data model
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Creating standard endpoints, clusters, attributes, commands. This can be
|
||||
used for the fields which HAVE been defined in the Matter specification.
|
||||
|
||||
2.4.2.1 Endpoints
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
The 'device' can be customized by editing the endpoint/device_type
|
||||
creating in the *app_main.cpp* of the example. Examples:
|
||||
|
||||
- on_off_light:
|
||||
|
||||
::
|
||||
|
||||
on_off_light::config_t light_config;
|
||||
endpoint_t *endpoint = on_off_light::create(node, &light_config, ENDPOINT_FLAG_NONE);
|
||||
|
||||
- fan:
|
||||
|
||||
::
|
||||
|
||||
fan::config_t light_config;
|
||||
endpoint_t *endpoint = fan::create(node, &light_config, ENDPOINT_FLAG_NONE);
|
||||
|
||||
|
||||
- door_lock:
|
||||
|
||||
::
|
||||
|
||||
door_lock::config_t light_config;
|
||||
endpoint_t *endpoint = door_lock::create(node, &light_config, ENDPOINT_FLAG_NONE);
|
||||
|
||||
|
||||
2.4.2.2 Clusters
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Additional clusters can also be added to an endpoint. Examples:
|
||||
|
||||
- on_off:
|
||||
|
||||
::
|
||||
|
||||
on_off::config_t on_off_config;
|
||||
cluster_t *cluster = on_off::create(endpoint, &on_off_config, CLUSTER_FLAG_SERVER, on_off::feature::lighting::get_id());
|
||||
|
||||
- temperature_measurement:
|
||||
|
||||
::
|
||||
|
||||
temperature_measurement::config_t temperature_measurement_config;
|
||||
cluster_t *cluster = temperature_measurement::create(endpoint, &temperature_measurement_config, CLUSTER_FLAG_SERVER);
|
||||
|
||||
2.4.2.3 Attributes and Commands
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Additional attributes or commands can also be added to a cluster.
|
||||
Examples:
|
||||
|
||||
- attribute: on_off:
|
||||
|
||||
::
|
||||
|
||||
bool default_on_off = true;
|
||||
attrbute_t *attribute = on_off::attribute::create_on_off(cluster, default_on_off);
|
||||
|
||||
- attribute: cluster_revision:
|
||||
|
||||
::
|
||||
|
||||
uint16_t default_cluster_revision = 1;
|
||||
attrbute_t *attribute = global::attribute::create_cluster_revision(cluster, default_cluster_revision);
|
||||
|
||||
- command: toggle:
|
||||
|
||||
::
|
||||
|
||||
command_t *command = on_off::command::create_toggle(cluster);
|
||||
|
||||
- command: move_to_level:
|
||||
|
||||
::
|
||||
|
||||
command_t *command = level_control::command::create_move_to_level(cluster);
|
||||
|
||||
2.4.3 Adding custom data model fields
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Creating custom endpoints, clusters, attributes, commands. This can be
|
||||
used for the fields which HAVE NOT been defined in the Matter
|
||||
specification.
|
||||
|
||||
2.4.3.1 Endpoints
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Non-Standard endpoint can be created, without any clusters.
|
||||
|
||||
- Endpoint create:
|
||||
|
||||
::
|
||||
|
||||
endpoint_t *endpoint = endpoint::create(node, ENDPOINT_FLAG_NONE);
|
||||
|
||||
2.4.3.2 Clusters
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Non-Standard/Custom clusters can also be created:
|
||||
|
||||
- Cluster create:
|
||||
|
||||
::
|
||||
|
||||
uint32_t custom_cluster_id = 0x131b0000;
|
||||
cluster_t *cluster = cluster::create(endpoint, custom_cluster_id, CLUSTER_FLAG_SERVER);
|
||||
|
||||
2.4.3.3 Attributes and Commands
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Non-Standard/Custom attributes can also be created on any cluster:
|
||||
|
||||
- Attribute create:
|
||||
|
||||
::
|
||||
|
||||
uint32_t custom_attribute_id = 0x0;
|
||||
uint16_t default_value = 100;
|
||||
attribute_t *attribute = attribute::create(cluster, custom_attribute_id, ATTRIBUTE_FLAG_NONE, esp_matter_uint16(default_value);
|
||||
|
||||
- Command create:
|
||||
|
||||
::
|
||||
|
||||
static esp_err_t command_callback(const ConcreteCommandPath &command_path, TLVReader &tlv_data, void
|
||||
*opaque_ptr)
|
||||
{
|
||||
ESP_LOGI(TAG, "Custom command callback");
|
||||
return ESP_OK;
|
||||
}
|
||||
|
||||
uint32_t custom_command_id = 0x0;
|
||||
command_t *command = command::create(cluster, custom_command_id, COMMAND_FLAG_ACCEPTED, command_callback);
|
||||
|
||||
2.4.4 Adding External Platforms for Matter
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This step is **optional** for most devices. ESP Matter provides support for overriding the default platform layer, so the BLE and Wi-Fi implementations can be customized. Here are the required steps for adding an external platform layer.
|
||||
|
||||
2.4.4.1 Creating the external platform directory
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Create a directory ``platform/${NEW_PLATFORM_NAME}`` in your codebase.
|
||||
You can typically copy
|
||||
``${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/src/platform/ESP32``
|
||||
as a start. Note that the new platform name should be something other than
|
||||
``ESP32``. In this article we'll use ``ESP32_custom`` as an example. The
|
||||
directory must be under ``platform`` folder to meet the Matter include
|
||||
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
|
||||
the ``ESP32_custom`` example platform. It simply compiles the ESP32
|
||||
platform in Matter without any modifications.
|
||||
|
||||
- The new platform directory must be added to the Matter include path. See
|
||||
the ``ESP32_custom_include`` config in the above mentioned file.
|
||||
- Multiple build configs must be exported to the build system. See the
|
||||
``buildconfig_header`` section in the file for the required definitions.
|
||||
|
||||
2.4.4.3 Editing Kconfigs
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Enable ``CONFIG_CHIP_ENABLE_EXTERNAL_PLATFORM``.
|
||||
- Set ``CONFIG_CHIP_EXTERNAL_PLATFORM_DIR`` to the relative path from
|
||||
``${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/config/esp32`` to
|
||||
the external platform directory. For instance, if your source tree is:
|
||||
|
||||
::
|
||||
|
||||
my_project
|
||||
├── esp-matter
|
||||
└── platform
|
||||
└── ESP32_custom
|
||||
|
||||
Then ``CONFIG_CHIP_EXTERNAL_PLATFORM_DIR`` would be ``../../../../../platform/ESP32_custom``.
|
||||
|
||||
- Disable ``CONFIG_BUILD_CHIP_TESTS``.
|
||||
- If your external platform does not support the *connectedhomeip/connectedhomeip/src/lib/shell/*
|
||||
provided in the Matter shell library, then disable ``CONFIG_ENABLE_CHIP_SHELL``.
|
||||
|
||||
2.4.4.4 Example Usage
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
As an example, you can build *light* example on ``ESP32_custom`` platform with following steps:
|
||||
|
||||
::
|
||||
|
||||
mkdir $ESP_MATTER_PATH/../platform
|
||||
cp -r $ESP_MATTER_PATH/connectedhomeip/connectedhomeip/src/platform/ESP32 $ESP_MATTER_PATH/../platform/ESP32_custom
|
||||
cp $ESP_MATTER_PATH/examples/common/external_platform/BUILD.gn $ESP_MATTER_PATH/../platform/ESP32_custom
|
||||
cd $ESP_MATTER_PATH/examples/light
|
||||
cp sdkconfig.defaults.ext_plat_ci sdkconfig.defaults
|
||||
idf.py build
|
||||
|
||||
2.5. Common Peripherals
|
||||
-----------------------
|
||||
|
||||
2.5.1 Button Driver
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- In the examples, the boot button on the devkit is mapped to
|
||||
``toggle``. In case the device is a client (eg. switch), the toggle
|
||||
command is sent to the binded devices.
|
||||
- Factory reset has also been mapped to the same boot button. When the
|
||||
button is pressed for more than 5 seconds, factory reset is
|
||||
triggered.
|
||||
|
||||
.. _using-a-different-button-driver:
|
||||
|
||||
2.5.1.1 Using a different button driver
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Out of the box, the SDK supports the button driver for buttons connected
|
||||
through GPIO or through ADC using a resistor divider circuit. You can
|
||||
switch the button driver by changing the *button_type* appropriately in
|
||||
your *esp_matter_device.cmake* file.
|
||||
|
||||
The selected button driver will be initialised in *app_driver_init()* by
|
||||
calling the *button_driver_get_config()* and the *iot_button_create()*
|
||||
APIs for that driver. More button driver configurations for button
|
||||
events can be done in *app_driver_init()*.
|
||||
|
||||
2.5.1.2 Writing your own button driver
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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
|
||||
the skeletal code and the empty APIs that the button driver is supposed
|
||||
to implement to plug into the SDK.
|
||||
|
||||
The driver has to implement the APIs in *button_driver.c*. These
|
||||
typically include APIs for initializing the driver and checking for
|
||||
button events. Take a look at *iot_button.h* for API definitions. You
|
||||
can also take a look at other button drivers for reference.
|
||||
|
||||
The configurations that this driver needs can be done from
|
||||
*button_driver_get_config()* in *device.c*
|
||||
|
||||
Once this driver is implemented, use this driver as mentioned in the
|
||||
subsection for :ref:`Using a different button driver <using-a-different-button-driver>`.
|
||||
|
||||
2.5.2 LED Driver
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
- In the light examples, the led on the devkit is initialized and the
|
||||
default values for power, brightness, hue, saturation, etc. are set
|
||||
to the default values from the data model.
|
||||
|
||||
.. _using-a-different-led-driver:
|
||||
|
||||
2.5.2.1 Using a different LED driver
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Espressif has production-ready drivers for a known set of LED drivers
|
||||
that we support out of the box. Please reach out to your Espressif
|
||||
representative to get a list of these drivers. Once you have the driver,
|
||||
you can rebuild the SDK by modifying your *esp_matter_device.cmake* file
|
||||
to point to the appropriate LED driver.
|
||||
|
||||
The selected LED driver will be initialised in *app_driver_init()* by
|
||||
calling the *led_driver_get_config()* and the *led_driver_init()* APIs
|
||||
for that driver.
|
||||
|
||||
2.5.2.2 Writing your own LED driver
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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
|
||||
skeletal code and the empty APIs that the LED driver is supposed to
|
||||
implement to plug into the SDK.
|
||||
|
||||
The driver has to implement the APIs in *led_driver.c*. These typically
|
||||
include APIs for initializing the driver and controlling the LEDs. Take
|
||||
a look at *led_driver.h* for API definitions. You can also take a look
|
||||
at other LED drivers for reference.
|
||||
|
||||
If there are any configurations that this driver needs, that can be done
|
||||
from *led_driver_get_config()* in *device.c*
|
||||
|
||||
Once this driver is implemented, use this driver as mentioned in the
|
||||
subsection for :ref:`Using a different led driver <using-a-different-led-driver>`.
|
||||
@@ -0,0 +1,41 @@
|
||||
Zigbee Bridge
|
||||
=============
|
||||
|
||||
1. Additional Environment Setup
|
||||
-------------------------------
|
||||
|
||||
todo.
|
||||
|
||||
2. Post Commissioning Setup
|
||||
---------------------------
|
||||
|
||||
todo.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,39 @@
|
||||
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.
|
||||
@@ -0,0 +1,147 @@
|
||||
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.
|
||||
@@ -0,0 +1,130 @@
|
||||
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 client send_to_binded <endpoint_id> <cluster_id> <command_id>
|
||||
|
||||
- Example: Off:
|
||||
|
||||
::
|
||||
|
||||
matter esp client send_to_binded 0x1 0x6 0x0
|
||||
|
||||
- Example: On:
|
||||
|
||||
::
|
||||
|
||||
matter esp client send_to_binded 0x1 0x6 0x1
|
||||
|
||||
- Example: Toggle:
|
||||
|
||||
::
|
||||
|
||||
matter esp client send_to_binded 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 ``send_to_binded``
|
||||
command and not the ``send`` command. The send command is 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.
|
||||
@@ -0,0 +1,97 @@
|
||||
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.
|
||||
+153
@@ -0,0 +1,153 @@
|
||||
A1 Appendix FAQs
|
||||
================
|
||||
|
||||
A1.1 Compilation errors
|
||||
-----------------------
|
||||
|
||||
I cannot build the application:
|
||||
|
||||
- Make sure you are on the correct esp-idf branch. Run ``git submodule
|
||||
update —init —recursive`` to make sure the submodules are at the
|
||||
correct heads
|
||||
- Make sure you have the correct ESP_MATTER_PATH (and any other paths)
|
||||
is (are) exported.
|
||||
- Delete the build/ directory and also sdkconfig and sdkconfig.old and
|
||||
then build again.
|
||||
- If you are still facing issues, reproduce the issue on the default
|
||||
example and then raise an `issue <https://github.com/espressif/esp-matter/issues>`__. Please make sure to
|
||||
share these:
|
||||
|
||||
- The complete build logs.
|
||||
- The esp-matter and esp-idf branch you are using.
|
||||
|
||||
A1.2 Device commissioning using chip-tool
|
||||
-----------------------------------------
|
||||
|
||||
I cannot commission a new device through the chip-tool:
|
||||
|
||||
- If the ``chip-tool pairing ble-wifi`` command is failing,
|
||||
make sure the arguments are correct.
|
||||
- Make sure Bluetooth is turned on, on your client (host).
|
||||
- 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.
|
||||
- The complete chip-tool logs.
|
||||
- The esp-matter and esp-idf branch you are using.
|
||||
|
||||
Bluetooth/BLE does not work on by device:
|
||||
|
||||
- There are some known issues where BLE does not work on MacOS.
|
||||
- In this case, the following can be done:
|
||||
|
||||
- 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``.
|
||||
|
||||
- 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 complete chip-tool logs.
|
||||
- The esp-matter and esp-idf branch you are using.
|
||||
|
||||
A1.3 Device crashing
|
||||
--------------------
|
||||
|
||||
My device is crashing:
|
||||
|
||||
- Given the tight footprint requirements of the device, please make
|
||||
sure any issues in your code have been ruled out. If you believe the
|
||||
issue is with the ESP Matter SDK itself, please recreate the issue on
|
||||
the default example application (without any changes) and go through
|
||||
the following steps:
|
||||
- Make sure you are on the correct esp-idf branch. Run ``git submodule
|
||||
update —init —recursive`` to make sure the submodules are at the
|
||||
correct heads.
|
||||
- Make sure you have the correct ESP_MATTER_PATH (and any other paths)
|
||||
is (are) exported.
|
||||
- Delete the build/ directory and also sdkconfig and sdkconfig.old and
|
||||
then build and flash 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 steps you followed to reproduce the issue.
|
||||
|
||||
- The complete device logs taken over UART.
|
||||
|
||||
-
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<example>
|
||||
|
||||
.elf file from the build/ directory.
|
||||
|
||||
- If you have gdb enabled, run the command ``backtrace`` and share the
|
||||
output of gdb too.
|
||||
|
||||
- The esp-matter and esp-idf branch you are using.
|
||||
|
||||
A1.4 Device not crashed but not responding
|
||||
------------------------------------------
|
||||
|
||||
My device is not responding to commands:
|
||||
|
||||
- Make sure your device is commissioned successfully and connected is
|
||||
to the Wi-Fi.
|
||||
- Make sure the node_id and the endpoint_id are correct in the command
|
||||
from chip-tool.
|
||||
- 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 steps you followed to reproduce the issue.
|
||||
- The complete device logs taken over UART.
|
||||
- The esp-matter and esp-idf branch you are using.
|
||||
|
||||
A1.5 QR code not rendering
|
||||
--------------------------
|
||||
|
||||
The QR code on my device console is not rendering properly:
|
||||
|
||||
- Check the below lines on your terminal and copy paste the given URL
|
||||
in a browser:
|
||||
|
||||
::
|
||||
|
||||
If QR code is not visible, copy paste the URL in a browser:
|
||||
https://dhrishi.github.io/connectedhomeip/qrcode.html?data=....
|
||||
|
||||
A1.6 Onboard LED not working
|
||||
----------------------------
|
||||
|
||||
The LED on my devkit is not working:
|
||||
|
||||
- Make sure you have selected the proper ``device``. You can explicitly
|
||||
do that by exporting the ``ESP_MATTER_DEVICE_PATH`` to the correct
|
||||
path.
|
||||
- Check the version of your board, and if it has the LED connected to a
|
||||
different pin. If it is different, you can change the
|
||||
led_driver_config_t accordingly in the device.c file.
|
||||
- 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 and esp-idf branch you are using.
|
||||
- The devkit and its version that you are using.
|
||||
|
||||
**Also check the "Appendix FAQs" sections of the respective examples.**
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Light <examples/light>
|
||||
RainMaker Light <examples/rainmaker_light>
|
||||
Switch <examples/switch>
|
||||
Zap Light <examples/zap_light>
|
||||
Zigbee Bridge <examples/bridge_zigbee>
|
||||
@@ -0,0 +1,26 @@
|
||||
ESP Matter Programming Guide
|
||||
============================
|
||||
|
||||
`Matter <https://csa-iot.org/all-solutions/matter/>`__ is the unified IP-based
|
||||
connectivity protocol built on proven technologies, helping connect and
|
||||
build open, reliable and 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
|
||||
Espressif's ESP32 series SoCs.
|
||||
|
||||
Espressif has put together a series of blog posts that look at various aspects of Matter. You can see here: `Espressif Matter Blog <https://blog.espressif.com/matter-38ccf1d60bcd>`__.
|
||||
|
||||
Table of Contents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
1. Introduction <introduction>
|
||||
2. Developing with ESP Matter <developing>
|
||||
3. Matter Certification <certification>
|
||||
4. Production Considerations <production>
|
||||
5. API Reference <api-reference/index>
|
||||
A1 Appendix FAQs <faq>
|
||||
@@ -0,0 +1,119 @@
|
||||
1. Introduction
|
||||
===============
|
||||
|
||||
1.1 Solution Architecture
|
||||
-------------------------
|
||||
|
||||
The typical solution architecture of the product is shown as below.
|
||||
|
||||
.. figure:: ../_static/solution_architecture.png
|
||||
:align: center
|
||||
:alt: ESP Matter Solution Architecture
|
||||
:figclass: align-center
|
||||
|
||||
todo. Add image. Add explanation.
|
||||
|
||||
1.2 The Software
|
||||
----------------
|
||||
|
||||
todo. Add some general explanation.
|
||||
|
||||
.. 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.
|
||||
|
||||
1.3 Solutions
|
||||
-------------
|
||||
|
||||
1.3.1 Simple Device
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
These are typically basic/simple devices.
|
||||
|
||||
- Light Bulb
|
||||
- Switch
|
||||
- Temperature sensor
|
||||
|
||||
1.3.2 Multi-Device
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
These are a combination of more than one simple devices.
|
||||
|
||||
- Fan with Light
|
||||
- Temperature sensor and Proximity sensor
|
||||
|
||||
1.3.3 Bridge
|
||||
~~~~~~~~~~~~
|
||||
|
||||
These devices facilitate using non-Matter devices in a Matter network.
|
||||
|
||||
- Zigbee bridge
|
||||
- BLE mesh bridge
|
||||
|
||||
1.3.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
|
||||
~~~~~~~~~
|
||||
|
||||
These can be used to control other Matter devices.
|
||||
|
||||
- Touch-screen control panel
|
||||
- Hub with internet connectivity for remote control
|
||||
|
||||
1.4 Examples
|
||||
------------
|
||||
|
||||
1.4.1 Light
|
||||
~~~~~~~~~~~
|
||||
|
||||
This application creates a Color Dimmable Light device using the ESP
|
||||
Matter data model.
|
||||
|
||||
1.4.2 RainMaker Light
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This application creates a Color Dimmable Light device using the ESP
|
||||
Matter data model.
|
||||
|
||||
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
|
||||
~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
switch and then controlled from the switch.
|
||||
|
||||
1.4.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
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
todo.
|
||||
|
||||
1.5 Try it yourself
|
||||
-------------------
|
||||
|
||||
1.5.1 ESP Launchpad
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This allows you to quickly try out Matter on Espressif devices through a web browser.
|
||||
|
||||
|
||||
ESP Launchpad: https://espressif.github.io/esp-launchpad/.
|
||||
@@ -0,0 +1,107 @@
|
||||
4. Production Considerations
|
||||
============================
|
||||
|
||||
4.1 Over-the-air Updates (OTA)
|
||||
------------------------------
|
||||
|
||||
ESP-IDF has a component for OTA from any URL. More information and
|
||||
details about implementing can be found here:
|
||||
`esp_https_ota <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/esp_https_ota.html#esp-https-ota>`__.
|
||||
|
||||
todo. add about DCL.
|
||||
|
||||
4.2 Getting your own Vendor ID and Product ID
|
||||
---------------------------------------------
|
||||
|
||||
todo. Info about DAC, pai, paa too.
|
||||
|
||||
4.3 Manufacturing
|
||||
-----------------
|
||||
|
||||
4.3.1 Mass Manufacturing Utility
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For commissioning a device into the Matter Fabric, the device requires the following information:
|
||||
|
||||
- **Device Attestation Certificate (DAC) and Certification Declaration (CD)**: verified by commissioner to determine whether a device is a Matter certified product or not.
|
||||
- **Discriminator**: advertised during commissioning to easily distinguish between advertising devices.
|
||||
- **Spake2+ parameters**: work as a proof of possession.
|
||||
|
||||
These details are generally programmed in the factory NVS partitions that are unique
|
||||
per device. ESP-Matter provides a utility (mfg_tool.py) to create instances of the factory NVS partition images on a per-device basis for mass manufacturing purposes.
|
||||
|
||||
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`.
|
||||
|
||||
4.3.2 Pre-Provisioned Modules
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
ESP32 modules can be pre-flashed with the factory NVS partition during
|
||||
manufacturing itself and then be shipped to you.
|
||||
|
||||
This saves you the overhead of securely generating, encrypting and then
|
||||
programming the NVS partition into the device at your end.
|
||||
Pre-provisioning is an optional service which Espressif provides.
|
||||
|
||||
Details about pre-provisioned modules can be found here:
|
||||
`docs <https://glab.espressif.cn/alexa/esp-va-sdk/wikis/home>`__.
|
||||
|
||||
Please contact your Espressif contact person for more information.
|
||||
|
||||
4.4 Security
|
||||
------------
|
||||
|
||||
4.4.1 Secure Boot
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Secure boot ensures that only trusted code runs on the device.
|
||||
|
||||
ESP32 supports RSA based secure boot scheme whereby the bootROM verifies
|
||||
the software boot loader for authenticity using the RSA algorithm. The
|
||||
verified software boot loader then checks the partition table and
|
||||
verifies the active application firmware and then boots it.
|
||||
|
||||
More information about how secure boot works on ESP32 can be found here:
|
||||
`docs <https://glab.espressif.cn/alexa/esp-va-sdk/wikis/home>`__.
|
||||
|
||||
Details about implementing the secure boot can be found here:
|
||||
`secure_boot <https://docs.espressif.com/projects/esp-idf/en/latest/security/secure-boot.html>`__.
|
||||
|
||||
4.4.2 Flash Encryption
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Flash encryption prevents the plain-text reading of the flash contents.
|
||||
|
||||
ESP32 supports AES-256 based flash encryption scheme. The ESP32 flash
|
||||
controller has an ability to access the flash contents encrypted with a
|
||||
key and place them in the cache after decryption. It also has ability to
|
||||
allow to write the data to the flash by encrypting it. Both the
|
||||
read/write encryption operations happen transparently.
|
||||
|
||||
More information about how flash encryption works on ESP32 can be found
|
||||
here: `docs <https://glab.espressif.cn/alexa/esp-va-sdk/wikis/home>`__.
|
||||
|
||||
Details about implementing the flash encryption can be found here:
|
||||
`flash_encryption <https://docs.espressif.com/projects/esp-idf/en/latest/security/flash-encryption.html>`__.
|
||||
|
||||
4.4.3 NVS Encryption
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For the manufacturing data that needs to be stored on the device in the
|
||||
NVS format, ESP-IDF provides the NVS image creation utility which allows
|
||||
the encryption of NVS partition on the host using a randomly generated
|
||||
(per device unique) or pre-generated (common for a batch) NVS encryption
|
||||
key.
|
||||
|
||||
A separate flash partition is used for storing the NVS encryption keys.
|
||||
This flash partition is then encrypted using flash encryption. So, flash
|
||||
encryption becomes a mandatory feature to secure the NVS encryption
|
||||
keys.
|
||||
|
||||
More information about how NVS encryption works on ESP32 can be found
|
||||
here: `docs <https://glab.espressif.cn/alexa/esp-va-sdk/wikis/home>`__.
|
||||
|
||||
Details about implementing the NVS encryption can be found here:
|
||||
`nvs_encryption <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/storage/nvs_flash.html#nvs-encryption>`__.
|
||||
@@ -0,0 +1 @@
|
||||
esp-docs==0.2.1
|
||||
Executable
+18
@@ -0,0 +1,18 @@
|
||||
# Bash helper functions for adding SSH keys
|
||||
|
||||
function add_ssh_keys() {
|
||||
local key_string="${1}"
|
||||
mkdir -p ~/.ssh
|
||||
chmod 700 ~/.ssh
|
||||
echo -n "${key_string}" >~/.ssh/id_rsa_base64
|
||||
base64 --decode --ignore-garbage ~/.ssh/id_rsa_base64 >~/.ssh/id_rsa
|
||||
chmod 600 ~/.ssh/id_rsa
|
||||
}
|
||||
|
||||
function add_doc_server_ssh_keys() {
|
||||
local key_string="${1}"
|
||||
local server_url="${2}"
|
||||
local server_user="${3}"
|
||||
add_ssh_keys "${key_string}"
|
||||
echo -e "Host ${server_url}\n\tStrictHostKeyChecking no\n\tUser ${server_user}\n" >>~/.ssh/config
|
||||
}
|
||||
@@ -34,7 +34,7 @@ note:
|
||||
After the binding is successful you can send the following command to control light from switch
|
||||
|
||||
```
|
||||
> matter esp driver send_bind <endpoint_id> <cluster_id> <command_id>
|
||||
> matter esp client send_to_binded <endpoint_id> <cluster_id> <command_id>
|
||||
```
|
||||
here, endpoint_id, cluster_id, command_id of switch must be given in hex format
|
||||
|
||||
@@ -43,17 +43,17 @@ e.g.
|
||||
- Power Off command
|
||||
|
||||
```
|
||||
> matter esp driver send_bind 0x0001 0x0006 0x0000
|
||||
> matter esp client send_to_binded 0x0001 0x0006 0x0000
|
||||
```
|
||||
|
||||
- Power On command
|
||||
|
||||
```
|
||||
> matter esp driver send_bind 0x0001 0x0006 0x0001
|
||||
> matter esp client send_to_binded 0x0001 0x0006 0x0001
|
||||
```
|
||||
|
||||
- Toggle command
|
||||
|
||||
```
|
||||
> matter esp driver send_bind 0x0001 0x0006 0x0002
|
||||
> matter esp client send_to_binded 0x0001 0x0006 0x0002
|
||||
```
|
||||
|
||||
@@ -34,11 +34,11 @@ static esp_err_t app_driver_console_handler(int argc, char **argv)
|
||||
if (argc == 1 && strncmp(argv[0], "help", sizeof("help")) == 0) {
|
||||
printf("Driver commands:\n"
|
||||
"\thelp: Print help\n"
|
||||
"\tsend_bind: <endpoint_id> <cluster_id> <command_id>. "
|
||||
"Example: matter esp driver send_bind 0x0001 0x0006 0x0002.\n"
|
||||
"\tsend_to_binded: <endpoint_id> <cluster_id> <command_id>. "
|
||||
"Example: matter esp client send_to_binded 0x0001 0x0006 0x0002.\n"
|
||||
"\tsend: <fabric_index> <remote_node_id> <remote_endpoint_id> <cluster_id> <command_id>. "
|
||||
"Example: matter esp driver send 0x0001 0xBC5C01 0x0001 0x0006 0x0002.\n");
|
||||
} else if (argc == 4 && strncmp(argv[0], "send_bind", sizeof("send_bind")) == 0) {
|
||||
"Example: matter esp client send 0x0001 0xBC5C01 0x0001 0x0006 0x0002.\n");
|
||||
} else if (argc == 4 && strncmp(argv[0], "send_to_binded", sizeof("send_to_binded")) == 0) {
|
||||
int endpoint_id = strtol((const char *)&argv[1][2], NULL, 16);
|
||||
int cluster_id = strtol((const char *)&argv[2][2], NULL, 16);
|
||||
int command_id = strtol((const char *)&argv[3][2], NULL, 16);
|
||||
@@ -66,9 +66,9 @@ static esp_err_t app_driver_console_handler(int argc, char **argv)
|
||||
static void app_driver_register_commands()
|
||||
{
|
||||
esp_matter_console_command_t command = {
|
||||
.name = "driver",
|
||||
.description = "This can be used to simulate on-device control. Usage: matter esp driver <driver_command>. "
|
||||
"Driver commands: help, send, send_bind",
|
||||
.name = "client",
|
||||
.description = "This can be used to simulate on-device control. Usage: matter esp client <driver_command>. "
|
||||
"Driver commands: help, send, send_to_binded",
|
||||
.handler = app_driver_console_handler,
|
||||
};
|
||||
esp_matter_console_add_command(&command);
|
||||
|
||||
@@ -49,6 +49,9 @@ esp_matter_export_main() {
|
||||
|
||||
# PATH for gn
|
||||
export PATH=${PATH}:${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/.environment/cipd/packages/pigweed/
|
||||
|
||||
# PATH for chip-tool
|
||||
export PATH=${PATH}:${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/examples/chip-tool/out/
|
||||
}
|
||||
|
||||
esp_matter_export_main
|
||||
|
||||
Executable
+23
@@ -0,0 +1,23 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
basedir=$(dirname "$0")
|
||||
ESP_MATTER_PATH=$(cd "${basedir}"; pwd)
|
||||
export ESP_MATTER_PATH
|
||||
|
||||
echo ""
|
||||
echo "Running Matter Setup"
|
||||
echo ""
|
||||
source ${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/scripts/bootstrap.sh
|
||||
|
||||
echo ""
|
||||
echo "Building chip-tool"
|
||||
echo ""
|
||||
${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/scripts/examples/gn_build_example.sh ${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/examples/chip-tool ${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/examples/chip-tool/out/
|
||||
echo ""
|
||||
echo "Created chip-tool executable at: ${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/examples/chip-tool/out/"
|
||||
echo ""
|
||||
|
||||
echo "All done! You can now run:"
|
||||
echo ""
|
||||
echo " . ${basedir}/export.sh"
|
||||
echo ""
|
||||
Reference in New Issue
Block a user