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 sandbox for a self-guided tour of the platform as well as the Memfault documentation for more details.

Note

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

Integration prerequisites

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

Solution architecture

The Memfault 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. You can monitor the overall fleet health through the dashboard of the Memfault web application. See the Memfault MCU Guide for more information.

Memfault Solution architecture

Memfault Solution architecture

Integration overview

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

Integration steps

To integrate Memfault into nRF Connect SDK, after completing the prerequisites, complete the following steps:

  1. Configure Memfault

  2. Add additional configuration files

Configuring Memfault

To include Memfault in your build, add the following Kconfig options 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

For the nRF Connect SDK samples that use Memfault, the Memfault configurations are already included in their folders. 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 on an nRF9160 DK:

west build -b nrf9160dk/nrf9160/ns -- -DEXTRA_CONF_FILE=overlay-memfault.conf

Adding additional configuration files

Memfault SDK requires 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 Kconfig 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 config folder in your project 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.

Note

In the nRF Connect SDK samples and applications that use Memfault, these configuration files are already added in the sample or application folders.

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 methods described in the following sections.

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)

You can trigger coredumps 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 the Metrics section of the following sample documents for more information:

See Memfault: Collecting Device Metrics for detailed documentation.

Configuration options

The nRF Connect SDK has different configuration options defined for the Memfault 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 available in the modules/memfault/Kconfig directory. 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:

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 an LTE network using an nRF91 Series DK, Thingy:91, or Thingy:91 X, or to Wi-Fi® using the nRF7002 DK, and sends the collected data to Memfault’s cloud using HTTPS.

Library support

The following nRF Connect SDK libraries support the Memfault integration:

Dependencies

Memfault integration uses the following secure firmware component: