Application description

The Asset Tracker v2 application is built on the following principles:

  • Ultra-low power by design - The application highlights the power saving features of the nRF9160 SiP, which is critical for successfully developing small form-factor devices and products which need very long battery lifetime.

  • Offline first - Highly-mobile cellular IoT products need to handle unreliable connections gracefully by implementing mechanisms to retry the failed sending of data.

  • Timestamping on the device - Sensor data is timestamped on the device using multiple time sources. When the device is offline (planned or unplanned), the timestamping does not rely on the cloud side.

  • Batching of data - Data is batched to reduce the number of messages transmitted, and to be able to retain collected data while the device is offline.

  • Configurable at run time - The application behavior (for example, accelerometer sensitivity or GNSS timeout) can be configured at run time. This improves the development experience with individual devices or when debugging the device behavior in specific areas and situations. It also reduces the cost for transmitting data to the devices by reducing the frequency of sending firmware updates to the devices.

Requirements

Hardware platforms

PCA

Board name

Build target

Thingy:91

PCA20035

thingy91_nrf9160

thingy91_nrf9160_ns

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160_ns

When built for an _ns build target, the sample is configured to compile and run as a non-secure application. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

Overview

The application samples and sends sensor data to a connected cloud service over IP using LTE. Following are the cloud services that are supported by the application:

To run the application on a development kit and connect to a cloud service, you must complete the following steps:

  1. Setting up the cloud service

  2. Configuring the application

  3. Building and running

Note

For more information on the protocols and technologies that are used in the connection towards a specific cloud service, see Supported cloud services.

Cloud setup

To set up a cloud service to work with the application firmware, complete the steps:

Important

The application defaults to the client ID used in the connection to the IMEI of the device. This value is printed on the development kit.

  • nRF Cloud - Connecting your device to nRF Cloud. The default configuration of the firmware is to communicate with nRF Cloud using the factory-provisioned certificates on the Thingy:91 and nRF9160 DK. This means that no additional configuration of the firmware is needed to connect to nRF Cloud. It is recommended to build and run the firmware on the device before completing the steps listed in Connecting your device to nRF Cloud. See Building and running.

  • AWS IoT Core - AWS IoT. This step retrieves a security tag and a hostname that will be needed during the configuration of the firmware.

  • Azure IoT Hub - Azure IoT Hub. This step retrieves a security tag and ID scope that will be needed during the configuration of the firmware. Make sure to follow the steps documented in the Configuration using DPS section to enable Device Provisioning Service (DPS).

  • AVSystem’s LwM2M Coiote Device Management - Server setup. No additional configuration is needed if the server is set up according to the linked documentation.

nRF Asset Tracker project

The application firmware is a part of the nRF Asset Tracker project, which is an open source end-to-end example that includes cloud backend and frontend code for the following cloud providers:

The nRF Asset Tracker project contains separate documentation that goes through setup of the firmware and cloud-side setup. If you want to use the nRF Asset Tracker, follow the nRF Asset Tracker project documentation instead of the Asset Tracker v2 documentation.

Carrier library support

See the section Using the carrier library for steps on how to connect to a operator’s device management platform, necessary in some LTE networks.

Configuration

To configure the firmware to connect to a specific cloud service, complete the following steps:

  1. Update the overlay configuration file that corresponds to the selected cloud service with the Kconfig option values that were extracted during the Setting up the cloud service step. The name of the overlay file must reflect the cloud service that has been chosen. For example, the file name is overlay-aws.conf for AWS IoT. Cloud-specific mandatory Kconfig options lists the mandatory options that are specific to each cloud service. The overlay files are located in the root folder of the application, under applications/asset_tracker_v2/.

  2. Include the overlay file when building the firmware, as documented in Building and running.

Configuration files

The application provides predefined configuration files for typical use cases.

Following are the available configuration files:

  • prj.conf - Configuration file common for thingy91_nrf9160_ns and nrf9160dk_nrf9160_ns build targets.

  • prj_qemu_x86.conf - Configuration file common for qemu_x86 build target.

  • boards/thingy91_nrf9160_ns.conf - Configuration file specific for Thingy:91. This file is automatically merged with the prj.conf file when you build for the thingy91_nrf9160_ns build target.

  • boards/nrf9160dk_nrf9160_ns.conf - Configuration file specific for nRF9160 DK. This file is automatically merged with the prj.conf file when you build for the nrf9160dk_nrf9160_ns build target.

  • boards/<BOARD>/led_state_def.h - Header file that describes the LED behavior of the CAF LEDs module.

