BLEManager changes

-- Introduced a new WoBLEAdvertisingChange device event that gets generated whenever the
BLEManager starts and stops WoBLE advertising.

-- Added method to ConnectivityManager to determine whether WoBLE advertising is currently
active.

-- Fixed logic bugs in the transition between fast and slow WoBLE advertising.  The system
will now properly transition between the two modes when the device’s provisioning state
changes, or when expressly asked to by the application.

-- Eliminated subtle race condition on Nordic platforms where WoBLE would be disabled
entirely due to an unexpected error from the SoftDevice if a connection arrived just as the
BLEManager was updating the advertising configuration.

-- Renamed BLEManager internal flag values and added documentation to make their meaning
clearer.

Author: Jay Logue

src/adaptations/device-layer/ESP32/BLEManagerImpl.cpp

@@ -242,21 +242,26 @@ void BLEManagerImpl::_OnPlatformEvent(const WeaveDeviceEvent * event)
         HandleConnectionError(event->WoBLEConnectionError.ConId, event->WoBLEConnectionError.Reason);
         break;
 
-    // If WOBLE_DISABLE_ADVERTISING_WHEN_PROVISIONED is enabled, and there is a change to the
-    // device's provisioning state, then automatically disable WoBLE advertising if the device
-    // is now fully provisioned.
-#if WEAVE_DEVICE_CONFIG_WOBLE_DISABLE_ADVERTISING_WHEN_PROVISIONED
     case DeviceEventType::kFabricMembershipChange:
     case DeviceEventType::kServiceProvisioningChange:
     case DeviceEventType::kAccountPairingChange:
+
+        // If WOBLE_DISABLE_ADVERTISING_WHEN_PROVISIONED is enabled, and there is a change to the
+        // device's provisioning state, then automatically disable WoBLE advertising if the device
+        // is now fully provisioned.
+#if WEAVE_DEVICE_CONFIG_WOBLE_DISABLE_ADVERTISING_WHEN_PROVISIONED
         if (ConfigurationMgr().IsFullyProvisioned())
         {
-            SetAdvertisingEnabled(false);
+            ClearFlag(mFlags, kFlag_AdvertisingEnabled);
             WeaveLogProgress(DeviceLayer, "WoBLE advertising disabled because device is fully provisioned");
         }
-        break;
 #endif // WEAVE_DEVICE_CONFIG_WOBLE_DISABLE_ADVERTISING_WHEN_PROVISIONED
 
+        // Force the advertising configuration to be refreshed to reflect new provisioning state.
+        ClearFlag(mFlags, kFlag_AdvertisingConfigured);
+
+        DriveBLEState();
+
     default:
         break;
     }
@@ -450,7 +455,7 @@ void BLEManagerImpl::DriveBLEState(void)
         }
 
         // Start advertising if needed.
-        if (!GetFlag(mFlags, kFlag_Advertising))
+        if (!GetFlag(mFlags, kFlag_Advertising) || GetFlag(mFlags, kFlag_AdvertisingRefreshNeeded))
         {
             err = StartAdvertising();
             ExitNow();
@@ -694,9 +699,10 @@ WEAVE_ERROR BLEManagerImpl::StartAdvertising(void)
     bool connectable = (numCons < kMaxConnections);
     advertParams.adv_type = connectable ? ADV_TYPE_IND : ADV_TYPE_NONCONN_IND;
 
-    // Advertise in fast mode if not paired to an account and there are no WoBLE connections.
+    // Advertise in fast mode if not fully provisioned and there are no WoBLE connections, or
+    // if the application has expressly requested fast advertising.
     advertParams.adv_int_min = advertParams.adv_int_max =
-        (numCons == 0 && !ConfigurationMgr().IsPairedToAccount())
+        ((numCons == 0 && !ConfigurationMgr().IsFullyProvisioned()) || GetFlag(mFlags, kFlag_FastAdvertisingEnabled))
         ? WEAVE_DEVICE_CONFIG_BLE_FAST_ADVERTISING_INTERVAL
         : WEAVE_DEVICE_CONFIG_BLE_SLOW_ADVERTISING_INTERVAL;
 
@@ -839,8 +845,10 @@ void BLEManagerImpl::HandleGATTCommEvent(esp_gatts_cb_event_t event, esp_gatt_if
         // Allocate a connection state record for the new connection.
         GetConnectionState(param->mtu.conn_id, true);
 
-        // Receiving a connection stops the advertising processes, so update the advertising state accordingly.
-        ClearFlag(mFlags, kFlag_Advertising);
+        // Receiving a connection stops the advertising processes.  So record that the advertising state
+        // in the ESP BLE layer needs to be refreshed.  If advertising should to be re-enabled, this will
+        // be handled in DriveBLEState() the next time it runs.
+        SetFlag(mFlags, kFlag_AdvertisingRefreshNeeded);
 
         // Re-evaluate the advertising state in light of the new connection.
         PlatformMgr().ScheduleWork(DriveBLEState, 0);
@@ -1211,11 +1219,24 @@ void BLEManagerImpl::HandleGAPEvent(esp_gap_ble_cb_event_t event, esp_ble_gap_cb
             ExitNow(err = ESP_ERR_INVALID_RESPONSE);
         }
 
-        WeaveLogProgress(DeviceLayer, "WoBLE advertising started");
-
-        SetFlag(sInstance.mFlags, kFlag_Advertising);
         ClearFlag(sInstance.mFlags, kFlag_ControlOpInProgress);
 
+        // Transition to the Advertising state...
+        if (!GetFlag(sInstance.mFlags, kFlag_Advertising))
+        {
+            WeaveLogProgress(DeviceLayer, "WoBLE advertising started");
+
+            SetFlag(sInstance.mFlags, kFlag_Advertising);
+
+            // Post a WoBLEAdvertisingChange(Started) event.
+            {
+                WeaveDeviceEvent advChange;
+                advChange.Type = DeviceEventType::kWoBLEAdvertisingChange;
+                advChange.WoBLEAdvertisingChange.Result = kActivity_Started;
+                PlatformMgr().PostEvent(&advChange);
+            }
+        }
+
         break;
 
     case ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT:
@@ -1226,16 +1247,29 @@ void BLEManagerImpl::HandleGAPEvent(esp_gap_ble_cb_event_t event, esp_ble_gap_cb
             ExitNow(err = ESP_ERR_INVALID_RESPONSE);
         }
 
-        ClearFlag(sInstance.mFlags, kFlag_Advertising);
         ClearFlag(sInstance.mFlags, kFlag_ControlOpInProgress);
 
-        WeaveLogProgress(DeviceLayer, "WoBLE advertising stopped");
+        // Transition to the not Advertising state...
+        if (GetFlag(sInstance.mFlags, kFlag_Advertising))
+        {
+            ClearFlag(sInstance.mFlags, kFlag_Advertising);
 
-        // Inform the ThreadStackManager that WoBLE advertising has stopped.
+            WeaveLogProgress(DeviceLayer, "WoBLE advertising stopped");
+
+            // Directly inform the ThreadStackManager that WoBLE advertising has stopped.
 #if WEAVE_DEVICE_CONFIG_ENABLE_THREAD
-        ThreadStackMgr().OnWoBLEAdvertisingStop();
+            ThreadStackMgr().OnWoBLEAdvertisingStop();
 #endif // WEAVE_DEVICE_CONFIG_ENABLE_THREAD
 
+            // Post a WoBLEAdvertisingChange(Stopped) event.
+            {
+                WeaveDeviceEvent advChange;
+                advChange.Type = DeviceEventType::kWoBLEAdvertisingChange;
+                advChange.WoBLEAdvertisingChange.Result = kActivity_Stopped;
+                PlatformMgr().PostEvent(&advChange);
+            }
+        }
+
         break;
 
     default:

src/adaptations/device-layer/include/Weave/DeviceLayer/ConnectivityManager.h

@@ -157,6 +157,7 @@ class ConnectivityManager
     WEAVE_ERROR SetBLEAdvertisingEnabled(bool val);
     bool IsBLEFastAdvertisingEnabled(void);
     WEAVE_ERROR SetBLEFastAdvertisingEnabled(bool val);
+    bool IsBLEAdvertising(void);
     WEAVE_ERROR GetBLEDeviceName(char * buf, size_t bufSize);
     WEAVE_ERROR SetBLEDeviceName(const char * deviceName);
     uint16_t NumBLEConnections(void);
@@ -479,6 +480,11 @@ inline WEAVE_ERROR ConnectivityManager::SetBLEFastAdvertisingEnabled(bool val)
     return static_cast<ImplClass*>(this)->_SetBLEFastAdvertisingEnabled(val);
 }
 
+inline bool ConnectivityManager::IsBLEAdvertising(void)
+{
+    return static_cast<ImplClass*>(this)->_IsBLEAdvertising();
+}
+
 inline WEAVE_ERROR ConnectivityManager::GetBLEDeviceName(char * buf, size_t bufSize)
 {
     return static_cast<ImplClass*>(this)->_GetBLEDeviceName(buf, bufSize);

src/adaptations/device-layer/include/Weave/DeviceLayer/ESP32/BLEManagerImpl.h

@@ -58,6 +58,7 @@ class BLEManagerImpl final
     WEAVE_ERROR _SetAdvertisingEnabled(bool val);
     bool _IsFastAdvertisingEnabled(void);
     WEAVE_ERROR _SetFastAdvertisingEnabled(bool val);
+    bool _IsAdvertising(void);
     WEAVE_ERROR _GetDeviceName(char * buf, size_t bufSize);
     WEAVE_ERROR _SetDeviceName(const char * deviceName);
     uint16_t _NumConnections(void);
@@ -90,18 +91,18 @@ class BLEManagerImpl final
 
     enum
     {
-        kFlag_AsyncInitCompleted        = 0x0001,
-        kFlag_ESPBLELayerInitialized    = 0x0002,
-        kFlag_AppRegistered             = 0x0004,
-        kFlag_AttrsRegistered           = 0x0008,
-        kFlag_GATTServiceStarted        = 0x0010,
-        kFlag_AdvertisingConfigured     = 0x0020,
-        kFlag_Advertising               = 0x0040,
-        kFlag_ControlOpInProgress       = 0x0080,
-
-        kFlag_AdvertisingEnabled        = 0x0100,
-        kFlag_FastAdvertisingEnabled    = 0x0200,
-        kFlag_UseCustomDeviceName       = 0x0400,
+        kFlag_AsyncInitCompleted        = 0x0001, /**< One-time asynchronous initialization actions have been performed. */
+        kFlag_ESPBLELayerInitialized    = 0x0002, /**< The ESP BLE layer has been initialized. */
+        kFlag_AppRegistered             = 0x0004, /**< The WoBLE application has been registered with the ESP BLE layer. */
+        kFlag_AttrsRegistered           = 0x0008, /**< The WoBLE GATT attributes have been registered with the ESP BLE layer. */
+        kFlag_GATTServiceStarted        = 0x0010, /**< The WoBLE GATT service has been started. */
+        kFlag_AdvertisingConfigured     = 0x0020, /**< WoBLE advertising has been configured in the ESP BLE layer. */
+        kFlag_Advertising               = 0x0040, /**< The system is currently WoBLE advertising. */
+        kFlag_ControlOpInProgress       = 0x0080, /**< An async control operation has been issued to the ESP BLE layer. */
+        kFlag_AdvertisingEnabled        = 0x0100, /**< The application has enabled WoBLE advertising. */
+        kFlag_FastAdvertisingEnabled    = 0x0200, /**< The application has enabled fast advertising. */
+        kFlag_UseCustomDeviceName       = 0x0400, /**< The application has configured a custom BLE device name. */
+        kFlag_AdvertisingRefreshNeeded  = 0x0800, /**< The advertising state in ESP BLE layer needs to be updated. */
     };
 
     enum
@@ -192,6 +193,11 @@ inline bool BLEManagerImpl::_IsFastAdvertisingEnabled(void)
     return GetFlag(mFlags, kFlag_FastAdvertisingEnabled);
 }
 
+inline bool BLEManagerImpl::_IsAdvertising(void)
+{
+    return GetFlag(mFlags, kFlag_Advertising);
+}
+
 } // namespace Internal
 } // namespace DeviceLayer
 } // namespace Weave

src/adaptations/device-layer/include/Weave/DeviceLayer/WeaveDeviceEvent.h

@@ -189,6 +189,13 @@ enum PublicEventTypes
      * Signals that the state of the Thread network interface has changed.
      */
     kThreadInterfaceStateChange,
+
+    /**
+     * Weave-over-BLE (WoBLE) Advertising Change
+     *
+     * Signals that the state of WoBLE advertising has changed.
+     */
+    kWoBLEAdvertisingChange,
 };
 
 /**
@@ -226,6 +233,18 @@ enum ConnectivityChange
     kConnectivity_Lost          = -1
 };
 
+/**
+ * Activity Change
+ *
+ * Describes a change in some activity associated with a Weave device.
+ */
+enum ActivityChange
+{
+    kActivity_NoChange          = 0,
+    kActivity_Started           = 1,
+    kActivity_Stopped           = -1,
+};
+
 inline ConnectivityChange GetConnectivityChange(bool prevState, bool newState)
 {
     if (prevState == newState)
@@ -374,6 +393,10 @@ struct WeaveDeviceEvent final
                 uint32_t Flags;
             } OpenThread;
         } ThreadStateChange;
+        struct
+        {
+            ActivityChange Result;
+        } WoBLEAdvertisingChange;
     };
 
     void Clear() { memset(this, 0, sizeof(*this)); }

src/adaptations/device-layer/include/Weave/DeviceLayer/internal/BLEManager.h

@@ -59,6 +59,7 @@ class BLEManager
     WEAVE_ERROR SetAdvertisingEnabled(bool val);
     bool IsFastAdvertisingEnabled(void);
     WEAVE_ERROR SetFastAdvertisingEnabled(bool val);
+    bool IsAdvertising(void);
     WEAVE_ERROR GetDeviceName(char * buf, size_t bufSize);
     WEAVE_ERROR SetDeviceName(const char * deviceName);
     uint16_t NumConnections(void);
@@ -148,6 +149,11 @@ inline WEAVE_ERROR BLEManager::SetFastAdvertisingEnabled(bool val)
     return static_cast<ImplClass*>(this)->_SetFastAdvertisingEnabled(val);
 }
 
+inline bool BLEManager::IsAdvertising(void)
+{
+    return static_cast<ImplClass*>(this)->_IsAdvertising();
+}
+
 inline WEAVE_ERROR BLEManager::GetDeviceName(char * buf, size_t bufSize)
 {
     return static_cast<ImplClass*>(this)->_GetDeviceName(buf, bufSize);

src/adaptations/device-layer/include/Weave/DeviceLayer/internal/GenericConnectivityManagerImpl_BLE.h

@@ -61,6 +61,7 @@ class GenericConnectivityManagerImpl_BLE
     WEAVE_ERROR _SetBLEAdvertisingEnabled(bool val);
     bool _IsBLEFastAdvertisingEnabled(void);
     WEAVE_ERROR _SetBLEFastAdvertisingEnabled(bool val);
+    bool _IsBLEAdvertising(void);
     WEAVE_ERROR _GetBLEDeviceName(char * buf, size_t bufSize);
     WEAVE_ERROR _SetBLEDeviceName(const char * deviceName);
     uint16_t _NumBLEConnections(void);
@@ -110,6 +111,12 @@ inline WEAVE_ERROR GenericConnectivityManagerImpl_BLE<ImplClass>::_SetBLEFastAdv
     return BLEMgr().SetFastAdvertisingEnabled(val);
 }
 
+template<class ImplClass>
+inline bool GenericConnectivityManagerImpl_BLE<ImplClass>::_IsBLEAdvertising(void)
+{
+    return BLEMgr().IsAdvertising();
+}
+
 template<class ImplClass>
 inline WEAVE_ERROR GenericConnectivityManagerImpl_BLE<ImplClass>::_GetBLEDeviceName(char * buf, size_t bufSize)
 {

src/adaptations/device-layer/include/Weave/DeviceLayer/nRF5/BLEManagerImpl.h

@@ -57,6 +57,7 @@ class BLEManagerImpl final
     WEAVE_ERROR _SetAdvertisingEnabled(bool val);
     bool _IsFastAdvertisingEnabled(void);
     WEAVE_ERROR _SetFastAdvertisingEnabled(bool val);
+    bool _IsAdvertising(void);
     WEAVE_ERROR _GetDeviceName(char * buf, size_t bufSize);
     WEAVE_ERROR _SetDeviceName(const char * deviceName);
     uint16_t _NumConnections(void);
@@ -89,11 +90,11 @@ class BLEManagerImpl final
 
     enum
     {
-        kFlag_AsyncInitCompleted                = 0x0001,
-        kFlag_AdvertisingEnabled                = 0x0002,
-        kFlag_FastAdvertisingEnabled            = 0x0004,
-        kFlag_Advertising                       = 0x0008,
-        kFlag_AdvertisingConfigChangePending    = 0x0010,
+        kFlag_AsyncInitCompleted                = 0x0001, /**< One-time asynchronous initialization actions have been performed. */
+        kFlag_AdvertisingEnabled                = 0x0002, /**< The application has enabled WoBLE advertising. */
+        kFlag_FastAdvertisingEnabled            = 0x0004, /**< The application has enabled fast advertising. */
+        kFlag_Advertising                       = 0x0008, /**< The system is currently WoBLE advertising. */
+        kFlag_AdvertisingRefreshNeeded          = 0x0010, /**< The advertising state/configuration has changed, but the SoftDevice has yet to be updated. */
     };
 
     enum
@@ -174,6 +175,11 @@ inline bool BLEManagerImpl::_IsFastAdvertisingEnabled(void)
     return GetFlag(mFlags, kFlag_FastAdvertisingEnabled);
 }
 
+inline bool BLEManagerImpl::_IsAdvertising(void)
+{
+    return GetFlag(mFlags, kFlag_Advertising);
+}
+
 } // namespace Internal
 } // namespace DeviceLayer
 } // namespace Weave