Memfault integration

Memfault is a cloud-based web application with nRF Connect SDK compatibility that monitors devices and allows you to debug issues remotely. Memfault integration provides the following features to nRF Connect SDK:

Remote debugging - Memfault issues can be efficiently resolved with automatic detection, alerts, deduplication, and actionable insights sent through the cloud.
Continuous monitoring - Monitors device and fleet-level metrics like connectivity and low power state in real-time dashboards and displays prepopulated metrics for your devices. You can access device level data to resolve bugs faster.

See the Memfault documentation for more details.

Note

Memfault has been integrated in nRF Connect SDK since the v1.6.0 release.

Prerequisites 

Before you start the nRF Connect SDK integration with Memfault, make sure that the following prerequisites are completed:

Installation of the nRF Connect SDK.
Setup of nRF9160 DK.
Sign up in the Memfault registration page and create a new project in Memfault. You will be directed to the Integration guide for Memfault. You receive the project key here to set in the CONFIG_MEMFAULT_NCS_PROJECT_KEY Kconfig option. After registration, you can connect up to 100 devices for free.

Solution architecture 

The SDK provides functionality to collect debug information from your devices in the form of coredumps, error traces, metrics, logs, and more. Memfault saves the data to a configurable storage, after which it is broken into chunks. These chunks are then forwarded at an interval that is set through the application’s configuration (CONFIG_MEMFAULT_HTTP_PERIODIC_UPLOAD_INTERVAL_SECS) to Memfault’s cloud solution for further analysis. If the CONFIG_MEMFAULT_HTTP_PERIODIC_UPLOAD Kconfig option is disabled, the application calls the appropriate APIs to send the data chunks. Communication with the Memfault Cloud is handled by APIs available in Memfault-SDK, while the integration code of the SDK in nRF Connect SDK provides some additional functionality. The Memfault cloud reassembles the data before analyzing and deduplicates the data. The overall fleet health of the issues can be examined through the dashboard of the Memfault web application. See the Memfault MCU Guide for more information.

Integration overview 

The SDK version is included in the west manifest file in nRF Connect SDK and is automatically downloaded when running west update. By default, it is downloaded to ncs/modules/lib/memfault-firmware-sdk/.

Complete the following steps to integrate Memfault into nRF Connect SDK:

Configure Memfault
Track errors
Collect metrices

Configuring Memfault 

To include Memfault in your build, add the following Kconfig option in your prj.conf file:

CONFIG_MEMFAULT=y
CONFIG_MEMFAULT_NCS_PROJECT_KEY=""

The APIs in the Memfault SDK can then be linked into your application. You can get your project key after signing up with Memfault.

Note

In the Memfault sample folder, the aforementioned Memfault configurations are already included. Make sure to add your project key in the CONFIG_MEMFAULT_NCS_PROJECT_KEY Kconfig option.

You can also add the configurations using a Kconfig configuration fragment file. See the following example on how to set an overlay configuration for Memfault integration:

west build -b nrf9160dk_nrf9160_ns -- -DOVERLAY_CONFIG=overlay-memfault.conf

Configuration files

Memfault SDK requires the three files in the include path during the build process. You can avoid adding these user configuration files by disabling the CONFIG_MEMFAULT_USER_CONFIG_ENABLE option. You can also skip these steps by enabling the CONFIG_MEMFAULT_USER_CONFIG_SILENT_FAIL option, even if the CONFIG_MEMFAULT_USER_CONFIG_ENABLE option is enabled.

To add the user configuration files, create a new folder in your project called config and add the following three files:

memfault_platform_config.h - Sets Memfault SDK configurations that are not covered by Kconfig options.
memfault_metrics_heartbeat_config.def - Defines application-specific metrics.
memfault_trace_reason_user_config.def - Defines application-specific trace reasons.

Add the following code in the CMakeLists.txt file to have these configuration files in the include path:

zephyr_include_directories(config)

See the Memfault nRF Connect SDK integration guide for more details.

Error Tracking 

Memfault captures all faults that happen at any time. The crash data is sent to the Memfault cloud for further inspection and analysis. The faults are tracked using the following methods.

Reboot reason tracking

The device might reboot due to a crash, a brownout, or a firmware update. The reboot events for each device are captured and displayed in the Memfault UI along with the recorded reboot reason.

See Memfault: Reboot tracking for detailed documentation.

Error tracking with trace events

You can use the trace event method if you want to track errors without capturing full coredump traces (that use less storage) and keep the device up and running. The following samples implement a user-defined trace reason for demonstration purposes.

Read the Error Tracking with trace events section of these sample documents for more information.

See Memfault: Error Tracking with Trace Events for detailed documentation. Faults are captured and displayed on the Issues page of Memfault UI.

RAM-backed stack dump collection (Coredumps)

The coredumps can be triggered to track the fault. The Coredumps section of the following sample documents provides more information:

See Memfault: Coredumps for detailed documentation. Faults are captured and displayed on the Issues page of the Memfault UI.

Collecting Metrics 

Memfault collects data from each device and visualizes it in a graph. The Memfault SDK integration layer in nRF Connect SDK adds the system property metrics. There are also some metrics specific to nRF Connect SDK. See Metrics section of the following sample documents for more information:

See Memfault: Collecting Device Metrics for detailed documentation.

Configuration options 

There are different configuration options defined for the Memfault SDK in nRF Connect SDK. The configuration options are defined both in Memfault-SDK and in the integration layer, which integrates the SDK into nRF Connect SDK. The configuration options of the integration layer are in modules/memfault/Kconfig. See the Configuration section of the following library documents for different Memfault SDK configuration options defined in nRF Connect SDK:

Applications and samples 

The following applications use the Memfault integration in nRF Connect SDK:

Asset Tracker v2 - The debug module of Asset Tracker v2 uses Memfault SDK to track nRF Connect SDK specific metrics such as LTE and stack metrics. See the Debug module documentation for more details. The Asset Tracker v2 application also uses Memfault on a custom transport, without using Memfault’s own HTTPS transport. See the Custom transport section for more details.
nRF Asset Tracker project - The nRF Asset Tracker Memfault integration for AWS IoT or the nRF Asset Tracker Memfault integration for Azure IoT Hub provide the necessary cloud resources to send Memfault data using the established MQTT cloud connection. See the nRF Asset Tracker Memfault integration documentation for more details.

The following samples demonstrate the Memfault integration in nRF Connect SDK:

Bluetooth: Peripheral Memfault Diagnostic Service (MDS) - This sample has an implementation of the Memfault Diagnostic Service (MDS). It sends data to the Memfault cloud through a Bluetooth gateway.
Memfault - This sample connects to the LTE network and sends data using HTTPS. It supports nRF9160-based build targets.

Library support 

The following nRF Connect SDK libraries support the Memfault integration:

Dependencies 

It uses the following secure firmware component:

Trusted Firmware-M