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.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

nRF5340 DK

PCA10095

nrf5340dk_nrf5340

nrf5340dk_nrf5340_cpuapp_ns nrf5340dk_nrf5340_cpuapp

nRF52 DK

PCA10040

nrf52dk_nrf52832

nrf52dk_nrf52832

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

nRF52833 DK

PCA10100

nrf52833dk_nrf52833

nrf52833dk_nrf52833

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

Note

If you use nRF5340 DK, the additional configuration of the network core will be taken from the child_image directory. For more details, see Image-specific variables.

Before using the Memfault platform, you must register an account in the Memfault registration page and create a new project in Memfault. After the registration, you can connect up to 100 devices for free.

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:

  • Button3PressCount - The number of Button 3 presses.

  • BatteryLvl - The simulated battery level.

  • Button1TimeMeasure - 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_BtConnectionCount - Number of Bluetooth connections.

    • Ncs_BtConnectionTime - Bluetooth connection time.

      Time with at least one live Bluetooth connection.

    • Ncs_BtBondCount - Number of Bluetooth bonds.

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

    • NcsBtRxUnusedStack - HCI Rx thread stack.

    • NcsBtTxUnusedStack - HCI Tx thread stack.

Error tracking with trace events

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

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

The trace events are defined in the file 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:

  • 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.

LED 1:

Blinks when the main loop is running (that is, the device is advertising) with a period of two seconds, duty cycle 50%.

LED 2:

Lit when the development kit is connected.

Button 1:

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

During the pairing procedure, press this button to accept pairing.

Button 2:

Triggers the Button2StateChanged trace event.

During the pairing procedure, press this button to reject pairing.

Button 3:

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

Button 4:

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

Configuration

See Configuring your application 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 option. You can find your project key in the project settings at Memfault Dashboards. You also need to set the following static configuration option for this sample:

Building and running

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

When built as a non-secure firmware image for the _ns build target, the sample automatically includes the Trusted Firmware-M (TF-M).

To build the sample with Visual Studio Code, follow the steps listed on the Building nRF Connect SDK application quick guide page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application 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:

Testing with Memfault WebBluetooth Client

  1. Connect to the kit with a terminal emulator that supports VT100/ANSI escape characters (for example, PuTTY). See How to connect with PuTTY for the required settings.

  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. Use the buttons on your development kit to confirm or reject a pairing request:

    Pairing confirmation required for 6D:99:66:6E:19:72 (random)
Press Button 1 to confirm, Button 2 to reject.

  9. 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 option CONFIG_BT_MDS_DATA_POLL_INTERVAL.

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

    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.

  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 MDS BLE gateway script

  1. Connect to the kit with a terminal emulator that supports VT100/ANSI escape characters (for example, PuTTY). See How to connect with PuTTY for the required settings.

  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. Use the buttons on the development kit to confirm or reject a pairing request.

    Pairing confirmation required for 6D:99:66:6E:19:72 (random)
Press Button 1 to confirm, Button 2 to reject.

  9. 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.

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

    Sending..
Forwarded 2 Memfault Chunks

  11. 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_memfault/build/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.

  12. 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

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

    See User interface for details about button functions.

  14. 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:

In addition, it uses the following Zephyr libraries:

  • Bluetooth APIs:

    • include/bluetooth/bluetooth.h

    • include/bluetooth/conn.h

    • samples/bluetooth/gatt/bas.h

The sample also uses the following secure firmware component: