Application module

The application module controls key mechanisms in the Asset Tracker v2. It decides when to sample data, what types of data to sample, and has explicit control over some aspects of the application.

Features

This section documents the features implemented by the module.

Sample requests

Depending on the application’s Real-time configurations, the application module sends periodic sample requests to other modules in the system. The sample requests are of type APP_EVT_DATA_GET and contains a list of Data types that must be sampled by the corresponding module. Each module handles the sample requests individually and if a module finds its corresponding data type in the list, it starts sampling for that particular data type. For instance, if the GNSS module finds the APP_DATA_GNSS data type, it starts searching for a GNSS fix. Some modules even support multiple data types, such as the Modem module, which supports APP_DATA_MODEM_STATIC, APP_DATA_MODEM_DYNAMIC, APP_DATA_MODEM_BATTERY, and APP_DATA_NEIGHBOR_CELLS. In addition to the sample list, the module also includes a sample timeout in the APP_EVT_DATA_GET event. This timeout sets how much time each module has to sample data before the Data module sends what is available.

Note

Sample requests are sent either periodically or upon detection of movement. The timeouts and modes that have an impact on the frequency of sample requests are documented in Real-time configurations.

Application start

The application module is the system’s initial point of entry and the source file of the module is asset_tracker_v2/src/main.c. When the application boots, the module initializes the Application Event Manager and sends out the initial event APP_EVT_START that starts the rest of the modules in the application. It also initializes the Common Application Framework overview by calling the module_set_state() API with the MODULE_STATE_READY state.

Configuration options

CONFIG_APP_REQUEST_GNSS_ON_INITIAL_SAMPLING

This option is used to include GNSS in the initial sample request sent from the module.

CONFIG_APP_REQUEST_GNSS_WAIT_FOR_AGPS

If this option is enabled, the application module waits for a configured number of seconds set by CONFIG_APP_REQUEST_GNSS_WAIT_FOR_AGPS_THRESHOLD_SEC before requesting GNSS data, unless A-GPS data has been processed.

CONFIG_APP_REQUEST_GNSS_WAIT_FOR_AGPS_THRESHOLD_SEC

Number of seconds that the application module waits for A-GPS data to be processed before requesting GNSS data. If set to -1, the application module waits until A-GPS data has been processed.

CONFIG_APP_REQUEST_NEIGHBOR_CELLS_DATA

Include LTE neighbor cell measurement data in regular sampling requests. The data will be encoded together with the other sampled data and sent to cloud, where it can be used to determine the device’s location.

Module states

The application module has an internal state machine with the following states:

• STATE_INIT - The initial state of the module.

• STATE_RUNNING - The module has receieved its initial configuration from the data module and has started the appropriate timers.

  • SUB_STATE_ACTIVE_MODE - The application is in the active mode. In this state, the module sends out sample requests periodically.

  • SUB_STATE_PASSIVE_MODE - The application is in the passive mode. In this state, the module sends out a sample request upon movement.

• STATE_SHUTDOWN - The module has been shut down after receiving a request from the utility module.

Module events

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

Dependencies

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

• Application Event Manager

• Modem library integration layer

• Common Application Framework overview

API documentation

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

Source files: asset_tracker_v2/src/events/app_module_event.c, asset_tracker_v2/src/main.c

group app_module_event

Application module event.

Enums

enum app_module_event_type

Event types submitted by Application module.

Values:

enumerator APP_EVT_START

Signal that the application has done necessary setup, and now started.

enumerator APP_EVT_LTE_CONNECT

Connect to LTE network.

enumerator APP_EVT_LTE_DISCONNECT

Disconnect from LTE network.

enumerator APP_EVT_DATA_GET

Signal other modules to start sampling and report the data when it’s ready. The event must also contain a list with requested data types, app_module_data_type.

enumerator APP_EVT_DATA_GET_ALL

Create a list with all available sensor types in the system and distribute it as a APP_EVT_DATA_GET event.

enumerator APP_EVT_CONFIG_GET

Request latest configuration from the cloud.

enumerator APP_EVT_ACTIVITY_DETECTION_ENABLE

Application module is waiting for movement to trigger the next sample request. This event is used to signal the sensor module to enable activity detection.

enumerator APP_EVT_ACTIVITY_DETECTION_DISABLE

Application module does not depend on activity detection. This event is used to signal the sensor module to disable activity detection.

enumerator APP_EVT_AGPS_NEEDED

The application module needs A-GPS to be processed before it requests GNSS.

enumerator APP_EVT_SHUTDOWN_READY

The application module has performed all procedures to prepare for a shutdown of the system.

enumerator APP_EVT_ERROR

An irrecoverable error has occurred in the application module. Error details are attached in the event structure.

enum app_module_data_type

Data types that the application module requests samples for in app_module_event_type APP_EVT_DATA_GET.

Values:

enumerator APP_DATA_ENVIRONMENTAL

enumerator APP_DATA_MOVEMENT

enumerator APP_DATA_MODEM_STATIC

enumerator APP_DATA_MODEM_DYNAMIC

enumerator APP_DATA_BATTERY

enumerator APP_DATA_GNSS

enumerator APP_DATA_NEIGHBOR_CELLS

enumerator APP_DATA_COUNT

struct app_module_event

#include <app_module_event.h>

Application module event.

Public Members

int err

Code signifying the cause of error.

int timeout

The time each module has to fetch data before what is available is transmitted.