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 Memfault integration.

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

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.

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:

  • button_3_press_count - The number of Button 3 presses.

  • battery_soc_pct - The simulated battery level.

  • button_1_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:

button_2_state_changed - 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, 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.

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

Button 2:

Triggers the button_2_state_changed trace event.

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

Button 3:

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

Button 4:

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

Configuration

See Configuring and building an 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 Kconfig option. You can find your project key in the project settings at Memfault Dashboards. You also need to set the CONFIG_MEMFAULT_NCS_DEVICE_ID static Kconfig 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 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:

Testing with nRF Memfault mobile applications

You can use the nRF Memfault for Android or the nRF Memfault for iOS applications for testing the Memfault Diagnostic Service (MDS). You can also use them 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, nRF Connect Serial Terminal). 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 Memfault application.

  5. In the mobile application, tap the Start button.

  6. Look for your device running the Memfault Diagnostic Service in the Discovered devices list.

  7. Select your device from the list.

  8. Tap Connect button to connect with your development kit.

  9. Wait for the application to establish connection with your development kit.

    In the mobile application, observe that Memfault chunks are forwarded from your device to the Memfault Cloud.

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

  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.

  13. When you have finished collecting diagnostic data, tap Disconnect to the close 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

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

  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.

Testing with Memfault WebBluetooth Client

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, nRF Connect Serial Terminal). 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. 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 Kconfig 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 zephyr.elf symbol file is located in the build folder peripheral_memfault/build/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.

  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.

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: