Pull request project-chip#1773: Update ICD docs for v1.3

mkardous-silabs · CuRahman · commit 067b3f564e1a · 2024-04-19T14:21:01.000Z
Merge in WMN_TOOLS/matter from feature/icd_documentation to RC_2.3.0-1.3

Squashed commit of the following:

commit 8af436906d57ba3d3b66bcc06be87ce145a979ec
Author: Curtis Rahman &lt;Curtis.Rahman@silabs.com&gt;
Date:   Fri Apr 19 14:10:57 2024 +0000

    Applied suggestion

commit d2fbaf2dbc6a02c91aa5501edd09d00dc750904a
Author: Curtis Rahman &lt;Curtis.Rahman@silabs.com&gt;
Date:   Fri Apr 19 14:10:46 2024 +0000

    Applied suggestion

commit 728c404fa8d9378c7689b65eed024dbda00e6a28
Author: Curtis Rahman &lt;Curtis.Rahman@silabs.com&gt;
Date:   Fri Apr 19 14:10:18 2024 +0000

    Applied suggestion

... and 13 more commits
diff --git a/docs/silabs/general/MATTER_ICD.md b/docs/silabs/general/MATTER_ICD.md
@@ -4,54 +4,35 @@ Matter introduces the concept of Intermittently Connected Devices (ICD) in the S
 An Intermittently Connected Device is the Matter representation of a device that is not always reachable.
 This covers battery-powered devices that disable their underlying hardware when in a low-power mode or devices that can be disconnected from the network, like a phone app.
 
-This page focuses on features designed to improve the performance and reliability of battery-powered devices. By default Matter ICD functionality is enabled.
+This page focuses on features designed to improve the performance and reliability of battery-powered devices and their different configuration options.
 
-## ICD Device Types
-
-Matter introduces two types of ICDs.
-
-- Short Idle Time ICDs
-- Long Idle Time ICDs
-
-### Short Idle Time ICDs
-
-Short Idle Time ICDs are battery powered devices that can always be reached by clients.
-This means that their polling intervals are small enough to guarantee that a message sent from a client will be able to reach the ICD without any synchronization.
-A door lock, for example, is typicaly a short idle time ICD because it needs to be able to receive commands from clients at any given time.
-These devices are usually not the initiators in the communication flow.
-
-### Long Idle ICDs
-
-Long Idle Time ICDs are battery powered devices that require synchronization between the client and the ICD for communication to succeed.
-A sensor device is an example of a device that are typicaly long idle time ICDs.
-
-Long Idle Time ICDs are provisional with the Matter 1.3 alpha release.
+## ICD Configurations
 
+The ICD feature-set offers two types of configurations : cluster configurations and subscription configurations.
+The cluster configurations are exposed through the ICD Manager Cluster interface.
+The subscription configurations are exposed through build arguments and public APIs of the Matter SDK.
 
-## ICD Management Cluster
+### ICD Management Cluster
 
 The ICD Management Cluster enables configuration of the ICD’s behavior.
-It is required for an ICD to have this cluster enabled on endpoint 0.
+It is required for an ICD to have this cluster enabled on endpoint 0 to be certifiable.
 
-The ICDM Cluster exposes three configuration attributes that enable to configure an ICD.
+#### Configuration Attributes
+
+The ICD Management Cluster exposes three configuration attributes.
+These configurations are independent from the underlying transport configurations.
 
 | Attribute | Type | Constraints | Description |
 |-|-|-|-|
-| IdleModeInterval      | uint32 | 1 to 64800 | Maximum interval in seconds or milliseconds the server can stay in idle mode |
-| ActiveModeInterval    | uint32 | min 300    | minimum interval in milliseconds the server will stay in active mode |
-| ActiveModeThreshold   | uint32 | min 300    | minimum amount of time in milliseconds the server typically will stay active after network activity when in active mode |
+| IdleModeInterval      | uint32 | 1 to 64800   | Maximum interval in seconds or milliseconds the server can stay in idle mode |
+| ActiveModeInterval    | uint32 | all          | minimum interval in milliseconds the server will stay in active mode |
+| ActiveModeThreshold   | uint16 | desc         | minimum amount of time in milliseconds the server typically will stay active after network activity when in active mode |
 
