Bluetooth: Peripheral Memfault Diagnostic Service (MDS)

The Peripheral Memfault Diagnostic Service sample demonstrates how to use the Memfault Diagnostic Service (MDS) with the Memfault SDK in an nRF Connect SDK Bluetooth application to collect core dumps and metrics. The Memfault diagnostic data is sent through a Bluetooth gateway.

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

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target
nRF54LV10 DK	PCA10188	nrf54lv10dk	nrf54lv10dk/nrf54lv10a/cpuapp/ns nrf54lv10dk/nrf54lv10a/cpuapp
nRF54LM20 DK	PCA10184	nrf54lm20dk	nrf54lm20dk/nrf54lm20b/cpuapp/ns nrf54lm20dk/nrf54lm20b/cpuapp nrf54lm20dk/nrf54lm20a/cpuapp/ns nrf54lm20dk/nrf54lm20a/cpuapp
nRF54LC10 DK	PCA10226	nrf54lc10dk	nrf54lc10dk/nrf54lc10a/cpuapp/ns nrf54lc10dk/nrf54lc10a/cpuapp
nRF54L15 DK	PCA10156	nrf54l15dk	nrf54l15dk/nrf54l15/cpuapp/ns nrf54l15dk/nrf54l15/cpuapp
nRF54L15 DK (emulating nRF54L10)	PCA10156	nrf54l15dk	nrf54l15dk/nrf54l10/cpuapp
nRF54L15 DK (emulating nRF54L05)	PCA10156	nrf54l15dk	nrf54l15dk/nrf54l05/cpuapp
nRF5340 DK	PCA10095	nrf5340dk	nrf5340dk/nrf5340/cpuapp/ns nrf5340dk/nrf5340/cpuapp
nRF52 DK	PCA10040	nrf52dk	nrf52dk/nrf52832
nRF52840 DK	PCA10056	nrf52840dk	nrf52840dk/nrf52840
nRF52833 DK	PCA10100	nrf52833dk	nrf52833dk/nrf52833

For more security, it is recommended to use the */ns variant of the board target. When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. 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, the Memfault SDK is used as a module in the nRF Connect SDK to collect core dumps, reboot reasons, metrics, and trace events from devices and send them through a Bluetooth gateway to the Memfault cloud. See Memfault terminology for more details on the various Memfault concepts. The sample also includes the BAS functionalities.

Metrics

The sample shows how to capture user-specific metrics. It defines the following metrics:

nRF52 and nRF53 DKsnRF54 DKs

• button_press_count - The number of Button 3 presses.

• battery_soc_pct - The simulated battery level.

• button_elapsed_time_ms - The time measured between two Button 1 presses.

These metrics are defined in the samples/bluetooth/peripheral_mds/memfault_config/memfault_metrics_heartbeat_config.def file. For more details about the metrics, see Memfault: Collecting Device Metrics.

There are also metrics that are specific to nRF Connect SDK. Memfault adds these system proprietary metrics. The following metrics are enabled by default in this sample:

• Bluetooth metrics, enabled and disabled using the CONFIG_MEMFAULT_NCS_BT_METRICS Kconfig option.

• ncs_bt_connection_count - Number of Bluetooth connections.

• ncs_bt_connection_time_ms - Bluetooth connection time.

  Time with at least one live Bluetooth connection.

• ncs_bt_bond_count - Number of Bluetooth bonds.

• Stack usage metrics shows the free stack space in bytes. Configurable by the CONFIG_MEMFAULT_NCS_STACK_METRICS Kconfig option.

• ncs_bt_rx_unused_stack - HCI RX thread stack.

• ncs_bt_tx_unused_stack - HCI TX thread stack.

Error tracking with trace events

The sample implements the following user-defined trace reason for demonstration purposes:

nRF52 and nRF53 DKsnRF54 DKs

button_state_changed - Collected every time when Button 2 changes its state.

The trace events are defined in the samples/bluetooth/peripheral_mds/memfault_config/memfault_trace_reason_user_config.def file. See Memfault: Error Tracking with Trace Events for more details about trace events.

