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.

Note

The data module will undergo substantial refactoring soon. Hence, some of its features are not currently documented.

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.

Configuration options

CONFIG_DATA_DEVICE_MODE

This configuration sets the device mode.

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_THRESHOLD

This configuration sets the accelerometer threshold value.

CONFIG_DATA_GNSS_TIMEOUT_SECONDS

This configuration sets the GNSS timeout value.

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:

• Event Manager

• nRF Cloud A-GPS

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

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.

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.

enumerator DATA_EVT_UI_DATA_READY

UI button data is ready to be sent.

enumerator DATA_EVT_NEIGHBOR_CELLS_DATA_SEND

Send neighbor cell measurements. The event has an associated payload of type data_module_data_buffers in the data.buffer member.

enumerator DATA_EVT_AGPS_REQUEST_DATA_SEND

Send A-GPS request. The event has an associated payload of type data_module_data_buffers in the data.buffer member.

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.

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.

struct data_module_event

#include <data_module_event.h>

Data module event.

Public Members

struct event_header header

Data module 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.