-These configurations can be change two different ways.
+These configurations can be changed two different ways.
 
-They can be changed by using the following build configuration.
-```cpp
-    sl_idle_mode_interval_ms = 600000  //10min Idle Mode Interval
-    sl_active_mode_interval_ms = 1000  //1s Active Mode Interval
-    sl_active_mode_threshold_ms = 500  //500ms Active Mode Threshold
-```   
 To change them within a build command
 ```shell
-./scripts/examples/gn_silabs_example.sh ./examples/light-switch-app/silabs ./out/light-switch-app_ICD BRD4187C --icd sl_idle_mode_interval_ms=600000 sl_active_mode_interval_ms=1000 sl_active_mode_threshold_ms= 500
+./scripts/examples/gn_silabs_example.sh ./examples/light-switch-app/silabs ./out/light-switch-app_ICD BRD4187C --icd sl_idle_mode_interval_ms=5000 sl_active_mode_interval_ms=0 sl_active_mode_threshold_ms=500
 ```
 These options can also be change by setting them to a default value in the projects openthread.gni file. See examples/lock-app/silabs/openthread.gni for an example on how they can be configured.
 ```cpp
@@ -61,34 +42,64 @@ sl_active_mode_interval_ms = 10000  //10s Active Mode Interval
 sl_active_mode_threshold_ms = 1000  //1s Active Mode Threshold
 ```
 The second way of changing the configuration is to set these defines in the projects ChipProjectConfig.h.
-
 ```cpp
 /**
  * @def CHIP_CONFIG_ICD_IDLE_MODE_INTERVAL_SEC
  *
  * @brief Default value for the ICD Management cluster IdleModeInterval attribute, in seconds
  */
-#define CHIP_CONFIG_ICD_IDLE_MODE_INTERVAL_SEC 2
+#define CHIP_CONFIG_ICD_IDLE_MODE_INTERVAL_SEC 5
 
 
 /**
  * @def CHIP_CONFIG_ICD_ACTIVE_MODE_INTERVAL_MS
  *
  * @brief Default value for the ICD Management cluster ActiveModeInterval attribute, in milliseconds
  */
-#define CHIP_CONFIG_ICD_ACTIVE_MODE_INTERVAL_MS 300
+#define CHIP_CONFIG_ICD_ACTIVE_MODE_INTERVAL_MS 0
 
 /**
  * @def CHIP_CONFIG_ICD_ACTIVE_MODE_THRESHOLD_MS
  *
  * @brief Default value for the ICD Management cluster ActiveModeThreshold attribute, in milliseconds
  */
-#define CHIP_CONFIG_ICD_ACTIVE_MODE_THRESHOLD_MS 300
+#define CHIP_CONFIG_ICD_ACTIVE_MODE_THRESHOLD_MS 500
 ```
-Using the build arguments either in the build command or in the openthread.gni file is the preferred method.
+Using the build arguments either in the build command or in the .gni file is the preferred method.
+
+#### ICD Check-In Protocol Use-Case
+
+The ICD Check-In Protocol use case is used by ICDs to maintain a known relationship in case subscriptions with clients are lost.
+This includes how a client shares a Check-In token (symmetric key) with the ICD, when Check-In messages are sent and how the Check-In Protocol requirements are respected.
+
+The Check-In Protocol is a fail-safe mechanism which allows an ICD to notify a registered client that it is available for communication when all subscriptions between the client and ICD are lost.
+A subscription can be lost for several reasons, such as:
+
+* The ICD might not have full RAM retention when it is in an idle state.
+* When the ICD is powered off to change the battery.
+* Power or network outage causing the connection between the client and the ICD to be interrupted.
+* The client is unavailable for any reason (e.g. during a software update or hosted on a mobile device that is sometimes out-of-home).
+
+The Check-In message is sessionless and relies on a shared secret that has been given to the ICD during the registration of the client using the ICD Management cluster.
+For more information on the ICD Check-In Protocol use-case, see the associated specification section.
+
+#### User Active Mode Trigger
 
