Memfault Firmware SDK 0.29.1 (Build 412506)

Author: Memfault Inc

CHANGES.md

@@ -1,3 +1,18 @@
+### Changes between Memfault SDK 0.29.1 and SDK 0.29.0 - Mar 16, 2022
+
+#### :house: Internal
+
+- Updated Memfault Diagnostic GATT Service (MDS) based on feedback. This service can
+  be used to transparently forward data collected by the SDK to a Bluetooth Low
+  Energy gateway and proxied to the cloud. See
+  [ports/include/memfault/ports/ble/mds.h](ports/include/memfault/ports/ble/mds.h#L1)
+- Updated Mbed OS invoke commands to be more resilient against python package conflicts
+
+#### :boom: Breaking Changes
+
+- If your project is based on Zephyr < 2.6, you now need to explicitly set
+  `CONFIG_OPENOCD_SUPPORT=y` in your `prj.conf`
+
 ### Changes between Memfault SDK 0.29.0 and SDK 0.28.2 - Feb 28, 2022
 
 #### :rocket: New Features

VERSION

@@ -1,2 +1,2 @@
-BUILD ID: 400378
-GIT COMMIT: b015b1226
+BUILD ID: 412506
+GIT COMMIT: f81a4f865

components/include/memfault/version.h

@@ -19,7 +19,7 @@ typedef struct {
   uint8_t patch;
 } sMfltSdkVersion;
 
-#define MEMFAULT_SDK_VERSION   { .major = 0, .minor = 29, .patch = 0 }
+#define MEMFAULT_SDK_VERSION   { .major = 0, .minor = 29, .patch = 1 }
 
 #ifdef __cplusplus
 }

ports/dialog/da1469x/memfault_diagnostic_service.c

@@ -75,18 +75,32 @@ MEMFAULT_STATIC_ASSERT(configTIMER_TASK_STACK_DEPTH >= 256,
 #define MDS_DYNAMIC_ACCESS_CONTROL 0
 #endif
 
-#define MDS_VERSION 0x01
+//! Payload returned via a read to "MDS Supported Features Characteristic"
+const static uint8_t s_mds_supported_features[] = {
+  // no feature additions since the first spin of the profile
+  0x0
+};
 
-#define MDS_MAJOR_VERSION 0x01
-#define MDS_MINOR_VERSION 0x00
-#define MDS_PATCH_VERSION 0x00
+//! Valid SNs used when sending data are 0-31
+#define MDS_TOTAL_SEQ_NUMBERS 32
+
+typedef enum {
+  kMdsDataExportMode_StreamingDisabled = 0x00,
+  kMdsDataExportMode_FullStreamingEnabled = 0x01,
+} eMdsDataExportMode;
 
-const static uint8_t s_mds_version[] = { MDS_VERSION, MDS_MINOR_VERSION, MDS_PATCH_VERSION};
+
+typedef MEMFAULT_PACKED_STRUCT {
+  // bits 5-7: rsvd for future use
+  // bits 0-4: sequence number
+  uint8_t hdr;
+  uint8_t chunk[];
+} sMdsDataExportPayload;
 
 typedef struct {
   ble_service_t svc;
 
-  uint16_t version_h;
+  uint16_t supported_features_h;
   uint16_t data_uri_h;
   uint16_t auth_h;
   uint16_t device_id_h;
@@ -100,13 +114,13 @@ typedef struct {
   // second request will be ignored.
   struct {
     bool active;
+    eMdsDataExportMode mode;
+    uint8_t seq_num; // current sequence number to use
     uint16_t conn_idx;
   } subscriber;
 
-  struct {
-    void *buf;
-    size_t buf_len;
-  } chunk;
+  sMdsDataExportPayload *payload;
+  size_t chunk_len;
 
   TimerHandle_t timer;
 } md_service_t;
@@ -115,6 +129,7 @@ typedef enum {
   kMdsAppError_InvalidLength = ATT_ERROR_APPLICATION_ERROR,
   kMdsAppError_ClientAlreadySubscribed,
   kMdsAppError_InsufficientLength,
+  kMdsAppError_ClientNotSubscribed,
 } eMdsAppError;
 
 static md_service_t *s_mds;
@@ -135,6 +150,8 @@ static void prv_handle_disconnected_evt(ble_service_t *svc,
   if (mds->subscriber.active && (mds->subscriber.conn_idx == evt->conn_idx)) {
     mds->subscriber.active = false;
     mds->subscriber.conn_idx = 0;
+    mds->subscriber.seq_num = 0;
+    mds->subscriber.mode = kMdsDataExportMode_StreamingDisabled;
   }
 
   xTimerStop(mds->timer, 0);
@@ -147,29 +164,37 @@ static void prv_try_notify(md_service_t *mds, uint16_t conn_idx) {
     return;
   }
 
+  if (mds->subscriber.mode == kMdsDataExportMode_StreamingDisabled) {
+    // client has subscribed but not yet enabled data export
+    return;
+  }
+
   uint16_t mtu_size = 0;
   ble_error_t rv = ble_gattc_get_mtu(conn_idx, &mtu_size);
   if (rv != BLE_STATUS_OK) {
     return;
   }
 
-  if ((mds->chunk.buf == NULL) && memfault_packetizer_data_available()) {
-    mds->chunk.buf = OS_MALLOC(mtu_size - MDS_ATT_HEADER_OVERHEAD);
-    if (mds->chunk.buf != NULL) {
-      mds->chunk.buf_len = mtu_size - MDS_ATT_HEADER_OVERHEAD;
-      memfault_packetizer_get_chunk(mds->chunk.buf, &mds->chunk.buf_len);
+  if ((mds->payload == NULL) && memfault_packetizer_data_available()) {
+    mds->payload = OS_MALLOC(mtu_size - MDS_ATT_HEADER_OVERHEAD);
+    if (mds->payload != NULL) {
+      mds->payload->hdr = mds->subscriber.seq_num & 0x1f;
+      mds->chunk_len = mtu_size - MDS_ATT_HEADER_OVERHEAD - sizeof(*mds->payload);
+      memfault_packetizer_get_chunk(&mds->payload->chunk[0], &mds->chunk_len);
     }
   }
 
-  if (mds->chunk.buf_len != 0) {
+  if (mds->chunk_len != 0) {
+
     rv = ble_gatts_send_event(conn_idx, mds->chunk_val_h, GATT_EVENT_NOTIFICATION,
-                              mds->chunk.buf_len, mds->chunk.buf);
+                              mds->chunk_len + sizeof(*mds->payload), mds->payload);
     if (rv == BLE_STATUS_OK) {
+      mds->subscriber.seq_num = (mds->subscriber.seq_num + 1) % MDS_TOTAL_SEQ_NUMBERS;
       // Note: No need to schedule a retry since we will pump more data when the sent callback is
       // invoked for the current notification
-      OS_FREE(mds->chunk.buf);
-      mds->chunk.buf = NULL;
-      mds->chunk.buf_len = 0;
+      OS_FREE(mds->payload);
+      mds->payload = NULL;
+      mds->chunk_len = 0;
       return;
     }
   }
@@ -216,9 +241,9 @@ static void prv_handle_read_req(ble_service_t *svc,
   char uri[MDS_MAX_DATA_URI_LENGTH];
   struct MemfaultDeviceInfo info;
 
-  if (evt->handle == mds->version_h) {
-    value = &s_mds_version;
-    length = sizeof(s_mds_version);
+  if (evt->handle == mds->supported_features_h) {
+    value = &s_mds_supported_features;
+    length = sizeof(s_mds_supported_features);
   } else if (evt->handle == mds->data_uri_h) {
     memfault_platform_get_device_info(&info);
     strncpy(uri, MDS_URI_BASE, sizeof(uri) - 1);
@@ -282,7 +307,7 @@ static att_error_t prv_handle_cccd_write(md_service_t *mds, uint16_t conn_idx,
   const bool subscribe_for_notifs = ((cccd & GATT_CCC_NOTIFICATIONS) != 0);
   if (!mds->subscriber.active) {
     // NB: we expect caller to subscribe for notifications each time they connect
-    // so don't persist the state across disconnects _and_ we only allow one
+    // so don't persist the mode across disconnects _and_ we only allow one
     // active subscription at a time.
     mds->subscriber.active = subscribe_for_notifs;
     mds->subscriber.conn_idx = conn_idx;
@@ -298,6 +323,37 @@ static att_error_t prv_handle_cccd_write(md_service_t *mds, uint16_t conn_idx,
   return ATT_ERROR_OK;
 }
 
+static att_error_t prv_handle_data_export_write(md_service_t *mds, uint16_t conn_idx,
+                                                uint16_t offset, uint16_t length,
+                                                const uint8_t *value) {
+  if (offset != 0) {
+    return ATT_ERROR_ATTRIBUTE_NOT_LONG;
+  }
+
+  if (length != sizeof(uint8_t)) {
+    return kMdsAppError_InvalidLength;
+  }
+
+  if ((!mds->subscriber.active) || (mds->subscriber.conn_idx != conn_idx)) {
+    return kMdsAppError_ClientNotSubscribed;
+  }
+
+  const eMdsDataExportMode cmd = (eMdsDataExportMode)get_u8(value);
+
+  switch (cmd) {
+    case kMdsDataExportMode_StreamingDisabled:
+    case kMdsDataExportMode_FullStreamingEnabled:
+      break;
+    default:
+      return ATT_ERROR_REQUEST_NOT_SUPPORTED;
+  }
+
+  mds->subscriber.mode = cmd;
+  prv_try_notify(mds, conn_idx);
+
+  return ATT_ERROR_OK;
+}
+
 static void prv_handle_write_req(ble_service_t *svc,
                              const ble_evt_gatts_write_req_t *evt) {
   if (!mds_access_enabled(evt->conn_idx)) {
@@ -312,22 +368,18 @@ static void prv_handle_write_req(ble_service_t *svc,
   if (evt->handle == mds->chunk_cccd_h) {
     status = prv_handle_cccd_write(mds, evt->conn_idx, evt->offset, evt->length,
                                    evt->value);
-    if (status == ATT_ERROR_OK) {
-      // Empirically, sending a notification immediately will wind up getting flushed
-      // before the response for the CCCD write so we defer starting to send chunk
-      // notifications so they do not arrive out of order
-      xTimerChangePeriod(mds->timer, 10, 0);
-      xTimerStart(mds->timer, 0);
-    }
+  } else if (evt->handle == mds->chunk_val_h) {
+    status = prv_handle_data_export_write(mds, evt->conn_idx, evt->offset, evt->length,
+                                          evt->value);
   }
 
   ble_gatts_write_cfm(evt->conn_idx, evt->handle, status);
 }
 
 static void prv_cleanup_service(ble_service_t *svc) {
   md_service_t *mds = (md_service_t *)svc;
-  if (mds->chunk.buf != NULL) {
-    OS_FREE(mds->chunk.buf);
+  if (mds->payload != NULL) {
+    OS_FREE(mds->payload);
   }
   if (mds->timer != NULL) {
     xTimerDelete(mds->timer, portMAX_DELAY);
@@ -365,7 +417,7 @@ void *mds_boot(void) {
 
   ble_uuid_from_string("54220001-f6a5-4007-a371-722f4ebd8436", &uuid);
   ble_gatts_add_characteristic(&uuid, GATT_PROP_READ, ATT_PERM_RW, sizeof(uint8_t),
-                               GATTS_FLAG_CHAR_READ_REQ, NULL, &mds->version_h);
+                               GATTS_FLAG_CHAR_READ_REQ, NULL, &mds->supported_features_h);
 
   ble_uuid_from_string("54220002-f6a5-4007-a371-722f4ebd8436", &uuid);
   ble_gatts_add_characteristic(&uuid, GATT_PROP_READ, ATT_PERM_RW, sizeof(uint8_t),
@@ -380,13 +432,13 @@ void *mds_boot(void) {
                                GATTS_FLAG_CHAR_READ_REQ, NULL, &mds->auth_h);
 
   ble_uuid_from_string("54220005-f6a5-4007-a371-722f4ebd8436", &uuid);
-  ble_gatts_add_characteristic(&uuid, GATT_PROP_NOTIFY, ATT_PERM_RW, sizeof(uint8_t),
+  ble_gatts_add_characteristic(&uuid, GATT_PROP_NOTIFY | GATT_PROP_WRITE, ATT_PERM_RW, sizeof(uint8_t),
                                GATTS_FLAG_CHAR_READ_REQ, NULL, &mds->chunk_val_h);
 
   ble_uuid_create16(UUID_GATT_CLIENT_CHAR_CONFIGURATION, &uuid);
   ble_gatts_add_descriptor(&uuid, ATT_PERM_RW, 2, 0, &mds->chunk_cccd_h);
 
-  ble_gatts_register_service(&mds->svc.start_h, &mds->version_h, &mds->device_id_h,
+  ble_gatts_register_service(&mds->svc.start_h, &mds->supported_features_h, &mds->device_id_h,
                              &mds->data_uri_h, &mds->auth_h, &mds->chunk_val_h,
                              &mds->chunk_cccd_h, 0);
 

ports/include/memfault/ports/ble/mds.h

@@ -13,10 +13,11 @@
 //!
 //! Memfault Diagnostic Service: (UUID 54220000-f6a5-4007-a371-722f4ebd8436)
 //!
-//!  MDS Version Characteristic:           (UUID 54220001-f6a5-4007-a371-722f4ebd8436)
-//!   read - (length: 3 bytes) returns the version of this profile where there is 1 byte for Major,
-//!    Minor, & Patch Version
-//!   Version 1.0.0 = Initial gatt service definition and prototype implementation
+//!  MDS Supported Features Characteristic: (UUID 54220001-f6a5-4007-a371-722f4ebd8436)
+//!   read - (length: variable*)
+//!   Octet 0:
+//!      bit 0-7: rsvd for future use
+//!    ...
 //!
 //!  MDS Device Identifier Characteristic: (UUID 54220002-f6a5-4007-a371-722f4ebd8436)
 //!   read - (length: variable*) returns the device identifier populated in the
@@ -30,11 +31,26 @@
 //!     "Memfault-Project-Key:YOUR_PROJECT_KEY"
 //!
 //!  MDS Data Export Characteristic:       (UUID 54220005-f6a5-4007-a371-722f4ebd8436)
-//!   notify
-//!    When subscribed to, streams any collected SDK data to listener as opaque packets.
-//!    Packets will be sized to fit within negotiated MTU. Listener is responsible
-//!    for forwarding chunks to the URI specified in the Data URI Characteristic using
-//!    the authorization scheme specified in the Authorization Characteristic.
+//!   notify - must be subscribed to in order for any collected SDK data to be streamed
+//!   write - (length: 1 byte) controls data export operation mode
+//!    0x00 - Streaming Disabled
+//!    0x01 - Streaming of any collected SDK data enabled
+//!    Other: reserved for future use
+//!
+//!    When subscribed to and when streaming mode has been enabled via a GATT Write with response,
+//!    packets will be sized to fit within negotiated MTU.
+//!    The format of a packet streamed is as follows:
+//!     byte 0:
+//!      bits 0-4: Sequence Number A sequentially increasing counter that can be used to detect
+//!       errors in the BLE stack. SN is reset to 0 anytime a disconnect takes place.
+//!       Errors client can check for:
+//!          - Packets are getting repeated when Last Sequence Number == Current Sequence Number
+//!          - Packets are getting dropped  when abs(Last Sequence Number - Current Sequence Number) != 1
+//!      bit 5-7: Reserved for future use
+//!
+//!     byte 1-N: opaque payload listener is responsible for forwarding to the URI specified in the Data URI
+//!        Characteristic using the authorization scheme specified in the Authorization Characteristic.
+//!
 //!   Client Characteristic Configuration Descriptor: (UUID 00002902-0000-1000-8000-00805f9b34fb)
 //!
 //! * If length exceeds negotiated MTU size, it is assumed that client has implemented support for
@@ -51,8 +67,8 @@
 //!
 //! Note 3: 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 Version Characteristic and only attempt to use the service
-//! as it is currently defined if the Major Version == 1.
+//! 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.
 
 #ifdef __cplusplus
 extern "C" {

ports/particle/README.md

@@ -10,18 +10,18 @@ The library is compatible with all versions of
 [Device OS](https://github.com/particle-iot/device-os) greater than or equal to
 Device OS 3.0
 
-:exclamation: Note: The
+:exclamation: Note: Use the
 [particle-firmware-library](https://github.com/memfault/particle-firmware-library)
-to include this in your project. This repository is updated as part of the
-release process for the
+repository to add memfault support to an application. This repository is updated
+as part of the release process for the
 [memfault-firmware-sdk](https://github.com/memfault/memfault-firmware-sdk).
 
 ## Welcome to your library!
 
 To get started, add the library to your particle application:
 
 ```bash
-$ git clone https://github.com/memfault/particle-firmware-library lib/memfault
+$ git submodule add https://github.com/memfault/particle-firmware-library lib/memfault
 ```
 
 ## Integration Steps

ports/zephyr/Kconfig

@@ -5,7 +5,6 @@ config MEMFAULT
         select RUNTIME_NMI
         select EXTRA_EXCEPTION_INFO
         select DEBUG_THREAD_INFO
-        select OPENOCD_SUPPORT
         help
           Enable Zephyr Integration with the Memfault SDK
           At the moment a port is only provided for Cortex-M based targets

ports/zephyr/common/memfault_platform_core.c

@@ -5,17 +5,31 @@
 
 #include "memfault/core/platform/core.h"
 
-#include <soc.h>
 #include <init.h>
+#include <soc.h>
 
 #include "memfault/core/build_info.h"
 #include "memfault/core/compiler.h"
 #include "memfault/core/event_storage.h"
-#include "memfault/core/platform/core.h"
 #include "memfault/core/reboot_tracking.h"
 #include "memfault/core/trace_event.h"
 #include "memfault/panics/coredump.h"
 #include "memfault/ports/reboot_reason.h"
+#include "memfault/ports/zephyr/version.h"
+
+#if !MEMFAULT_ZEPHYR_VERSION_GT(2, 5)
+
+// Note: CONFIG_OPENOCD_SUPPORT was deprecated in Zephyr 2.6 and fully removed in the 3.x line. To
+// maintain backward compatibility with older versions of Zephyr we inline the check here.
+//
+// When support for Zephyr <= 2.5 is removed, we should adopt an approach like the following
+//  https://github.com/memfault/memfault-firmware-sdk/pull/26
+
+#if !CONFIG_OPENOCD_SUPPORT
+#error "CONFIG_OPENOCD_SUPPORT=y must be added to your prj.conf"
+#endif
+
+#endif
 
 #if CONFIG_MEMFAULT_METRICS
 #include "memfault/metrics/metrics.h"

scripts/mflt-build-id/.gitignore

@@ -0,0 +1 @@
+/build/