Memfault

The Memfault module provides an integration of Memfault SDK into nRF Connect SDK and expands the functionality of the SDK with some options that are specific to nRF Connect SDK. To get started with Memfault integration in nRF Connect SDK, see nRF Cloud powered by Memfault integration.

Memfault SDK is an SDK for embedded devices to make use of services that Memfault offers on their platform. For official documentation for Memfault SDK and the Memfault platform in general, see Memfault Docs.

Note

When building applications with Trusted Firmware-M (TF-M), the faults resulting from memory access in secure regions are not caught by Memfault’s fault handler. Instead, they are handled by TF-M. This means that those faults are not reported to the Memfault platform.

Configuration

In general, configuration of Memfault SDK in nRF Connect SDK is done using Kconfig options. Kconfig options are defined both in Memfault SDK and in the integration layer, which integrates the SDK into nRF Connect SDK. Kconfig options of the integration layer are located in modules/memfault/Kconfig. These Kconfig options are differentiated by two distinct prefixes:

  • CONFIG_MEMFAULT_ - Prefix for options defined in Memfault SDK

  • CONFIG_MEMFAULT_NCS_ - Prefix for options defined in nRF Connect SDK

Additionally, nRF Connect SDK has an implementation of the Memfault Diagnostic Service (MDS). Use the CONFIG_BT_MDS option to enable it. The MDS cannot be used concurrently with HTTP transport.

Configuration files

If you just want to do a quick test with a sample, disable the CONFIG_MEMFAULT_USER_CONFIG_ENABLE option in the prj.conf file to avoid adding the user configuration files. Otherwise, follow the instructions below.

Memfault SDK requires three files in the include path during the build process. Add a new folder called config into 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.

For more information, see the Memfault nRF Connect SDK integration guide. You can use the files in the Memfault sample as a reference. To have these configuration files in the include path, add the following to the CMakeLists.txt file:

zephyr_include_directories(config)

Automatic sending of coredumps to Memfault

To post a stored coredump from a previous crash to Memfault upon network connection, set the CONFIG_MEMFAULT_NCS_POST_COREDUMP_ON_NETWORK_CONNECTED Kconfig option to y. The option is only supported for nRF91 Series devices.

The library has built-in connection awareness and tries to post the coredump to a maximum of the number set in the CONFIG_MEMFAULT_NCS_POST_COREDUMP_RETRIES_MAX Kconfig option, at an interval of the time set in the CONFIG_MEMFAULT_NCS_POST_COREDUMP_RETRY_INTERVAL_SECONDS Kconfig option between each attempt. If unsuccessful within the number of attempts, the library gives up. If at any point the network is lost during the retry process, the library waits for the device to reconnect before restarting the retry process.

When a coredump is found after boot, the library automatically triggers a heartbeat and sends the heartbeat data along with the coredump to Memfault.

To also send an initial heartbeat when no coredump is available, set the CONFIG_MEMFAULT_NCS_POST_INITIAL_HEARTBEAT_ON_NETWORK_CONNECTED Kconfig option to y. This is useful for sending initial metrics to Memfault after boot without having to wait for the first automatic upload set by CONFIG_MEMFAULT_HTTP_PERIODIC_UPLOAD_INTERVAL_SECS.

This feature is useful when you want to post the coredump as soon as possible after a crash and it is not desirable to wait for the next periodic upload set by CONFIG_MEMFAULT_HTTP_PERIODIC_UPLOAD_INTERVAL_SECS. Alternatively, you can manually trigger the coredump upload by calling the memfault_zephyr_port_post_data() function. You can use the memfault_coredump_has_valid_coredump() function to check whether a coredump is available.

Automatic sending of modem trace to Memfault

To post modem traces to Memfault together with coredumps, set the CONFIG_MEMFAULT_NCS_POST_MODEM_TRACE_ON_COREDUMP Kconfig option to y. This option is only supported for nRF91 Series devices.

The modem trace will be posted as a CDR (Custom Data Record) to Memfault and depends on the Modem trace module being configured to use a trace backend that persists traces across reboots. Depending on the Memfault account type you use, different rate limits are imposed on the number of CDRs that can be posted. During development you can enable Developer Mode for selected devices, allowing them to post more CDRs. For more information, see the Memfault Server-Side Developer Mode.

Configuration options in Memfault SDK

Following are some of the configuration options that Memfault SDK defines:

For more details on each option, use menuconfig or guiconfig, and see the Kconfig sources in modules/lib/memfault-firmware-sdk/ports/zephyr/Kconfig.

Note

The Memfault shell is enabled by default, using the UART interface. If AT Host library and the Memfault module are enabled simultaneously, both will not behave as expected, as they both require the same UART interface. Therefore, it is recommended to enable only one of these at a time. To disable the Memfault shell, you need to disable the Kconfig option CONFIG_MEMFAULT_SHELL.

Configuration options in nRF Connect SDK

The Kconfig options for Memfault that are defined in nRF Connect SDK provide some additional features compared to the options that are already implemented in Memfault SDK:

Flash-backed coredump storage

When the CONFIG_MEMFAULT_NCS_INTERNAL_FLASH_BACKED_COREDUMP Kconfig option is enabled, the storage region is resolved at build time using one of the following sources:

  • Partition Manager (legacy): When CONFIG_PARTITION_MANAGER_ENABLED is y, a MEMFAULT_STORAGE partition is generated automatically. The size defaults to 64 kB, and you can override it with CONFIG_PM_PARTITION_SIZE_MEMFAULT_STORAGE.

  • Devicetree (nRF Connect SDK v3.4.0 or later recommended): When Partition Manager is disabled, the backend locates a fixed partition labeled memfault_coredump_partition under the internal flash controller.

The easiest way to enable the devicetree path is the Flash-backed coredump storage snippet that supplies a board-specific overlay defining the partition:

west build -b <board> -S memfault-coredump <application>

For boards not covered by the snippet, add a node similar to the following to your application overlay:

&flash0 {
    partitions {
        memfault_coredump_partition: partition@fc000 {
            compatible = "zephyr,mapped-partition";
            label = "memfault_coredump_partition";
            reg = <0x000fc000 0x4000>;
        };
    };
};

The nRF Connect SDK integration of Memfault SDK provides default values for some metadata that is required to identify the firmware when it is sent to Memfault cloud. You can control the defaults by using the configuration options below:

The Kconfig options for CONFIG_BT_MDS are the following:

API documentation

Header file: include/memfault_ncs.h
Source files: modules/memfault/
Memfault integration in NCS