Utility module

The utility module provides the functionality to administer and monitor mechanisms in the application architecture.

Features

This section documents the various features implemented by the module.

Application Shutdown

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:

1. 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, CLOUD_EVT_ERROR.

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

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

4. When each module has handled the shutdown request, it acknowledges the shutdown by sending an event suffixed with EVT_SHUTDOWN_READY. For example, CLOUD_EVT_SHUTDOWN_READY.

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

Watchdog

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 asset_tracker_v2/src/watchdog/watchdog_app.h.

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 nRF91 Series 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.

Configuration options

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.

Module states

This module has no internal states.

Module events

The asset_tracker_v2/src/events/util_module_event.h header file contains a list of various events sent by the module.

Dependencies

This module uses the following nRF Connect SDK libraries and drivers:

• Application Event Manager

• asset_tracker_v2/src/watchdog/watchdog_app.h

API documentation

Header file: asset_tracker_v2/src/events/util_module_event.h

Source files: asset_tracker_v2/src/events/util_module_event.c, asset_tracker_v2/src/modules/util_module.c

group util_module_event

Util module event.

Enums

enum util_module_event_type

Event types submitted by the utility module.

Values:

enumerator UTIL_EVT_SHUTDOWN_REQUEST

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.

enum shutdown_reason

Shutdown reason included in shutdown requests from the utility module.

Values:

enumerator REASON_GENERIC

Generic reason, typically an irrecoverable error.

enumerator REASON_FOTA_UPDATE

The application shuts down because a FOTA update finished.

struct util_module_event

#include <util_module_event.h>

Utility module event.

Public Members

struct app_event_header header

Utility module application event header.

enum util_module_event_type type

Utility module event type.

enum shutdown_reason reason

Variable that contains the reason for the shutdown request.