Core dumps

You can trigger core dumps in this sample using the following methods:

nRF52 and nRF53 DKsnRF54 DKs

• Button 4 - Triggers a hardfault exception by division by zero.

• mfl crash shell command - Triggers an assertion fail.

When a fault occurs, it results in crashes that are captured by Memfault. After your development kit reboots and reconnects with the Bluetooth gateway, it sends core dump data to the Memfault cloud for further inspection and analysis.

Memfault shell

The Bluetooth MDS sample enables a shell interface by default. You can use it instead of the development kit buttons to trigger a separate event.

For a list of available commands, see Memfault Demo CLI.

User interface

The sample supports a simple user interface. You can control the sample using predefined buttons, while LEDs are used to display information.

nRF52 and nRF53 DKsnRF54 DKs

LED 1:

Blinks, toggling on/off every second, when the main loop is running and the device is advertising.

LED 2:

Lit when the development kit is connected.

Button 1:

Press this button to start time measuring. The second press stops time measuring.

Button 2:

Triggers the button_state_changed trace event.

Button 3:

Every press of this button is counted under the button_press_count metric.

Button 4:

Simulate a development kit crash by triggering a hardfault exception by division by zero.

Configuration

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

The Memfault SDK allows configuring some of its options using Kconfig. For the options not configurable using Kconfig, use the samples/bluetooth/peripheral_mds/memfault_config/memfault_platform_config.h file. See Memfault SDK for more information.

To send data to the Memfault cloud through a Bluetooth gateway, you must configure a project key using the CONFIG_MEMFAULT_NCS_PROJECT_KEY Kconfig option. You can find your project key in the project settings at Memfault Dashboards. Use the CONFIG_MEMFAULT_NCS_DEVICE_ID Kconfig option to set a static device ID. For this sample, the device ID is ncs-ble-testdevice by default.

Building and running

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

For more security, it is recommended to use the */ns variant of the board target (see the Requirements section above.) When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

When building this sample with Sysbuild for an SoC that has a network core, the IPC radio firmware is automatically applied to the build. The IPC radio is one of the companion components in the nRF Connect SDK and allows to use the radio peripheral from another core in a multicore device. If needed, you can modify the IPC radio configuration in the prj.conf source file in the sample’s sysbuild/ipc_radio directory.

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:

Testing with nRF Memfault mobile applications

You can use the nRF Connect Device Manager application for testing the Memfault Diagnostic Service (MDS). You can also use it for your custom applications using the Memfault Diagnostic Service.

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

2. Reset your development kit.

3. Observe that the sample starts.

4. On your mobile phone with access to the Internet, open the nRF Connect Device Manager application and allow it a moment to scan for devices.

5. Select your device from the list. If you use the settings defined in the prj.conf file of this sample, it is titled “Nordic_Memfault.” If your device requires a PIN for a pairing request, it is visible through a serial terminal connection. If you are having trouble connecting to your device, forget the device’s entry from your phone’s Bluetooth settings and try again.

6. Once connected, navigate to the Logs and Stats or Diagnostics tab (labeled differently depending on your platform). You should see “Status: Awaiting New Chunks” or a message such as “Uploaded: 2 chunk(s), 152 bytes” (or both).

7. 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: peripheral_mds/build/peripheral_mds/zephyr/zephyr.elf:

   1. Open Memfault in a web browser.

   2. Log in to your account and select the project you created earlier.

   3. Navigate to Fleet > Devices in the left side menu. You can see your newly connected device and the software version in the list.

   4. Select the software version number for your device and click Upload to upload the symbol file.

8. Return to the terminal and press Tab to confirm that the Memfault shell is working. The shell commands available are displayed.

   To learn about the Memfault shell commands, issue command mflt help.

9. Use the buttons to trigger Memfault crashes, traces and metrics collection.

   See User interface for details about button functions.

10. Explore the Memfault user interface to see the errors and metrics sent from your device.

11. When you have finished collecting diagnostic data, tap Disconnect to close the connection with your development kit.

    As the bond information is preserved, you can tap Connect again to immediately reconnect to the device.

Testing with MDS BLE gateway script

nRF52 and nRF53 DKsnRF54 DKs

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

2. Reset your development kit.

3. Observe that the sample starts.

4. Run the following command in the nRF Connect SDK root directory to install the MDS BLE gateway script dependencies:

   pip install --user -r scripts/memfault/requirements.txt
   

5. Connect the nRF52 development kit to your PC that uses the MDS BLE gateway script.

6. Start the mds_ble_gateway.py script with the correct parameters, for example:

   python3 mds_ble_gateway.py --snr 682900407 --com COM0
   

7. Wait for the script to establish a connection with your development kit.

8. Upon connection, data already collected by the Memfault SDK is forwarded to the cloud for further analysis. When connected, the new data is periodically transferred to the cloud with the interval configured in the CONFIG_BT_MDS_DATA_POLL_INTERVAL Kconfig option.

9. On the terminal running the script, you can observe the Memfault chunk counter:

   Sending..
   Forwarded 2 Memfault Chunks
   

10. 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: peripheral_mds/build/peripheral_mds/zephyr/zephyr.elf:

    1. Open Memfault in a web browser.

    2. Log in to your account and select the project you created earlier.

    3. Navigate to Fleet > Devices in the left side menu. You can see your newly connected device and the software version in the list.

    4. Select the software version number for your device and click Upload to upload the symbol file.

11. Return to the terminal and press the Tab button on your keyboard to confirm that the Memfault shell is working. The shell commands available are displayed.

    To learn about the Memfault shell commands, issue command mflt help

12. Use the buttons to trigger Memfault crashes, traces and metrics collection.

    See User interface for details about button functions.

13. Explore the Memfault user interface to see the errors and metrics sent from your device.

Testing with Memfault WebBluetooth Client

nRF52 and nRF53 DKsnRF54 DKs

Note

The Web Bluetooth API used by the Memfault WebBluetooth Client is an experimental feature. The functionality depends on your browser and computer OS compatibility.

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

2. Reset your development kit.

3. Observe that the sample starts.

4. Open a recent version of the Google Chrome browser.

5. Run the Memfault WebBluetooth Client script to forward Memfault diagnostic data to the cloud. For more details, see the Memfault WebBluetooth Client source code.

6. Make sure that your development kit is advertising.

7. In the browser, click the Connect button and select your device from the list.

8. Upon connection, data already collected by the Memfault SDK is forwarded to the cloud for further the analysis. When connected, the new data is periodically flushed to the cloud with the interval configured by the Kconfig option CONFIG_BT_MDS_DATA_POLL_INTERVAL.

9. Upload the symbol file generated from your build to your Memfault account so that the information from your application can be parsed. The zephyr.elf symbol file is located in the build folder peripheral_mds/build/peripheral_mds/zephyr.

   1. In a web browser, navigate to Memfault.

   2. Log in to your account and select the project you created earlier.

   3. Navigate to Fleet > Devices in the left side menu. You can see your newly connected device and the software version in the list.

   4. Select the software version number for your device and click Upload to upload the symbol file.

10. Return to the terminal and press the Tab button on your keyboard to confirm that the Memfault shell is working. The shell commands available are displayed.

    To learn about the Memfault shell commands, issue command mflt help.

11. Use the buttons to trigger Memfault crashes, traces and metrics collection. See User interface for details about button functions.

12. Explore the Memfault user interface to see the errors and metrics sent from your device.

Dependencies

This sample uses the following nRF Connect SDK libraries:

• Memfault Diagnostic Service (MDS)

• DK Buttons and LEDs

• Memfault

In addition, it uses the following Zephyr libraries:

• API:

  • include/bluetooth/bluetooth.h

  • include/bluetooth/conn.h

  • samples/bluetooth/gatt/bas.h

The sample also uses the following secure firmware component:

• Trusted Firmware-M