Data module

The data module gathers data that has been sampled by other modules in the system and stores it into ring buffers. It keeps track of data requested by the Application module and decides when data is sent to the cloud.

Features

This section documents the features implemented by the module.

Requested data types

The data module maintains a list of requested data types that is updated every time a sample request of type APP_EVT_DATA_GET is sent from the Application module. When all the data types present in the list is received by the module, the event DATA_EVT_DATA_READY is sent out. This event signifies that all data has been gathered for a sample request. The available data can now be encoded and sent to the cloud. The APP_EVT_DATA_GET event also carries a sample timeout. This timeout is used by the data module to trigger a DATA_EVT_DATA_READY event, even if not all types in the requested list have been received. This acts as a fail-safe in case some modules do not manage to sample the requested data in time. For example, it is not always possible to acquire a GNSS fix.

Note

The module can decide not to send data after a sample request. If this happens, data is persisted in the ring buffers and sent to the cloud in batch messages after the next sample request, in case the application is connected to the cloud. The ring buffers in the module are implemented so that the oldest entry is always overwritten in case the buffer is filled.

Device configuration

When the application boots, the data module distributes the current values of the applications Real-time configurations to the rest of the application with the DATA_EVT_CONFIG_INIT event. These value are persisted in flash between reboots using the Settings and updated each time the application receives a new configuration update. If a new configuration update is received from the cloud, the data module distributes the new configuration values using the DATA_EVT_CONFIG_READY event. You can alter the default values of the Real-time configurations compile time using the options listed in the Default device configuration options.

Connection evaluation

This is an experimental feature. The module can decide to hold off encoding and sending of sampled data based on evaluation of the LTE connection and estimated energy consumed to send the data. This feature is enabled by setting the CONFIG_DATA_GRANT_SEND_ON_CONNECTION_QUALITY Kconfig option. The module can deny the sending of data a number of times before it is sent regardless. This limit is configurable and set by the CONFIG_DATA_SEND_ATTEMPTS_COUNT_MAX Kconfig option. This feature is supported for regular updates that include neighbor cell measurements, generic (GNSS, sensor data, and so on), and historical batched data, which are scheduled based on the application’s Real-time configurations.

To adjust the minimum allowed energy threshold for a specific type, set the following Kconfig options:

• CONFIG_DATA_GENERIC_UPDATES_ENERGY_THRESHOLD_MIN

• CONFIG_DATA_NEIGHBOR_CELL_UPDATES_ENERGY_THRESHOLD_MIN

• CONFIG_DATA_BATCH_UPDATES_ENERGY_THRESHOLD_MIN

The energy levels map directly to the LTE link control structure lte_lc_energy_estimate and the current energy level that is evaluated before sending of data is retrieved with the lte_lc_conn_eval_params_get() function call.

Configuration options

Options that alter the default values of the application’s real-time configurations:

CONFIG_DATA_DEVICE_MODE_ACTIVE

This configuration sets the device in active mode. Default mode for nRF91 Series devices.

CONFIG_DATA_DEVICE_MODE_PASSIVE

This configuration sets the device in passive mode. Default mode for the Thingy:91.

CONFIG_DATA_ACTIVE_TIMEOUT_SECONDS

This configuration sets the active mode timeout value.

CONFIG_DATA_MOVEMENT_RESOLUTION_SECONDS

This configuration sets the movement resolution timeout value.

CONFIG_DATA_MOVEMENT_TIMEOUT_SECONDS

This configuration sets the movement timeout value.

CONFIG_DATA_ACCELEROMETER_ACT_THRESHOLD

This configuration sets the upper accelerometer threshold value.

CONFIG_DATA_ACCELEROMETER_INACT_THRESHOLD

This configuration sets the lower accelerometer threshold value.

CONFIG_DATA_ACCELEROMETER_INACT_TIMEOUT_SECONDS

This configuration sets a timeout in seconds after which the accelerometer reports inactivity.

CONFIG_DATA_LOCATION_TIMEOUT_SECONDS

This configuration sets the location timeout value.

CONFIG_DATA_SAMPLE_GNSS_DEFAULT

This configuration includes GNSS during sampling. Enabled by default.

CONFIG_DATA_SAMPLE_NEIGHBOR_CELLS_DEFAULT

This configuration includes neighbor cell measurements during sampling. Enabled by default.

CONFIG_DATA_SAMPLE_WIFI_DEFAULT

This configuration includes Wi-Fi APs during sampling. Enabled by default.

Other options:

