Memfault Diagnostic Service (MDS)

The Bluetooth® Low Energy (LE) GATT Memfault Diagnostic Service is a custom service that forwards diagnostic data collected by firmware through a Bluetooth gateway. The diagnostic data is collected by the Memfault SDK integrated with the nRF Connect SDK.

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

The MDS is used in the Bluetooth: Peripheral Memfault Diagnostic Service (MDS) sample.

Service UUID

The 128-bit service UUID is 54220000-f6a5-4007-a371-722f4ebd8436.

Characteristics

The MDS characteristics are described in detail in the Memfault Diagnostic GATT Service documentation. The service implementation available in the nRF Connect SDK follows these requirements.

Note

Access restriction to diagnostic data is implemented differently from the one described in the Memfault Diagnostic GATT Service documentation. See Restricting access for more details.

Configuration

Set the CONFIG_BT_MDS Kconfig option to enable the service.

The following configuration options are available for this service:

  • CONFIG_BT_MDS_MAX_URI_LENGTH sets the maximum length of the URI to which diagnostic data should be forwarded. The URI contains the device ID. See Memfault for more details.

  • CONFIG_BT_MDS_PERM provides permission to the service characteristic. In the default configuration, it is set to CONFIG_BT_MDS_PERM_RW_ENCRYPT. This is because the potentially sensitive Memfault project key and diagnostic data are sent through service’s characteristics. There is not hard requirement for access restriction to diagnostic data.

  • CONFIG_BT_MDS_PIPELINE_COUNT sets the maximum number of service notifications that can be queued in the Bluetooth stack.

  • CONFIG_BT_MDS_DATA_POLL_INTERVAL sets the interval of checking if any diagnostic data is available for sending.

See the Kconfig help for details.

Implementation details

The implementation uses BT_GATT_SERVICE_DEFINE to statically define and register the Memfault Diagnostic GATT service. The service automatically checks if there is data available to be sent with the interval defined by the CONFIG_BT_MDS_DATA_POLL_INTERVAL and sends it using the notification mechanism. No application input is required to send diagnostic data. However, if you pass bt_mds_cb to the bt_mds_cb_register() function, the application needs to confirm that the connected client can access the diagnostic data every time the client performs a read or write operation on the service characteristic.

Use the bt_mds_cb_register() function to register callbacks the service.

Note

Call the bt_mds_cb_register() function before enabling Bluetooth stack to ensure a proper access restriction to MDS service data.

Note

Only one connected client can operate on the MDS characteristic and receive a notification with diagnostic data.

Restricting access

The Memfault service characteristics data might contain sensitive data. It is recommended to use the Bluetooth privacy and encrypted link to access the diagnostic data. Enable the CONFIG_BT_SMP Kconfig option to require encryption for access in the default configuration. It is also highly recommended to implement the access_enable callback. See Bluetooth: Peripheral Memfault Diagnostic Service (MDS) for an implementation example.

Bluetooth privacy

It is recommended to use the Bluetooth Privacy feature when you use this service. To enable privacy, set the CONFIG_BT_PRIVACY option.

API documentation

Header file: include/bluetooth/services/mds.h
Source file: subsys/bluetooth/services/mds.c
group bt_mds

API for the Memfault Diagnostic GATT service (MDS).

Defines

BT_UUID_MDS_VAL

UUID of the Memfault Diagnostic Service.

BT_UUID_MDS_SUPPORTED_FEATURES_VAL

UUID of the MDS Supported Features Characteristic.

BT_UUID_MDS_DEVICE_IDENTIFIER_VAL

UUID of the MDS Device Identifier Characteristic.

BT_UUID_MDS_DATA_URI_VAL

UUID of the MDS Data URI Characteristic.

BT_UUID_MDS_AUTHORIZATION_VAL

UUID of the MDS Authorization Characteristic.

BT_UUID_MDS_DATA_EXPORT_VAL

UUID of the MDS Data Export Characteristic.

BT_UUID_MEMFAULT_DIAG
BT_UUID_MDS_SUPPORTED_FEATURES
BT_UUID_MDS_DEVICE_IDENTIFIER
BT_UUID_MDS_DATA_URI
BT_UUID_MDS_AUTHORIZATION
BT_UUID_MDS_DATA_EXPORT

Functions

int bt_mds_cb_register(const struct bt_mds_cb *cb)

Register the Memfault Diagnostic service callback.

This function should be called before enabling Bluetooth stack to ensure proper access grating to MDS characteristics data through access_enable callback.

Parameters:

  • cb – [in] Memfault callback structure. This parameter can be set to NULL but it will let the first connected client access the Memfault data without authentication.

Return values:

0 – If the operation was successful. Otherwise, a negative error code is returned

struct bt_mds_cb
#include <mds.h>

Memfault Diagnostic Service callback structure.

Public Members

bool (*access_enable)(struct bt_conn *conn)

A callback for enabling Memfault access.

If this callback is not implemented, any connected peer can access the Memfault characteristics and descriptors data, including write access to them, without authentication.

The Memfault Diagnostic service allows only one client subscription.

Param conn:

[in] Connection object.

Retval True:

if peer associated with connection object has granted access to the Memfault data. False if access to the Memfault data is forbidden.