Sensor module

Important

The Asset Tracker v2 application is in maintenance mode. For new projects, it is recommended to use the Cellular: nRF Cloud multi-service sample instead.

The sensor module interacts with external sensors present on the Thingy:91 and Thingy:91 X. 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.

Thingy:91 X has a BME688 gas sensor and ADXL367 motion sensor that can be used by the Sensor module module.

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

An nRF91 Series DK does not have any external sensors and battery fuel gauge. 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. For battery fuel gauge data, SENSOR_EVT_FUEL_GAUGE_NOT_SUPPORTED is sent.

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

Note

Impact detection is not implemented for Thingy:91 X.

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. In the beginning, the IAQ shows 50 (good air), but it is automatically calibrated over time.

Note

Using the BSEC library requires accepting a separate license agreement. For details, see BME68X IAQ driver.

Perform the following steps to enable BSEC:

  1. To disable the Zephyr BME680 driver, set the CONFIG_BME680 Kconfig option to false.

  2. To enable the external sensors API BSEC integration layer, use the CONFIG_BME68X_IAQ Kconfig 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_BME68X_IAQ

This option configures the Bosch BSEC library for the BME680.

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 Zephyr API:

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
Sensor module event