Merge pull request #14672 from paul-szczepanek-arm/fix-advertising-start

BLE: Fix advertising start and stop

Author: 0xc0170

connectivity/FEATURE_BLE/include/ble/Gap.h

@@ -747,7 +747,9 @@ class Gap {
      * @param handle Advertising set handle.
      * @param maxDuration Max duration for advertising (in units of 10ms) - 0 means no limit.
      * @param maxEvents Max number of events produced during advertising - 0 means no limit.
-     * @return BLE_ERROR_NONE on success.
+     * @return BLE_ERROR_NONE on success. This does not guarantee the set has started if
+     * extended advertising is enabled. Register an event handler and wait for onAdvertisingStart
+     * event. An (unlikely) failed start the status of the event will contain an error.
      *
      * @see EventHandler::onAdvertisingStart when the advertising starts.
      * @see EventHandler::onScanRequestReceived when a scan request is received.
@@ -765,7 +767,9 @@ class Gap {
      *  which will not be affected.
      *
      * @param handle Advertising set handle.
-     * @return BLE_ERROR_NONE on success.
+     * @return BLE_ERROR_NONE on success. For extented advertising this does not guarantee
+     * the set is stopped if. Register an event handler and wait for onAdvertisingEnd event.
+     * An (unlikely) failed stop the event status will contain the error code.
      */
     ble_error_t stopAdvertising(advertising_handle_t handle);
 

connectivity/FEATURE_BLE/include/ble/gap/Events.h

@@ -586,9 +586,10 @@ struct AdvertisingStartEvent {
     /** Create an advertising start event.
      *
      * @param advHandle Advertising set handle.
+     * @param status Advertising set start command status.
      */
-    AdvertisingStartEvent(advertising_handle_t advHandle) :
-        advHandle(advHandle)
+    AdvertisingStartEvent(advertising_handle_t advHandle, ble_error_t status = BLE_ERROR_NONE) :
+        advHandle(advHandle), status(status)
     {
     }
 
@@ -600,8 +601,15 @@ struct AdvertisingStartEvent {
         return advHandle;
     }
 
+    /** Get status of operation. */
+    ble_error_t getStatus() const
+    {
+        return status;
+    }
+
 private:
     advertising_handle_t advHandle;
+    ble_error_t status;
 };
 
 /**
@@ -610,7 +618,8 @@ struct AdvertisingStartEvent {
  * @see ble::Gap::EventHandler::onAdvertisingEnd().
  *
  * @note The connection handle, connected flag and completed_event fields are
- * valid if the flag legacy is not set to true.
+ * valid if the flag legacy is not set to true. If status is different from BLE_ERROR_NONE
+ * the completed_events field is not valid and the set may still be active.
  */
 struct AdvertisingEndEvent {
 #if !defined(DOXYGEN_ONLY)
@@ -621,18 +630,21 @@ struct AdvertisingEndEvent {
      * @param connection Connection handle.
      * @param completed_events Number of events created during before advertising end.
      * @param connected True if connection has been established.
+     * @param status Error code if stop command failed.
      */
     AdvertisingEndEvent(
         advertising_handle_t advHandle,
         connection_handle_t connection,
         uint8_t completed_events,
-        bool connected
+        bool connected,
+        ble_error_t status = BLE_ERROR_NONE
     ) :
         advHandle(advHandle),
         connection(connection),
         completed_events(completed_events),
         connected(connected),
-        legacy(false)
+        legacy(false),
+        status(status)
     {
     }
 
@@ -643,7 +655,8 @@ struct AdvertisingEndEvent {
         connection(),
         completed_events(0),
         connected(false),
-        legacy(true)
+        legacy(true),
+        status(BLE_ERROR_NONE)
     {
     }
 
@@ -683,12 +696,20 @@ struct AdvertisingEndEvent {
         return legacy;
     }
 
+    /** Get the result of the stop advertising event. If the status is not BLE_ERROR_NONE the set
+     * may still be active. */
+    ble_error_t getStatus() const
+    {
+        return status;
+    }
+
 private:
     advertising_handle_t advHandle;
     connection_handle_t connection;
     uint8_t completed_events;
     bool connected;
     bool legacy;
+    ble_error_t status;
 };
 
 /**

connectivity/FEATURE_BLE/mbed_lib.json

@@ -108,6 +108,11 @@
             "value": 16,
             "macro_name": "BLE_GAP_HOST_PRIVACY_RESOLVED_CACHE_SIZE"
         },
+        "ble-gap-host-max-advertising-start-commands": {
+            "help": "There can only be one outstanding advertising set command sent to the controller. This determines how many advertising set start commands can be queued on the host. Must be between 1 and BLE_GAP_MAX_ADVERTISING_SETS. If privacy is used, this must be at equal or higher than then number of simultaneously active sets with a private address.",
+            "value": 4,
+            "macro_name": "BLE_GAP_HOST_MAX_OUTSTANDING_ADVERTISING_START_COMMANDS"
+        },
 
         "ble-passkey-display-reversed-digits-deprecation": {
           "help": "This option is part of the deprecation process. Set this to false to remove the deprecation notice. When set to true, the digits in the SecurityManager passkeyDiplay event are reversed. When set to false the digits are in the correct order.",