Sensor module

The sensor module interacts with external sensors present on the Thingy:91. It collects environmental data and detects motion over a set threshold value.

Features

This section documents the various features implemented by the module.

Sensor types

The following table lists the sensors and sensor data types supported by the module:

Sensor data type	External device
Humidity	BME680
Temperature	BME680
Atmospheric Pressure	BME680
Acceleration	ADXL362

The module controls and collects data from the sensors by interacting with their device drivers using Zephyr’s generic sensor API.

Data sampling

When the module receives an APP_EVT_DATA_GET event and the APP_DATA_ENVIRONMENTAL type is present in the app_data list carried in the event, it will sample data. When data sampling has been carried out, the SENSOR_EVT_ENVIRONMENTAL_DATA_READY event is sent from the module with the sampled environmental sensor values.

Note

The nRF9160 DK does not have any external sensors. If the sensor module is queried for sensor data when building for the DK, the event SENSOR_EVT_ENVIRONMENTAL_NOT_SUPPORTED is sent out by the module upon data sampling.

Motion detection

Motion is detected when acceleration in either X, Y or Z plane exceeds the configured threshold value. The threshold is set in one of the following two ways:

• When receiving the DATA_EVT_CONFIG_INIT event after boot. This event contains the default threshold value set by CONFIG_DATA_ACCELEROMETER_THRESHOLD or retrieved from flash.

• When receiving the DATA_EVT_CONFIG_READY event. This occurs when a new threshold value has been updated from cloud.

Both events contain an accelerometer threshold value accelerometer_threshold in m/s2, present in the event structure.

Motion detection in the module is enabled and disabled in turn to control the number of SENSOR_EVT_MOVEMENT_DATA_READY events that are sent out by the sensor module. This functionality acts as flow control. It prevents the sensor module from sending events to the rest of the application if the device is accelerating over the threshold for extended periods of time.

The applicaton module controls this behavior through the APP_EVT_ACTIVITY_DETECTION_ENABLE and APP_EVT_ACTIVITY_DETECTION_DISABLE events. The sensor module will only send out a SENSOR_EVT_MOVEMENT_DATA_READY event if it detects movement and activity detection is enabled.

Note

The DK does not have an external accelerometer. However, you can use Button 2 on the DK to trigger movement for testing purposes.

Note

The accelerometer available on the Thingy:91 needs detailed tuning for each use case to determine reliably which readings are considered as motion. This is beyond the scope of the general asset tracker framework this application provides. Therefore, the readings are not transmitted to the cloud and are only used to detect a binary active and inactive state.

Configuration options

CONFIG_SENSOR_THREAD_STACK_SIZE - Sensor module thread stack size

This option configures the sensor module’s internal thread stack size.

Module states

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

• STATE_INIT - The initial state of the module in which it awaits its initial configuation from the data module.

• STATE_RUNNING - The module is initialized and can be queried for sensor data. It will also send SENSOR_EVT_MOVEMENT_DATA_READY on movement.

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

State transitions take place based on events from other modules, such as the app module, data module, and utility module.

Module events

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

• Generic sensor API

• ADXL362: Three Axis Accelerometer

• BME680: Integrated environmental sensor

API documentation

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

Source files: asset_tracker_v2/src/events/sensor_module_event.c asset_tracker_v2/src/modules/sensor_module.c

group sensor_module_event

Sensor module event.

Defines

ACCELEROMETER_AXIS_COUNT

Enums

enum sensor_module_event_type

Sensor event types submitted by the Sensor module.

Values:

enumerator SENSOR_EVT_MOVEMENT_DATA_READY

Motion detected. Acceleration of the device has exceeded the configured threshold. Payload is of type sensor_module_accel_data (accel). The associated acceleration values contains the motion that caused the device to exceed the configured threshold.

enumerator SENSOR_EVT_ENVIRONMENTAL_DATA_READY

Environmental sensors has been sampled. Payload is of type sensor_module_data (sensors).

enumerator SENSOR_EVT_ENVIRONMENTAL_NOT_SUPPORTED

Environmental sensors are not supported on the current board.

enumerator SENSOR_EVT_SHUTDOWN_READY

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

enumerator SENSOR_EVT_ERROR

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

struct sensor_module_data

#include <sensor_module_event.h>

Structure used to provide environmental data.

Public Members

int64_t timestamp

Uptime when the data was sampled.

double temperature

Temperature in Celsius degrees.

double humidity

Humidity in percentage.

double pressure

Atmospheric pressure in kilopascal.

struct sensor_module_accel_data

#include <sensor_module_event.h>

Structure used to provide acceleration data.

Public Members

int64_t timestamp

Uptime when the data was sampled.

double values[3]

Acceleration in X, Y and Z planes in m/s2.

struct sensor_module_event

#include <sensor_module_event.h>

Sensor module event.

Public Members

struct event_header header

Sensor module event header.

enum sensor_module_event_type type

Sensor module event type.

struct sensor_module_data sensors

Variable that contains sensor readings.

struct sensor_module_accel_data accel

Variable that contains acceleration data.

uint32_t id

Module ID, used when acknowledging shutdown requests.

int err

Code signifying the cause of error.