CONFIG_DATA_GRANT_SEND_ON_CONNECTION_QUALITY

Grants or denies encoding and sending of data based on LTE connection quality.

CONFIG_DATA_SEND_ATTEMPTS_COUNT_MAX

Maximum number of times sending can be denied due to connection quality before the data is sent regardless.

CONFIG_DATA_GENERIC_UPDATES_ENERGY_THRESHOLD_MIN

Minimum energy threshold for generic updates.

CONFIG_DATA_NEIGHBOR_CELL_UPDATES_ENERGY_THRESHOLD_MIN

Minimum energy threshold for neighbor cell updates.

CONFIG_DATA_BATCH_UPDATES_ENERGY_THRESHOLD_MIN

Minimum energy threshold for batch updates.

Module states

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

• STATE_CLOUD_DISCONNECTED - Cloud is disconnected. Data transmission is not attempted.

• STATE_CLOUD_CONNECTED - Cloud is connected. Data transmission is attempted.

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

Module events

The asset_tracker_v2/src/events/data_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

• nRF Cloud A-GNSS

• nRF Cloud P-GPS

• Settings

API documentation

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

Source files: asset_tracker_v2/src/events/data_module_event.c, asset_tracker_v2/src/modules/data_module.c

group data_module_event

Data module event.

Enums

enum data_module_event_type

Data event types submitted by Data module.

Values:

enumerator DATA_EVT_DATA_READY

All data has been received for a given sample request.

enumerator DATA_EVT_DATA_SEND

Send newly sampled data. The event has an associated payload of type data_module_data_buffers in the data.buffer member.

If a non LwM2M build is used the data is heap allocated and must be freed after use by calling k_free() on data.buffer.buf.

enumerator DATA_EVT_DATA_SEND_BATCH

Send older batched data. The event has an associated payload of type data_module_data_buffers in the data.buffer member.

If a non LwM2M build is used the data is heap allocated and must be freed after use by calling k_free() on data.buffer.buf.

enumerator DATA_EVT_UI_DATA_SEND

Send UI button data. The event has an associated payload of type data_module_data_buffers in the data.buffer member.

If a non LwM2M build is used the data is heap allocated and must be freed after use by calling k_free() on data.buffer.buf.

enumerator DATA_EVT_UI_DATA_READY

UI button data is ready to be sent.

enumerator DATA_EVT_IMPACT_DATA_READY

Impact data is ready to be sent.

enumerator DATA_EVT_IMPACT_DATA_SEND

Send impact data, similar to DATA_EVT_UI_DATA_SEND

enumerator DATA_EVT_CLOUD_LOCATION_DATA_SEND

Send cloud location data. The event has an associated payload of type data_module_data_buffers in the data.buffer member.

If a non LwM2M build is used the data is heap allocated and must be freed after use by calling k_free() on data.buffer.buf.

enumerator DATA_EVT_CONFIG_INIT

Send the initial device configuration. The event has an associated payload of type cloud_data_cfg in the data.cfg member.

enumerator DATA_EVT_CONFIG_READY

Send the updated device configuration. The event has an associated payload of type cloud_data_cfg in the data.cfg member.

enumerator DATA_EVT_CONFIG_SEND

Acknowledge the applied device configuration to cloud. The event has an associated payload of type data_module_data_buffers in the data.buffer member.

If a non LwM2M build is used the data is heap allocated and must be freed after use by calling k_free() on data.buffer.buf.

enumerator DATA_EVT_CONFIG_GET

Get the recent device configuration from cloud.

enumerator DATA_EVT_DATE_TIME_OBTAINED

Date time has been obtained.

enumerator DATA_EVT_SHUTDOWN_READY

The data module has performed all procedures to prepare for a shutdown of the system. The event carries the ID (id) of the module.

enumerator DATA_EVT_ERROR

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

struct data_module_data_buffers

#include <data_module_event.h>

Structure that contains a pointer to encoded data.

Public Members

struct lwm2m_obj_path paths[CONFIG_CLOUD_CODEC_LWM2M_PATH_LIST_ENTRIES_MAX]

Object paths used in lwM2M. NULL terminated.

struct data_module_event

#include <data_module_event.h>

Data module event.

Public Members

struct app_event_header header

Data module application event header.

enum data_module_event_type type

Data module event type.

struct data_module_data_buffers buffer

Variable that carries a pointer to data encoded by the module.

struct cloud_data_cfg cfg

Variable that carries the current device configuration.

uint32_t id

Module ID, used when acknowledging shutdown requests.

int err

Code signifying the cause of error.