The utility module provides the functionality to administer and monitor mechanisms in the application architecture.
This section documents the various features implemented by the module.
When an irrecoverable error or a successful FOTA update is reported to the utility module, it initiates a shutdown sequence and ensures a graceful shutdown of the application.
During initialization, each module registers if it supports graceful shutdown.
This is done by calling the
module_start() function in the Modules common API and passing a configuration value in the
module_data structure for each module that registers for graceful shutdown.
This then expands an internal list in the Modules common API.
The typical chain of events that completes the shutdown sequence is as follows:
A module detects an irrecoverable error and sends an event carrying the associated error code. This event name is typically the module name suffixed with
EVT_ERROR. For example,
The utility module receives the error event and starts a reboot timer that times out after the duration specified by the CONFIG_REBOOT_TIMEOUT option. When this timer expires, the application reboots in any case.
The utility module sends out a shutdown request,
UTIL_EVT_SHUTDOWN_REQUEST, that is handled individually by each module in the system that supports shutdown.
When each module has handled the shutdown request, it acknowledges the shutdown by sending an event suffixed with
EVT_SHUTDOWN_READY. For example,
When the utility module receives a shutdown acknowledgment, for each incoming shutdown acknowledgment, the aforementioned list in the Modules common API is checked using
modules_shutdown_register(). When all the modules in the list have acknowledged the request, the utility module reboots the application at a much earlier point than the time set initially by the reboot timer.
The module implements a watchdog library that monitors the system workqueue using the Zephyr Watchdog driver.
To configure the watchdog timeout that is used, set the CONFIG_WATCHDOG_APPLICATION_TIMEOUT_SEC Kconfig option.
The header file of the library is located at
If the watchdog is not fed within the timeout indicated by CONFIG_WATCHDOG_APPLICATION_TIMEOUT_SEC, a watchdog timeout occurs, causing a reboot that is initiated by the watchdog peripheral hardware unit on the nRF9160 DK. The watchdog library is set up to feed the Zephyr Watchdog driver with the system workqueue constantly at a time interval that equals half of the value specified by CONFIG_WATCHDOG_APPLICATION_TIMEOUT_SEC. This means that if the watchdog timeout is set to 60 seconds, the system workqueue feeds the watchdog every 30 seconds. A reboot caused by a watchdog timeout occurs if the system workqueue is blocked and it is unable to feed the watchdog.
You can set the following options to configure the utility module:
- CONFIG_REBOOT_TIMEOUT - Utility module reboot timeout
This option specifies the timeout within which the utility module initiates a reboot, after an irrecoverable error has been reported to the module. However, if all modules acknowledge the utility module’s shutdown request before this timeout expires, the reboot occurs earlier.
- CONFIG_WATCHDOG_APPLICATION - Enable the application watchdog
This option enables the application watchdog timer.
- CONFIG_WATCHDOG_APPLICATION_TIMEOUT_SEC - Application watchdog timeout
This option specifies the watchdog timeout.
This module has no internal states.
asset_tracker_v2/src/events/util_module_event.h header file contains a list of various events sent by the module.
This module uses the following nRF Connect SDK libraries and drivers:
- group util_module_event
Util module event.
Event types submitted by the utility module.
Shutdown request sent to all modules in the system upon an irrecoverable error or finished FOTA update. It is expected that each module performs the necessary shutdown routines and reports back upon this event.
- enumerator UTIL_EVT_SHUTDOWN_REQUEST
- #include <util_module_event.h>
Utility module event.
- enum util_module_event_type