Memfault Diagnostic Service
Introduction
The Memfault Diagnostic Service (MDS) GATT service is a standardized way for BLE devices to send Chunk payloads to a gateway device (eg mobile phone) which can then forward the data to the Memfault cloud.
The service is designed such that the gateway can be agnostic to the data being forwarded.
Memfault Diagnostic Service (MDS) Description
GATT Service
| Service | UUID |
|---|---|
| Memfault Diagnostic Service | 54220000-f6a5-4007-a371-722f4ebd8436 |
Characteristics
| Name | Properties | UUID | Length | Description |
|---|---|---|---|---|
| MDS Supported Features Characteristic | Read | 54220001-f6a5-4007-a371-722f4ebd8436 | Variable | Bitmask of features that have been added to MDS Profile. At the moment, returns 0x0 since this is the first version of the profile |
| MDS Device Identifier Characteristic | Read | 54220002-f6a5-4007-a371-722f4ebd8436 | Variable | Returns the device identifier populated in the memfault_platform_get_device_info() dependency function |
| MDS Data URI Characteristic | Read | 54220003-f6a5-4007-a371-722f4ebd8436 | Variable | Returns the URI diagnostic data should be forwarded to |
| MDS Authorization Characteristic | Read | 54220004-f6a5-4007-a371-722f4ebd8436 | Variable | Returns the configured authorization to use such as "Memfault-Project-Key:YOUR_PROJECT_KEY" |
| MDS Data Export Characteristic | Notify, Write | 54220005-f6a5-4007-a371-722f4ebd8436 | Streams any collected SDK data to listener as opaque packets. See below. | |
| Client Characteristic Configuration Descriptor | Read, Write | 00002902-0000-1000-8000-00805f9b34fb | Associated with MDS Data Export Characteristic above |
MDS Data Export Characteristic
To enabling streaming, the characteristic must be subscribed to and a mode must be configured via a GATT write to the characteristic.
Valid Modes (1 Octet):
| Mode | Description |
|---|---|
| 0x00 | Streaming Disabled |
| 0x01 | Streaming of all data is enabled |
Other modes are reserved for future use.
Packets will be sized to fit within negotiated MTU.
Packet Format:
| Offset | Size | Description |
|---|---|---|
| byte 0 | 1 | bits 0-4: A sequentially increasing counter (0-31) that can be used to detect accidental repeat or dropped notifications which wraps around at 31 bits. Bits 5-7: Reserved for future use |
| byte 1 | 1+ | Variable payload bytes (chunk data) |
Listener is responsible for forwarding chunks to the URI specified in the Data URI Characteristic using the authorization scheme specified in the Authorization Characteristic."
WebBluetooth client
We've implemented a reference client in WebBluetooth. Any device which implements the MDS profile can be connected and the WebBluetooth client will forward diagnostic data published.
Note: currently Web Bluetooth is best supported on Chrome, and depends on the device's BLE stack to support the necessary features. It should work on most modern Android devices and desktops with BLE support.
It may be necessary to enable these flags:
Nordic Clients
As of the v2.1.0 release of the nRF-Connect SDK, there is built-in support for the Memfault Diagnostic Service, which is a Bluetooth LE GATT service designed to enable exporting Memfault data in a standardized way.
Nordic has detailed documentation on the Memfault Diagnostic service here:
https://docs.nordicsemi.com/bundle/ncs-2.6.0/page/nrf/libraries/bluetooth_services/services/mds.html
To enable MDS, add CONFIG_BT_MDS=y to your prj.conf file. Nordic provides
mobile apps specifically built to collect Memfault chunks from MDS devices, you
can download them for
iOS and
Android
There is also a sample application, "Bluetooth LE: Peripheral Memfault Diagnostic Service (MDS)", documented here:
https://docs.nordicsemi.com/bundle/ncs-2.6.0/page/nrf/samples/bluetooth/peripheral_mds/README.html
Nordic and Memfault provide the following Bluetooth LE gateways for testing the MDS implementation:
-
the Python MDS Bluetooth LE gateway script, from the nRF-Connect SDK: https://github.com/nrfconnect/sdk-nrf/tree/v2.6.0/scripts/memfault
-
a Web Bluetooth LE browser-based tool, from Memfault: https://mflt.io/mds
-
iOS and Android open-source libraries:
- Android library: https://github.com/NordicSemiconductor/Android-Memfault-Library
- iOS library: https://github.com/NordicSemiconductor/IOS-Memfault-Library
For a quick test, we recommend using the "Bluetooth LE: Peripheral Memfault Diagnostic Service (MDS)" sample application and one of the mobile apps with a compatible mobile device.
Notes
Length requirement
If length exceeds negotiated MTU size, it is assumed that client has implemented support for long attribute reads. (iOS & Android both support this). If long attribute reads are not supported for some reason, an MTU needs to be negotiated which exceeds the length of the Project Key and Device Identifier.
Future characteristic updates
If additional characteristics are ever added to the service, they will be appended to the table to minimize impact for clients who have not (correctly) implemented the "Service Changed" characteristic in the Generic Attribute Profile Service.
Restricting access
For production applications and enhanced security and privacy, it is recommended
the memfault_mds_access_enabled() be implemented. See function comments
here for more details.
When implemented, diagnostic data will only be published if the connection is
bonded and the link is encrypted.
Development and version guarantees
This GATT service is currently under development and subject to updates and enhancements in the future with no current guarantees for backward compatibility. Client implementations should read the MDS Supported Features Characteristic and only attempt to use the service as it is currently defined if the value is 0x00.