1 1. Overview
2 2. Configuring nPM1300 Watchdog in Zephyr BSP
3 3. Controlling nPM1300 Watchdog in User Application
4 4. Validating nPM1300 Watchdog Operations

1. Overview

This application note describes how to configure nPM1300 Watchdog in Zephyr BSP and use it in the user application.

2. Configuring nPM1300 Watchdog in Zephyr BSP

The nPM1300 Watchdog device is declared in nrf9151som_nrf9151_ns.dts as a child node of the npm1300_pmic device:

	npm1300_pmic: pmic@6b {
		compatible = "nordic,npm1300";
...
		npm1300_wdt: npm1300_wdt {
			compatible = "nordic,npm1300-wdt";
		};
...
	};

The devicetree node configures the following parameters:

Parameter	Value	Description

Parameter	Value	Description
`compatible`	`"nordic,npm1300-wdt"`	Enables the `wdt_npm1300.c` driver and associates it with the device.

3. Controlling nPM1300 Watchdog in User Application

3.1. nPM1300 Watchdog C-binding API

The Customized Asset Tracker v2 application implements the following C-binding helper API for nPM1300 watchdog, defined in watchdog_app.* files:

Function	Description	Comments
`int watchdog_init_and_start(void);`	Initialize and start application watchdog module.	Returns zero on success, otherwise a negative error code is returned.
`void watchdog_register_handler(watchdog_evt_handler_t evt_handler);`	Register handler to receive watchdog callback events.	`evt_handler` - a pointer to the watchdog event handler. Handler is de-registered if parameter is NULL. The library only allows for one event handler to be registered at a time. A passed in event handler in this function will overwrite the previously set event handler.
`void watchdog_stop_feed(int reason_id, void *user_data);`	Stop watchdog feed.	`reason_id` - reset reason ID that caused device reset; `user_data` - unused. Added for compatibility with task wdt. Calling this function will cause power cycle when the nPM1300 WDT timeout expires.

3.2. nPM1300 Watchdog Static Functions

The Customized Asset Tracker v2 application implements several static functions, which are used by the watchdog workqueue thread:

Function	Description	Comments
`static int watchdog_setup(void);`	This function is being called by SYS_INIT at Zephyr boot to initialize the watchdog thread.	Returns zero on success, otherwise a negative error code is returned.
`static void watchdog_disable_worker(struct k_work *work_desc);`	System workqueue handler, used to disable the nPM1300 watchdog.	`work_desc` - a pointer to the workqueue item calling the handler.
`static void watchdog_enable_worker(struct k_work *work_desc);`	System workqueue handler, used to enable the nPM1300 watchdog.	`work_desc` - a pointer to the workqueue item calling the handler.
`static void watchdog_feed_worker(struct k_work *work_desc);`	System workqueue handler, used to feed the nPM1300 watchdog.	`work_desc` - a pointer to the workqueue item calling the handler. Calls `wdt_feed()` with period specified by the `CONFIG_WATCHDOG_APPLICATION_FEED_PERIOD_MS` configuration parameter.
`static int watchdog_enable(const struct watchdog_config_storage config, struct watchdog_data_storage data);`	Configure and start nPM1300 watchdog.	Calls `watchdog_timeout_install()` to configure nPM1300 watchdog timeout specified by `CONFIG_WATCHDOG_APPLICATION_TIMEOUT_MS`, then starts the watchdog by calling `watchdog_start()`.
`static int watchdog_disable(const struct watchdog_config_storage *config);`	Disable the watchdog.	Calls `wdt_disable()` driver function to disable the watcdog.
`static int watchdog_start(const struct watchdog_config_storage *config);`	Start the watchdog.	Calls `wdt_setup()` driver function to start the watcdog.
`static int watchdog_timeout_install(const struct watchdog_config_storage config, struct watchdog_data_storage data);`	Configure the watchdog timeout.	Calls `wdt_install_timeout()` driver function to configure nPM1300 watchdog timeout specified by `CONFIG_WATCHDOG_APPLICATION_TIMEOUT_MS`, then starts the watchdog by calling `watchdog_start()`.

The static functions are defined in watchdog_app.c file and make use of the Zephyr watchdog driver API.

3.3. nPM1300 Watchdog Threads and Tasks

The Customized Asset Tracker v2 application implements a separate workqueue thread for nPM1300 operations, which prevents other threads from interfering with the watchdog initialization sequence and feed cycle. The watchdog workqueue thread operates in the following sequence:

SYS_INIT() initializes the watchdog workqueue thread by calling watchdog_init_and_start() at Zephyr boot.
The watchdog workqueue thread calls watchdog_enable_worker(), which calls configures and starts the watchdog by calling watchdog_timeout_install() and watchdog_start(). Watchdog timeout is specified by the CONFIG_WATCHDOG_APPLICATION_TIMEOUT_MS configuration parameter.
After initializing the watchdog, the workqueue thread periodically calls watchdog_feed_worker().
When watchdog_stop_feed() is called, the watchdog thread stops calling watchdog_feed_worker(), which in turn causes board reset performed by the nPM1300 PMIC.

3.4. nPM1300 Watchdog Shell Commands

The Customized Asset Tracker v2 application provides a set of Zephyr shell commands for nPM1300 watchdog, defined in the watchdog_app.c file:

Command	Comments
`watchdog enable`	Enable the watchdog.
`watchdog disable`	Disable the watchdog.
`watchdog status`	Prints watchdog status in the following format: `uart:~$ watchdog status Watchdog status: <enabled\|disabled> Watchdog stop requested: <yes\|no> Watchdog feed period: <feed period> ms Watchdog timeout: <timeout> ms` `<feed period>` is specified at build time by the `CONFIG_WATCHDOG_APPLICATION_FEED_PERIOD_MS` parameter at build time. `<timeout>` is specified at build time by the `CONFIG_WATCHDOG_APPLICATION_TIMEOUT_MS` parameter at build time. `Watchdog stop requested` indicates if the watcdog reset is pending.
`watchdog reset`	Stop feeding the watchdog. Calling this command will cause watchdog reset when the watchdog timeout expires.

4. Validating nPM1300 Watchdog Operations

From the SOM-NRF9151 serial console, issue the watchdog reset command and verify that the system has been reset by the PMIC WDT.
Issue the watchdog disable command to disable the PMIC WDT:
uart:~$ watchdog disable [00:00:46.817,230] <inf> watchdog: Disabling watchdog [00:00:46.817,749] <inf> watchdog: Watchdog disabled
Issue the watchdog status command to read PMIC WDT status:
uart:~$ watchdog status Watchdog status: disabled Watchdog stop requested: no Watchdog feed period: 2500 ms Watchdog timeout: 5000 ms
Issue the watchdog reset command and verify that the board is not being reset:
uart:~$ watchdog reset [00:01:28.096,984] <inf> watchdog: Reset command received, stopping watchdog feed [00:01:28.097,015] <err> watchdog: Watchdog disabled, stopping feed has no effect
Issue the watchdog enable command to enable the PMIC WDT:
uart:~$ watchdog enable [00:01:49.899,200] <inf> watchdog: Enabling watchdog [00:01:49.901,458] <inf> watchdog: Watchdog enabled
Issue the watchdog reset command and verify that the system has been reset by the PMIC WDT.

SOM-NRF9151

Using nPM1300 Watchdog