/
Using nPM1300 Watchdog

Using nPM1300 Watchdog

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:

  1. SYS_INIT() initializes the watchdog workqueue thread by calling watchdog_init_and_start() at Zephyr boot.

  2. 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.

  3. After initializing the watchdog, the workqueue thread periodically calls watchdog_feed_worker().

  4. 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.