Memfault

The Memfault sample shows how to use the Memfault SDK in an nRF Connect SDK application to collect coredumps and metrics. The sample connects to an LTE network using an nRF91 Series DK or a Thingy:91, or to Wi-Fi® using the nRF7002 DK, and sends the collected data to Memfault’s cloud using HTTPS.

Cellular connectivity is supported on the nRF91 Series SiPs, while Wi-Fi connectivity is supported on the nRF52 or nRF53 Series SoCs hosting the nRF70 Series Wi-Fi companion ICs.

The sample uses the connection manager that provides a common connectivity API for LTE and Wi-Fi stacks.

To get started with Memfault integration in nRF Connect SDK, see Memfault integration.

Requirements 

Before using this sample, make sure to 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 will receive the project key here to set in the CONFIG_MEMFAULT_NCS_PROJECT_KEY Kconfig option.

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Build target
Thingy:91	PCA20035	thingy91_nrf9160	`thingy91_nrf9160_ns`
nRF9161 DK	PCA10153	nrf9161dk_nrf9161	`nrf9161dk_nrf9161_ns`
nRF9160 DK	PCA10090	nrf9160dk_nrf9160	`nrf9160dk_nrf9160_ns`
nRF9151 DK	PCA10171	nrf9151dk_nrf9151	`nrf9151dk_nrf9151_ns`
nRF7002 DK	PCA10143	nrf7002dk_nrf5340	`nrf7002dk_nrf5340_cpuapp`

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

Overview 

In this sample, Memfault SDK is used as a module in nRF Connect SDK to collect coredumps, reboot reasons, metrics and trace events from devices and send to the Memfault cloud. See Memfault terminology for more details on the various Memfault concepts.

Metrics 

The sample adds properties specific to the application, while the Memfault SDK integration layer in nRF Connect SDK adds the system property metrics. See Memfault: Collecting Device Metrics for details on working and implementation of metrics. Some metrics are collected by the Memfault SDK directly. There are also some metrics, which are specific to nRF Connect SDK that are enabled by default:

LTE metrics:
- Enabled and disabled using CONFIG_MEMFAULT_NCS_LTE_METRICS.
- ncs_lte_time_to_connect_ms - Time from the point when the device starts to search for an LTE network until the time when it gets registered with the network.
- ncs_lte_connection_loss_count - The number of times that the device has lost the LTE network connection after the initial network registration.
Stack usage metrics:
- Shows how many bytes of unused space is left in a stack.
- Configurable using CONFIG_MEMFAULT_NCS_STACK_METRICS.
- ncs_connection_poll_unused_stack- Stack used by the cloud libraries for nRF Cloud, AWS IoT and Azure IoT Hub.

In addition to showing the capturing of metrics provided by the Memfault SDK integration layer in nRF Connect SDK, the sample also shows how to capture an application-specific metric. This metric is defined in samples/debug/memfault/config/memfault_metrics_heartbeat_config.h:

switch_1_toggle_count - The number of times Switch 1 has been toggled on an nRF9160 DK.

Error tracking with trace events 

The sample implements a user-defined trace reason for demonstration purposes. The trace reason is called switch_2_toggled, and is collected every time Switch 2 is toggled on an nRF9160 DK. In addition to detection of the event, the trace includes the current switch state. See Memfault: Error Tracking with Trace Events for information on how to configure and use trace events.

Coredumps 

The sample enables Memfault shell by default. The shell offers multiple commands to test a wide range of functionality offered by the Memfault SDK. Run the command mflt help in the terminal for more information on the available commands.

Coredumps can be triggered in the following ways:

Press Button 1 to trigger stack overflow
Press Button 2 to trigger division by zero
Use the Memfault shell to trigger a specific fault. Run the command mflt test help to see the possible options.

These faults cause crashes that are captured by Memfault. After rebooting, the crash data can be sent to the Memfault cloud for further inspection and analysis. See Memfault documentation for more information on the debugging possibilities offered by the Memfault platform.

