samples: matter: Extend Matter Watchdog by new configs

Added possibility to configure watchdog CONFIG register by:
- Pausing watchdog when CPU is in the sleep state.
- Pausing watchdog when the CPU is halted by a debugger.

Signed-off-by: Arkadiusz Balys <[email protected]>

doc/nrf/protocols/matter/end_product/watchdog.rst

@@ -27,16 +27,39 @@ This approach eliminates the need to directly call the ``Feed()`` method in your
 A time window specifies the period within which the feeding signal must be sent to each watchdog channel to reset the timer and prevent the device from rebooting.
 If the feeding signal is sent after the time window has elapsed, it does not prevent the device from rebooting.
 
-To enable the Matter watchdog feature, set the :kconfig:option:`CONFIG_NCS_SAMPLE_MATTER_WATCHDOG` Kconfig option to ``y``.
+To enable the Matter watchdog feature in a matter sample, set the :kconfig:option:`CONFIG_NCS_SAMPLE_MATTER_WATCHDOG` Kconfig option to ``y``.
 The feature is enabled by default for the release build type in all Matter samples and applications.
 
 To set the timeout for the watchdog timer, configure the :kconfig:option:`CONFIG_NCS_SAMPLE_MATTER_WATCHDOG_TIMEOUT` with a value in milliseconds.
 By default, the timeout is set to 10 seconds.
 
+.. note::
+
+   The Matter watchdog implementation demonstrates how to use the Zephyr watchdog API and is specifically designed for Matter samples within the |NCS|.
+   If you want to use it in your application, refer to the source code and Kconfig options from this implementation.
+
+.. _ug_matter_device_watchdog_pause_mode:
+
+Matter watchdog pause mode
+**************************
+
+You can set the Matter watchdog to pause when the CPU is in idle (sleep) mode or when the CPU is halted by the debugger.
+This means the watchdog timer will stop counting down when the CPU is idle or halted.
+
+If pause mode is disabled, the watchdog must be fed within a specified time window, regardless of the CPU state, otherwise the device will reboot.
+If pause mode is enabled, the device will only reboot if the task feeding the watchdog is blocked for longer than the set time window.
+Pause mode is less accurate and may cause the device to reboot later than expected, but it allows feeding the watchdog only when the CPU is active.
+Non-pause mode requires periodic feeding to avoid a timeout, impacting power consumption as the CPU must wake up periodically.
+
+To enable pause mode while CPU is in the idle state, set the :kconfig:option:`CONFIG_NCS_SAMPLE_MATTER_WATCHDOG_PAUSE_IN_SLEEP` Kconfig option to ``y``.
+To enable pause mode during debugging, set the :kconfig:option:`CONFIG_NCS_SAMPLE_MATTER_WATCHDOG_PAUSE_ON_DEBUG` Kconfig option to ``y``.
+
+By default, Matter samples enable the pause mode only during debugging.
+
 Creating a Matter watchdog source
 *********************************
 
-The Matter watchdog feature is based on the ``Nrf::WatchdogSource`` class, which is located in the :file:`samples/matter/common/watchdog/watchdog.h` file.
+The Matter watchdog feature is based on the ``Nrf::WatchdogSource`` class, which is located in the :file:`samples\matter\common\src\watchdog\watchdog.h` file.
 Each Matter watchdog source constructor includes two optional arguments:
 
 * ``feedingInterval`` - Specifies the duration in milliseconds for automatically calling the attached feeding callback.

doc/nrf/releases_and_maturity/migration/migration_guide_2.9.rst

@@ -83,7 +83,18 @@ Samples and applications
 
 This section describes the changes related to samples and applications.
 
-|no_changes_yet_note|
+Matter
+------
+
+.. toggle::
+
+   * For the Matter samples and applications:
+
+      * The :ref:`ug_matter_device_watchdog` mode has been changed.
+        Previously, the :ref:`ug_matter_device_watchdog_pause_mode` was enabled by default for all Matter samples.
+        Now, this mode is disabled and all Matter watchdog sources must be fed within the specified time window.
+
+        To re-enable the pause mode, set the :kconfig:option:`CONFIG_NCS_SAMPLE_MATTER_WATCHDOG_PAUSE_IN_SLEEP` Kconfig option to ``y``.
 
 Libraries
 =========

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -138,9 +138,13 @@ Gazell
 Matter
 ------
 
-* Added implementation of the :cpp:class:`Spake2pVerifier` class for the PSA crypto backend.
-  You can use this class to generate the Spake2+ verifier at runtime.
-  To use this class, enable the :kconfig:option:`CONFIG_PSA_WANT_ALG_PBKDF2_HMAC` and :kconfig:option:`CONFIG_PSA_WANT_KEY_TYPE_SPAKE2P_KEY_PAIR_DERIVE` Kconfig options.
+* Added:
+
+  * Implementation of the :cpp:class:`Spake2pVerifier` class for the PSA crypto backend.
+    You can use this class to generate the Spake2+ verifier at runtime.
+    To use this class, enable the :kconfig:option:`CONFIG_PSA_WANT_ALG_PBKDF2_HMAC` and :kconfig:option:`CONFIG_PSA_WANT_KEY_TYPE_SPAKE2P_KEY_PAIR_DERIVE` Kconfig options.
+  * The Matter watchdog pause mode to the :ref:`ug_matter_device_watchdog` feature.
+
 
 Matter fork
 +++++++++++
@@ -393,6 +397,9 @@ Matter samples
 * Updated all Matter samples that support low-power mode to enable the :ref:`lib_ram_pwrdn` feature.
   It is enabled by default for the release configuration of the :ref:`matter_lock_sample`, :ref:`matter_light_switch_sample`, :ref:`matter_smoke_co_alarm_sample`, and :ref:`matter_window_covering_sample` samples.
 
+* Disabled pausing Matter watchdog while CPU is in idle state in all Matter samples.
+  To enable it set the :kconfig:option:`CONFIG_NCS_SAMPLE_MATTER_WATCHDOG_PAUSE_IN_SLEEP` Kconfig option to ``y``.
+
 * :ref:`matter_template_sample` sample:
 
   * Updated the internal configuration for the :ref:`zephyr:nrf54l15dk_nrf54l15` target to use the DFU image compression and provide more memory space for the application.

samples/matter/common/src/watchdog/Kconfig

@@ -10,6 +10,19 @@ menuconfig NCS_SAMPLE_MATTER_WATCHDOG
 
 if NCS_SAMPLE_MATTER_WATCHDOG
 
+config NCS_SAMPLE_MATTER_WATCHDOG_PAUSE_IN_SLEEP
+    bool "Pause watchdog while CPU is in sleep state"
+    help
+        If enabled, the watchdog will be paused while the CPU is in idle (sleep) state.
+
+config NCS_SAMPLE_MATTER_WATCHDOG_PAUSE_ON_DEBUG
+    bool "Pause watchdog while the CPU is halted by the debugger"
+    default y
+    help
+        If disabled, the watchdog will not be paused while the CPU is halted by the debugger and
+        the device reset will be triggered, if the feeding signal is not received within the
+        specified time.
+
 config NCS_SAMPLE_MATTER_WATCHDOG_DEFAULT
     bool "Use watchdog object dedicated for Main and Matter threads"
     default y

samples/matter/common/src/watchdog/watchdog.cpp

@@ -34,7 +34,16 @@ bool Nrf::Watchdog::Enable()
 		return false;
 	}
 
-	if (wdt_setup(wdt, WatchdogSource::kWatchdogOptions) != 0) {
+	/* Pause Watchdog when the CPU is in sleep state or is halted by the debugger */
+	uint8_t watchdogOptions = 0;
+#ifdef CONFIG_NCS_SAMPLE_MATTER_WATCHDOG_PAUSE_IN_SLEEP
+	watchdogOptions |= WDT_OPT_PAUSE_IN_SLEEP;
+#endif /* CONFIG_NCS_SAMPLE_MATTER_WATCHDOG_PAUSE_IN_SLEEP */
+#ifdef CONFIG_NCS_SAMPLE_MATTER_WATCHDOG_PAUSE_ON_DEBUG
+	watchdogOptions |= WDT_OPT_PAUSE_HALTED_BY_DBG;
+#endif /* CONFIG_NCS_SAMPLE_MATTER_WATCHDOG_PAUSE_ON_DEBUG */
+
+	if (wdt_setup(wdt, watchdogOptions) != 0) {
 		return false;
 	}
 

samples/matter/common/src/watchdog/watchdog.h

@@ -129,9 +129,6 @@ namespace Watchdog
 	private:
 		constexpr static uint8_t kInvalidChannel = -1;
 
-		/* Pause Watchdog when the CPU is in sleep state or is halted by the debugger */
-		constexpr static uint8_t kWatchdogOptions = WDT_OPT_PAUSE_HALTED_BY_DBG | WDT_OPT_PAUSE_IN_SLEEP;
-
 		/* Timer for feeding in the required interval */
 		static void TimerTimeoutCallback(k_timer *timer);