+Since ICDs are not immediately responsive, they require a means to render them available for communication within user initiated use cases.
+Some of the user initiated use cases are:
 
-## Subscription Maximum Interval
+* Opening a new commissioning window to add another administrator.
+* Reconfiguration of an existing fabric (e.g. IPKs, NOC rotation, ACL changes).
+* Reconfiguration of cluster functionality (e.g. ICD Management, Bindings, Groups, Scenes).
+* Removal of a device from a fabric.
+* Changes to the device's settings.
+
+To enable these user initiated use cases, ICDs need to provide a way for a user to put them in active mode and render them responsive.
+The User Active Mode Trigger feature in the ICD Management cluster indicates whether a particular device implements an active mode trigger.
+
+### Subscription Configurations
+
+#### Subscription Maximum Interval Negotiation
 
 The subscription mechanism is used by ecosystems and controllers to receive attribute change updates and liveness checks.
 The maximum interval of a subscription request is what defines the frequency at which a device will send a liveness check if there are no attribute changes.
@@ -105,8 +116,6 @@ The following table shows the subscribe response fields.
 | SubscriptionId | uint32 | identifies the subscription |
 | MaxInterval | uint16 | the final maximum interval for the subscription in seconds |
 
-### Maximum Interval Negotiation
-
 The Matter SDK provides a default implementation that allows an ICD to negotiate its MaxInterval.
 The goal of the algorithm is to set the MaxInterval to the IdleModeInterval.
 
@@ -163,7 +172,7 @@ The goal of the algorithm is to set the MaxInterval to the IdleModeInterval.
 #endif // CHIP_CONFIG_ENABLE_ICD_SERVER
 ```
 
-If the default implementation does fit within the use-case,
+If the default implementation does not fit within the use-case,
 an implementation can override the default implementation.
 The first step is to implement the `ApplicationCallback` class from the `ReadHandler.h` header.
 
@@ -217,7 +226,7 @@ The second step is registering the callback object to the Interaction Model Engi
 chip::app::InteractionModelEngine::GetInstance()->RegisterReadHandlerAppCallback(&mICDSubscriptionHandler);
 ```
 
-## Persistent Subscriptions
+#### Persistent Subscriptions
 
 Persistent subscriptions were added to Matter as a means to ensure that an ICD can re-establish its subscription and by extension its secure session to a subscriber in the event of a power cycle.
 When a device accepts a subscription request, it will persist the subscription.
@@ -227,17 +236,112 @@ the subscription will be deleted.
 
 Persistent subscriptions are enabled by default on all Silicon Labs sample applications.
 
-### Subscription Timeout Resumption
+#### Subscription Timeout Resumption
 
 Matter also provides a retry mechanism for devices to try to re-establish a lost subscription with a client. This feature should not be used on an ICD since it can significantly reduce battery life. This functionality can be disabled by adding
 
 `chip_subscription_timeout_resumption = false`
 
-## Subscription Synchronization
+#### Subscription Synchronization
 
 To avoid forcing an ICD to become active multiple times, the Matter SDK allows an ICD to synchronize its subscription reporting and send all the reports at the same time. The mecansim syncrhonizes the maximum interval of the all subscription to only require the ICD to become active one. This functionality can be enabled by adding
 
 `sl_use_subscription_synching = true`
 
 For further details on Matter ICD's operating on OpenThread, visit [Matter Intermittently Connected Devices over OpenThread](../thread/OT_SLEEPY_END_DEVICE.md).
 And for Matter ICD's operating via WiFi, visit [Matter Intermittently Connected Devices over WiFi](../wifi/WIFI_SLEEPY_END_DEVICE.md).
