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	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 the CONFIG_DATA_ACCELEROMETER_THRESHOLD option 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.

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, that 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_DATA_ACCELEROMETER_THRESHOLD

This configuration sets the accelerometer threshold value.

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

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

uint32_t id

Module ID, used when acknowledging shutdown requests.

int err

Code signifying the cause of error.