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

Air Quality (BSEC only)

BME680

Acceleration (Activity)

ADXL362

Acceleration (Impact)

ADXL372

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 activity detection

Motion activity is detected when acceleration in either X, Y or Z plane exceeds the configured activity threshold value. Stillness is detected when the acceleration is less than the configured inactivity threshold value for the duration of the inactivity time. The threshold values are set in one of the following two ways:

Both events contain upper and lower accelerometer threshold values accelerometer_activity_threshold and accelerometer_inactivity_threshold in m/s2, present in the event structure. Further, they contain a timeout value accelerometer_inactivity_timeout in seconds.

Motion detection is enabled and disabled according to the device mode parameter, received in the configuration events. It is enabled in the passive mode and disabled in the active mode. Data sampling requests are sent out both on activity events and inactivity events.

The sensor module sends out a SENSOR_EVT_MOVEMENT_ACTIVITY_DETECTED event if it detects movement. Similarly, SENSOR_EVT_MOVEMENT_INACTIVITY_DETECTED is sent out if there is no movement within the configured timeout.

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.

Motion impact detection

Motion impact is detected when the magnitude (root sum squared) of acceleration exceeds the configured threshold value. To enable motion impact detection, you must include CONFIG_EXTERNAL_SENSORS_IMPACT_DETECTION and CONFIG_ADXL372 when building the application.

The threshold is configured using the CONFIG_ADXL372_ACTIVITY_THRESHOLD option. The accelerometer records acceleration magnitude when it is in the active mode and reports the peak magnitude once it reverts to the inactive mode. The accelerometer changes to active mode when the activity threshold is exceeded and reverts to inactive mode once acceleration stays below CONFIG_ADXL372_INACTIVITY_THRESHOLD for the duration specified in the CONFIG_ADXL372_INACTIVITY_TIME option.

When an impact has been detected, a SENSOR_EVT_MOVEMENT_IMPACT_DETECTED event is sent from the sensor module.

Bosch Software Environmental Cluster (BSEC) library

The sensor module supports integration with the BSEC signal processing library using the external sensors, internal convenience API. If enabled, the BSEC library is used instead of the BME680 Zephyr driver to provide sensor readings from the BME680 for temperature, humidity, and atmospheric pressure. In addition, the BSEC driver provides an additional sensor reading, indoor air quality (IAQ), which is a metric given in between 0-500 range, which estimates the air quality of the environment.

As the BSEC library requires a separate license, it is not a default part of nRF Connect SDK, but can be downloaded externally and imported into the nRF Connect SDK source tree.

Perform the following steps to enable BSEC:

  1. Download the BSEC library, using the Bosch BSEC link.

  2. Extract and store the folder containing the library contents in the path specified by CONFIG_EXTERNAL_SENSORS_BME680_BSEC_PATH option or update the path configuration to reference the library location.

  3. Disable the Zephyr BME680 driver by setting CONFIG_BME680 to false.

  4. Enable the external sensors API BSEC integration layer by enabling CONFIG_EXTERNAL_SENSORS_BME680_BSEC option.

Air quality readings are provided with the SENSOR_EVT_ENVIRONMENTAL_DATA_READY event.

To check and configure the BSEC configuration options, see External sensors API BSEC configurations section.

Configuration options

CONFIG_SENSOR_THREAD_STACK_SIZE - Sensor module thread stack size

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

CONFIG_EXTERNAL_SENSORS_IMPACT_DETECTION

This configuration option enables the impact detection feature.

External sensors API BSEC configurations

CONFIG_EXTERNAL_SENSORS_BME680_BSEC

This option configures the Bosch BSEC library for the BME680.

CONFIG_EXTERNAL_SENSORS_BME680_BSEC_PATH

This option sets the path for the Bosch BSEC library folder.

CONFIG_EXTERNAL_SENSORS_BSEC_SAMPLE_MODE_ULTRA_LOW_POWER

This option configures the BSEC ultra Low Power Mode. In this mode, the BME680 is sampled every 300 seconds.

CONFIG_EXTERNAL_SENSORS_BSEC_SAMPLE_MODE_LOW_POWER

This option configures BSEC Low Power Mode. In this mode, the BME680 is sampled every 3 seconds.

CONFIG_EXTERNAL_SENSORS_BSEC_SAMPLE_MODE_CONTINUOUS

This option configures BSEC continuous Mode. In this mode, the BME680 is sampled every second.

CONFIG_EXTERNAL_SENSORS_BSEC_TEMPERATURE_OFFSET

This option configures BSEC temperature offset in degree Celsius multiplied by 100.

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 configuration 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:

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_ACTIVITY_DETECTED

Accelerometer reported activity. Acceleration exceeded the configured activity threshold.

enumerator SENSOR_EVT_MOVEMENT_INACTIVITY_DETECTED

Accelerometer reported inactivity. Acceleration stayed below the threshold for a given time.

enumerator SENSOR_EVT_MOVEMENT_IMPACT_DETECTED

Impact detected. Payload is of type sensor_module_data (impact).

enumerator SENSOR_EVT_ENVIRONMENTAL_DATA_READY

Environmental sensors have 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.

int bsec_air_quality

BSEC air quality in Indoor-Air-Quality (IAQ) index. If -1, the value is not provided.

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_impact_data
#include <sensor_module_event.h>

Structure used to provide impact data.

Public Members

int64_t timestamp

Uptime when the data was sampled.

double magnitude

Acceleration on impact, measured in G.

struct sensor_module_event
#include <sensor_module_event.h>

Sensor module event.

Public Members

struct app_event_header header

Sensor module application 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.

struct sensor_module_impact_data impact

Variable that contains impact data.

uint32_t id

Module ID, used when acknowledging shutdown requests.

int err

Code signifying the cause of error.