+
+
+## ICD Device Types
+
+Matter introduces two types of ICDs.
+
+- Short Idle Time ICDs
+- Long Idle Time ICDs
+
+### Short Idle Time ICDs
+
+Short Idle Time ICDs are battery powered devices that can always be reached by clients.
+This means that their polling intervals are small enough to guarantee that a message sent from a client will be able to reach the ICD without any synchronization.
+A door lock, for example, is typicaly a short idle time ICD because it needs to be able to receive commands from clients at any given time.
+These devices are usually not the initiators in the communication flow.
+
+#### Requirements
+
+This section lists the requirements that Short Idle Time ICDs must respect to be certifiable.
+
+1. The ICD Management Cluster must be present on the Root Endpoint (0) with mandatory attributes.
+2. The transport slow poll configuration must be smaller or equal to 15s.
+This requirement is not enforced in Matter 1.3 since LIT ICD are not certifiable.
+Once LIT ICD officially launch, this will be a mandatory requirement.
+
+Support of the ICD Check-In Protocol use-case and the user active mode trigger is optional for SIT ICDs.
+
+#### Configurations
+
+These are recommended configurations based on the state of the current implementation of SIT ICDs.
+The recommended configurations are likely to change with the Matter 1.4 release.
+
+```cpp
+// ICD Default configurations
+chip_enable_icd_server = true
+chip_subscription_timeout_resumption = false
+sl_use_subscription_synching = true
+
+// ICD Matter Configuration flags
+sl_idle_mode_duration_s = 600  // 10min Idle Mode Duration
+sl_active_mode_duration_ms = 10000  // 10s Active Mode Duration
+sl_active_mode_threshold_ms = 1000  // 1s Active Mode Threshold
+
+// Openthread Configuration flags
+sl_ot_idle_interval_ms = 5000  // 5s Idle Intervals
+sl_ot_active_interval_ms = 500  // 500ms Active Intervals
+```
+> **Note**: Wi-Fi polling configuration are dictated by the Access Point and cannot be changed at the Matter level.
+
+### Long Idle ICDs
+
+Long Idle Time ICDs are battery powered devices that require synchronization between the client and the ICD for communication to succeed.
+A sensor device is an example of a device that are typically a long idle time ICD.
+
+Long Idle Time ICDs are ready for integration in the Matter 1.3 release. The core feature-set for ICDs has been implemented through the `ICDManager`.
+LIT ICDs should be certifiable with the Matter 1.4 release. 
+Splitting the two milestones in different releases is to allow more in depth interoperability testing to validate the proposed feature-set achieves it's power consumption and usability goals.
+
+#### Requirements
+
+This section lists the requirements that Long Idle Time ICDs must respect to be certifiable.
+
+1. The ICD Management Cluster must be present on the Root Endpoint (0) with mandatory attributes.
+2. The `LITS` (Long Idle Time Support) feature map must be set to 1.
+All required features, attributes and commands required by this feature map must also be present.
+2. The `CIP` (Check-In Protocol support) feature map must be set to 1.
+All required attributes and commands required by this feature map must also be present.
+3. The `UAT` (User Active Mode Trigger support) feature map must be set to 1.
+All required attributes and commands required by this feature map must also be present.
+4. The `ActiveModeThreshold` cannot be lower than 5 seconds.
+
+
+#### Configurations
+
+These are recommended configurations based on the state of the current implementation of LIT ICDs.
+The recommended configurations are likely to change with the Matter 1.4 release.
+
+```cpp
+// ICD Default configurations
+chip_enable_icd_server = true
+chip_subscription_timeout_resumption = false
+sl_use_subscription_synching = true
+icd_enforce_sit_slow_poll_limit = true
+chip_icd_report_on_active_mode = true
+chip_enable_icd_lit = true
+
+# Openthread Configuration flags
+sl_ot_idle_interval_ms = 3600000  // 60mins Idle Polling Interval
+sl_ot_active_interval_ms = 1000  // 1s Active Polling Interval
+
+# ICD Matter Configuration flags
+sl_idle_mode_duration_s = 3600  // 60min Idle Mode Duration
+sl_active_mode_duration_ms = 0  // 0 Active Mode Duration
+sl_active_mode_threshold_ms = 5000  // 5s Active Mode Threshold
+```