Configuration 

The Memfault SDK allows the configuration of some of its options using Kconfig. To configure the options in the SDK that are not available for configuration using Kconfig, use samples/debug/memfault/config/memfault_platform_config.h. See Memfault SDK for more information.

See Configuring and building an application for information about how to permanently or temporarily change the configuration.

Minimal setup 

To send data to the Memfault cloud, a project key must be configured using CONFIG_MEMFAULT_NCS_PROJECT_KEY. If you are using the nRF7002 DK and want to automatically connect to a Wi-Fi network upon boot, configure the Wi-Fi credentials using the Kconfig options CONFIG_WIFI_CREDENTIALS_STATIC_SSID and CONFIG_WIFI_CREDENTIALS_STATIC_PASSWORD.

Note

The Memfault SDK requires certificates required for the HTTPS transport. The certificates are by default provisioned automatically by the nRF Connect SDK integration layer for Memfault SDK to sec tags 1001 - 1005. If other certificates exist at these sec tags, HTTPS uploads will fail.

Additional configuration 

There are two sources for Kconfig options when using Memfault SDK in nRF Connect SDK:

Kconfig options defined within the Memfault SDK.
Kconfig options defined in the nRF Connect SDK integration layer of the Memfault SDK. These configuration options are prefixed with CONFIG_MEMFAULT_NCS.

Check and configure the following options in Memfault SDK that are used by the sample:

If CONFIG_MEMFAULT_ROOT_CERT_STORAGE_NRF9160_MODEM is enabled, TLS certificates used for HTTP uploads are provisioned to the nRF91 Series modem when memfault_zephyr_port_install_root_certs() is called.

Check and configure the following options for Memfault that are specific to nRF Connect SDK:

If CONFIG_MEMFAULT_NCS_INTERNAL_FLASH_BACKED_COREDUMP is enabled, CONFIG_PM_PARTITION_SIZE_MEMFAULT_STORAGE can be used to set the flash partition size for the flash storage.

Configuring Wi-Fi access point credentials 

This sample uses the Wi-Fi credentials library to manage Wi-Fi credentials. Before the sample can connect to a Wi-Fi network, you must configure at least one credential set.

Once you have flashed your device with this sample, connect to your device’s UART interface and add credentials using the following command:

wifi_cred add NetworkSSID SecurityMode (OPEN, WPA2-PSK, WPA2-PSK-SHA256, WPA3-SAE) NetworkPassword

Where NetworkSSID is replaced with the SSID of the Wi-Fi access point you want your device to connect to, and NetworkPassword is its password. If you are not sure which security mode to use, enable the CONFIG_NET_L2_WIFI_SHELL Kconfig option and use the wifi scan command to display a list of all accessible networks along with their corresponding security modes. Then either reboot the device or use the wifi_cred auto_connect command to manually trigger a connection attempt.

From now on, these credentials will be automatically used when the configured network is reachable.

When building as firmware image for a non-secure build target, the Wi-Fi credentials backend will be set to PSA using TF-M.

See the Wi-Fi: Shell sample document for more details on the wifi_cred command.

Wi-Fi static credential options

If you want to configure the credentials statically, set the CONFIG_WIFI_CREDENTIALS_STATIC Kconfig option to y.

Important

Do not use static credentials in production environments.

Other options for statically configuring your Wi-Fi credentials:

CONFIG_WIFI_CREDENTIALS_STATIC - This option enables static Wi-Fi configuration.
CONFIG_WIFI_CREDENTIALS_STATIC_SSID - Wi-Fi SSID.
CONFIG_WIFI_CREDENTIALS_STATIC_PASSWORD - Wi-Fi password.
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_OPEN - Wi-Fi network uses no password.
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_PSK - Wi-Fi network uses a password and PSK security (default).
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_PSK_SHA256 - Wi-Fi network uses a password and PSK-256 security.
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_SAE - Wi-Fi network uses a password and SAE security.

Sending traces over UART on an nRF91 Series DK 

To send modem traces over UART on an nRF91 Series DK, configuration must be added for the UART device in the devicetree and Kconfig. This is done by adding the modem trace UART snippet when building and programming.

Use the Cellular Monitor app for capturing and analyzing modem traces.

TF-M logging must use the same UART as the application. For more details, see shared TF-M logging.

Building and running 

This sample can be found under samples/debug/memfault in the nRF Connect SDK folder structure.

When built as firmware image for the _ns build target, the sample has Cortex-M Security Extensions (CMSE) enabled and separates the firmware between Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE). Because of this, it automatically includes the Trusted Firmware-M (TF-M). To read more about CMSE, see Processing environments.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Configuring and building an application for other building scenarios, Programming an application for programming steps, and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Testing 

Before testing, ensure that your device is configured with the project key of your Memfault project. After programming the sample to your development kit, complete the following steps to test it:

Open a serial port connection to the kit using a terminal emulator that supports VT100/ANSI escape characters (for example, nRF Connect Serial Terminal). See Testing and optimization for the required settings and steps.

Observe that the sample starts. Following is a sample output on the terminal:

*** Booting Zephyr OS build v3.0.99-ncs1-4913-gf7b06162027d  ***
<inf> mflt: Reset Reason, RESETREAS=0x0
<inf> mflt: Reset Causes:
<inf> mflt: Power on Reset
<inf> mflt: GNU Build ID: a09094cdf9da13f20719f87016663ab529b71267
<inf> memfault_sample: Memfault sample has started

The sample connects to an available LTE or Wi-Fi network, which is indicated by the following message:
```
<inf> memfault_sample: Connecting to network
```
When the connection is established, the following message is shown:
```
<inf> memfault_sample: Connected to network.
```
If LTE is used, the sample displays the captured LTE time-to-connect metric (ncs_lte_time_to_connect_ms) in the terminal:
```
<inf> memfault_sample: Time to connect: 3602 ms
```

Subsequently, all captured Memfault data will be sent to the Memfault cloud:

<inf> memfault_sample: Sending already captured data to Memfault
<dbg> mflt: memfault_platform_log: Response Complete: Parse Status 0 HTTP Status 202!
<dbg> mflt: memfault_platform_log: Body: Accepted
<dbg> mflt: memfault_platform_log: Response Complete: Parse Status 0 HTTP Status 202!
<dbg> mflt: memfault_platform_log: Body: Accepted
<dbg> mflt: memfault_platform_log: No more data to send

Upload the symbol file generated from your build to your Memfault account so that the information from your application can be parsed. The symbol file is located in the build folder: memfault/build/zephyr/zephyr.elf:
1. In a web browser, navigate to Memfault.
2. Login to your account and select the project you created earlier.
3. Navigate to Fleet > Devices in the left menu.
  
  You can see your newly connected device and the software version in the list.
4. Click on the software version number for your device and then the Upload button to upload the symbol file.

Back in the terminal, press <TAB> on your keyboard to confirm that the Memfault shell is working. The available shell commands are displayed:

uart:~$
  clear              device             flash              help
  history            kernel             log                mcuboot
  mflt               mflt_nrf           nrf_clock_control  resize
  shell

Learn about the available Memfault shell commands by issuing the command mflt help.
Press Button 1 or Button 2 to trigger a stack overflow or a division by zero, respectively.
Explore the Memfault user interface to look at the errors and metrics that has been sent from your device.

Dependencies 

The sample requires the Memfault SDK, which is part of nRF Connect SDK’s west manifest, and will be downloaded automatically when west update is run.

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

It uses the following Zephyr libraries:

It uses the following sdk-nrfxlib libraries:

Modem library

In addition, it uses the following secure firmware component:

Trusted Firmware-M