Understanding Customised Asset Tracker v2 Application
- Dmitry Starchenko
- Natalia Sofronova
1. Introduction
Asset Tracker v2 is a real-time configurable ultra-low power capable application firmware for the nRF91 Series System in Package (SiP). Emcraft develops a customized version of the Asset Tracker v2 application, which supports nRF9151 System-On-Module (SOM) Hardware Architecture and implements several additional features.
This document provides an overview of the overall application architecture and the differences between the original and customized versions of the application. For details about the original Asset Tracker v2 application refer to the Nordic documentation page.
2. Asset Tracker v2 Architecture
The following table provides a brief overview of the Asset Tracker v2 application architecture:
Module/API | Location in Source Tree | Description |
|---|---|---|
Application module |
| The application module an initial point of entry for the application and sends periodic sample requests to other modules in the system. |
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. |
Cloud module |
| The cloud module establishes and maintains the connection to a supported cloud service. It uses the Cloud wrapper API to integrate and handle the client libraries present in the nRF Connect SDK. |
Cloud wrapper API |
| The cloud wrapper API is a generic API used for controlling the connection to a supported nRF Connect SDK client library through Integration layers. It exposes generic functions such as |
Debug module |
| The debug module intends to improve the overall debugging experience in the application. By default, it subscribes to all the events in the system and implements support for Memfault through the Memfault module integrated in nRF Connect SDK. |
Location module |
| The location module controls the GNSS, cellular, and Wi-Fi® positioning functionality. It can be used to retrieve the location of the device in the form of events containing a position, velocity and time (PVT) structure. |
Modem module |
| The modem module communicates with the modem to control the LTE connection and retrieve information from the modem about the device and LTE network. |
Sensor module |
| The sensor module interacts with external sensors present on SOM-NRF95151. It collects environmental data and detects motion over a set threshold value. |
External sensors API |
| The External sensors API is used to configure external sensors and collect sensor readings. |
User Interface and LED modules |
| The User Interface and LED modules handle events from the UI (buttons, LEDs) elements on SOM-NRF95151. |
Utility module |
| The utility module provides the functionality to administer and monitor mechanisms in the application architecture. |
Modules common API |
| The Modules common API provides the functionality to administer mechanisms in the application architecture, and consist of functions that are shared between modules. |
Unit tests |
| Unit tests, applicable to a set of Asset Tracker v2 modules. |
Watchdog |
| Watchdog module. |
Events |
| Source files that declare events, which are used by other application modules. |
Add-ons |
| Various add-ons that implement support for nPM1300 PMIC, LPS22HH and LIS2DW12 sensors, RTC, etc. Refer to Understanding Customised Asset Tracker v2 Application | 4. New Features of the Customised Asset Tracker v2 Application for details |
Application Configuration |
| Various configuration files and overlays for Asset Tracker v2 application. |
MCUboot Configuration |
| Subdirectory containing configuration files and devicetree overlays for MCUboot bootloader. |
Memfault Configuration |
| Configuration files used to integrate Memfault SDK into the Asset Tracker v2 application. |
3. Changes in the Customised Asset Tracker v2 Application
3.1. Real-time Configurations
The default configuration has been modified to lower the device power consumption and reduce frequency of cloud data transfers.
The real-time configurations supported by the application are listed in the following table:
Real-time Configurations | Description | Default values | |
|---|---|---|---|
Device mode | Either in active or passive mode. | Passive | |
Active |
| Cloud updates occur at regular intervals. |
|
Active wait time | Number of seconds between each cloud update in active mode. | 300 seconds | |
Passive |
| Cloud updates occur upon movement. |
|
Movement resolution | Number of seconds between each cloud update in passive mode, given that the device is moving. | 1800 seconds | |
Movement timeout | Number of seconds between each cloud update in passive mode, regardless of movement. | 7200 seconds | |
Location timeout | Timeout for location retrieval during data sampling. This value should be large enough so that the location can be retrieved in different conditions. This can be considered more of a safeguard rather than the deadline when the operation must be completed. Hence, this value can be larger than the sampling interval. | 300 seconds | |
Accelerometer activity threshold | Accelerometer activity threshold in g. Minimal absolute value for accelerometer readings to be considered valid movement. | 4 g | |
Accelerometer inactivity threshold | Accelerometer inactivity threshold in g. Maximal absolute value for accelerometer readings to be considered stillness. | 4 g | |
Accelerometer inactivity timeout | Accelerometer inactivity timeout in seconds. Minimum time for lack of movement to be considered stillness. | 60 seconds | |
No Data List (NOD) | A list of strings that references data types, which will not be sampled by the application. Used to disable sampling from sensor sources. For instance, when GNSS should be disabled in favor of location based on neighbor cell measurements, the string identifier | No entries (Request all) | |
It can be altered at compile time by setting the options listed in Default device configuration options or at run time through through the cloud service.
3.2. Watchdog Module
The modified watchdog module controls the nPM1300 WDT instead of the internal WDT. The module configures a separate work queue to prevent other work items in the system work queue from interfering with the watchdog.
For details refer to Using nPM1300 Watchdog.
3.3. Sensor Module and External Sensors
The sensor module and external sensors code are modified to support the LPS22HH and LIS2DW12 sensors present on SOM-NRF9151-BSB and nPM1300 PMIC on SOM-NRF9151.
src/modules/sensor_module.cis modified to configure the barometer threshold trigger and gather the nPM1300 State of Charge (SoC) readings in addition to other sensor data onAPP_EVT_DATA_GETevent.src/ext_sensors/ext_sensors.*files have been modified to configure the LIS2DW12 accelerometer threshold using g units instead of m/s2.
For details refer to the following Application Notes:
Using nPM1300 Battery Charger and Power Rails
Using LPS22HH and LIS2DW12 Sensors
3.4. UI and LED Modules
The UI and LED modules have been modified to handle the User Button events and send the button data to the cloud service and control the LEDs installed on SOM-NRF9151-BSB on button events.
For details refer to Controlling User Buttons and LEDs .
4. New Features of the Customised Asset Tracker v2 Application
4.1. nPM1300 PMIC Support
The customized Asset Tracker v2 application implements API and Shell commands to control the nPM1300 PMIC and handle PMIC events.
The majority of the PMIC-related source code is located in src/addons/pmic. The src/events/pmic_module_event.c and src/events/pmic_module_event.h files declare PMIC events that are distributed by the Application Event Manager and handled by other modules.
The API also allows the application to collect the battery level data and send it to the cloud service.
For details refer to the following Application Notes:
Using nPM1300 Battery Charger and Power Rails
4.2. LPS22HH and LIS2DW12 Sensors Support
The customized Asset Tracker v2 application implements API and Shell commands to control the LPS22HH and LIS2DW12 sensors present on SOM-NRF9151-BSB.
The sensors-related source code is located in src/addons/sensors.
For details refer to Using LPS22HH and LIS2DW12 Sensors .
4.3. PCF85263A RTC Support
The application implements API and Shell commands to control the PCF85263A RTC, which includes setting and reading RTC time and alarm.
For details refer to Using RTC PCF85263A .
4.4. GPIO Shell
The GPIO shell, combined with the modified GPIO driver, allows the user to read the GPIO IRQ counters with gpio_interrupt command:
uart:~$ gpio_interrupt <GPIO port.number>This command is useful for debugging various GPIO interrupts.
The GPIO shell source code is located in src/addons/gpio_shell.c.
4.5. Location Shell
The application implements a set of location shell commands, which can be used to trigger or cancel location requests from the serial console.
The location shell source code is located in src/addons/location_shell.c.
For details refer to Using nRF9151 GNSS Module.