diff --git a/docs/conf_common.py b/docs/conf_common.py index 8555d89f7..002ac59d2 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -25,6 +25,8 @@ linkcheck_anchors = False linkcheck_ignore = [ # Private repositories 'https://github.com/CHIP-Specifications/.*', + 'https://community.csa-iot.org/.*', + 'https://groups.csa-iot.org/.*', # Internal documentation links './developing.html#.*', diff --git a/docs/en/api-reference/index.rst b/docs/en/api-reference/index.rst index 50b30d141..8ab270914 100644 --- a/docs/en/api-reference/index.rst +++ b/docs/en/api-reference/index.rst @@ -1,5 +1,5 @@ -7. API Reference -================ +API Reference +============= .. toctree:: :maxdepth: 1 diff --git a/docs/en/app_guide.rst b/docs/en/app_guide.rst index 88d93fbe4..ce2d44f5a 100644 --- a/docs/en/app_guide.rst +++ b/docs/en/app_guide.rst @@ -1,303 +1,419 @@ Application User Guide ====================== -1. Delegate Implementation --------------------------- +Delegate Implementation +----------------------- As per the implementation in the connectedhomeip repository, some of the clusters require an application defined delegate to consume specific data and actions. In order to provide this flexibity to the application, esp-matter facilitates delegate -initilization callbacks in the cluster create API. It is expected that application +initialization callbacks in the cluster create API. It is expected that application will define it's data and actions in the form of delegate-impl class and set the delegate while creating cluster/device type. List of clusters with delegate: - - Account Login Cluster. - - Actions Cluster. - - Application Basic Cluster. - - Application Launcher Cluster. - - Audio Output Cluster. - - Boolean State Configuration Cluster. - - Camera AV Settings User Level Management Cluster. - - Channel Cluster. - - Closure Control Cluster. - - Closure Dimension Cluster. - - Commissioner Control Cluster. - - Content App Observer Cluster. - - Content Control Cluster. - - Content Launcher Cluster. - - Device Energy Management Cluster. - - Dishwasher Alarm Cluster. - - Door Lock Cluster. - - Electrical Power Measurement Cluster. - - Energy EVSE Cluster. - - Energy Preference Cluster. - - Fan Control Cluster. - - Keypad Input Cluster. - - Laundry Dryer Controls Cluster. - - Laundry Washer Controls Cluster. - - Low Power Cluster. - - Media Input Cluster. - - Media Playback Cluster. - - Messages Cluster. - - Microwave Oven Control Cluster. - - Mode Base Cluster (all derived types of clusters). - - Mode Select Cluster. - - Operational State Cluster. - - Power Topology Cluster. - - Resource Monitoring Cluster. - - Service Area Cluster. - - Target Navigator Cluster. - - Thermostat Cluster. - - Time Synchronization Cluster. - - Valve Configuration And Control Cluster. - - Wake On Lan Cluster. - - Water Heater Management Cluster. - - WebRTC Transport Provider Cluster. - - Window Covering Cluster. - - Chime Cluster. - - Push AV Stream Transport Cluster. - - Commodity Tariff Cluster. - - Commodity Price Cluster. - - Electrical Grid Conditions Cluster. + +.. keep-sorted start + +- Account Login Cluster. +- Actions Cluster. +- Application Basic Cluster. +- Application Launcher Cluster. +- Audio Output Cluster. +- Boolean State Configuration Cluster. +- Camera AV Settings User Level Management Cluster. +- Channel Cluster. +- Chime Cluster. +- Closure Control Cluster. +- Closure Dimension Cluster. +- Commissioner Control Cluster. +- Commodity Price Cluster. +- Commodity Tariff Cluster. +- Content App Observer Cluster. +- Content Control Cluster. +- Content Launcher Cluster. +- Device Energy Management Cluster. +- Dishwasher Alarm Cluster. +- Door Lock Cluster. +- Electrical Grid Conditions Cluster. +- Electrical Power Measurement Cluster. +- Energy EVSE Cluster. +- Energy Preference Cluster. +- Fan Control Cluster. +- Keypad Input Cluster. +- Laundry Dryer Controls Cluster. +- Laundry Washer Controls Cluster. +- Low Power Cluster. +- Media Input Cluster. +- Media Playback Cluster. +- Messages Cluster. +- Microwave Oven Control Cluster. +- Mode Base Cluster (all derived types of clusters). +- Mode Select Cluster. +- Operational State Cluster. +- Power Topology Cluster. +- Push AV Stream Transport Cluster. +- Resource Monitoring Cluster. +- Service Area Cluster. +- Target Navigator Cluster. +- Thermostat Cluster. +- Time Synchronization Cluster. +- Valve Configuration And Control Cluster. +- Wake On Lan Cluster. +- Water Heater Management Cluster. +- WebRTC Transport Provider Cluster. +- Window Covering Cluster. + +.. keep-sorted end Below is the list of clusters with delegate and their reference implementation header files: -1.1 Account Login Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~ +.. keep-sorted start block=yes -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" +.. { - `Account Login`_, `Account Login Delegate`_ - -1.2 Actions Cluster -~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Actions`_, None - -1.3 Application Basic Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Application Basic`_, `Application Basic Delegate`_ - -1.4 Application Launcher Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Application Launcher`_, `Application Launcher Delegate`_ - -1.5 Audio Output Cluster -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Audio Output`_, `Audio Output Delegate`_ - -1.6 Boolean State Configuration Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Boolean State Configuration`_, `Boolean State Configuration Delegate`_ - -1.7 Camera AV Settings User Level Management Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Camera AV Settings User Level Management`_, `Camera AV Settings User Level Management Delegate`_ - -1.8 Channel Cluster -~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Channel`_, `Channel Delegate`_ - -1.9 Closure Control Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Closure Control`_, `Closure Control Delegate`_ - -1.10 Closure Dimension Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Closure Dimension`_, `Closure Dimension Delegate`_ - -1.11 Commissioner Control Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Commissioner Control`_, `Commissioner Control Delegate`_ - -1.12 Content App Observer Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Content App Observer`_, None - -1.13 Content Control Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Content Control`_, None - -1.14 Content Launcher Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Content Launcher`_, `Content Launcher Delegate`_ - -1.15 Device Energy Management Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Device Energy Management`_, `Device Energy Management Delegate`_ - -1.16 Dishwasher Alarm Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Dishwasher Alarm`_, `Dishwasher Alarm Delegate`_ - -1.17 Door Lock Cluster -~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Door Lock`_, `Door Lock Delegate`_ - -1.18 Electrical Power Measurement Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Electrical Power Measurement`_, `Electrical Power Measurement Delegate`_ - -1.19 Energy Evse Cluster -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Energy Evse`_, `Energy Evse Delegate`_ - -1.20 Energy Preference Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Energy Preference`_, `Energy Preference Delegate`_ - -1.21 Fan Control Cluster -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Fan Control`_, `Fan Control Delegate`_ - -1.22 Keypad Input Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Keypad Input`_, `Keypad Input Delegate`_ - -1.23 Laundry Dryer Controls Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Laundry Dryer Controls`_, `Laundry Dryer Controls Delegate`_ - -1.24 Laundry Washer Controls Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Laundry Washer Controls`_, `Laundry Washer Controls Delegate`_ - -1.25 Low Power Cluster -~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Low Power`_, `Low Power Delegate`_ - -1.26 Media Input Cluster -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Media Input`_, `Media Input Delegate`_ - -1.27 Media Playback Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Media Playback`_, `Media Playback Delegate`_ - -1.28 Messages Cluster +Account Login Cluster ~~~~~~~~~~~~~~~~~~~~~ .. csv-table:: :header: "Delegate Class", "Reference Implementation" - `Messages`_, `Messages Delegate`_ + `Account Login`_, `Account Login Delegate`_ +.. } +.. { -1.29 Microwave Oven Control Cluster +Actions Cluster +~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Actions`_, None +.. } +.. { + +Application Basic Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Application Basic`_, `Application Basic Delegate`_ +.. } +.. { + +Application Launcher Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Application Launcher`_, `Application Launcher Delegate`_ +.. } +.. { + +Audio Output Cluster +~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Audio Output`_, `Audio Output Delegate`_ +.. } +.. { + +Boolean State Configuration Cluster ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. csv-table:: :header: "Delegate Class", "Reference Implementation" - `Microwave Oven Control`_, `Microwave Oven Control Delegate`_ + `Boolean State Configuration`_, `Boolean State Configuration Delegate`_ +.. } +.. { -1.30 Mode Base Cluster +Camera AV Settings User Level Management Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Camera AV Settings User Level Management`_, `Camera AV Settings User Level Management Delegate`_ +.. } +.. { + +Channel Cluster +~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Channel`_, `Channel Delegate`_ +.. } +.. { + +Chime Cluster +~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Chime`_, `Chime Delegate`_ +.. } +.. { + +Closure Control Cluster +~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Closure Control`_, `Closure Control Delegate`_ +.. } +.. { + +Closure Dimension Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Closure Dimension`_, `Closure Dimension Delegate`_ +.. } +.. { + +Commissioner Control Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Commissioner Control`_, `Commissioner Control Delegate`_ +.. } +.. { + +Commodity Price Cluster +~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Commodity Price`_, `Commodity Price Delegate`_ +.. } +.. { + +Commodity Tariff Cluster +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Commodity Tariff`_, `Commodity Tariff Delegate`_ +.. } +.. { + +Content App Observer Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Content App Observer`_, None +.. } +.. { + +Content Control Cluster +~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Content Control`_, None +.. } +.. { + +Content Launcher Cluster +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Content Launcher`_, `Content Launcher Delegate`_ +.. } +.. { + +Device Energy Management Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Device Energy Management`_, `Device Energy Management Delegate`_ +.. } +.. { + +Dishwasher Alarm Cluster +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Dishwasher Alarm`_, `Dishwasher Alarm Delegate`_ +.. } +.. { + +Door Lock Cluster +~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Door Lock`_, `Door Lock Delegate`_ +.. } +.. { + +Electrical Grid Conditions Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Electrical Grid Conditions`_, `Electrical Grid Conditions Delegate`_ + +.. note:: + Make sure that after implementing delegate class, you set the delegate class pointer at the time of creating cluster. + + :: + + robotic_vacuum_cleaner::config_t rvc_config; + rvc_config.rvc_run_mode.delegate = object_of_delegate_class; + endpoint_t *endpoint = robotic_vacuum_cleaner::create(node, & rvc_config, ENDPOINT_FLAG_NONE); +.. } +.. { + +Electrical Power Measurement Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Electrical Power Measurement`_, `Electrical Power Measurement Delegate`_ +.. } +.. { + +Energy Evse Cluster +~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Energy Evse`_, `Energy Evse Delegate`_ +.. } +.. { + +Energy Preference Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Energy Preference`_, `Energy Preference Delegate`_ +.. } +.. { + +Fan Control Cluster +~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Fan Control`_, `Fan Control Delegate`_ +.. } +.. { + +Keypad Input Cluster +~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Keypad Input`_, `Keypad Input Delegate`_ +.. } +.. { + +Laundry Dryer Controls Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Laundry Dryer Controls`_, `Laundry Dryer Controls Delegate`_ +.. } +.. { + +Laundry Washer Controls Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Laundry Washer Controls`_, `Laundry Washer Controls Delegate`_ +.. } +.. { + +Low Power Cluster +~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Low Power`_, `Low Power Delegate`_ +.. } +.. { + +Media Input Cluster +~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Media Input`_, `Media Input Delegate`_ +.. } +.. { + +Media Playback Cluster ~~~~~~~~~~~~~~~~~~~~~~ +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Media Playback`_, `Media Playback Delegate`_ +.. } +.. { + +Messages Cluster +~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Messages`_, `Messages Delegate`_ +.. } +.. { + +Microwave Oven Control Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Microwave Oven Control`_, `Microwave Oven Control Delegate`_ +.. } +.. { + +Mode Base Cluster +~~~~~~~~~~~~~~~~~ + It is a base cluster for ModeEVSE, ModeOven, ModeRVSRun, ModeRVSClean, ModeDishwasher, ModeWaterHeater, ModeRefrigerator, ModeLaundryWasher and ModeMicrowaveOven. @@ -312,261 +428,255 @@ ModeWaterHeater, ModeRefrigerator, ModeLaundryWasher and ModeMicrowaveOven. , `Microwave Oven Mode`_ , `Device Energy Management Mode`_ , `Water Heater Mode`_ +.. } +.. { -1.31 Mode Select Cluster -~~~~~~~~~~~~~~~~~~~~~~~~ +Mode Select Cluster +~~~~~~~~~~~~~~~~~~~ .. csv-table:: :header: "Delegate Class", "Reference Implementation" `Mode Select`_, `Mode Select Delegate`_ +.. } +.. { -1.32 Operational State Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Operational State Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~ .. csv-table:: :header: "Delegate Class", "Reference Implementation" `Operational State`_, `Operational State Delegate`_ +.. } +.. { -1.33 Power Topology Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Power Topology Cluster +~~~~~~~~~~~~~~~~~~~~~~ .. csv-table:: :header: "Delegate Class", "Reference Implementation" `Power Topology`_, `Power Topology Delegate`_ +.. } +.. { -1.34 Resource Monitoring Cluster +Push AV Stream Transport Cluster ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Push AV Stream Transport`_, `Push AV Stream Transport Delegate`_ +.. } +.. { + +Resource Monitoring Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. csv-table:: :header: "Delegate Class", "Reference Implementation" `Resource Monitoring`_, `HEPA Filter Monitoring Delegate`_ , `Activated Carbon Filter Monitoring Delegate`_ , `Water Tank Level Monitoring Delegate` +.. } +.. { -1.35 Service Area Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~ +Service Area Cluster +~~~~~~~~~~~~~~~~~~~~ .. csv-table:: :header: "Delegate Class", "Reference Implementation" `Service Area`_, `Service Area Delegate`_ +.. } +.. { -1.36 Target Navigator Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Target Navigator`_, `Target Navigator Delegate`_ - -1.37 Thermostat Cluster -~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Thermostat`_, `Thermostat Delegate`_ - -1.38 Time Synchronization Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Time Synchronization`_, `Time Synchronization Delegate`_ - -1.39 Valve Configuration And Control Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Valve Configuration And Control`_, `Valve Configuration And Control Delegate`_ - -1.40 Wake On LAN Cluster +Target Navigator Cluster ~~~~~~~~~~~~~~~~~~~~~~~~ .. csv-table:: :header: "Delegate Class", "Reference Implementation" - `Wake On LAN`_, `Wake On LAN Delegate`_ + `Target Navigator`_, `Target Navigator Delegate`_ +.. } +.. { -1.41 Water Heater Management Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Water Heater Management`_, `Water Heater Management Delegate`_ - -1.42 WebRTC Transport Provider Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `WebRTC Transport Provider`_, `WebRTC Transport Provider Delegate`_ - -1.43 Window Covering Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Window Covering`_, `Window Covering Delegate`_ - -1.44 Chime Cluster +Thermostat Cluster ~~~~~~~~~~~~~~~~~~ .. csv-table:: :header: "Delegate Class", "Reference Implementation" + + `Thermostat`_, `Thermostat Delegate`_ +.. } +.. { - `Chime`_, `Chime Delegate`_ - -1.45 Push AV Stream Transport Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Push AV Stream Transport`_, `Push AV Stream Transport Delegate`_ - -1.46 Commodity Tariff Cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: - :header: "Delegate Class", "Reference Implementation" - - `Commodity Tariff`_, `Commodity Tariff Delegate`_ - -1.47 Commodity Price Cluster +Time Synchronization Cluster ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. csv-table:: :header: "Delegate Class", "Reference Implementation" - `Commodity Price`_, `Commodity Price Delegate`_ + `Time Synchronization`_, `Time Synchronization Delegate`_ +.. } +.. { -1.48 Electrical Grid Conditions Cluster +Valve Configuration And Control Cluster ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. csv-table:: :header: "Delegate Class", "Reference Implementation" - `Electrical Grid Conditions`_, `Electrical Grid Conditions Delegate`_ + `Valve Configuration And Control`_, `Valve Configuration And Control Delegate`_ +.. } +.. { -.. note:: - Make sure that after implementing delegate class, you set the delegate class pointer at the time of creating cluster. +Wake On LAN Cluster +~~~~~~~~~~~~~~~~~~~ - :: +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" - robotic_vacuum_cleaner::config_t rvc_config; - rvc_config.rvc_run_mode.delegate = object_of_delegate_class; - endpoint_t *endpoint = robotic_vacuum_cleaner::create(node, & rvc_config, ENDPOINT_FLAG_NONE); + `Wake On LAN`_, `Wake On LAN Delegate`_ +.. } +.. { + +Water Heater Management Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Water Heater Management`_, `Water Heater Management Delegate`_ +.. } +.. { + +WebRTC Transport Provider Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `WebRTC Transport Provider`_, `WebRTC Transport Provider Delegate`_ +.. } +.. { + +Window Covering Cluster +~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Delegate Class", "Reference Implementation" + + `Window Covering`_, `Window Covering Delegate`_ +.. } + +.. keep-sorted end + +.. keep-sorted start -.. _`Account Login`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/account-login-server/account-login-delegate.h .. _`Account Login Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/android/include/account-login/AccountLoginManager.h -.. _`Actions`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/actions-server/actions-server.h +.. _`Account Login`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/account-login-server/account-login-delegate.h .. _`Actions Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/bridged-actions-stub.h -.. _`Application Basic`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/application-basic-server/application-basic-delegate.h +.. _`Actions`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/actions-server/actions-server.h +.. _`Activated Carbon Filter Monitoring Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/resource-monitoring-delegates.h .. _`Application Basic Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/application-basic/ApplicationBasicManager.h -.. _`Application Launcher`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/application-launcher-server/application-launcher-delegate.h +.. _`Application Basic`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/application-basic-server/application-basic-delegate.h .. _`Application Launcher Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/application-launcher/ApplicationLauncherManager.h -.. _`Audio Output`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/audio-output-server/audio-output-delegate.h +.. _`Application Launcher`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/application-launcher-server/application-launcher-delegate.h .. _`Audio Output Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/audio-output/AudioOutputManager.h -.. _`Boolean State Configuration`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/boolean-state-configuration-server/boolean-state-configuration-delegate.h +.. _`Audio Output`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/audio-output-server/audio-output-delegate.h .. _`Boolean State Configuration Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/src/boolcfg-stub.cpp -.. _`Camera AV Settings User Level Management`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/camera-av-settings-user-level-management-server/camera-av-settings-user-level-management-server.h +.. _`Boolean State Configuration`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/boolean-state-configuration-server/boolean-state-configuration-delegate.h .. _`Camera AV Settings User Level Management Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/camera-av-settings-user-level-management-instance.h -.. _`Channel`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/channel-server/channel-delegate.h +.. _`Camera AV Settings User Level Management`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/camera-av-settings-user-level-management-server/camera-av-settings-user-level-management-server.h .. _`Channel Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/channel/ChannelManager.h -.. _`Closure Control`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/closure-control-server/closure-control-cluster-delegate.h +.. _`Channel`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/channel-server/channel-delegate.h +.. _`Chime Delegate`: https://github.com/espressif/connectedhomeip/blob/faf4d09/examples/all-clusters-app/all-clusters-common/include/chime-instance.h +.. _`Chime`: https://github.com/espressif/connectedhomeip/blob/faf4d09/src/app/clusters/chime-server/chime-server.h .. _`Closure Control Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/closure-app/closure-common/include/ClosureControlEndpoint.h -.. _`Closure Dimension`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/closure-dimension-server/closure-dimension-delegate.h +.. _`Closure Control`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/closure-control-server/closure-control-cluster-delegate.h .. _`Closure Dimension Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/closure-app/closure-common/include/ClosureDimensionEndpoint.h -.. _`Commissioner Control`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/commissioner-control-server/commissioner-control-server.h +.. _`Closure Dimension`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/closure-dimension-server/closure-dimension-delegate.h .. _`Commissioner Control Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/fabric-bridge-app/linux/include/CommissionerControlDelegate.h +.. _`Commissioner Control`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/commissioner-control-server/commissioner-control-server.h +.. _`Commodity Price Delegate`: https://github.com/espressif/connectedhomeip/blob/faf4d09/examples/energy-gateway-app/commodity-price/include/CommodityPriceDelegate.h +.. _`Commodity Price`: https://github.com/espressif/connectedhomeip/blob/faf4d09/src/app/clusters/commodity-price-server/commodity-price-server.h +.. _`Commodity Tariff Delegate`: https://github.com/espressif/connectedhomeip/blob/faf4d09/examples/energy-gateway-app/commodity-tariff/include/CommodityTariffInstance.h +.. _`Commodity Tariff`: https://github.com/espressif/connectedhomeip/blob/faf4d09/src/app/clusters/commodity-tariff-server/commodity-tariff-server.h .. _`Content App Observer`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/content-app-observer/content-app-observer-delegate.h .. _`Content Control`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/content-control-server/content-control-delegate.h -.. _`Content Launcher`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/content-launch-server/content-launch-delegate.h .. _`Content Launcher Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/content-launcher/ContentLauncherManager.h -.. _`Device Energy Management`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/device-energy-management-server/device-energy-management-server.h +.. _`Content Launcher`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/content-launch-server/content-launch-delegate.h .. _`Device Energy Management Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/energy-management-app/energy-management-common/device-energy-management/include/DeviceEnergyManagementDelegateImpl.h -.. _`Dishwasher Alarm`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/dishwasher-alarm-server/dishwasher-alarm-delegate.h -.. _`Dishwasher Alarm Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/src/dishwasher-alarm-stub.cpp -.. _`Door Lock`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/door-lock-server/door-lock-delegate.h -.. _`Door Lock Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/lock-app/lock-common/src/LockEndpoint.cpp -.. _`Electrical Power Measurement`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/electrical-power-measurement-server/electrical-power-measurement-server.h -.. _`Electrical Power Measurement Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/energy-management-app/energy-management-common/energy-reporting/include/ElectricalPowerMeasurementDelegate.h -.. _`Energy Evse`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/energy-evse-server/energy-evse-server.h -.. _`Energy Evse Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/energy-management-app/energy-management-common/energy-evse/include/EnergyEvseDelegateImpl.h -.. _`Energy Preference`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/energy-preference-server/energy-preference-server.h -.. _`Energy Preference Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/src/energy-preference-delegate.cpp -.. _`Fan Control`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/fan-control-server/fan-control-delegate.h -.. _`Fan Control Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/src/fan-stub.cpp -.. _`Keypad Input`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/keypad-input-server/keypad-input-delegate.h -.. _`Keypad Input Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/keypad-input/KeypadInputManager.h -.. _`Laundry Dryer Controls`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/laundry-dryer-controls-server/laundry-dryer-controls-delegate.h -.. _`Laundry Dryer Controls Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/laundry-dryer-controls-delegate-impl.h -.. _`Laundry Washer Controls`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/laundry-washer-controls-server/laundry-washer-controls-delegate.h -.. _`Laundry Washer Controls Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/laundry-washer-controls-delegate-impl.h -.. _`Low Power`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/low-power-server/low-power-delegate.h -.. _`Low Power Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/low-power/LowPowerManager.h -.. _`Media Input`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/media-input-server/media-input-delegate.h -.. _`Media Input Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/media-input/MediaInputManager.h -.. _`Media Playback`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/media-playback-server/media-playback-delegate.h -.. _`Media Playback Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/media-playback/MediaPlaybackManager.h -.. _`Messages`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/messages-server/messages-delegate.h -.. _`Messages Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/messages/MessagesManager.h -.. _`Microwave Oven Control`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/microwave-oven-control-server/microwave-oven-control-server.h -.. _`Microwave Oven Control Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/microwave-oven-app/microwave-oven-common/include/microwave-oven-device.h -.. _`Mode Base`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/mode-base-server/mode-base-server.h -.. _`Refrigeratore And TCC Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/tcc-mode.h -.. _`Laundry Washer Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/laundry-washer-mode.h -.. _`Dish Washer Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/dishwasher-mode.h -.. _`Rvc Run And Rvc Clean Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/rvc-modes.h -.. _`Energy Evse Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/energy-management-app/energy-management-common/energy-evse/include/energy-evse-modes.h -.. _`Microwave Oven Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/microwave-oven-mode.h .. _`Device Energy Management Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/energy-management-app/energy-management-common/device-energy-management/include/device-energy-management-modes.h -.. _`Water Heater Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/water-heater-mode.h -.. _`Mode Select`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/mode-select-server/supported-modes-manager.h -.. _`Mode Select Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/static-supported-modes-manager.h -.. _`Operational State`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/operational-state-server/operational-state-server.h -.. _`Operational State Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/operational-state-delegate-impl.h -.. _`Power Topology`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/power-topology-server/power-topology-server.h -.. _`Power Topology Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/energy-management-app/energy-management-common/energy-reporting/include/PowerTopologyDelegate.h -.. _`Resource Monitoring`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/resource-monitoring-server/resource-monitoring-server.h -.. _`HEPA Filter Monitoring Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/resource-monitoring-delegates.h -.. _`Activated Carbon Filter Monitoring Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/resource-monitoring-delegates.h -.. _`Service Area`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/service-area-server/service-area-server.h -.. _`Service Area Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/rvc-app/rvc-common/include/rvc-service-area-delegate.h -.. _`Target Navigator`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/target-navigator-server/target-navigator-delegate.h -.. _`Target Navigator Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/target-navigator/TargetNavigatorManager.h -.. _`Thermostat`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/thermostat-server/thermostat-delegate.h -.. _`Thermostat Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/thermostat/thermostat-common/include/thermostat-delegate-impl.h -.. _`Time Synchronization`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/time-synchronization-server/time-synchronization-delegate.h -.. _`Time Synchronization Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/time-synchronization-server/DefaultTimeSyncDelegate.h -.. _`Valve Configuration And Control`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/valve-configuration-and-control-server/valve-configuration-and-control-delegate.h -.. _`Valve Configuration And Control Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/linux/ValveControlDelegate.h -.. _`Wake On LAN`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/wake-on-lan-server/wake-on-lan-server.h -.. _`Wake On LAN Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/wake-on-lan/WakeOnLanManager.h -.. _`Water Heater Management`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/water-heater-management-server/water-heater-management-server.h -.. _`Water Heater Management Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/WhmDelegate.h -.. _`WebRTC Transport Provider`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/webrtc-transport-provider-server/webrtc-transport-provider-server.h -.. _`WebRTC Transport Provider Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/camera-app/linux/include/clusters/webrtc_provider/webrtc-provider-manager.h -.. _`Window Covering`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/window-covering-server/window-covering-delegate.h -.. _`Window Covering Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/chef/common/clusters/window-covering/chef-window-covering.h -.. _`Chime`: https://github.com/espressif/connectedhomeip/blob/faf4d09/src/app/clusters/chime-server/chime-server.h -.. _`Chime Delegate`: https://github.com/espressif/connectedhomeip/blob/faf4d09/examples/all-clusters-app/all-clusters-common/include/chime-instance.h -.. _`Push AV Stream Transport`: https://github.com/espressif/connectedhomeip/blob/faf4d09/src/app/clusters/push-av-stream-transport-server/push-av-stream-transport-delegate.h -.. _`Push AV Stream Transport Delegate`: https://github.com/espressif/connectedhomeip/blob/faf4d09/examples/all-clusters-app/all-clusters-common/include/push-av-stream-transport-delegate-impl.h -.. _`Commodity Tariff`: https://github.com/espressif/connectedhomeip/blob/faf4d09/src/app/clusters/commodity-tariff-server/commodity-tariff-server.h -.. _`Commodity Tariff Delegate`: https://github.com/espressif/connectedhomeip/blob/faf4d09/examples/energy-gateway-app/commodity-tariff/include/CommodityTariffInstance.h -.. _`Commodity Price`: https://github.com/espressif/connectedhomeip/blob/faf4d09/src/app/clusters/commodity-price-server/commodity-price-server.h -.. _`Commodity Price Delegate`: https://github.com/espressif/connectedhomeip/blob/faf4d09/examples/energy-gateway-app/commodity-price/include/CommodityPriceDelegate.h -.. _`Electrical Grid Conditions`: https://github.com/espressif/connectedhomeip/blob/faf4d09/src/app/clusters/electrical-grid-conditions-server/electrical-grid-conditions-server.h +.. _`Device Energy Management`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/device-energy-management-server/device-energy-management-server.h +.. _`Dish Washer Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/dishwasher-mode.h +.. _`Dishwasher Alarm Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/src/dishwasher-alarm-stub.cpp +.. _`Dishwasher Alarm`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/dishwasher-alarm-server/dishwasher-alarm-delegate.h +.. _`Door Lock Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/lock-app/lock-common/src/LockEndpoint.cpp +.. _`Door Lock`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/door-lock-server/door-lock-delegate.h .. _`Electrical Grid Conditions Delegate`: https://github.com/espressif/connectedhomeip/blob/faf4d09/examples/energy-gateway-app/electrical-grid-conditions/include/ElectricalGridConditionsDelegate.h +.. _`Electrical Grid Conditions`: https://github.com/espressif/connectedhomeip/blob/faf4d09/src/app/clusters/electrical-grid-conditions-server/electrical-grid-conditions-server.h +.. _`Electrical Power Measurement Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/energy-management-app/energy-management-common/energy-reporting/include/ElectricalPowerMeasurementDelegate.h +.. _`Electrical Power Measurement`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/electrical-power-measurement-server/electrical-power-measurement-server.h +.. _`Energy Evse Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/energy-management-app/energy-management-common/energy-evse/include/EnergyEvseDelegateImpl.h +.. _`Energy Evse Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/energy-management-app/energy-management-common/energy-evse/include/energy-evse-modes.h +.. _`Energy Evse`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/energy-evse-server/energy-evse-server.h +.. _`Energy Preference Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/src/energy-preference-delegate.cpp +.. _`Energy Preference`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/energy-preference-server/energy-preference-server.h +.. _`Fan Control Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/src/fan-stub.cpp +.. _`Fan Control`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/fan-control-server/fan-control-delegate.h +.. _`HEPA Filter Monitoring Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/resource-monitoring-delegates.h +.. _`Keypad Input Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/keypad-input/KeypadInputManager.h +.. _`Keypad Input`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/keypad-input-server/keypad-input-delegate.h +.. _`Laundry Dryer Controls Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/laundry-dryer-controls-delegate-impl.h +.. _`Laundry Dryer Controls`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/laundry-dryer-controls-server/laundry-dryer-controls-delegate.h +.. _`Laundry Washer Controls Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/laundry-washer-controls-delegate-impl.h +.. _`Laundry Washer Controls`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/laundry-washer-controls-server/laundry-washer-controls-delegate.h +.. _`Laundry Washer Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/laundry-washer-mode.h +.. _`Low Power Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/low-power/LowPowerManager.h +.. _`Low Power`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/low-power-server/low-power-delegate.h +.. _`Media Input Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/media-input/MediaInputManager.h +.. _`Media Input`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/media-input-server/media-input-delegate.h +.. _`Media Playback Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/media-playback/MediaPlaybackManager.h +.. _`Media Playback`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/media-playback-server/media-playback-delegate.h +.. _`Messages Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/messages/MessagesManager.h +.. _`Messages`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/messages-server/messages-delegate.h +.. _`Microwave Oven Control Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/microwave-oven-app/microwave-oven-common/include/microwave-oven-device.h +.. _`Microwave Oven Control`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/microwave-oven-control-server/microwave-oven-control-server.h +.. _`Microwave Oven Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/microwave-oven-mode.h +.. _`Mode Base`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/mode-base-server/mode-base-server.h +.. _`Mode Select Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/static-supported-modes-manager.h +.. _`Mode Select`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/mode-select-server/supported-modes-manager.h +.. _`Operational State Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/operational-state-delegate-impl.h +.. _`Operational State`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/operational-state-server/operational-state-server.h +.. _`Power Topology Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/energy-management-app/energy-management-common/energy-reporting/include/PowerTopologyDelegate.h +.. _`Power Topology`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/power-topology-server/power-topology-server.h +.. _`Push AV Stream Transport Delegate`: https://github.com/espressif/connectedhomeip/blob/faf4d09/examples/all-clusters-app/all-clusters-common/include/push-av-stream-transport-delegate-impl.h +.. _`Push AV Stream Transport`: https://github.com/espressif/connectedhomeip/blob/faf4d09/src/app/clusters/push-av-stream-transport-server/push-av-stream-transport-delegate.h +.. _`Refrigeratore And TCC Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/tcc-mode.h +.. _`Resource Monitoring`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/resource-monitoring-server/resource-monitoring-server.h +.. _`Rvc Run And Rvc Clean Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/rvc-modes.h +.. _`Service Area Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/rvc-app/rvc-common/include/rvc-service-area-delegate.h +.. _`Service Area`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/service-area-server/service-area-server.h +.. _`Target Navigator Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/target-navigator/TargetNavigatorManager.h +.. _`Target Navigator`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/target-navigator-server/target-navigator-delegate.h +.. _`Thermostat Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/thermostat/thermostat-common/include/thermostat-delegate-impl.h +.. _`Thermostat`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/thermostat-server/thermostat-delegate.h +.. _`Time Synchronization Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/time-synchronization-server/DefaultTimeSyncDelegate.h +.. _`Time Synchronization`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/time-synchronization-server/time-synchronization-delegate.h +.. _`Valve Configuration And Control Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/linux/ValveControlDelegate.h +.. _`Valve Configuration And Control`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/valve-configuration-and-control-server/valve-configuration-and-control-delegate.h +.. _`Wake On LAN Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/tv-app/tv-common/clusters/wake-on-lan/WakeOnLanManager.h +.. _`Wake On LAN`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/wake-on-lan-server/wake-on-lan-server.h +.. _`Water Heater Management Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/WhmDelegate.h +.. _`Water Heater Management`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/water-heater-management-server/water-heater-management-server.h +.. _`Water Heater Mode`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/all-clusters-app/all-clusters-common/include/water-heater-mode.h +.. _`WebRTC Transport Provider Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/camera-app/linux/include/clusters/webrtc_provider/webrtc-provider-manager.h +.. _`WebRTC Transport Provider`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/webrtc-transport-provider-server/webrtc-transport-provider-server.h +.. _`Window Covering Delegate`: https://github.com/espressif/connectedhomeip/blob/d144bbb/examples/chef/common/clusters/window-covering/chef-window-covering.h +.. _`Window Covering`: https://github.com/espressif/connectedhomeip/blob/d144bbb/src/app/clusters/window-covering-server/window-covering-delegate.h + +.. keep-sorted end \ No newline at end of file diff --git a/docs/en/certification.rst b/docs/en/certification.rst index 97af5d4cf..62af57251 100644 --- a/docs/en/certification.rst +++ b/docs/en/certification.rst @@ -5,11 +5,11 @@ The Matter Certification denotes compliance to a Connectivity Standards Alliance You need to `become a member `__ of CSA and request a Vendor ID code from CSA Certification before you apply for a Matter Certification. Then you need to choose an `authorized test provider `__ (must be validated for Matter testing) and submit your product for testing. Below are the steps for the Matter Certification. -1 Firmware Development ----------------------- +Firmware Development +-------------------- -1.1 Choose an esp-matter branch -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Choose an esp-matter branch +~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use the branch corresponding to the Matter version you plan to certify for firmware development. @@ -32,8 +32,8 @@ Use the branch corresponding to the Matter version you plan to certify for firmw * - Matter 1.5 - `release/v1.5 `__ -1.2 Product Attestation Authority (PAA) Generation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Product Attestation Authority (PAA) Generation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For Matter certification testing, vendors should generate the test Product Attestation Authority (PAA) certificate, Product Attestation Intermediate (PAI), and Device Attestation Certificate (DAC), rather than using the default test PAA certificate from the connectedhomeip SDK repository. Therefore, you need to generate a PAA certificate and use it to sign the PAI certificate, which is then used to sign the DAC. The PAI certificate, DAC certificate, and DAC private key should be stored in the product under test. The `chip-cert `__ tool which is built in `esp-matter setup `__ process can be used to generate the PAA certificate and Certification Declaration (CD). @@ -46,8 +46,8 @@ The `chip-cert `__ to generate the corresponding factory partition bin file. This file contains commissioning information (discriminator, salt, iteration count, and SPAKE2+ verifier), device attestation information (Certification Declaration (CD), Product Attestation Intermediate (PAI) certificate, Device Attestation Certificate (DAC), and DAC private key), device instance information (vendor ID, vendor name, product ID, product name, etc.), and device information (fixed label, supported locales, etc.). This information is used to identify the product and ensure secure commissioning. @@ -76,8 +76,8 @@ In the reference command below, the -n option specifies the number of factory bi -cd /path/to/CD_file -v 0x131B --vendor-name Espressif -p 0x1234 \ --product-name Test-light --hw-ver 1 --hw-ver-str v1.0 -1.5 Firmware Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Firmware Configuration +~~~~~~~~~~~~~~~~~~~~~~~ When generating test product firmware, the following configurations can be set in menuconfig to enable accessing the information from the factory bin file generated above: @@ -90,8 +90,8 @@ When generating test product firmware, the following configurations can be set i CONFIG_FACTORY_COMMISSIONABLE_DATA_PROVIDER=y CONFIG_FACTORY_DEVICE_INSTANCE_INFO_PROVIDER=y -1.6 OTA File Generation -~~~~~~~~~~~~~~~~~~~~~~~ +OTA File Generation +~~~~~~~~~~~~~~~~~~~ If the test device supports standard Matter OTA, you need to prepare OTA files for certification testing. (Note: You can add OTA `rollback `__ functionality to facilitate certification testing) @@ -105,8 +105,8 @@ Use `ota_image_tool.py -p -vn 2 -vs 1.1 -da sha256 \ /path/to/original_app_bin /path/to/out_ota_bin -1.7 Other Notes -~~~~~~~~~~~~~~~ +Other Notes +~~~~~~~~~~~ For products that support the Identify cluster, you need to set the identify type according to the specific product form: @@ -181,13 +181,13 @@ Implement the corresponding identify command and trigger effect command handlers return err; } -2 Preparation of Files Required for Certification Testing ------------------------------------------------------------ +Preparation of Files Required for Certification Testing +--------------------------------------------------------- After preparing the device under test, users need to prepare the following files to submit to the testing organization along with the device. -2.1 PICS File -~~~~~~~~~~~~~~ +PICS File +~~~~~~~~~~ The PICS file is used to define all Matter features of the product, including endpoints, device types, clusters, attributes, commands, etc. The testing organization will determine the test cases to execute during certification testing based on the PICS file submitted by the user. @@ -206,33 +206,33 @@ The `PICS-generator tool `__. -3.1 Different Matter versions use different `Test Harness tool versions `__ for certification. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Different Matter versions use different `Test Harness tool versions `__ for certification. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: TH Version Mapping :widths: 20 35 20 @@ -260,18 +260,18 @@ After preparing the device under test, users can perform self-testing using the - v2.14+fall2025 - ca9d111 -3.2 Test Harness Setup -~~~~~~~~~~~~~~~~~~~~~~~ +Test Harness Setup +~~~~~~~~~~~~~~~~~~~ After selecting the Test Harness version according to the table above, refer to the `Matter_TH_User_Guide.pdf `__ document for each Matter version setup, for different test harness versions, the Matter_TH_User_Guide.pdf file may be different. -4 Submitting Certification Application Online ---------------------------------------------- +Submitting Certification Application Online +------------------------------------------- After the device under test passes all tests from the testing organization, users can fill out the application on the CSA certification application `website `__ . The following explanation uses Add New Product Application as an example. -4.1 Information to Fill In -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Information to Fill In +~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: Application Parameters Description :widths: 30 70 @@ -350,48 +350,48 @@ After the device under test passes all tests from the testing organization, user * - Security Attestation - Security attestation document -4.2 `Declaration of Conformance `__ (Doc) Instructions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +`Declaration of Conformance `__ (Doc) Instructions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Based on the Doc template provided by Espressif, fill in the relevant content. After the manufacturer signs this document, send it to the certification testing organization. After the testing organization signs it, the manufacturer uploads the signed Doc. -4.3 Transport Attestations (`Bluetooth `__, `Wi-Fi `__, `Thread `__, `Ethernet `__) Instructions: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Transport Attestations (`Bluetooth `__, `Wi-Fi `__, `Thread `__, `Ethernet `__) Instructions: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Fill in based on the Transport Attestation template provided by Espressif (version description). Different chip models may have different certificate numbers, which should be verified before filling in. After completion, sign and upload yourself. -4.4 Security Attestation Instructions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Security Attestation Instructions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Fill in based on the Security Attestation template provided by Espressif. After completion, sign and upload yourself. -4.5 Get the AID and test report -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Get the AID and test report +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ After completing and submitting the application, you will receive an Application ID (AID). Provide this ID to the certification testing organization, and the testing organization will upload the product test report to the CSA certification body. -4.6 Other steps -~~~~~~~~~~~~~~~~ +Other steps +~~~~~~~~~~~~ After completing the application and payment, the CSA certification team will review the application and test report submitted by the manufacturer. If there are issues, the manufacturer will be notified by email. If there are no issues, the certification is passed, and the official CD file will be issued. -5 Filling in Certified Product Information on DCL Website ----------------------------------------------------------- +Filling in Certified Product Information on DCL Website +-------------------------------------------------------- After the product passes certification, manufacturers also need to add Model, Model Version, and Compliance on the `Distributed Compliance Ledger `__ (DCL). Refer to the documentation: `HowTo - Writing to the DCL.pdf `__ . -6 Other notes for some certification test cases ------------------------------------------------- +Other notes for some certification test cases +---------------------------------------------- -6.1 Route Information Option (RIO) notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Route Information Option (RIO) notes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For Wi-Fi products using LwIP, TC-SC-4.9 should be tested in order to verify that the product can receive Router Advertisement (RA) message with RIO and add route table that indicates whether the prefix can be reached by way of the router. It can be tested with a Thread Border Router (BR) which sends RA message periodically and a Thread End Device that is used to verify the Wi-Fi product can reach the Thread network via Thread BR. Some Wi-Fi Routers might have the issue that they cannot forward RA message sent by the Thread BR, so please use a Wi-Fi Router that can forward RA message when you are testing TC-SC-4.9. Here are the steps to set up the Thread BR and Thread End Device. You should prepare 2 Radio Co-Processors (RCP) to set up the `ot-br-posix `__ and `ot-cli-posix `__. The `RCP on ESP32-H2 `__ is suggested to be used here. And you can also use other platforms (such as nrf52840, efr32, etc.) as the RCPs. -6.1.1 Setup Thread BR -^^^^^^^^^^^^^^^^^^^^^^ +Setup Thread BR +^^^^^^^^^^^^^^^^ The otbr-posix can be run on RaspberryPi or Ubuntu machine. Connecting an RCP to the host, the port ``RCP_PORT1`` for it will be ``/dev/ttyUSBX`` or ``/dev/ttyACMX``. @@ -430,8 +430,8 @@ The otbr-posix is running on the host now. Open another terminal, start console Please record the dataset you get with the last command, it will be used by ot-cli-posix to join the BR's network in the next step. -6.1.2 Setup Thread End Device -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Setup Thread End Device +^^^^^^^^^^^^^^^^^^^^^^^ We use the Posix Thread Command-Line Interface (CLI) as the Thread End Device. Connect another RCP to the host and get the port `RCP_PORT2` for it. @@ -482,23 +482,23 @@ Ping the IP address of the Wi-Fi device. The ping command should be successful. -6.2 TC-CNET-3.11 -~~~~~~~~~~~~~~~~~ +TC-CNET-3.11 +~~~~~~~~~~~~~ No response on step 7 is expected (`Related issue `__). All the NetworkCommissioning commands are fail-safe required. If the commands fail with a ``FAILSAFE_REQUIRED`` status code. You need to send ``arm-fail-safe`` command and then send the NetworkCommissioning commands. -6.3 TC-RR-1.1 -~~~~~~~~~~~~~~ +TC-RR-1.1 +~~~~~~~~~~ For more application endpoints with group cluster, need more nvs size to store group table, so if the ``TC-RR-1.1`` failed, can try to increase the nvs size. (`Related issue `__) Please note that the minimum NVS size required is 48 KB (0xC000) when using a single endpoint with a group cluster. -7 FW/SDK configuration notes ------------------------------ +FW/SDK configuration notes +--------------------------- - ``Enable OTA Requestor`` in ``→ Component config → CHIP Core → System Options`` diff --git a/docs/en/controller.rst b/docs/en/controller.rst index b51c74424..4a81edb8b 100644 --- a/docs/en/controller.rst +++ b/docs/en/controller.rst @@ -19,8 +19,8 @@ This example implements a Matter controller in RainMaker Matter Fabric without a Once you have flashed the controller example onto the device, you can use the `device console <./developing.html#device-console>`__ to commission the device and send commands to the end-device. All of the controller commands begin with the prefix ``matter esp controller``. -1 Controller features ----------------------- +Controller features +------------------- The controller is the role of a node that has permissions to enable it to control one or more nodes. It has a complete chain of Node Operational Credentials (NOC) and acts as an administer or an operator in its Matter fabric. And the NodeId of the controller or CASE Authenticated Tag (CAT) of the controller's NOC should in the Access Control List of other end-devices with administer/operator privilege. The controller should support the following features: @@ -31,8 +31,8 @@ The controller should support the following features: - Send Subscribe Attribute/Event commands to other nodes. - Join Matter Groups and manage the Group Key Set. -1.1 Cluster Invoking commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Cluster Invoking commands +~~~~~~~~~~~~~~~~~~~~~~~~~ The ``invoke-cmd`` command is used for sending cluster commands to the end-devices. It utilizes a ``cluster_command`` class to establish the sessions and send the command packets. The class constructor function could accept two callback inputs: - **Success callback**: @@ -76,8 +76,8 @@ Here are some examples of the ``command-data`` format. matter esp controller invoke-cmd 0x4 0 "{\"0:U16\": 1, \"1:STR\": \"grp1\"}" -1.2 Read commands -~~~~~~~~~~~~~~~~~ +Read commands +~~~~~~~~~~~~~ The ``read_command`` class is used for sending read commands to other end-devices. Its constructor function could accept two callback inputs: - **Attribute report callback**: @@ -86,8 +86,8 @@ The ``read_command`` class is used for sending read commands to other end-device - **Event report callback**: This callback will be called upon the reception of the event report for read-event commands. -1.2.1 Read attribute commands -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Read attribute commands +^^^^^^^^^^^^^^^^^^^^^^^ The ``read-attr`` commands are used for sending the commands of reading attributes on end-devices. - Send the read-attribute command: @@ -100,8 +100,8 @@ The ``read-attr`` commands are used for sending the commands of reading attribut - endpoint-ids can represent a single or multiple endpoints, e.g. '0' or '0,1'. And the same applies to cluster-ids, attribute-ids, and event-ids below. -1.2.2 Read event commands -^^^^^^^^^^^^^^^^^^^^^^^^^ +Read event commands +^^^^^^^^^^^^^^^^^^^ The ``read-event`` commands are used for sending the commands of reading events on end-devices. - Send the read-event command: @@ -110,8 +110,8 @@ The ``read-event`` commands are used for sending the commands of reading events matter esp controller read-event -1.3 Write attribute commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Write attribute commands +~~~~~~~~~~~~~~~~~~~~~~~~ The ``write-attr`` command is used for sending the commands of writing attributes on the end-device. - Send the write-attribute command: @@ -122,7 +122,7 @@ The ``write-attr`` command is used for sending the commands of writing attribute .. note:: - - ``attribute_value`` should utilize a JSON object string. And the format of this string is the same as the ``command_data`` in `cluster commands <./developing.html#cluster-commands>`__. This JSON object should contain only one item that represents the attribute value. + - ``attribute_value`` should utilize a JSON object string. And the format of this string is the same as the ``command_data`` in `cluster commands <./developing.html#cluster-control>`__. This JSON object should contain only one item that represents the attribute value. Here are some examples of the ``attribute_value`` format. @@ -158,8 +158,8 @@ For attributes of type uint64_t or int64_t, if the absolute value is greater tha matter esp controller write-attr 42 0 "{\"0:ARR-OBJ\":[{\"1:U64\": \"9007199254740993\", \"2:U8\": 0}]}" -1.4 Subscribe commands -~~~~~~~~~~~~~~~~~~~~~~ +Subscribe commands +~~~~~~~~~~~~~~~~~~ The ``subscribe_command`` class is used for sending subscribe commands to other end-devices. Its constructor function could accept four callback inputs: @@ -175,8 +175,8 @@ inputs: - **Subscription terminated callback**: This callback will be invoked when the subscription is terminated or shutdown. -1.4.1 Subscribe attribute commands -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Subscribe attribute commands +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``subs-attr`` commands are used for sending the commands of subscribing attributes on end-devices. - Send the subscribe-attribute command: @@ -185,8 +185,8 @@ The ``subs-attr`` commands are used for sending the commands of subscribing attr matter esp controller subs-attr -1.4.2 Subscribe event commands -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Subscribe event commands +^^^^^^^^^^^^^^^^^^^^^^^^ The ``subs-event`` commands are used for sending the commands of subscribing events on end-devices. - Send the subscribe-event command: @@ -195,8 +195,8 @@ The ``subs-event`` commands are used for sending the commands of subscribing eve matter esp controller subs-event -1.5 Group settings commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Group settings commands +~~~~~~~~~~~~~~~~~~~~~~~ The ``group-settings`` commands are used to set group information of the controller. If the controller wants to send multicast commands to end-devices, it should be in the same group as the end-devices. - Set group information of the controller: @@ -212,8 +212,8 @@ The ``group-settings`` commands are used to set group information of the control matter esp controller group-settings bind-keyset matter esp controller group-settings unbind-keyset -2 Commissioner features ------------------------ +Commissioner features +--------------------- The commissioner is an enhanced controller that can perform commissioning which is the sequence of operations to bring a Node into a Fabric by assigning an Operational Node ID and Node Operational credentials. The commissioner should support the additional features: @@ -222,8 +222,8 @@ The commissioner should support the additional features: - Verify the commissionee's Device Attestation Certificate (DAC) chain and Certificate Declaration (CD) during commissioning. - Receive the Certificate Signing Request (CSR) and issue NOC for it during commissioning. -2.1 Pairing commands -~~~~~~~~~~~~~~~~~~~~ +Pairing commands +~~~~~~~~~~~~~~~~ The ``pairing`` commands are used for commissioning end-devices and are available when the ``Enable matter commissioner`` option is enabled. Here are three standard pairing methods: - **Onnetwork pairing:** Prior to executing this commissioning method, it is necessary to connect both the controller and the end-device to the same network and ensure that the commissioning window of the end-device is open. To complete this process, you can use the command ``matter esp wifi connect``. After the devices are connected, the pairing process can be initiated. @@ -269,11 +269,11 @@ Below are supported commands: matter esp controller pairing code-wifi-thread -2.2 Attestation Verification -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Attestation Verification +~~~~~~~~~~~~~~~~~~~~~~~~ -2.2.1 Attestation Trust Storage -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Attestation Trust Storage +^^^^^^^^^^^^^^^^^^^^^^^^^ The commissioner offers four options for the Attestation Trust Storage which is used to store and utilize the PAA certificates for the Device Attestation verification. This feature is available when the ``Enable matter commissioner`` option is enabled in menuconfig. You can modify this setting in menuconfig ``Components`` -> ``ESP Matter Controller`` -> ``Attestation Trust Store``. - ``Attestation Trust Store - Test`` @@ -292,8 +292,8 @@ The commissioner offers four options for the Attestation Trust Storage which is Use the custom Attestation Trust Storage. You should call ``set_custom_attestation_trust_store()`` to set the custom Attestation Trust Store before setting up the commissioner. -2.3 NOC Issuer -~~~~~~~~~~~~~~ +NOC Issuer +~~~~~~~~~~ In the `esp_matter commissioner `_ example, the commissioner offers two options to issue the NOC chains for itself and other operational nodes. @@ -305,38 +305,38 @@ In the `esp_matter commissioner ` to know more about the releases -1 ESP-IDF Setup -------------------- +ESP-IDF Setup +------------- This section talks about setting up ESP-IDF. -1.1 Host Setup -~~~~~~~~~~~~~~ +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, the recommended host versions: @@ -21,8 +21,8 @@ host. Linux and Mac OS-X are the supported development hosts in Matter, the reco Additionally, we also support developing on Windows Host using WSL. -1.1.1 Windows 10 -^^^^^^^^^^^^^^^^ +Windows 10 +^^^^^^^^^^ Development on Windows is supported using Windows Subsystem for Linux (WSL). Please follow the below instructions to set up host. @@ -35,7 +35,7 @@ Development on Windows is supported using Windows Subsystem for Linux (WSL). Ple - Here onwards process for setting esp-matter and building examples is same as other hosts. - Please clone the repositories from inside the WSL environment and not inside a mounted directory. -For using CHIP tool on WSL, please check `Using CHIP-tool in WSL `__. +For using CHIP tool on WSL, please check :doc:`Using CHIP-tool in WSL `. For using VSCode for development, please check `Developing in WSL `__. @@ -45,8 +45,8 @@ For using VSCode for development, please check `Developing in WSL -1.2 Getting the Repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Getting the Repository +~~~~~~~~~~~~~~~~~~~~~~ The Prerequisites for ESP-IDF: @@ -83,8 +83,8 @@ The Prerequisites for ESP-IDF: ./install.sh cd .. -1.3 Configuring the Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Configuring the Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~ This should be done each time a new terminal is opened @@ -93,19 +93,19 @@ This should be done each time a new terminal is opened cd esp-idf; source ./export.sh; cd .. -2 ESP Matter Setup ------------------- +ESP Matter Setup +---------------- There are two options to setup esp-matter, you can select one according to demand: - ESP matter repository, including esp-matter SDK and tools (e.g., CHIP-tool, CHIP-cert, ZAP, ...). - ESP matter component, including esp-matter SDK. -2.1 ESP-Matter Repository -~~~~~~~~~~~~~~~~~~~~~~~~~~ +ESP-Matter Repository +~~~~~~~~~~~~~~~~~~~~~ -2.1.1 Getting the Repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Getting the Repository +^^^^^^^^^^^^^^^^^^^^^^ The Prerequisites for Matter: @@ -185,8 +185,8 @@ To clone the esp-matter repository with all the submodules, use the following co It's probably caused by some network connectivity issue, a VPN is required for most of the cases. -2.1.2 Configuring the Environment -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Configuring the Environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^ This should be done each time a new terminal is opened @@ -208,8 +208,8 @@ Ccache caches the previous compilations and speeds up recompilation in subsequen Above can also be added to your shell’s profile file (.profile, .bashrc, .zprofile, etc.) to enable ccache every time you open a new terminal. -2.2 ESP Matter Component (experimental) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ESP Matter Component (experimental) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can check the component in `Espressif Component Registry `__. @@ -229,8 +229,8 @@ An example with esp_matter component is offered: Use ``compote version`` to show the version. Use ``pip install 'idf-component-manager~=1.4.0'`` or ``pip install 'idf-component-manager~=2.0.0'`` to install. -2.3 Building Applications -~~~~~~~~~~~~~~~~~~~~~~~~~ +Building Applications +~~~~~~~~~~~~~~~~~~~~~ - :project_file:`Light ` - :project_file:`Light Switch ` @@ -238,8 +238,8 @@ An example with esp_matter component is offered: - :project_file:`Zigbee Bridge ` - :project_file:`BLE Mesh Bridge ` -2.4 Flashing the Firmware -~~~~~~~~~~~~~~~~~~~~~~~~~ +Flashing the Firmware +~~~~~~~~~~~~~~~~~~~~~ Choose IDF target. @@ -354,8 +354,8 @@ Choose IDF target. pip install -r $IDF_PATH/requirements.txt -3 Commissioning and Control ---------------------------- +Commissioning and Control +------------------------- There are a few implementations of Matter commissioners present in the `connectedhomeip`_ repository. @@ -368,8 +368,8 @@ Espressif's ESP RainMaker iOS and Android applications support commissioning and - `ESP-RainMaker iOS App`_ -3.1 Test Setup (CHIP Tool) -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Test Setup (CHIP Tool) +~~~~~~~~~~~~~~~~~~~~~~ A host-based chip-tool can be used as a commissioner to commission and control a Matter device. During the previous ``install.sh`` step, the ``chip-tool`` is generated under the folder: @@ -383,8 +383,8 @@ A host-based chip-tool can be used as a commissioner to commission and control a Instructions to download the profile can be found in the `profile installation section`_ -3.1.1 Commissioning -^^^^^^^^^^^^^^^^^^^ +Commissioning +^^^^^^^^^^^^^ Use ``chip-tool`` in interactive mode to commission the device: @@ -491,8 +491,8 @@ If you want to use different values for commissioning the device, please use the `esp-matter-mfg-tool`_ to generate the factory partition which has to be flashed on the device. It also generates the new pairing code and QR code image using which you can commission the device. -3.1.2 Post Commissioning Setup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Post Commissioning Setup +^^^^^^^^^^^^^^^^^^^^^^^^ The device would need additional configuration depending on the example, for it to work. Check the "Post Commissioning Setup" section in examples for more information. @@ -503,8 +503,8 @@ for it to work. Check the "Post Commissioning Setup" section in examples for mor - :project_file:`Zigbee Bridge ` - :project_file:`BLE Mesh Bridge ` -3.1.3 Cluster Control -^^^^^^^^^^^^^^^^^^^^^ +Cluster Control +^^^^^^^^^^^^^^^ Use the cluster commands to control the attributes. @@ -532,8 +532,8 @@ chip-tool when used in interactive mode uses CASE resumption as against establis For more details about the commands, please check `chip-tool usage guide`_ -4 Device console ----------------- +Device console +-------------- The console on the device can be used to run commands for testing. It is configurable through menuconfig and enabled by default in the firmware. Here are some useful commands: @@ -631,14 +631,14 @@ Additional Matter specific commands: matter esp bridge add -5 Developing your Product -------------------------- +Developing your Product +----------------------- Understanding the structure before actually modifying and customising the device is helpful. -5.1 Building a Color Temperature Lightbulb -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Building a Color Temperature Lightbulb +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A device is represented in Matter in terms of its data model. As a first step of building your product, you will have to define the data model for your @@ -647,8 +647,8 @@ can use. Please refer to the `Espressif Matter Blog `__ for clarity on the terms like endpoints, clusters, etc. that are used in this section. -5.1.1 Data Model -^^^^^^^^^^^^^^^^ +Data Model +^^^^^^^^^^ - Typically, the data model is defined in the example's *app_main.cpp*. First off we start by creating a Matter node, which is the root of @@ -675,8 +675,8 @@ for clarity on the terms like endpoints, clusters, etc. that are used in this se endpoints can be created on the same node. Check the following sections for more info. -5.1.2 Attribute Callback -^^^^^^^^^^^^^^^^^^^^^^^^ +Attribute Callback +^^^^^^^^^^^^^^^^^^ - Whenever a Matter client makes changes to the device, they end up updating the attributes in the data model. @@ -703,8 +703,8 @@ for clarity on the terms like endpoints, clusters, etc. that are used in this se return err; } -5.1.3 Identify Callback -^^^^^^^^^^^^^^^^^^^^^^^^ +Identify Callback +^^^^^^^^^^^^^^^^^ - This callback is invoked when clients interact with the Identify Cluster. In the callback implementation, an endpoint can identify itself. (e.g., by flashing an LED or light). @@ -717,8 +717,8 @@ for clarity on the terms like endpoints, clusters, etc. that are used in this se return ESP_OK; } -5.1.4 Device Drivers -^^^^^^^^^^^^^^^^^^^^ +Device Drivers +^^^^^^^^^^^^^^ - The drivers, depending on the device, are typically initialized and updated in the example's *app_driver.cpp*. @@ -777,14 +777,14 @@ for clarity on the terms like endpoints, clusters, etc. that are used in this se } -5.2 Defining your own data model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Defining your own data model +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section demonstrates creating standard endpoints, clusters, attributes, and commands that are defined in the Matter specification -5.2.1 Endpoints -^^^^^^^^^^^^^^^ +Endpoints +^^^^^^^^^ The device can be customized by editing the endpoint/device_type creating in the *app_main.cpp* of the example. Examples: @@ -834,8 +834,8 @@ creating in the *app_main.cpp* of the example. Examples: Once a ``config_t`` instance has been instantiated, these three values cannot be modified. -5.2.2 Clusters -^^^^^^^^^^^^^^ +Clusters +^^^^^^^^ Additional clusters can also be added to an endpoint. Examples: @@ -877,8 +877,8 @@ Additional clusters can also be added to an endpoint. Examples: maximum pressure, maximum speed and maximum flow values. If they aren't set, they will be set to null by default. Once a ``config_t`` instance has been instantiated, these three values cannot be modified. -5.2.3 Attributes and Commands -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Attributes and Commands +^^^^^^^^^^^^^^^^^^^^^^^ Additional attributes and commands can also be added to a cluster. Examples: @@ -902,8 +902,8 @@ Examples: command_t *command = level_control::command::create_move_to_level(cluster); -5.2.4 Features -^^^^^^^^^^^^^^ +Features +^^^^^^^^ Mandatory features for a device type or endpoint can be configured at endpoint level. - feature: lighting: On/Off cluster: @@ -935,15 +935,15 @@ Optional features which are applicable to a cluster can also be added. cluster_t* cluster = cluster::get(endpoint, Descriptor::Id); descriptor::feature::tag_list::add(cluster); -5.3 Adding custom data model fields -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Adding custom data model fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section demonstrates creating custom endpoints, clusters, attributes, and commands that are not defined in the Matter specification and can be specific to the vendor. -5.3.1 Endpoints -^^^^^^^^^^^^^^^ +Endpoints +^^^^^^^^^ Non-Standard endpoint can be created, without any clusters. @@ -953,8 +953,8 @@ Non-Standard endpoint can be created, without any clusters. endpoint_t *endpoint = endpoint::create(node, ENDPOINT_FLAG_NONE); -5.3.2 Clusters -^^^^^^^^^^^^^^ +Clusters +^^^^^^^^ Non-Standard/Custom clusters can also be created: @@ -965,8 +965,8 @@ Non-Standard/Custom clusters can also be created: uint32_t custom_cluster_id = 0x131bfc00; cluster_t *cluster = cluster::create(endpoint, custom_cluster_id, CLUSTER_FLAG_SERVER); -5.3.3 Attributes and Commands -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Attributes and Commands +^^^^^^^^^^^^^^^^^^^^^^^ Non-Standard/Custom attributes can also be created on any cluster: @@ -992,12 +992,12 @@ Non-Standard/Custom attributes can also be created on any cluster: uint32_t custom_command_id = 0x0; command_t *command = command::create(cluster, custom_command_id, COMMAND_FLAG_ACCEPTED, command_callback); -5.4 Advanced Setup -~~~~~~~~~~~~~~~~~~ +Advanced Setup +~~~~~~~~~~~~~~ This section explains adding external platforms for Matter. This step is **optional** for most devices. Espressif's SDK for 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. -5.4.1 Creating the external platform directory -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Creating the external platform directory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Create a directory ``platform/${NEW_PLATFORM_NAME}`` in your codebase. You can typically copy @@ -1007,8 +1007,8 @@ as a start. Note that the new platform name should be something other than directory must be under ``platform`` folder to meet the Matter include path conventions. -5.4.2 Modifying the BUILD.gn target -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Modifying the BUILD.gn target +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There is an example :project_file:`BUILD.gn ` file for the ``ESP32_custom`` example platform. It simply compiles the ESP32 @@ -1019,8 +1019,8 @@ platform in Matter without any modifications. - Multiple build configs must be exported to the build system. See the ``buildconfig_header`` section in the file for the required definitions. -5.4.3 Editing Kconfigs -^^^^^^^^^^^^^^^^^^^^^^ +Editing Kconfigs +^^^^^^^^^^^^^^^^ - Enable ``CONFIG_CHIP_ENABLE_EXTERNAL_PLATFORM``. - Set ``CONFIG_CHIP_EXTERNAL_PLATFORM_DIR`` to the relative path from @@ -1040,8 +1040,8 @@ platform in Matter without any modifications. - 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``. -5.4.4 Example Usage -^^^^^^^^^^^^^^^^^^^ +Example Usage +^^^^^^^^^^^^^ As an example, you can build *light* example on ``ESP32_custom`` platform with following steps: @@ -1054,11 +1054,11 @@ As an example, you can build *light* example on ``ESP32_custom`` platform with f cp sdkconfig.defaults.ext_plat sdkconfig.defaults idf.py build -6 Factory Data Providers ------------------------- +Factory Data Providers +---------------------- -6.1 Providers Introduction -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Providers Introduction +~~~~~~~~~~~~~~~~~~~~~~ There are four factory data providers, each with its own implementation, that need to be configured. These providers supply the device with necessary factory data, which is then read by the device according to their respective implementations. - ``Commissionable Data Provider`` @@ -1077,8 +1077,8 @@ There are four factory data providers, each with its own implementation, that ne This particular provider is responsible for retrieving device information, which includes fixed-labels, user-labels, supported-locales, and supported-calendar-types. -6.2 Configuration Options -~~~~~~~~~~~~~~~~~~~~~~~~~ +Configuration Options +~~~~~~~~~~~~~~~~~~~~~ Different implementations of the four providers can be chosen in meuconfig: @@ -1125,7 +1125,7 @@ Different implementations of the four providers can be chosen in meuconfig: - ``Device Instance Info - Test``, the device will use the hardcoded Device Instance Information. - ``Device Instance Info - Factory``, the device will use device instance information from the factory partition. - This option is visable only when ``CONFIG_ENABLE_ESP32_FACTORY_DATA_PROVIDER`` and + This option is visible only when ``CONFIG_ENABLE_ESP32_FACTORY_DATA_PROVIDER`` and ``ENABLE_ESP32_DEVICE_INSTANCE_INFO_PROVIDER`` is selected. - ``Device Instance Info - Secure Cert``, the device will use the unique identifier for generating the rotating @@ -1143,23 +1143,23 @@ Different implementations of the four providers can be chosen in meuconfig: are not related clusters on the device. - ``Device Info - Factory``, the device will use device information from the factory partition. This option is - visable only when ``CONFIG_ENABLE_ESP32_FACTORY_DATA_PROVIDER`` and ``ENABLE_ESP32_DEVICE_INFO_PROVIDER`` is + visible only when ``CONFIG_ENABLE_ESP32_FACTORY_DATA_PROVIDER`` and ``ENABLE_ESP32_DEVICE_INFO_PROVIDER`` is selected. - ``Device Info - Custom``, the device will use custom defined Device Info Provider to obtain the Device Information. ``esp_matter::set_custom_device_info_provider`` should be called before ``esp_matter::start()`` to set the custom provider. -6.3 Custom Providers -~~~~~~~~~~~~~~~~~~~~ +Custom Providers +~~~~~~~~~~~~~~~~ In order to use custom providers, you need to define implementations of the four base classes of the providers and override the functions within them. And the custom providers should be set before ``esp_matter::start()`` is called. -7 Using esp_secure_cert partition ---------------------------------- +Using esp_secure_cert partition +------------------------------- -7.1 Configuration Options -~~~~~~~~~~~~~~~~~~~~~~~~~ +Configuration Options +~~~~~~~~~~~~~~~~~~~~~ Build the firmware with below configuration options @@ -1186,8 +1186,8 @@ Build the firmware with below configuration options you need to enable the ``CONFIG_ESP_SECURE_CERT_DS_PERIPHERAL=y`` option. -7.2 Certification Declaration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Certification Declaration +~~~~~~~~~~~~~~~~~~~~~~~~~ If you do not have an certification declaration file then you can generate the test CD with the help of below mentioned steps. We need to generate the new CD because it SHALL match the VID, PID in DAC and the ones reported by basic cluster. @@ -1212,8 +1212,8 @@ For more info about the arguments, please check `chip-cert's gen-cd command`_ in -O TEST_CD_FFF1_8001.der -7.3 Factory Partition -~~~~~~~~~~~~~~~~~~~~~ +Factory Partition +~~~~~~~~~~~~~~~~~ Factory partition contains basic information like VID, PID, etc. @@ -1257,8 +1257,8 @@ Factory partition binary will be generated at the below path. Please check for < [2022-12-02 11:18:12,381] [ INFO] - Generated output files at: out/fff1_8001/e17c95e1-521e-4979-b90b-04da648e21bb -7.4 Flashing firmware, secure cert and factory partition -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Flashing firmware, secure cert and factory partition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Flashing secure cert partition. Please check partition table for ``esp_secure_cert`` partition address. @@ -1285,8 +1285,8 @@ Flash application idf.py flash -7.5 Test commissioning using chip-tool -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Test commissioning using chip-tool +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If using the DACs signed by custom PAA that is not present in connectedhomeip repository, then download the PAA certificate, please make sure it is in DER format. @@ -1298,16 +1298,16 @@ Run the following command from host to commission the device. ./chip-tool pairing ble-wifi 1234 my_SSID my_PASSPHRASE my_PASSCODE my_DISCRIMINATOR --paa-trust-store-path /path/to/PAA-Certificates/ -8 Matter OTA ------------- +Matter OTA +---------- - Enable the ``CONFIG_ENABLE_OTA_REQUESTOR`` option to enable Matter OTA Requestor functionality. Please follow the `OTA guide`_ in the connectedhomeip repository for generating a Matter OTA image and performing OTA. -8.1 Encrypted Matter OTA -~~~~~~~~~~~~~~~~~~~~~~~~ +Encrypted Matter OTA +~~~~~~~~~~~~~~~~~~~~ The esp-matter SDK supports using a pre-encrypted application image for OTA upgrades. Please follow the steps below to enable and use encrypted application images for OTA upgrades. @@ -1337,24 +1337,24 @@ Please follow the steps below to enable and use encrypted application images for file, or reading it from the NVS. We have demonstrated the use of the private key by embedding it as a text file in the light example. -9 Mode Select -------------- +Mode Select +----------- This cluster provides an interface for controlling a characteristic of a device that can be set to one of several predefined values. For example, the light pattern of a disco ball, the mode of a massage chair, or the wash cycle of a laundry machine. -9.1 Attribute Supported Modes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Attribute Supported Modes +~~~~~~~~~~~~~~~~~~~~~~~~~ This attribute is the list of supported modes that may be selected for the CurrentMode attribute. Each item in this list represents a unique mode as indicated by the Mode field of the ModeOptionStruct. Each entry in this list SHALL have a unique value for the Mode field. ESP_MATTER uses factory partition to set the values of Supported Modes attribute. -9.2 Generate Factory Partition Using esp-matter-mfg-tool -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Generate Factory Partition Using esp-matter-mfg-tool +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use `esp-matter-mfg-tool`_ to generate factory partition of the supported modes attribute. -9.2.1 Usage -^^^^^^^^^^^ +Usage +^^^^^ :: @@ -1370,8 +1370,8 @@ Use `esp-matter-mfg-tool`_ to generate factory partition of the supported modes --supported-modes mode1/label1/endpointId mode2/label2/endpointId -9.3 Build example -~~~~~~~~~~~~~~~~~ +Build example +~~~~~~~~~~~~~ For example we want to use mode_select cluster in light example. @@ -1396,13 +1396,13 @@ For example we want to use mode_select cluster in light example. ModeSelect::setSupportedModesManager(&sStaticSupportedModesManager); } -10 Custom Cluster ------------------ +Custom Cluster +-------------- Matter enables users to implement custom clusters for unique features. This section introduces how to add a custom cluster. -10.1 Cluster XML Template -~~~~~~~~~~~~~~~~~~~~~~~~~ +Cluster XML Template +~~~~~~~~~~~~~~~~~~~~ Before adding a custom cluster, you should design the attributes, commands, and events it will include, and create the cluster XML template file based on your design. @@ -1476,13 +1476,13 @@ Run ``zap_regen_all.py`` in Matter virtual environment to generate common code a The code generation script will create client code for the custom cluster, supporting Android, Darwin, and Python controllers, as well as the chip-tool. It will also generate app-common code for the new custom cluster. The chip-tool can be used to test the custom cluster after recompiling. -10.2 Cluster Implementation -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Cluster Implementation +~~~~~~~~~~~~~~~~~~~~~~ The custom cluster should be implemented after the app-common code has been generated. -10.2.1 Custom Cluster Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Custom Cluster Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^ The attributes in a cluster can be managed with the two following methods. A cluster can utilize both the methods to manage its attributes. @@ -1498,8 +1498,8 @@ The attributes in a cluster can be managed with the two following methods. A clu Notes that attributes of complex types(structure or array) cannot be handled by Attribute Accessors and MUST be managed using AAI. -10.2.2 Custom Cluster Commands -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Custom Cluster Commands +^^^^^^^^^^^^^^^^^^^^^^^ The commands in a cluster can be handled with one of the two following methods. A cluster can only choose one method to handle its commands. @@ -1513,21 +1513,21 @@ The commands in a cluster can be handled with one of the two following methods. If the commands in a cluster are handled by CHI. The cluster should be added to the ``CommandHandlerInterfaceOnlyClusters`` array in the `zap configuration data`_ file. After modifying the `zap configuration data`_, the code should be regenerated, which will remove the Ember command callback declarations. -10.2.3 Custom Cluster Events -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Custom Cluster Events +^^^^^^^^^^^^^^^^^^^^^ All the events are managed by the `EventLogging `__. If an event is triggered, ``chip::app::LogEvent()`` can be called to record it. The event will then be reported to the subscriber that has subscribed to it. -10.2.4 Custom Cluster Functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Custom Cluster Functions +^^^^^^^^^^^^^^^^^^^^^^^^ -A custom cluster might requires special funtions to handle initialization, attribute changes, shutdown, and pre-attribute changes. +A custom cluster might requires special functions to handle initialization, attribute changes, shutdown, and pre-attribute changes. For instance, the AAI and CHI need to be registered so that they can be accessed by the Matter data model. Therefore, the cluster requires an initialization function to register them. To enable these functions, the cluster should be added to the appropriate entry in the `zap configuration data`_ file. -10.3 Example Usage -~~~~~~~~~~~~~~~~~~ +Example Usage +~~~~~~~~~~~~~ - Zap Example diff --git a/docs/en/faq.rst b/docs/en/faq.rst index 9df7b0407..f9ee9261a 100644 --- a/docs/en/faq.rst +++ b/docs/en/faq.rst @@ -1,8 +1,12 @@ -A1 Appendix FAQs -================ +FAQs +==== -A1.1 Compilation errors ------------------------ +.. sectnum:: + :prefix: A + :depth: 2 + +Compilation errors +------------------ I cannot build the application: @@ -15,8 +19,8 @@ I cannot build the application: - If you are still facing issues, reproduce it on the default example and then raise a `Github issue`_. -A1.2 Device commissioning using chip-tool ------------------------------------------ +Device commissioning using chip-tool +------------------------------------ I cannot commission a new device through the chip-tool: @@ -38,8 +42,8 @@ Bluetooth/BLE does not work on by device: - If you are still facing issues, reproduce it on the default example for the device and then raise a `Github issue`_. -A1.3 Device crashing --------------------- +Device crashing +--------------- My device is crashing: @@ -65,8 +69,8 @@ My device is crashing: - If you have gdb enabled, run the command ``backtrace`` and share the output of gdb too. -A1.4 Device not crashed but not responding ------------------------------------------- +Device not crashed but not responding +------------------------------------- My device is not responding to commands: @@ -82,8 +86,8 @@ My device is not responding to commands: - The complete device logs taken over UART. -A1.5 Onboard LED not working ----------------------------- +Onboard LED not working +----------------------- The LED on my devkit is not working: @@ -97,8 +101,8 @@ The LED on my devkit is not working: example for the device and then raise a `Github issue`_. -A1.6 Using Rotating Device Identifier -------------------------------------- +Using Rotating Device Identifier +-------------------------------- What is Rotating Device Identifier: @@ -137,8 +141,8 @@ Difference between Rotating ID Unique ID and Unique ID - it SHALL not be printed on the product or delivered with the product -A1.7 ModuleNotFoundError: No module named 'lark' ------------------------------------------------- +ModuleNotFoundError: No module named 'lark' +------------------------------------------- Encountering the above error while building the esp-matter example could indicate that the steps outlined in the `getting the repository`_ section of the documentation were not properly followed. @@ -164,8 +168,8 @@ However, if the error persists, you can try the following steps to resolve it: idf.py build -A1.8 Why does free RAM increase after first commissioning ---------------------------------------------------------- +Why does free RAM increase after first commissioning +---------------------------------------------------- After the first commissioning, you may notice that the free RAM increases. This is because, by default, BLE is only used for the commissioning process. Once the commissioning is complete, BLE is deinitialized, @@ -176,8 +180,8 @@ However, if you want to continue using the BLE even after the commissioning proc ``CONFIG_USE_BLE_ONLY_FOR_COMMISSIONING``. This will ensure that the memory allocated to the BLE functionality is not released after the commissioning process, and the free RAM won't go up. -A1.9 How to generate Matter Onboarding Codes (QR Code and Manual Pairing Code) ------------------------------------------------------------------------------- +How to generate Matter Onboarding Codes (QR Code and Manual Pairing Code) +------------------------------------------------------------------------- When creating a factory partition using ``esp-matter-mfg-tool``, both the QR code and manual pairing codes are generated. @@ -213,8 +217,8 @@ Along with that, there are two more methods for generating Matter onboarding cod To create a QR code image, copy the QR code text and paste it into `CHIP QR Code`_. -A1.10 Chip stack locking error ... Code is unsafe/racy ------------------------------------------------------- +Chip stack locking error ... Code is unsafe/racy +------------------------------------------------ :: @@ -250,8 +254,8 @@ To address this, there are two possible approaches: chip::DeviceLayer::PlatformMgr().ScheduleWork(WorkHandler, (nullptr)); -A1.11 Firmware Version Number ------------------------------ +Firmware Version Number +----------------------- Similar to the ESP-IDF's application versioning scheme, the ESP-Matter SDK provides two options for setting the firmware version. It depends on `CONFIG_APP_PROJECT_VER_FROM_CONFIG`_ option and by default option is disabled. @@ -284,8 +288,8 @@ the following configuration options: version, even though the binary content may match the previous OTA image. -A1.12 Stuck at "Solving dependencies requirements ....." --------------------------------------------------------- +Stuck at "Solving dependencies requirements ....." +-------------------------------------------------- When building an example, if it is stuck at "Solving dependencies requirements..." you can resolve this issue by clearing the component manager cache. @@ -299,8 +303,8 @@ you can resolve this issue by clearing the component manager cache. rm -rf ~/Library/Caches/Espressif/ComponentManager -A1.13 ESP32-C2 log garbled, unable to perform Matter commissioning and other abnormal issues --------------------------------------------------------------------------------------------- +ESP32-C2 log garbled, unable to perform Matter commissioning and other abnormal issues +-------------------------------------------------------------------------------------- When encountering the above issues, the following possible causes may exist: 1. Incorrect baud rate settings. See `UART console baud rate`_ @@ -318,8 +322,8 @@ When encountering the above issues, the following possible causes may exist: Crystal is 26MHz MAC: 08:3a:8d:49:b3:90 -A1.14 Generating Matter Onboarding Codes on the device itself -------------------------------------------------------------- +Generating Matter Onboarding Codes on the device itself +------------------------------------------------------- The Passcode serves as both proof of possession for the device and the shared secret needed to establish the initial secure channel for onboarding. @@ -341,11 +345,11 @@ along with the corresponding Spake2p verifier and onboarding payload, directly o Please check `#1128`_ and `#1126`_ for relevant discussion on Github issue -A1.15 Using BLE after Matter commissioning ------------------------------------------- +Using BLE after Matter commissioning +------------------------------------ Most Matter applications do not require BLE after commissioning. By default, BLE is deinitialized after commissioning -to reclaim RAM and increase the available free heap. Refer to `A1.8 Why does free RAM increase after first commissioning`_ +to reclaim RAM and increase the available free heap. Refer to `Why does free RAM increase after first commissioning`_ for more details. However, if BLE functionality is needed even after commissioning, you can disable the ``CONFIG_USE_BLE_ONLY_FOR_COMMISSIONING`` @@ -376,8 +380,8 @@ Please refer to the `advance setup`_ section in the programming guide. This has been demonstrated in the `blemesh_bridge`_ examples. -A1.16 Moving BSS Segments to PSRAM to Reduce Memory Usage ---------------------------------------------------------- +Moving BSS Segments to PSRAM to Reduce Memory Usage +---------------------------------------------------- The BSS section of libesp_matter.a and libCHIP.a can consume significant internal memory. For devices with PSRAM, you can move the BSS segments to external memory to significantly @@ -404,8 +408,8 @@ significantly reducing the internal memory usage of your application. Please check `#1123`_ for relevant discussion on Github issue. -A1.17 Updating attribute marked as ATTRIBUTE_FLAG_MANAGED_INTERNALLY ----------------------------------------------------------------------- +Updating attribute marked as ATTRIBUTE_FLAG_MANAGED_INTERNALLY +-------------------------------------------------------------- When an attribute is marked with the flag ``ATTRIBUTE_FLAG_MANAGED_INTERNALLY``, application can not directly modify the attribute's value using ``esp_matter::attribute::update``. To update such attributes, retrieve the corresponding diff --git a/docs/en/index.rst b/docs/en/index.rst index 3e133eba1..80c32e1e3 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -13,23 +13,29 @@ We have put together a series of blog posts that introduces various aspects of M We recommend that you go through this `Espressif Matter Blog`_. Table of Contents -================= +----------------- .. toctree:: :maxdepth: 2 + :numbered: - 1. Introduction - 2. Developing with the SDK - 3. Matter Controller - 4. Matter Certification - 5. Production Considerations - 6. Security Considerations - 7. RAM and Flash Optimizations - 8. API Reference - 9. Integration with esp-insights - 10. Application User Guide - 11. Copyrights and Licenses - A1 Appendix FAQs + Introduction + Developing with the SDK + Matter Controller + Matter Certification + Production Considerations + Security Considerations + RAM and Flash Optimizations + API Reference + Integration with esp-insights + Application User Guide + Copyrights and Licenses + +.. toctree:: + :maxdepth: 1 + :caption: Appendix + + FAQs .. _Matter: https://csa-iot.org/all-solutions/matter/ .. _Espressif Matter Blog: https://blog.espressif.com/matter-38ccf1d60bcd diff --git a/docs/en/introduction.rst b/docs/en/introduction.rst index 475bde200..72813620e 100644 --- a/docs/en/introduction.rst +++ b/docs/en/introduction.rst @@ -1,8 +1,8 @@ Introduction ============ -1 Espressif Matter Solutions ----------------------------- +Espressif Matter Solutions +-------------------------- .. figure:: ../_static/solution_architecture.png :align: center @@ -15,8 +15,8 @@ Espressif's Matter Solutions consist of: - Production ready SDK for Matter - Matter and ESP RainMaker integration -1.1 Espressif Matter Platforms -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Espressif Matter Platforms +~~~~~~~~~~~~~~~~~~~~~~~~~~ Espressif platform solutions are as shown below: @@ -30,8 +30,8 @@ Espressif platform solutions are as shown below: - By efficiently combining ESP32-H and our Wi-Fi SoCs, a **Thread Border Router** can be built to connect the Thread network with the Wi-Fi network. We provide hardware devkits, reference designs and production-ready SDK, which supports the latest Thread 1.3 feature for Matter. - We also provide Matter-Zigbee and Matter-BLE Mesh bridge solutions that enable non-Matter devices based on Zigbee, Bluetooth LE Mesh and other protocols to connect to the Matter ecosystem. A **Matter-Zigbee Bridge** uses ESP32-H and another Wi-Fi SoC, while a **Matter-BLE Mesh Bridge** can be done on a single SoC with both Wi-Fi and Bluetooth LE interfaces. -1.2 Espressif's SDK for Matter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Espressif's SDK for Matter +~~~~~~~~~~~~~~~~~~~~~~~~~~ Espressif's SDK for Matter is built on top of the `open source Matter SDK `__, and provides simplified APIs, commonly used peripherals, tools and utilities for security, manufacturing and production accompanied by exhaustive documentation. It includes rich production references, aimed to simplify the development process of Matter products and enable the users to go to production in the shortest possible time. @@ -42,16 +42,16 @@ Espressif's SDK for Matter is built on top of the `open source Matter SDK `__ and `ESP Insights `__ for cloud services and remote diagnostics. -1.3 Matter and ESP RainMaker Integration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Matter and ESP RainMaker Integration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Espressif's AIoT cloud platform `ESP RainMaker `__ can provide remote control and enable cloud-based device management for Matter devices. By combining the above-mentioned Matter hardware and software solutions with ESP RainMaker, this one-stop Matter ecosystem solution provides a full-fledged cloud deployment through your own private account with advanced device management features. -2 Try it yourself ------------------ +Try it yourself +--------------- If you want to test Matter on Espressif devices without any additional setup: diff --git a/docs/en/optimizations.rst b/docs/en/optimizations.rst index 1a69b382c..a3bc9b6d4 100644 --- a/docs/en/optimizations.rst +++ b/docs/en/optimizations.rst @@ -1,8 +1,8 @@ Configuration options to optimize RAM and Flash =============================================== -1 Overview ----------- +Overview +-------- There are several configuration options available to optimize Flash and RAM storage. The following list highlights key options that significantly increase the free DRAM, heap, and reduce the flash @@ -10,11 +10,11 @@ footprint. For more optimizations, we've also listed the reference links to esp-idf's optimization guide. -2 Configurations ----------------- +Configurations +-------------- -2.1 Test Environment setup -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Test Environment setup +~~~~~~~~~~~~~~~~~~~~~~ All numbers mentioned below are collected in the following environment: @@ -42,8 +42,8 @@ All numbers mentioned below are collected in the following environment: allocated as heap. Therefore, a direct increase in the free DRAM will reflect as an increase in free heap. -2.2 Default Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~ +Default Configuration +~~~~~~~~~~~~~~~~~~~~~ We have used the default light example here, and below listed are the static and dynamic sizes. @@ -76,8 +76,8 @@ We have used the default light example here, and below listed are the static and Post Commissioning, 101580, -- -2.3 Disable the chip-shell -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Disable the chip-shell +~~~~~~~~~~~~~~~~~~~~~~ Console shell is helpful when developing/debugging the application, but may not be necessary in production. Disabling the shell can save space. Disable the below configuration option. @@ -115,8 +115,8 @@ production. Disabling the shell can save space. Disable the below configuration Post Commissioning, 112340, 10760 -2.4 Adjust the dynamic endpoint count -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Adjust the dynamic endpoint count +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The default dynamic endpoint count and default device type count is 16, which may be excessive for a normal application creating only 2 endpoints. eg: light, only has two endpoints, one for root endpoint and one for actual light. @@ -158,8 +158,8 @@ Here, we have set the dynamic endpoint count and device type count to 2. Increas Post Commissioning, 107984, 6404 -2.5 Use the newlib nano formatting -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Use the newlib nano formatting +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This optimization saves approximately 25-50K of flash, depending on the target. In our case, it results in a flash reduction of 47 KB. @@ -200,8 +200,8 @@ functions. Fore more details please take a look at esp-idf's `newlib nano format Post Commissioning, 103500, 1920 -2.6 BLE Optimizations -~~~~~~~~~~~~~~~~~~~~~ +BLE Optimizations +~~~~~~~~~~~~~~~~~ Since most devices will primarily operate as BLE peripherals and typically won't need more than one connection (especially if it's just a Matter app), we can optimize by reducing the maximum allowed connections, thereby @@ -262,8 +262,8 @@ Below are the configuration options that can be set to achieve these optimizatio Post Commissioning, 101176, -404 -2.7 Configuring logging event buffer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Configuring logging event buffer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Matter events serve as a historical record, stored in chronological order in the logging event buffer. By reducing the buffer size we can potentially save the DRAM. However, it's important to note that this reduction @@ -322,8 +322,8 @@ Reduce the chip device event queue size can reduce IRAM size usage, lead to free Post Commissioning, 108184, 6604 -2.8 Relocate certain code from IRAM to flash memory -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Relocate certain code from IRAM to flash memory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Relocating certain code from IRAM to flash can reduce IRAM usage, so increase available heap size. However, this may increase execution time. @@ -331,8 +331,8 @@ Relocating certain code from IRAM to flash can reduce IRAM usage, so increase av The options in this section may impact performance. Please perform thorough testing before using them in production. -2.8.1 Reduce BLE IRAM usage -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Reduce BLE IRAM usage +^^^^^^^^^^^^^^^^^^^^^ Move most IRAM into flash. This will increase the usage of flash and reduce ble performance. Because the code is moved to the flash, the execution speed of the code is reduced. To have @@ -371,8 +371,8 @@ a small impact on performance, you need to enable flash suspend (SPI_FLASH_AUTO_ Post Commissioning, 119608, 18028 -2.8.2 Place FreeRTOS functions into Flash -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Place FreeRTOS functions into Flash +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When enabled the selected Non-ISR FreeRTOS functions will be placed into Flash memory instead of IRAM. This saves up to 8KB of IRAM depending on which functions are used. @@ -410,8 +410,8 @@ This saves up to 8KB of IRAM depending on which functions are used. Post Commissioning, 111020, 9440 -2.8.3 Place non-ISR ringbuf functions into flash -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Place non-ISR ringbuf functions into flash +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Place non-ISR ringbuf functions (like xRingbufferCreate/xRingbufferSend) into flash. This frees up IRAM, but the functions can no longer be called when the cache is disabled. @@ -449,8 +449,8 @@ This frees up IRAM, but the functions can no longer be called when the cache is Post Commissioning, 105652, 4072 -2.8.4 Use esp_flash implementation in ROM -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Use esp_flash implementation in ROM +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Enable this flag to use new SPI flash driver functions from ROM instead of ESP-IDF. After enable CONFIG_SPI_FLASH_ROM_IMPL, will increase free IRAM. @@ -491,8 +491,8 @@ But may miss out on some flash features and support for new flash chips. Post Commissioning, 110512, 8932 -2.8.5 Force the entire heap component to be placed in flash memory -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Force the entire heap component to be placed in flash memory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Enable this flag to save up RAM space by placing the heap component in the flash memory Note that it is only safe to enable this configuration if no functions from esp_heap_caps.h or @@ -531,8 +531,8 @@ esp_heap_trace.h are called from IRAM ISR which runs when cache is disabled. Post Commissioning, 108192, 6612 -2.9 Reduce Task Stack Size -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Reduce Task Stack Size +~~~~~~~~~~~~~~~~~~~~~~ Reduce some task stack size can increase free heap size. @@ -571,8 +571,8 @@ Reduce some task stack size can increase free heap size. Post Commissioning, 104828, 3248 -2.10 Excluding Unused Matter Clusters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Excluding Unused Matter Clusters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the cluster implementation source files use a class derived from another class with virtual functions and instantiate a global object of this class, the linker may keep all the related symbols that may be used for this class in the vtable. @@ -686,8 +686,8 @@ The default configuration disables all unused clusters. .. only:: esp32c2 or esp32c3 or esp32c5 or esp32c6 or esp32h2 - 2.11 Link Time Optimization (LTO) - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Link Time Optimization (LTO) + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Link Time Optimization (LTO) helps further optimize both binary size and runtime performance. You can read more about LTO in `GCC's LTO documentation`_. @@ -699,8 +699,8 @@ The default configuration disables all unused clusters. enabling LTO can result in around ~90 KB of flash savings, though it also increases stack usage by ~1700 bytes. -3 References for futher optimizations -------------------------------------- +References for further optimizations +------------------------------------ - `RAM optimization`_ - `Binary size optimization`_ diff --git a/docs/en/production.rst b/docs/en/production.rst index 56828363c..04a08e20e 100644 --- a/docs/en/production.rst +++ b/docs/en/production.rst @@ -1,13 +1,13 @@ Production Considerations ========================= -1 Prerequisites ---------------- +Prerequisites +------------- All Matter examples use certain test or evaluation values that enables you to quickly build and test Matter. As you get ready to go to production, these must be replaced with the actual values. These values are typically a part of the manufacturing partition in your device. -1.1 Vendor ID and Product ID -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Vendor ID and Product ID +~~~~~~~~~~~~~~~~~~~~~~~~ A **Vendor Identifier (VID)** is a 16-bit number that uniquely identifies a particular product manufacturer or a vendor. It is allocated by the Connectivity Standards @@ -18,8 +18,8 @@ of a vendor. It is assigned by the vendor (you). A VID-PID combination uniquely identifies a Matter product. -1.2 Certificates -~~~~~~~~~~~~~~~~ +Certificates +~~~~~~~~~~~~ A **Device Attestation Certificate (DAC)** proves the authenticity of the device manufacturer and the certification status of the device's hardware and software. @@ -32,16 +32,16 @@ The PAA certificate is an implicitly trusted self-signed root certificate. Please reach out to your Espressif representative for the details about how to procure the DAC. -1.3 Certification Declaration (CD) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Certification Declaration (CD) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A **Certification Declaration (CD)** is a cryptographic document that allows a Matter device to assert its protocol compliance. Once your product is certified, the CSA creates a CD for that device. The CD should then be included in the device firmware by the device manufacturer. -1.4 Setup Passcode, Discriminator and Onboarding Payload -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Setup Passcode, Discriminator and Onboarding Payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The unique **setup passcode** serves as the proof of possession and is also used to compute the shared secret during commissioning. The corresponding SPAKE2+ verifier of the @@ -56,8 +56,8 @@ The QR code and/or the manual pairing code are generally printed on the packagin device. -1.5 Manufacturing Partition -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Manufacturing Partition +~~~~~~~~~~~~~~~~~~~~~~~ Espressif's SDK for Matter uses a separate manufacturing partition to store all the information mentioned above. Because the DACs are unique to every device, the manufacturing partition @@ -73,8 +73,8 @@ images before shipping the modules and provides a manifest (CSV file) along with bundle. -2 Over-the-Air (OTA) Updates ----------------------------- +Over-the-Air (OTA) Updates +--------------------------- Matter devices must support OTA firmware updates, either by using Matter-based OTA or vendor specific means. @@ -89,11 +89,11 @@ on the devices remotely. As opposed to the Matter OTA, ESP RainMaker OTA allows the flexibility of delivering the OTA upgrades incrementally or to groups of devices. -3 Manufacturing ---------------- +Manufacturing +-------------- -3.1 Mass Manufacturing Utility -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Mass Manufacturing Utility +~~~~~~~~~~~~~~~~~~~~~~~~~~~ For commissioning a device into the Matter Fabric, the device requires the following information: @@ -109,8 +109,8 @@ When using the utility, by default, the above details will be included in the ge Details about using the mass manufacturing utility can be found here: `esp-matter-mfg-tool`_ -3.2 Pre-Provisioned Modules -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Pre-Provisioned Modules +~~~~~~~~~~~~~~~~~~~~~~~~ {IDF_TARGET_NAME} modules can be pre-flashed with the manufacturing partition images during module manufacturing itself and then be shipped to you. @@ -120,8 +120,8 @@ programming the partition into the device at your end. Please contact your Espressif contact person for more information. -3.3 The esp-matter-mfg-tool Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The esp-matter-mfg-tool Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In Espressif Matter Prep-provisioning modules, the DAC key pair, DAC and PAI certificates are pre-flashed by default. @@ -177,8 +177,8 @@ This is the example to generate factory images after pre-provisioning: .. _`esp-matter-mfg-tool`: https://github.com/espressif/esp-matter-tools/tree/main/mfg_tool .. _`ESP RainMaker OTA`: https://rainmaker.espressif.com/docs/ota.html -4.3.4 Recommended Providers to Use -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Recommended Providers to Use +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: diff --git a/docs/en/security.rst b/docs/en/security.rst index fd5dbd3bc..f0d032443 100644 --- a/docs/en/security.rst +++ b/docs/en/security.rst @@ -3,8 +3,8 @@ Security Considerations {IDF_TARGET_RELEASE:default="v5.4.1"} -1 Overview ----------- +Overview +-------- This guide provides an overview of the overall security features that should be considered while designing the products with Matter framework on ESP32 SoCs. @@ -14,11 +14,11 @@ High level security goals are as follows: #. Securing device identity (e.g., Matter DAC Private Key) #. Secure storage for confidential data -2 Platform Security -------------------- +Platform Security +----------------- -2.1 Secure Boot -~~~~~~~~~~~~~~~ +Secure Boot +~~~~~~~~~~~ The Secure Boot feature ensures that only authenticated software can execute on the device. The Secure Boot process forms a chain of trust by verifying all **mutable** software entities involved in the boot-up process. Signature verification happens during both boot-up as well as in OTA updates. @@ -30,20 +30,20 @@ Please refer to `Secure Boot V2`_ guide for detailed documentation about this fe .. _flash_enc-guide: -2.2 Flash Encryption -~~~~~~~~~~~~~~~~~~~~ +Flash Encryption +~~~~~~~~~~~~~~~~ The Flash Encryption feature helps to encrypt the contents on the off-chip flash memory and thus provides the confidentiality aspect to the software or data stored in the flash memory. Please refer to `Flash Encryption`_ guide for detailed documentation about this feature in {IDF_TARGET_NAME}. -3 Product Security ------------------- +Product Security +---------------- .. _secure_storage-guide: -3.1 Secure Storage -~~~~~~~~~~~~~~~~~~ +Secure Storage +~~~~~~~~~~~~~~ Secure storage refers to the application-specific data that can be stored in a secure manner on the device, i.e., off-chip flash memory. This is typically a read-write flash partition and holds device specific configuration data, e.g., Wi-Fi credentials. @@ -51,8 +51,8 @@ ESP-IDF provides the **NVS (Non-volatile Storage)** management component which a Please refer to the `NVS Encryption`_ for detailed documentation on the working and instructions to enable this feature in {IDF_TARGET_NAME}. -3.2 Device Identity -~~~~~~~~~~~~~~~~~~~ +Device Identity +~~~~~~~~~~~~~~~ Matter specification requires a unique Device Attestation Key (DAC) per device. This is a private ECDSA (secp256r1 curve) key that establishes the device identity to the Matter Ecosystem. DAC private needs to be protected from remote as well as physical attacks in the best possible way. @@ -81,26 +81,26 @@ Recommended ways for DAC private key protection: Espressif provides pre-provisioning service to build Matter-Compatible devices. This service also ensures the security of the DAC private key and configuration data. Please contact Espressif Sales for more information. -4 More Security Considerations ------------------------------- +More Security Considerations +---------------------------- Please refer to the overall ESP-IDF `Security Guide`_ for more considerations related to the debug interfaces, network, transport and OTA updates related security. -5 Security Policy ------------------ +Security Policy +--------------- The ESP-Matter GitHub repository has attached `Security Policy Brief`_. -5.1 Advisories -~~~~~~~~~~~~~~ +Advisories +~~~~~~~~~~ - Espressif publishes critical `Security Advisories`_, which includes security advisories regarding both hardware and software. - The specific advisories of the ESP-Matter software components shall be published through the `GitHub repository`_. -5.2 Software Updates -~~~~~~~~~~~~~~~~~~~~ +Software Updates +~~~~~~~~~~~~~~~~ -Critical security issues in the ESP-Matter components, ESP-IDF components and dependant third-party libraries are fixed as and when we find them or when they are reported to us. Gradually, we make the fixes available in all applicable release branches in ESP-Matter. +Critical security issues in the ESP-Matter components, ESP-IDF components and dependent third-party libraries are fixed as and when we find them or when they are reported to us. Gradually, we make the fixes available in all applicable release branches in ESP-Matter. .. important:: diff --git a/docs/en/using_chip_tool.rst b/docs/en/using_chip_tool.rst index c2812c8fe..6d9937d17 100644 --- a/docs/en/using_chip_tool.rst +++ b/docs/en/using_chip_tool.rst @@ -1,5 +1,5 @@ -1. Working with the CHIP Tool in WSL2 -===================================== +Working with the CHIP Tool in WSL2 +=================================== The CHIP Tool (chip-tool) is a Matter controller implementation that allows to commission a Matter device into the network and to communicate with it using Matter messages, which may encode Data Model actions, such as cluster commands. @@ -7,31 +7,31 @@ The tool also provides other utilities specific to Matter, such as parsing of th The CHIP Tool requires access to the local network and bluetooth. -1.1 Requirements ----------------- +Requirements +------------ - Windows 11 64-Bit Pro/Enterprise/Education [for Hyper-V Manager] -1.2 Providing access to local network -------------------------------------- +Providing access to local network +--------------------------------- WSL2 does not share an IP address with your computer. Because WSL2 was implemented with Hyper-V, it runs with a virtualized ethernet adapter. Your computer hides WSL2 behind a NAT where WSL2 has its own unique IP. To provide an IP address from the local network, WSL2 instance needs to be connected to a virtual Bridge through Hyper-V Manager. -1.2.1 Enabling Hyper-V for use on Windows 10 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Enabling Hyper-V for use on Windows 10 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1.2.1.1 Enable Hardware Virtualization in BIOS -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Enable Hardware Virtualization in BIOS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - In the Startup Menu, enter the BIOS setup. - In the BIOS Setup Utility,open the Configuration or Security tab. - Enable the Virtualization Technology option -1.2.1.2 Setting Up Hyper-V -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Setting Up Hyper-V +^^^^^^^^^^^^^^^^^^ Ensure that hardware virtualization support is turned on in the BIOS settings Save the BIOS settings and boot up the machine normally. @@ -47,8 +47,8 @@ Save the BIOS settings and boot up the machine normally. .. image:: ../_static/windows_feature.png :alt: Windows Features -1.2.2 Configure Hyper-V for Bridge Network -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Configure Hyper-V for Bridge Network +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. image:: ../_static/HyperV_bridge.png :alt: Configuration of Bridge Network for WSL @@ -75,8 +75,8 @@ Create .wslconfig file on C:/Users/user-name/ and add the following lines to con ipv6 = true -1.2.2.1 Checking the configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Checking the configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: ini @@ -91,8 +91,8 @@ The IPv4 Address assigned to the eth0 will be from the local network and IPv6 Ad If the configuration was done correctly, all the matter operational nodes performing mDns advertisement on the local network will be shown. -1.2.2.2 Troubleshoot -^^^^^^^^^^^^^^^^^^^^ +Troubleshoot +^^^^^^^^^^^^ **If no IP address assigned to WSL or same IP address as host, uspipd fails with tcp connect error, not able to ping external network.** @@ -105,14 +105,14 @@ If the configuration was done correctly, all the matter operational nodes perfor 5) If still no IP is assigned, run `sudo dhclient` -1.3 Providing access to bluetooth ---------------------------------- +Providing access to bluetooth +----------------------------- Bluetooth support is missing in default WSL kernel. To add support for bluetooth, WSL kernel needs to be recompiled with right drivers. -1.3.1 Building custom kernel for bluetooth access in WSL2 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Building custom kernel for bluetooth access in WSL2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: ini @@ -151,8 +151,8 @@ The new kernel image will be built. cp arch/x86/boot/bzImage /mnt/path/to/kernel/bluetooth-bzImage -1.3.2 Configure WSL to use new custom kernel image -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Configure WSL to use new custom kernel image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Add the following line to the created `.wslconfig` file. @@ -163,8 +163,8 @@ Add the following line to the created `.wslconfig` file. Replace the path with the path of new custom kernel built. -1.3.3 Attaching Bluetooth module to WSL2 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Attaching Bluetooth module to WSL2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Get the BUSID of the bluetooth module. [`Tested using usbipd-win 4.0.0`] @@ -187,8 +187,8 @@ Attach the bluetooth module to WSL2 instance using usbipd. The bluetooth module should be available to WSL. -1.3.4 Testing Bluetooth -~~~~~~~~~~~~~~~~~~~~~~~ +Testing Bluetooth +~~~~~~~~~~~~~~~~~ Install bluez library and scan for bluetooth devices. @@ -212,8 +212,8 @@ The bluetooth discovery should start. - Intel AX201 series and above - Marvell AVASTAR Bluetooth Radio Adapter. -1.4 Final .wslconfig file -------------------------- +Final .wslconfig file +--------------------- .. code-block:: ini