Overlay configurations files that enable specific features:

  • overlay-aws.conf - Configuration file that enables communication with AWS IoT Core.

  • overlay-azure.conf - Configuration file that enables communication with Azure IoT Hub.

  • overlay-lwm2m.conf - Configuration file that enables communication with AVSystem’s Coiote IoT Device Management.

  • overlay-pgps.conf - Configuration file that enables P-GPS.

  • overlay-low-power.conf - Configuration file that achieves the lowest power consumption by disabling features that consume extra power, such as LED control and logging.

  • overlay-debug.conf - Configuration file that adds additional verbose logging capabilities and enables the debug module.

  • overlay-memfault.conf - Configuration file that enables Memfault.

  • overlay-carrier.conf - Configuration file that adds nRF Connect SDK LwM2M carrier support. See Carrier library support for more information.

Multiple overlay files can be included to enable multiple features at the same time.

Note

Generally, Kconfig overlays have an overlay- prefix and a .conf extension. Board-specific configuration files are placed in the boards folder and are named as <BOARD>.conf. DTS overlay files are named the same as the build target and use the file extension .overlay. They are placed in the boards folder. When the DTS overlay filename matches the build target, the overlay is automatically chosen and applied by the build system.

Optional library configurations

You can add the following optional configurations to configure the heap or to provide additional information such as Access Point Name (APN) to the modem for registering with an LTE network:

Note

This application supports the Secure bootloader chain (also called immutable bootloader), which has been enabled by default since the nRF Connect SDK v2.0.0 release. Devices that do not have the immutable bootloader cannot be upgraded over the air to use the immutable bootloader. To disable the Secure bootloader chain, set both CONFIG_SECURE_BOOT and CONFIG_BUILD_S1_VARIANT Kconfig options to n.

Building and running

This application can be found under applications/asset_tracker_v2 in the nRF Connect SDK folder structure. See Building and programming an application for information about how to build and program the application.

Testing

After programming the application and all the prerequisites to your development kit, test the application by performing the following steps:

  1. Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.

  2. Connect to the kit with a terminal emulator (for example, LTE Link Monitor). See How to connect with LTE Link Monitor for more information.

  3. Reset the development kit.

  4. Observe in the terminal window that application boots as shown in the following output:

    *** Booting Zephyr OS build v2.4.0-ncs1-2616-g3420cde0e37b  ***
    <inf> app_event_manager: APP_EVT_START
    
  5. Observe in the terminal window that LTE connection is established, indicated by the following output:

    <inf> app_event_manager: MODEM_EVT_LTE_CONNECTING
    ...
    <inf> app_event_manager: MODEM_EVT_LTE_CONNECTED
    
  6. Observe that the device establishes connection to the cloud:

    <inf> app_event_manager: CLOUD_EVT_CONNECTING
    ...
    <inf> app_event_manager: CLOUD_EVT_CONNECTED
    
  7. Observe that data is sampled periodically and sent to the cloud:

    <inf> app_event_manager: APP_EVT_DATA_GET_ALL
    <inf> app_event_manager: APP_EVT_DATA_GET - Requested data types (MOD_DYN, BAT, ENV, GNSS)
    <inf> app_event_manager: GNSS_EVT_ACTIVE
    <inf> app_event_manager: SENSOR_EVT_ENVIRONMENTAL_NOT_SUPPORTED
    <inf> app_event_manager: MODEM_EVT_MODEM_DYNAMIC_DATA_NOT_READY
    <inf> app_event_manager: MODEM_EVT_BATTERY_DATA_READY
    <inf> app_event_manager: GNSS_EVT_INACTIVE
    <inf> app_event_manager: GNSS_EVT_DATA_READY
    <inf> app_event_manager: DATA_EVT_DATA_READY
    <inf> app_event_manager: DATA_EVT_DATA_SEND_BATCH
    <inf> app_event_manager: CLOUD_EVT_DATA_SEND_QOS
    

Dependencies

This application uses the following nRF Connect SDK libraries and drivers:

It uses the following sdk-nrfxlib library:

In addition, it uses the following secure firmware component: