Generic Access Profile (GAP)

The GAP layer of the Bluetooth Low Energy protocol stack is responsible for connection functionality. This layer handles the access modes and procedures of the device including device discovery, link establishment, link termination, initiation of security features, and device configuration. See GAP State Diagram. for more details.

Figure 66. GAP State Diagram.

Based on the role for which the device is configured, GAP State Diagram. shows the states of the device. The following describes these states.

• Standby: The device is in the initial idle state upon reset.

• Advertiser: The device is advertising with specific data letting any scanner/initiator devices know its existence. (This advertisement contains the device address and can contain some additional data such as the device name).

• Scanner: When receiving the advertisement, the scanning device can send a scan request to the advertiser. The advertiser responds with a scan response. This process is called device discovery. The scanning device is aware of the advertising device and can initiate a connection with it.

• Initiator: When initiating, the initiator must specify a peer device address to which to connect. If an advertisement is received matching that address of the peer device, the initiating device then sends out a request to establish a connection (link) with the advertising device with the connection parameters described in GAP Connection State.

• Peripheral/Central: When a connection is formed, the device functions as a Peripheral if it is the advertiser and a Central if it is the initiator.

Bluetooth devices operate in one or more GAP roles based on the application use case. The GAP roles utilize one or more of the GAP states. Based on this configuration, many Bluetooth Low Energy protocol stack events are handled directly by the main application task and sometimes routed from the GAP Bond Manager. The application can register with the stack to be notified of certain events.

GAP Roles

Based on the configuration of the device, the GAP layer always operates in one of four (4) roles as defined by the specification:

• Broadcaster - The device is an advertiser that is non connectable.

• Observer - The device scans for advertisements but cannot initiate connections.

• Peripheral - The device is an advertiser that is connectable and operates as Peripheral in a single link-layer connection.

• Central - The device scans for advertisements and initiates connections and operates as a Central in a single or multiple link-layer connections.

The Bluetooth Core Specifications Version 5.3 allows for certain combinations of multiple roles, which are supported by the Bluetooth Low Energy protocol stack. The following modules will modify and examine the basic_ble example project included in the SDK. For configuration of the Bluetooth Low Energy stack features, see Developing with SDK CC23xx and Stack Configurations.

Note

Bluetooth 5 also introduces new features including Extended Advertising. Bluetooth 5 supports legacy advertising maintaining backwards compatibility with previous versions. The following sections will describe how to operate the device for various GAP roles along with how to use the Extended Advertising features.

Warning

CC23xx devices do not support extended advertisement yet

The following sections will describe how to use the LE Advertising Extension feature. As its name suggests, the amount of advertising data that can be sent over the air has been extended from 31 bytes to 1650 bytes. Also multiple advertising sets can be created using a mix of legacy and extended advertisements. Extended advertisements introduces use the secondary advertising channels which uses the data channels to send extensive data in addition to the primary advertising channels (Ch. 37, 38, and 39) used in legacy advertisement.

GAP Constraints

• GAP Scanner can only scan one PHY per scanning cycle.

• The data length of the advertising data and the scan response data for Extended Advertising is limited to 1650 bytes. The connectable undirected advertising data is limited to 212 bytes. The connectable directed advertising data is limited to 206 bytes. For more information, refer to the Host Advertising Data section ([Vol 6], Part B, Section 2.3.4.9) of the Bluetooth Core Specifications Version 5.3.

GAP Advertiser

The application and profiles can directly call GAP API functions to perform Bluetooth Low Energy-related functions such as advertising or connecting. The GAP layer functionality is mostly defined in library code. The function headers can be found in gap.h. The advertising specific implementation is found in gap_advertiser.h. Most of these functions can be called directly.

Note

Here we will use the BLEAppUtil framework as example code which abstracts the direct gap api interaction, therefore, you may not see the actual gap APIs from the following code snippets.

The GAP Advertiser module lets you create advertisement sets. The application can then enable and disable the sets. This way, the application can quickly change the advertisement parameters and advertisement data. For example, an application can create an advertisement set for legacy advertising and one for long range advertising. If both sets are enabled, the application advertises both on the primary advertising channels with legacy advertising, and on a LE Coded PHY with the long range set. With long range advertising, more advertising data can be sent and connections can be formed from larger distances compared to legacy advertising.

Note

The advertisement data is de-coupled from the advertisement sets, so multiple sets can use the same advertisement data.

Multiple active advertising sets can set different advertising intervals. The figure below illustrate how two advertising sets with different intervals are scheduled. The intervals do not have to be multiples of each other. The advertising interval can be set in the .primIntMin and .primIntMax Advertisement Params (GapAdv_params_t) member before the advertisement set is enabled or during advertising as described in Changing advertising parameters.

Listing 28. app_peripheral.c :: Peripheral_start() - Change advertising interval before advertisment enable

  advSetInitParamsSet_1.advParam->primIntMin = 160; //100ms
  advSetInitParamsSet_1.advParam->primIntMax = 160; //100ms

  status = BLEAppUtil_initAdvSet(&peripheralAdvHandle_1, &advSetInitParamsSet_1);

Following shows an alternative for changing the advertising interval after the advertising set is initialized by using gap_advertiser.h.

Listing 29. app_peripheral.c :: Peripheral_start() - Change advertising interval after advertisment initialized

  status = BLEAppUtil_initAdvSet(&peripheralAdvHandle_1, &advSetInitParamsSet_1);

  uint32_t advInt = 160; //160*0.625ms = 100ms

  GapAdv_setParam(peripheralAdvHandle_1, GAP_ADV_PARAM_PRIMARY_INTERVAL_MIN, &advInt);
  GapAdv_setParam(peripheralAdvHandle_1, GAP_ADV_PARAM_PRIMARY_INTERVAL_MAX, &advInt);

Figure 67. Multiple AE Advertising sets with different interval.

The following list describes how to configure the GAP layer for advertising. The basic_ble example project will be used as an example.

Note

The advertisement set creation can be done using SysConfig.

Create Advertisement

1. Create Advertisement set with GapAdv_create(). This function expects application to register a callback, pass in advertising parameter and allocate a handle for the associated advertising set.

   The first step is to create a callback function. By using BLEAppUtil framework, the advertising callback function is already created.

   Listing 30. bleapputil_stack_callback.c :: BLEAppUtil_advCB() - Create Application Callback

   void BLEAppUtil_advCB(uint32_t event, GapAdv_data_t *pBuf, uint32_t *arg)
   {
       BLEAppUtil_AdvEventData_t *pData = BLEAppUtil_malloc(sizeof(BLEAppUtil_AdvEventData_t));
   
       if (pData)
       {
           pData->event = event;
           pData->pBuf = pBuf;
           pData->arg = arg;
   
           // Enqueue the event
           if (BLEAppUtil_enqueueMsg(BLEAPPUTIL_EVT_ADV_CB_EVENT, pData) != SUCCESS)
           {
               BLEAppUtil_free(pData);
           }
       }
   }
   

   Next we need to create advertising parameters with GapAdv_params_t struct which by default is generated using SysConfig tool.

   Listing 31. ti_ble_config.c :: advParams1 - Create Advertising Parameters

   GapAdv_params_t advParams1 = {
     .eventProps =   GAP_ADV_PROP_CONNECTABLE | GAP_ADV_PROP_LEGACY | GAP_ADV_PROP_SCANNABLE,
     .primIntMin =   160,
     .primIntMax =   160,
     .primChanMap =  GAP_ADV_CHAN_ALL,
     .peerAddrType = PEER_ADDRTYPE_PUBLIC_OR_PUBLIC_ID,
     .peerAddr =     { 0xaa, 0xaa, 0xaa, 0xaa, 0xaa, 0xaa },
     .filterPolicy = GAP_ADV_AL_POLICY_ANY_REQ,
     .txPower =      GAP_ADV_TX_POWER_NO_PREFERENCE,
     .primPhy =      GAP_ADV_PRIM_PHY_1_MBPS,
     .secPhy =       GAP_ADV_SEC_PHY_1_MBPS,
     .sid =          0
   };
   

   The Tx Power of legacy advertisements cannot be individually set.

   Lastly, we need to create a handle for this advertising set.

   Listing 32. app_peripheral.c - Create Advertising Handle 1

   //! Store handle needed for each advertise set
   uint8 peripheralAdvHandle_1;
   

   Now we have all the pieces ready, let’s see how the BLEAppUtil framework creates an advertising set.

   Listing 33. app_peripheral.c :: Peripheral_start - Application Layer Abstraction

   // Initialize Advertising Set
   status = BLEAppUtil_initAdvSet(&peripheralAdvHandle_1, &advSetInitParamsSet_1);
   

   Listing 34. bleapputil_init.c :: BLEAppUtil_initAdvSet - Dissect The Parameters

     bStatus_t BLEAppUtil_initAdvSet(uint8 *advHandle, const BLEAppUtil_AdvInit_t *advInitInfo)
     {
         return bleStk_initAdvSet(BLEAppUtil_advCB, advHandle, GAP_ADV_EVT_MASK_ALL,
                                  advInitInfo->advParam, advInitInfo->advDataLen ,
                                  advInitInfo->advData, advInitInfo->scanRespDataLen,
                                  advInitInfo->scanRespData);
     }
   

   Listing 35. ble_stack_api.c :: bleStk_initAdvSet - Create the Advertising Set

     bStatus_t bleStk_initAdvSet(pfnBleStkAdvCB_t advCallback, uint8_t *advHandle,
                                        GapAdv_eventMaskFlags_t eventMask,
                                        GapAdv_params_t *advParams,
                                        uint16_t advDataLen ,uint8_t advData[],
                                        uint16_t scanRespDataLen, uint8_t scanRespData[])
     {
       bStatus_t status;
   
     #ifdef ERPC_SERVER
      // keep the remote eRPC app callback
       remote_bleApp_GapAdvCb = advCallback;
   
       // Create Advertisement set and assign handle
       status = GapAdv_create((pfnGapCB_t)local_bleApp_GapAdvCb, advParams, advHandle);
     #else
       status = GapAdv_create((pfnGapCB_t)advCallback, advParams, advHandle);
     #endif
       if (status != SUCCESS)
       {
         return status;
       }
       // .....
       // .....
     }
   

2. Set Advertiser’s virtual address set with GapAdv_setVirtualAdvAddr(). The handle for the advertisement set, returned from GapAdv_create(), can also be used to create a custom private address for that advertisement set. This allows different advertising sets to have different addresses.

   Warning

   This is only applicable for legacy non-connectable and non-scannable advertising sets and it is optional.

3. Load Advertisement and Scan Response data. Advertising and scan response data is decoupled from the advertising set. That is, it is possible for multiple advertising sets to use the same memory for advertising/scan response data. An advertising set could also use the same memory for its advertising and scan response data. (Note that this requires diligence as there are some data types that are only allowed once in the advertisement and scan response data. See the Bluetooth Core Specification Supplement (CSSv7) for specifics.)

   If your advertisement set is not scannable, you can of course skip the last step (load scan response data). Example advertising and scan response data is shown in Listing 37. and Listing 38.

   Listing 36. ble_stack_api.c ::bleStk_initAdvSet - Load the Advertising and Scan Response Data

   bStatus_t bleStk_initAdvSet(pfnBleStkAdvCB_t advCallback, uint8_t *advHandle,
                                      GapAdv_eventMaskFlags_t eventMask,
                                      GapAdv_params_t *advParams,
                                      uint16_t advDataLen ,uint8_t advData[],
                                      uint16_t scanRespDataLen, uint8_t scanRespData[])
   {
    bStatus_t status;
    //...
    //...
   
    // Load advertising data for set that is statically allocated by the app
    status = GapAdv_loadByHandle(*advHandle, GAP_ADV_DATA_TYPE_ADV, advDataLen, advData);
   
    if (status != SUCCESS)
    {
      return status;
    }
   
    // Load scan response data for set that is statically allocated by the app
    if (scanRespData != NULL)
    {
      status = GapAdv_loadByHandle(*advHandle, GAP_ADV_DATA_TYPE_SCAN_RSP, scanRespDataLen, scanRespData);
      if (status != SUCCESS)
      {
        return status;
      }
    }
    //....
    //....
   }
   

   Listing 37. ti_ble_config.c - Example Advertisement Data

    uint8_t advData1[] =
    {
      0x02,
      GAP_ADTYPE_FLAGS,
      GAP_ADTYPE_FLAGS_BREDR_NOT_SUPPORTED | GAP_ADTYPE_FLAGS_GENERAL,
   
      0x03,
      GAP_ADTYPE_16BIT_MORE,
      LO_UINT16(0xfff0),
      HI_UINT16(0xfff0),
    };
   

   Listing 38. ti_ble_config.c - Example Scan Response Data

    uint8_t scanResData1[] =
    {
      0x12,
      GAP_ADTYPE_LOCAL_NAME_COMPLETE,
      'B',
      'a',
      's',
      'i',
      'c',
      ' ',
      'B',
      'L',
      'E',
      ' ',
      'p',
      'r',
      'o',
      'j',
      'e',
      'c',
      't',
   
      0x02,
      GAP_ADTYPE_POWER_LEVEL,
      0,
   
      0x05,
      GAP_ADTYPE_PERIPHERAL_CONN_INTERVAL_RANGE,
      LO_UINT16(80),
      HI_UINT16(80),
      LO_UINT16(104),
      HI_UINT16(104),
   
    };
   

4. Set events of interest to send to application. The events will be sent to the callback function given in GapAdv_create().

   Listing 39. bleapputil_init.c ::BLEAppUtil_initAdvSet - Declare Callback Function and the events to registers

   bStatus_t BLEAppUtil_initAdvSet(uint8 *advHandle, const BLEAppUtil_AdvInit_t *advInitInfo)
   {
       // BLEAppUtil_advCB is the callback function
       // The mask is to register all GAP_ADV_EVT_MASK_ALL
       // That means in BLEAppUtil
       return bleStk_initAdvSet(BLEAppUtil_advCB, advHandle, GAP_ADV_EVT_MASK_ALL,
                                advInitInfo->advParam, advInitInfo->advDataLen ,
                                advInitInfo->advData, advInitInfo->scanRespDataLen,
                                advInitInfo->scanRespData);
   }
   

   As you can see that the registered events for advertising callback is all. However, this only applies to the BLEAppUtil layer. In the application layer, you can further refine it to what you are interested in knowing. You can also just update the GAP_ADV_EVT_MASK_ALL to something else.

   If you don’t want to modify the BLEAppUtil Framework, then you can use BLEAppUtil_registerEventHandler to register the advertising events of interest on top of the BLEAppUtil framework. The aforementioned API expects BLEAppUtil_EventHandler_t struct.

   Listing 40. app_peripheral.c - Advertising Event Handler

   BLEAppUtil_EventHandler_t peripheralAdvHandler =
   {
       .handlerType    = BLEAPPUTIL_GAP_ADV_TYPE,
       .pEventHandler  = Peripheral_AdvEventHandler,
       .eventMask      = BLEAPPUTIL_ADV_START_AFTER_ENABLE |
                         BLEAPPUTIL_ADV_END_AFTER_DISABLE
   };
   

   The first parameter is highlighted in Listing 41.. Here we are interested in advertising, thus we choose BLEAPPUTIL_GAP_ADV_TYPE. The second one is declaration of the function name, Listing 42., of where/how the events will be processed. Lastly, it takes the event masks Listing 43. which are mapped to the GAP Event masks.

   Listing 41. bleapputil_api.h - Event Handler Type

   // Event Handler Types
   typedef enum BLEAppUtil_eventHandlerType_e
   {
       BLEAPPUTIL_GAP_CONN_TYPE,
       BLEAPPUTIL_CONN_NOTI_TYPE,
       BLEAPPUTIL_GAP_ADV_TYPE,
       BLEAPPUTIL_GAP_SCAN_TYPE,
       BLEAPPUTIL_GAP_PERIODIC_TYPE,
       BLEAPPUTIL_GATT_TYPE,
       BLEAPPUTIL_PASSCODE_TYPE,
       BLEAPPUTIL_PAIR_STATE_TYPE,
       BLEAPPUTIL_L2CAP_DATA_TYPE,
       BLEAPPUTIL_L2CAP_SIGNAL_TYPE,
       BLEAPPUTIL_HCI_DATA_TYPE,
       BLEAPPUTIL_HCI_GAP_TYPE,
       BLEAPPUTIL_HCI_SMP_TYPE,
       BLEAPPUTIL_HCI_SMP_META_TYPE,
       BLEAPPUTIL_HCI_CTRL_TO_HOST_TYPE
   } BLEAppUtil_eventHandlerType_e;
   

   Listing 42. app_peripheral.c - Function to process the event

   void Peripheral_AdvEventHandler(uint32 event, BLEAppUtil_msgHdr_t *pMsgData)
   {
       switch(event)
       {
           case BLEAPPUTIL_ADV_START_AFTER_ENABLE:
           {
               MenuModule_printf(APP_MENU_ADV_EVENT, 0, "Adv status: Started - handle: "
                                 MENU_MODULE_COLOR_YELLOW "%d" MENU_MODULE_COLOR_RESET,
                                 ((BLEAppUtil_AdvEventData_t *)pMsgData)->pBuf->advHandle);
               break;
           }
   
           case BLEAPPUTIL_ADV_END_AFTER_DISABLE:
           {
               MenuModule_printf(APP_MENU_ADV_EVENT, 0, "Adv status: Ended - handle: "
                                 MENU_MODULE_COLOR_YELLOW "%d" MENU_MODULE_COLOR_RESET,
                                 ((BLEAppUtil_AdvEventData_t *)pMsgData)->pBuf->advHandle);
               break;
           }
   
           default:
           {
               break;
           }
        }
    }
   

   Listing 43. bleapputil_api.h - GAP Adv Event Mask

   typedef enum BLEAppUtil_GAPAdvEventMaskFlags_e
   {
       // Gets advertising handle using pBuf
       BLEAPPUTIL_ADV_START_AFTER_ENABLE    = GAP_EVT_ADV_START_AFTER_ENABLE,
       // Gets advertising handle using pBuf
       BLEAPPUTIL_ADV_END_AFTER_DISABLE     = GAP_EVT_ADV_END_AFTER_DISABLE,
       // Gets advertising handle using pBuf
       BLEAPPUTIL_ADV_START                 = GAP_EVT_ADV_START,
       // Gets advertising handle using pBuf
       BLEAPPUTIL_ADV_END                   = GAP_EVT_ADV_END,
       // Gets @ref GapAdv_setTerm_t using pBuf
       BLEAPPUTIL_ADV_SET_TERMINATED        = GAP_EVT_ADV_SET_TERMINATED,
       // Gets @ref GapAdv_scanReqReceived_t using pBuf
       BLEAPPUTIL_SCAN_REQ_RECEIVED         = GAP_EVT_SCAN_REQ_RECEIVED,
       // Gets @ref GapAdv_truncData_t using pBuf
       BLEAPPUTIL_ADV_DATA_TRUNCATED        = GAP_EVT_ADV_DATA_TRUNCATED,
       BLEAPPUTIL_ADV_INSUFFICIENT_MEMORY   = GAP_EVT_INSUFFICIENT_MEMORY
   } BLEAppUtil_GAPAdvEventMaskFlags_e;
   

5. Enable advertising. Calling GapAdv_enable() to start advertising. Note that BLEAppUtil_advStart is a wrapper for GapAdv_enable

   Listing 44. app_peripheral.c :: Peripheral_start() - Start advertising.

      // Enable advertising
      status = BLEAppUtil_advStart(peripheralAdvHandle_1, &advSetStartParamsSet_1);
   

   Listing 45. bleapputil_init.c :: BLEAppUtil_advStart - Start advertising.

   bStatus_t BLEAppUtil_advStart(uint8 handle, const BLEAppUtil_AdvStart_t *advStartInfo)
   {
       return GapAdv_enable(handle, advStartInfo->enableOptions ,
                            advStartInfo->durationOrMaxEvents);
   }
   

The above steps can be repeated to create multiple advertising sets. There is an upper limit of 20 advertising sets (defined in the controller). The heap may also restrict the number of advertising sets you can create in one application.

Changing advertising parameters

In order to change an individual parameter after advertising has been enabled, advertising must first be disabled. Re-enable advertising after the parameter is modified. Here we will illustrate the sequence using BLEAppUtil framework.

Listing 46. Changing advertising parameter during advertising.

   // Stop advertising
   BLEAppUtil_advStop(peripheralAdvHandle_1);

   // Set a parameter
   uint32_t newAdvInt = 200;
   GapAdv_setParam(peripheralAdvHandle_1, GAP_ADV_PARAM_PRIMARY_INTERVAL_MIN, &newAdvInt);
   GapAdv_setParam(peripheralAdvHandle_1, GAP_ADV_PARAM_PRIMARY_INTERVAL_MAX, &newAdvInt);

   // Re-enable advertising
   status = BLEAppUtil_advStart(peripheralAdvHandle_1, &advSetStartParamsSet_1);

Ending Advertisement

An advertising set can be disabled with GapAdv_disable() and deleted (such that all memory related to the set is freed) with GapAdv_destroy().

Listing 47. Stop advertising and free memory.

  // Stop advertising
  BLEAppUtil_advStop(peripheralAdvHandle_1);

  // Free all parameter settings related to advertising set
  // Keep the advertising / scan response data
  // Note that this can be called while advertising is still enabled
  GapAdv_destroy(peripheralAdvHandle_1, GAP_ADV_FREE_OPTION_DONT_FREE);

Warning

In the out of box example, the advertising and scan response data are declared as global array using sysconfig tool, thus the BLE5-Stack has not allocated memory to the advertising and scan response data. If attempt to free the data using GAP_ADV_FREE_OPTION_ADV_DATA or GAP_ADV_FREE_OPTION_SCAN_RESP_DATA, it will cause hardfault.

Updating Advertisement/Scan Response Data

Again, since the advertising and scan response data is decoupled from the advertising set, it is possible for multiple advertising sets to use the same memory for advertising/scan response data. An advertising set could also use the same memory for its advertising and scan response data. The memory used for advertising/scan response data is referred to as a “buffer” throughout this section.

The preferred and safest method to update a buffer is to use the prepare/load latching mechanism. This will ensure the following:

• No buffer is freed if it is used by another advertising set.

• Advertising is always disabled before the buffer is modified, thus ensuring that no corrupted advertisement packets are transmitted.

• Prevent double-copying.

The following offers several ways to update the advertising and scan response data.

Update the Advertising/Scan Response Data of a Single Handle

If the application wants to modify a few bytes of advertising/scan response data that is used by a single advertisement set, use GapAdv_prepareLoadByHandle() and GapAdv_loadByHandle().

Listing 48. Update the advertising buffer of a single handle.

  bStatus_t status;

  // Don't free anything since we're going to use the same buffer to re-load
  status = GapAdv_prepareLoadByHandle(peripheralAdvHandle_1, GAP_ADV_FREE_OPTION_DONT_FREE);

  // Only update the data when return is successful
  if (status == SUCCESS)
  {
    // Sample buffer modification
    advData1[3] = 0xAA;

    // Reload buffer to handle
    // Here the advDataLen = sizeof(advData1) and it is setup in the app\_peripheral.c
    // under advSetInitParamsSet_1
    GapAdv_loadByHandle(peripheralAdvHandle_1, GAP_ADV_DATA_TYPE_ADV, advSetInitParamsSet_1->advDataLen, advData1);
  }

The GapAdv_prepareLoadByHandle() will perform the following here:

• Check that this buffer isn’t used by other handles. If GapAdv_prepareLoadByHandle() returns success, the application will know that it can now safely modify this buffer.

• Automatically disable advertising and mark it for re-enabling

GapAdv_loadByHandle() will automatically re-enable advertising with the updated buffer. This method can also be used to use a subset of the original advertising data. In this case, simply update the data length parameter of GapAdv_loadByHandle().

Warning

The above methods of changing advertising or scan response data have one limitation. A special procedure is required when the data length is currently set to zero and application wants to change that to a non-zero length. In this case the application needs to

1. Destroy the advertisement set, please see Ending Advertisement

2. Re-create it with the desired data, please see Create Advertisement

Load a New Buffer to a Single Advertising Handle

If the application wants to load a new buffer to a single advertising handle without double-copying, use GapAdv_prepareLoadByHandle() and GapAdv_loadByHandle(). This way, the advertising data exists in only one place in memory that is used by the GAP Advertiser. In this case we will free the buffer and allocate a new one.

Listing 49. Load a new advertising buffer for a single handle.

  // Free the buffer (to avoid double copying) since we're loading a new buffer
  // However, only free the buffer if it's allocated in the application.
  // Using out of box example, the buffer is a global array and can not be freed
  GapAdv_prepareLoadByHandle(advHandleLegacy, GAP_ADV_FREE_OPTION_ADV_DATA);

  // Allocate new buffer (and then fill it as desired)
  uint8_t *advertData2= ICall_malloc(ADV_DATA2_LEN);

  // Load the new buffer to the advertisement set handle
  GapAdv_loadByHandle(peripheralAdvHandle_1, GAP_ADV_DATA_TYPE_ADV, ADV_DATA2_LEN, advertData2);

GapAdv_prepareLoadByHandle() will perform the following here:

• Check that the buffer isn’t used by any other advertisement handles. If GapAdv_prepareLoadByHandle() returns success, the application will know that it can now safely modify this buffer.

• Automatically disable advertising and mark it for re-enabling

• Free the original buffer

The GapAdv_loadByHandle() will automatically re-enable advertising on the handle with the new buffer.

Update Advertising/Scan Response Data that is Used for Multiple Advertising Handles

This is the case where the application wants to modify a few bytes of advertising or scan response data that is shared among advertisement sets.

Listing 50. Update an advertising buffer used by multiple handles.

  // Don't free anything since we're going to use the same buffer to reload
  GapAdv_prepareLoadByBuffer(advertData, FALSE);

  // Sample buffer modification
  advertData[3] = 0xAA;

  // Reload the buffer to be used by the advertisement set handles
  GapAdv_loadByBuffer(ADV_DATA_LEN, advertData);

GapAdv_prepareLoadByBuffer() will automatically disable advertising for all advertising handles that use this buffer. GapAdv_loadByBuffer() will automatically re-enable advertising for all handles that use this buffer.

Load a New Buffer To Multiple Advertising Handles

This is the case where the applications wants to load a new buffer to all advertisement set handles that are using this buffer.

Listing 51. Load new advertising buffer for multiple handles.

  // Free buffer (to avoid double copying) since we're loading a new buffer
  // However, only free the buffer if it's allocated in the application.
  // Using out of box example, the buffer is a global array and can not be freed
  GapAdv_prepareLoadByBuffer(advertData, TRUE);

  // Allocate new buffer (and then fill as desired)
  uint8_t *advertData2= ICall_malloc(ADV_DATA2_LEN);

  // Reload the buffer to be used by all the handles
  GapAdv_loadByBuffer(ADV_DATA2_LEN, advertData2);

GapAdv_loadByBuffer() will perform the following here:

• Automatically disable advertising and mark it for re-enabling on all handles that use this buffer

• Free the original buffer

GapAdv_loadByBuffer() will automatically re-enable advertising on all handles that used the original buffer.

Directly Manipulating a Buffer While Advertising is Enabled

Since the application owns the advertising and scan response buffers and thus has access to the memory where the buffers are stored, there is nothing preventing it from directly modifying this memory. While discouraged, there are scenarios where this can be useful, such as updating the data after each advertisement in the most power-efficient manner. The main drawback to this is that there is no way to guarantee that this update won’t occur while an advertising packet is being transmitted that is using this buffer, potentially resulting in a corrupted advertising packet. This is especially true if multiple advertising sets are using the same buffer. If the application accepts the risk of potentially corrupting an advertising packet, there is a recommended way to do this with minimized risk.

The buffer should be updated directly in the advertising callback (in the stack context) when the GAP_EVT_ADV_END or BLEAPPUTIL_ADV_END is received. Generally, it is recommended to minimize processing in these callbacks and, instead, to post an event to process in the application context. It should be noted that any processing in the stack context has the potential to break the timing of the controller. This should not be a problem if the only processing is to update the buffer. Also, for both this reason and because it will lead to a semaphore that never gets posted due to calling an ICall API from the stack context, it should be noted that no stack API calls can be made from the stack context. To reiterate for clarity, no BLE-Stack APIs can be called from the callback (stack) context.

Listing 52. Directly update advertising data in advertising event handle.

void Peripheral_AdvEventHandler(uint32 event, BLEAppUtil_msgHdr_t *pMsgData)
{
  switch(event)
  {
    // Advertisement just ended so it should be safe to update buffer here
    // without corrupting an advertisement.
    case BLEAPPUTIL_ADV_END:
    {
       advertData[3] = 0xAA;
    }
  }
}

Note that this can not be guaranteed to work all the time without corrupting an advertisement. Also, if the buffer is used by multiple advertisement handles, the application would need to track the GAP_EVT_ADV_END or BLEAPPUTIL_ADV_END across all of these handles to find an ideal time to update the buffer. If this processing is added to the callback in the stack context, this increases the risk of breaking the timing of the controller. Also, remember to include GAP_EVT_ADV_END or BLEAPPUTIL_ADV_END in the event mask, please refer to Listing 40..

Limited Advertising

The above code can set the advertising for limited or general advertising modes. By default, the peripheral advertises in general discoverable mode. To use limited discoverable mode, the corresponding fields inside the Listing 37. should be corresponding fields inside the Listing 37. should be changed by changing GAP_ADTYPE_FLAGS_GENERAL to GAP_ADTYPE_FLAGS_LIMITED. This can be achieved by using BLE5-Stack SysConfig Features.

Periodic Advertising

Warning

This functionnality is not yet implemented in the stack.

Directed Advertisements as GATT Server

In BLE5-Stack 3.02.04.00, Privacy is always enabled. Most of the privacy features are handled by the GAP bond manager in the stack. To conserve flash memory, by default, the GAP bond manager does not enable GATT client features. The implication of these disabled GATT client features is that the GAP bond manager will not query the Central Address Resolution characteristic of the remote device.

In order to perform a directed advertisement when the initiator’s address is set to Private Resolvable Address, the peripheral device must read the Central Address Resolution characteristic of its remote device to make sure address resolution is supported. Failure to do so before sending directed advertisements violates the Bluetooth Core Specifications Version 5.3.

By default, sample applications such as basic_ble does not define GATT_NO_CLIENT but initializes the GATT Client as shown below:

Listing 53. ble_stack_api.c :: bleStack_initGatt - Initialize GATT Client for peripheral & central

if (role & (GAP_PROFILE_PERIPHERAL | GAP_PROFILE_CENTRAL))
{
    // Initialize GATT Client
    GATT_InitClient();
}

Note

GATT_NO_CLIENT can be set using BLE5-Stack SysConfig Features.

GAP Peripheral

The Peripheral role demonstrates the use of the advertising and connection states. The steps to use this role will be demonstrated by examining the basic_ble example project and related GAP APIs.

Note

Many of the GAP default values may configured using syscfg. The examples below show how to make these modifications when syscfg is not desired.

1. Initialize the GAP parameters. This initialization typically occurs in the application initialization function by calling GAP_SetParamValue(). In the basic_ble example project included in the SDK, this initialization occurs in bleStack_initGap() as shown below.

   Listing 54. ble_stack_api.c :: bleStack_initGap() - Setup of the GAP Peripheral Role

   {
     bStatus_t status = SUCCESS;
     // Pass all parameter update requests to the app for it to decide
     GAP_SetParamValue(GAP_PARAM_LINK_UPDATE_DECISION, paramUpdateDecision);
   
     //...
     return status;
   }
   

   Additional calls to GAP_SetParamValue() may be made in bleStack_initGap() to override default GAP parameters when using basic_ble. A list of configurable parameters may be located in the BLE Stack API Reference GAP section.

2. Modifing GAP initialization parameters in basic_ble. By default, basic_ble will send all GAP parameter updates to the application. To change this behavior, modify the appMainPeriCentParams structure located in app_main.c.

   Listing 55. app_main.c :: appMainPeriCentParams - Modifying GAP Parameters

   BLEAppUtil_PeriCentParams_t appMainPeriCentParams =
   {
    .connParamUpdateDecision = DEFAULT_PARAM_UPDATE_REQ_DECISION,
    .gapBondParams = &gapBondParams
   };
   

3. Initialize the application task using GAP_DeviceInit for the Peripheral Role and register to receive GAP events. To modify the default GAP device initialization parameters in basic_ble, modify the appMainParams structure located in app_main.c.

   Listing 56. app_main.c :: appMainParams - GAP Application Parameters.

   // Parameters that should be given as input to the BLEAppUtil_init function
   BLEAppUtil_GeneralParams_t appMainParams =
   {
       .taskPriority = 1,
       .taskStackSize = 1024,
       .profileRole = (BLEAppUtil_Profile_Roles_e)(HOST_CONFIG),
       .addressMode = DEFAULT_ADDRESS_MODE,
       .deviceNameAtt = attDeviceName,
   };
   

   Listing 57. bleapputil_init.c :: BLEAppUtil_stackInit() - Initialize the GAP layer and register for GAP events.

   //...
   
   status = GAP_DeviceInit(BLEAppUtilLocal_GeneralParams->profileRole,
                           BLEAppUtilSelfEntity,
                           BLEAppUtilLocal_GeneralParams->addressMode,
                           BLEAppUtilLocal_GeneralParams->pDeviceRandomAddress);
   
   //...
   

4. Now you can send commands from the application. The following is an example of the application initiating PHY change using HCI_LE_SetPhyCmd().

   Listing 58. bleapputil_init.c :: BLEAppUtil_setConnPhy() - Changing the PHY

   bStatus_t BLEAppUtil_setConnPhy(BLEAppUtil_ConnPhyParams_t *phyParams)
   {
       // Set Phy Preference on the current connection. Apply the same value
       // for RX and TX. For more information, see the LE 2M PHY section in the User's Guide:
       // http://software-dl.ti.com/lprf/ble5stack-latest/
       return HCI_LE_SetPhyCmd(phyParams->connHandle, phyParams->allPhys, phyParams->txPhy, phyParams->rxPhy, phyParams->phyOpts);
   }
   

   The following shows the software flow when the user chooses to set the PHY preference from the terminal in the basic_ble example:

   

   Figure 68. Context Diagram of Application Updating PHY.

   As shown in the diagram above, the actual PHY change is returned asynchronously and is passed to the application with event code HCI_BLE_PHY_UPDATE_COMPLETE_EVENT.

5. The application task processes most of the GAP-related events passed to it from the Bluetooth Low Energy protocol stack. For example, when a link is terminated, the application removes the connection information and displays the terminated device’s peer address and connection handle number. The following code snippet can be found in app_connection.c:

   Listing 59. app_connection.c :: Connection_ConnEventHandler() - Removing connection info

   void Connection_ConnEventHandler(uint32 event, BLEAppUtil_msgHdr_t *pMsgData)
   {
       switch(event)
       {
           // ...
           case BLEAPPUTIL_LINK_TERMINATED_EVENT:
           {
               gapTerminateLinkEvent_t *gapTermMsg = (gapTerminateLinkEvent_t *)pMsgData;
   
               // Remove the connection from the conneted device list
               Connection_removeConnInfo(gapTermMsg->connectionHandle);
   
               /*! Print the peer address and connection handle number */
               MenuModule_printf(APP_MENU_CONN_EVENT, 0, "Conn status: Terminated - "
                                 "connectionHandle = " MENU_MODULE_COLOR_YELLOW "%d " MENU_MODULE_COLOR_RESET
                                 "reason = " MENU_MODULE_COLOR_YELLOW "%d" MENU_MODULE_COLOR_RESET,
                                 gapTermMsg->connectionHandle, gapTermMsg->reason);
   
               /*! Print the number of current connections */
               MenuModule_printf(APP_MENU_NUM_CONNS, 0, "Connections number: "
                                 MENU_MODULE_COLOR_YELLOW "%d " MENU_MODULE_COLOR_RESET,
                                 linkDB_NumActive());
   
               break;
           }
           // ...
   

GAP Scanner

The GAP Scanner performs Extended Scanning, Legacy Scanning and Synchronization with periodic advertisements operations as defined by the Bluetooth Core Specifications Version 5.3. It controls the Scanner GAP state (see GAP State Diagram.). The Central and Observer role uses the scanning state implemented by the GAP Scanner. The GAP Scanner is demonstrated in the app_central.c and app_observer.c source files in the basic_ble example project. The periodic advertisement synchronization capability of the GAP Scanner is demonstrated in the rtls_master example project. See the BLE Stack API Reference for the full GAP Scanner API including commands, configurable parameters, events, and callbacks. The steps to use this module are listed in the following, along with example code from basic_ble.

1. Start a Central or Observer GAP role. In this case we will use the GAP Central role. For configuration of the Bluetooth Low Energy stack features, and changing the role in basic_ble, see Developing with SDK CC23xx and Stack Configurations.

2. Register an event callback handler for scanner events. In the basic_ble project, an event handler is registered using BLEAppUtil_registerEventHandler. The centralScanHandler structure contains the event mask and callback function to handle GAP scan events.

   Listing 60. app_central.c :: centralScanHandler - Scan event handler structure.

   // Events handlers struct, contains the handlers and event masks
   // of the application central role module
   BLEAppUtil_EventHandler_t centralScanHandler =
   {
       .handlerType    = BLEAPPUTIL_GAP_SCAN_TYPE, // Event handler type
       .pEventHandler  = Central_ScanEventHandler, // Callback to event handler
       .eventMask      = BLEAPPUTIL_SCAN_ENABLED | // Event mask
                         BLEAPPUTIL_SCAN_DISABLED
   };
   

This structure determines what events will be passed to the callback handler, Central_ScanEventHandler(). For a full list of GAP scan events, please see BLEAppUtil_GAPScanEventMaskFlags_e enum located in bleapputil_api.h. Before taking a look at the event handler, it must be registered so that the application recieves GAP scan events.

Listing 61. app_central.c :: Central_start() :: BLEAppUtil_registerEventHandler() - Register the event handler.

  // Register callback to process Scanner events
  bStatus_t Central_start()
  {
      bStatus_t status = SUCCESS;

      status = BLEAppUtil_registerEventHandler(&centralScanHandler);
      if(status != SUCCESS)
      {
          // Return status value
          return(status);
      }
      // ...
  }

3. Handling events in the event handler. The code block below shows the general callback structure to handle events.

   Listing 62. app_central.c :: Central_ScanEventHandler() - Central scan event handler.

     void Central_ScanEventHandler(uint32 event, BLEAppUtil_msgHdr_t *pMsgData)
     {
         BLEAppUtil_ScanEventData_t *scanMsg = (BLEAppUtil_ScanEventData_t *)pMsgData;
   
         switch (event)
         {
             case BLEAPPUTIL_SCAN_ENABLED:
             {
                 //...code...
                 break;
             }
   
             case BLEAPPUTIL_SCAN_DISABLED:
             {
                 //...code...
                 break;
             }
   
             default:
             {
                 //...more code...
                 break;
             }
   
         }
     }
   

4. Set scan parameters. It’s worth noting that the parameters are split into PHY-related parameters (set with GapScan_setPhyParams()) and non-PHY-related parameters (set with GapScan_setParam()). The basic_ble example project abstracts these calls through BLEAppUtil_scanInit() and BLEAppUtil_setConnParams() with their definitions located in bleapputil_init.c. The basic_ble example project provides structures to modify the initial scan and PHY parameters.

Note

Make sure the scanning window is at least twice the length of the expected advertising interval to ensure at least 1 advertising event is captured in each scanning window. Otherwise, the scanning device may not find the advertising device.

Listing 63. app_central.c :: centralScanInitParams :: centralConnInitParams - Set PHY-related GAP scanner parameters.

  const BLEAppUtil_ScanInit_t centralScanInitParams =
  {
      /*! Opt SCAN_PRIM_PHY_1M | SCAN_PRIM_PHY_CODED */
      .primPhy                    = DEFAULT_SCAN_PHY,

      /*! Opt SCAN_TYPE_ACTIVE | SCAN_TYPE_PASSIVE */
      .scanType                   = DEFAULT_SCAN_TYPE,

      /*! Scan interval shall be greater than or equal to scan window */
      .scanInterval               = DEFAULT_SCAN_INTERVAL, /* Units of 625 us */

      /*! Scan window shall be less than or equal to scan interval */
      .scanWindow                 = DEFAULT_SCAN_WINDOW, /* Units of 625 us */

      /*! Select which fields of an advertising report will be stored */
      /*! in the AdvRptList, For mor field see @ref Gap_scanner.h     */
      .advReportFields            = ADV_RPT_FIELDS,

      /*! Opt SCAN_PRIM_PHY_1M | SCAN_PRIM_PHY_CODED */
      .scanPhys                   = DEFAULT_SCAN_PHY,

      /*! Opt SCAN_FLT_POLICY_ALL | SCAN_FLT_POLICY_AL |   */
      /*! SCAN_FLT_POLICY_ALL_RPA | SCAN_FLT_POLICY_AL_RPA */
      .fltPolicy                  = SCANNER_FILTER_POLICY,

      /*! For more filter PDU @ref Gap_scanner.h */
      .fltPduType                 = SCANNER_FILTER_PDU_TYPE,

      /*! Opt SCAN_FLT_RSSI_ALL | SCAN_FLT_RSSI_NONE */
      .fltMinRssi                 = SCANNER_FILTER_MIN_RSSI,

      /*! Opt SCAN_FLT_DISC_NONE | SCAN_FLT_DISC_GENERAL | SCAN_FLT_DISC_LIMITED
       *  | SCAN_FLT_DISC_ALL | SCAN_FLT_DISC_DISABLE */
      .fltDiscMode                = SCANNER_FILTER_DISC_MODE,

      /*! Opt SCAN_FLT_DUP_ENABLE | SCAN_FLT_DUP_DISABLE | SCAN_FLT_DUP_RESET */
      .fltDup                     = SCANNER_DUPLICATE_FILTER
  };

  const BLEAppUtil_ConnParams_t centralConnInitParams =
  {
       /*! Opt INIT_PHY_ALL | INIT_PHY_1M | INIT_PHY_2M | INIT_PHY_CODED */
      .initPhys              = DEFAULT_INIT_PHY,

      .scanInterval          = INIT_PHYPARAM_SCAN_INT,      /* Units of 0.625ms */
      .scanWindow            = INIT_PHYPARAM_SCAN_WIN,      /* Units of 0.625ms */
      .minConnInterval       = INIT_PHYPARAM_MIN_CONN_INT,  /* Units of 1.25ms  */
      .maxConnInterval       = INIT_PHYPARAM_MAX_CONN_INT,  /* Units of 1.25ms  */
      .connLatency           = INIT_PHYPARAM_CONN_LAT,
      .supTimeout            = INIT_PHYPARAM_SUP_TO         /* Units of 10ms */
  };

These structures are then passed to BLEAppUtil_scanInit() and BLEAppUtil_setConnParams() respectively. These initialization functions may be found in Central_start().

5. Start Scanning. Menu_scanStartCB() callback triggers when selected in the basic_ble menu. This callback calls BLEAppUtil_scanStart(), which starts scanning for advertisement reports and scan responses. Menu_scanStartCB() contains parameters for the scan period, duration, and the maximum number of advertisement reports.

   Listing 64. app_menu.c :: Menu_scanStartCB() - Set scan period, duration, and maximum number of reports.

    void Menu_scanStartCB(uint8 index)
    {
        bStatus_t status;
        const BLEAppUtil_ScanStart_t centralScanStartParams =
        {
            /*! Zero for continuously scanning */
            .scanPeriod     = DEFAULT_SCAN_PERIOD, /* Units of 1.28sec */
   
            /*! Scan Duration shall be greater than to scan interval,*/
            /*! Zero continuously scanning. */
            .scanDuration   = DEFAULT_SCAN_DURATION, /* Units of 10ms */
   
            /*! If non-zero, the list of advertising reports will be */
            /*! generated and come with @ref GAP_EVT_SCAN_DISABLED.  */
            .maxNumReport   = APP_MAX_NUM_OF_ADV_REPORTS
        };
   
        // Will start scanning by calling GapScan_enable.
        status = BLEAppUtil_scanStart(&centralScanStartParams);
   
        // Print the status of the scan
        MenuModule_printf(APP_MENU_GENERAL_STATUS_LINE, 0, "Call Status: ScanStart = "
                          MENU_MODULE_COLOR_BOLD MENU_MODULE_COLOR_RED "%d" MENU_MODULE_COLOR_RESET,
                          status);
    }
   

   BLEAppUtil_scanStart() calls GapScan_enable() with the parameters of the centralScanStartParams structure.

   Listing 65. bleapputil_init.c :: BLEAppUtil_scanStart() - Abstraction to GapScan_Enable.

      bStatus_t BLEAppUtil_scanStart(const BLEAppUtil_ScanStart_t *scanStartInfo)
      {
          return GapScan_enable(scanStartInfo->scanPeriod, scanStartInfo->scanDuration, scanStartInfo->maxNumReport);
      }
   

   The return status from the protocol stack call of GapScan_enable() indicates only whether or not the attempt to perform device discovery was successful. The actual device discovered is returned asynchronously as a BLEAPPUTIL_ADV_REPORT forwarded through the GAP Scanner callbacks registered by the application (here: Central_ScanEventHandler()). This is described below.

6. The GAP Scanner performs some processing on the GAP events it receives from the protocol stack. The task also forwards some events to the application. Figure 69. shows this and how the BLEAPPUTIL_ADV_REPORT is processed from the protocol stack to the application.

   

   Figure 69. Context Diagram of Application using GapScan_enable()

Note that during scanning, individual advertisements and scan responses are returned as BLEAPPUTIL_ADV_REPORT. This is defined by the Bluetooth Core Specifications Version 5.3. By default, duplicate reports are filtered such that only one event is returned to the application per peer device BDA. This can be configured via the SCAN_PARAM_FLT_DUP GAP Scanner parameter (You can change scanning parameters with GapScan_setParam() or by modifying the centralScanInitParams structure within app_central.c).

BLEAPPUTIL_SCAN_ENABLED indicates the start of scanning. After the scan has completed, a summary of discovered reports will be returned to the application with BLEAPPUTIL_SCAN_DISABLED. You can see the implementation of this in Central_ScanEventHandler().

  void Central_ScanEventHandler(uint32 event, BLEAppUtil_msgHdr_t *pMsgData)
  {
      BLEAppUtil_ScanEventData_t *scanMsg = (BLEAppUtil_ScanEventData_t *)pMsgData;

      switch (event)
      {
          case BLEAPPUTIL_SCAN_ENABLED:
          {
              centralScanIndex = 0;
              MenuModule_printf(APP_MENU_SCAN_EVENT, 0, "Scan status: Scan started...");

              break;
          }

          case BLEAPPUTIL_SCAN_DISABLED:
          {
              uint8 i;

              for(int i = 0; i < APP_MAX_NUM_OF_ADV_REPORTS; i++)
              {
                  memset(&centralScanRes[i], 0, sizeof(App_scanResults));
              }

              // Go over the advertise reports that was saved in the host level and save it
              for (i = 0; i < scanMsg->pBuf->pScanDis.numReport; i++)
              {
                GapScan_Evt_AdvRpt_t advReport;
                // Get the address from the report
                GapScan_getAdvReport(i, &advReport);
                // Add the report to the scan list
                Central_addScanRes(&advReport);
              }

              MenuModule_printf(APP_MENU_SCAN_EVENT, 0, "Scan status: Scan disabled - "
                                "Reason: " MENU_MODULE_COLOR_YELLOW "%d " MENU_MODULE_COLOR_RESET
                                "Num results: " MENU_MODULE_COLOR_YELLOW "%d " MENU_MODULE_COLOR_RESET,
                                scanMsg->pBuf->pScanDis.reason,
                                scanMsg->pBuf->pScanDis.numReport);
              break;
          }

          default:
          {
              break;
          }

      }
  }

The maximum amount of scan responses that can be discovered during one scan can be set with the DEFAULT_MAX_SCAN_RES parameter that is passed into the maxNumReport parameter of GapScan_enable().

In an environment saturated with advertisements and scan responses, this can have a drastic impact on heap usage to the point of potentially breaking the stack. Therefore, it is essential to profile your application for the worst-case scenario where the maximum amount of scan responses are discovered during a scan.

Note that some scanning parameters will not be updated before scanning has been disabled and re-enabled. This is true for the following parameters:

• SCAN_PARAM_FLT_PDU_TYPE - Filter by PDU Type

• SCAN_PARAM_FLT_MIN_RSSI - Filter by Minimum RSSI

• SCAN_PARAM_FLT_DISC_MODE - Filter by Discoverable Mode

• SCAN_PARAM_RPT_FIELDS - Advertising Report Fields

Advertising Report Recording

The Advertising Report Recording feature allows a developer to specify what information is received and recorded in an Advertisement Report. This is useful in the use case where the application does not require the payload of the Advertising Report, but requires specific information such as address type, address, RSSI, etc. while eleminating the BLEAPPUTIL_ADV_REPORT event from GAP Scanner.

To prepare recording, GAP Scanner allocates necessary amount of memory when calling GapScan_enable(). Whenever a new packet arrives, GAP Scanner puts the specified fields of the information in the Advertising Report List in packed form. The list resides in RAM after the scanning ends until the application calls GapScan_discardAdvReportList() or a new scanning session starts. While the list is available, the application may retrieve the information by using GapScan_getAdvReport(). When the list fills, GAP Scanner issues BLEAPPUTIL_ADV_REPORT_FULL notifying the application that no more Advertising Reports will be recorded. The application may specify which fields of the Advertising Report information by using GapScan_setParam() with the parameter ID SCAN_PARAM_RPT_FIELDS and the associated bitmap.

The number of an Advertising Report’s information recorded may be found in the numReport field of the data buffer of type GapScan_Evt_End_t, coming with BLEAPPUTIL_SCAN_DISABLED event. Alternatively, if the application didn’t mask BLEAPPUTIL_SCAN_DISABLED, GapScan_getParam() with parameter ID SCAN_PARAM_NUM_ADV_RPT may be used.

Obtain Advertising Channel from Advertising Report

The application can extract the advertising channel from the advertising report with the following modifications:

1. Enable the advertising channel in the advertising report:

   • With SysConfig: Enable the setting Add Advertisement Channel Number inside Observer Configuration, see Observer Configurations

   • Without SysConfig: Add -DADV_RPT_INC_CHANNEL=1 in the file ti_ble_app_config.opt

2. Use the following example code in SimpleCentral_processAppMsg() to access the channel information

   Listing 66. simple_central.c :: SimpleCentral_processAppMsg() :: SC_EVT_ADV_REPORT - Extract the advertising channel

      case SC_EVT_ADV_REPORT:
      {
        GapScan_Evt_AdvRpt_t* pAdvRpt = (GapScan_Evt_AdvRpt_t*) (pMsg->pData);
        volatile uint8_t advChannel = pAdvRpt->secPhy >> 2;
   
        //...
   

Filtering

The GAP Scanner module provides 5 different types of filter to reduce the amount of advertising report notifications to the application and eventually save memory and power consumption. The result of the filtering affects both advertising reports and advertising report recording. The packets filtered out by the filter configurations are discarded and will neither be reported nor recorded. The filters are set by using the API GapScan_setParam() with the following parameter IDs:

• Filter by LL Filter Policy: SCAN_PARAM_FLT_POLICY

• Filter by PDU Type: SCAN_PARAM_FLT_PDU_TYPE

• Filter by Minimum RSSI: SCAN_PARAM_FLT_MIN_RSSI

• Filter by Discoverable Mode: SCAN_PARAM_FLT_DISC_MODE

• Filter by Duplicates: SCAN_PARAM_FLT_DUP.

All parameter IDs are described in the following sections. The GAP Scanner allows the application to apply any combination of the individual filters at the same time to narrow the scope of packets to receive.

Filter by LL Filter Policy

This filter is a link layer-level filter. The associated parameter ID used in GapScan_setParam() is SCAN_PARAM_FLT_POLICY. The parameter accompanying SCAN_PARAM_FLT_POLICY is passed to the link layer when GapScan_enable() is called before actually enabling scanning. Since the filtering is done by the link layer, the application only receives advertising report events that have passed the filter. The parameter value can be one of the following:

Name	Value	Description
SCAN_FLT_POLICY_ALL	0	Accept all Advs except directed Adv not addressed to this device.
SCAN_FLT_POLICY_WL	1	Accept only Advs from devices where the advertiser’s address is in the FIlter Accept List.
SCAN_FLT_POLICY_ALL_RPA	2	Accept all Advs except directed Adv not addressed to this device and any packet addressed to this device or addressed to a private resolvable address.
SCAN_FLT_POLICY_WL_RPA	3	Accept only Advs from devices where the advertiser’s address is in the FIlter Accept List and any packet addressed to this device or addressed to a private resolvable address.

Filter by PDU Type

This filter is based on the Event_Type parameter coming with the LE Extended Advertising Report Event. The associated parameter ID is SCAN_PARAM_FLT_PDY_TYPE. The parameter value specifies packets classified in six categories:

• Connectable/Non-Connectable

• Scannable/Non-Scannable

• Directed/Undirected

• ScanRsp/Adv

• Legacy/Extended

• Complete/Incomplete.

Every incoming packet has exactly one attribute in each category. For example, SCAN_FLT_PDU_NONSCANNABLE_ONLY and SCAN_FLT_PDU_SCANNABLE_ONLY cannot be chosen together since they represent scannable and non-scannable packets. Only either one can be used. If neither type is selected in a set, the filter will not care about that category. For example, if neither SCAN_FLT_PDU_NONCONNECTABLE_ONLY nor SCAN_FLT_PDU_CONNECTABLE_ONLY is set in the parameter value, the GAP Scanner will notify the application of both connectable packets and non-connectable packets. It will also record both connectable packets and non-connectable packets. The SCAN_PARAM_FLT_PDY_TYPE parameter value can be any combination of the following individual values (except individual values that are mutually exclusive):

Name	Value	Description
SCAN_FLT_PDU_NONCONNECTABLE_ONLY	0x0001	Non-connectable packets only. Mutually exclusive with SCAN_FLT_PDU_CONNECTABLE_ONLY
SCAN_FLT_PDU_CONNECTABLE_ONLY	0x0002	Connectable packets only. Mutually exclusive with SCAN_FLT_PDU_NONCONNECTABLE_ONLY
SCAN_FLT_PDU_NONSCANNABLE_ONLY	0x0004	Non-scannable packets only. Mutually exclusive with SCAN_FLT_PDU_SCANNABLE_ONLY
SCAN_FLT_PDU_SCANNABLE_ONLY	0x0008	Scannable packets only. Mutually exclusive with SCAN_FLT_PDU_NONSCANNABLE_ONLY
SCAN_FLT_PDU_UNDIRECTED_ONLY	0x0010	Undirected packets only. Mutually exclusive with SCAN_FLT_PDU_DIRECTIED_ONLY
SCAN_FLT_PDU_DIRECTED_ONLY	0x0020	Directed packets only. Mutually exclusive with SCAN_FLT_PDU_UNDIRECTED_ONLY
SCAN_FLT_PDU_ADV_ONLY	0x0040	Advertisement packets only. Mutually exclusive with SCAN_FLT_PDU_SCANRSP_ONLY
SCAN_FLT_PDU_SCANRSP_ONLY	0x0080	Scan Response packets only. Mutually exclusive with SCAN_FLT_PDU_ADV_ONLY
SCAN_FLT_PDU_EXTENDED_ONLY	0x0100	Extended packets only. Mutually exclusive with SCAN_FLT_PDU_LEGACY_ONLY
SCAN_FLT_PDU_LEGACY_ONLY	0x0200	Legacy packets only. Mutually exclusive with SCAN_FLT_PDU_EXTENDED_ONLY
SCAN_FLT_PDU_TRUNCATED_ONLY	0x0400	Truncated packets only. Mutually exclusive with SCAN_FLT_PDU_COMPLETE_ONLY
SCAN_FLT_PDU_COMPLETE_ONLY	0x0800	Complete packets only. Mutually exclusive with SCAN_FLT_PDU_TRUNCATED_ONLY

Filter by Minimum RSSI

This filter is based on the RSSI parameter coming with the LE Extended Advertising Report Event. The associated parameter ID used in GapScan_setParam() is SCAN_PARAM_FLT_MIN_RSSI. The GAP Scanner will discard LE Extended Advertising Report Event whose RSSI parameter value is smaller than the minimum RSSI value given by the application. The available range is -128 dBm to 127 dBm.

Filter by Discoverable Mode

This filter is based on the Flags AD type value in the payload (in the Data parameter) of the LE Extended Advertising Report Event. The associated parameter ID used in GapScan_setParam() is SCAN_PARAM_FLT_DISC_MODE. This filter is applied after the GAP Scanner reassembles all the fragmented payloads delivered by multiple LE Extended Advertising Report Events. The GAP Scanner will discard the defragmented packet if the found Flags AD type value doesn’t match the parameter value given by the application. The parameter value can be one of the following:

Name	Value	Description
SCAN_FLT_DISC_NONE	0	Accept only Non-Discoverable mode
SCAN_FLT_DISC_GENERAL	1	Accept only General Discoverable mode
SCAN_FLT_DISC_LIMITED	2	Accept only Limited Discoverable mode
SCAN_FLT_DISC_ALL	3	Accept both General and Limited Discoverable mode
SCAN_FLT_DISC_DISABLE	4	Discoverable Mode Filter Off (Don’t care about the Flags AD type value)

Filter by Duplicates

Like the Link Layer Scanner Filter Policy, this filter is a link layer-level filter. The associated parameter ID used in GapScan_setParam() is SCAN_PARAM_FLT_DUP. The parameter accompanying the SCAN_PARAM_FLT_DUP parameter ID is passed to the link layer when GapScan_enable() internally calls LE_SetExtScanEnable to enable scanning. Since the filtering is done by the link layer, GAP Scanner receives only the LE Extended Advertising Report Events that have passed the filter. The parameter value can be one of the following:

Name	Value	Description
SCAN_FLT_DUP_DISABLE	0	Disable duplicate filtering.
SCAN_FLT_DUP_ENABLE	1	Enable duplicate filtering.
SCAN_FLT_DUP_RESET	2	Enable duplicate filtering. Reset for each scan period.

Warning

When the duplicate filtering is enabled, the maximum amount of devices that can be found is 16. If more than 16 devices need to be discovered, the duplicate filtering needs to be disabled.

Synchronize with a Periodic Advertising Train

Warning

This functionnality is not yet implemented in the stack.

GAP Initiator

The initiator module is used to initiate the connection to a peripheral device. An initiator generally scans for advertisements then connects to a specific device. The initiator is a short lived state that transitions to the Central Role after a connection is established. Unlike the GAP Advertiser and GAP Scanner modules, GAP Initiator doesn’t have any callback function to call or to be called. Only a device initiated with the GAP Central Role can become an initiator.

In the basic_ble example, developers choose the device role in Sysconfig. This is covered in Developing with SDK CC23xx. Like all other BLE roles, after the stack is initialized, handlers are registered in the role’s respective start function.

Listing 67. app_central.c :: Central_Start() Setup of Central Role

bStatus_t Central_start()
{
    bStatus_t status = SUCCESS;

    status = BLEAppUtil_registerEventHandler(&centralScanHandler);
    if(status != SUCCESS)
    {
        // Return status value
        return(status);
    }

    status = BLEAppUtil_scanInit(&centralScanInitParams);
    if(status != SUCCESS)
    {
        // Return status value
        return(status);
    }

    status = BLEAppUtil_setConnParams(&centralConnInitParams);
    if(status != SUCCESS)
    {
        // Return status value
        return(status);
    }

    // Return status value
    return(status);
}

Initiiating connections is handled through the application menu, located in app_menu.c.

Listing 68. app_menu.c :: Menu_connectToDeviceCB - Initiating connection in Central Role

void Menu_connectToDeviceCB(uint8 index)
{
    bStatus_t status;

    // Get the scan results list
    App_scanResults *menuScanRes;
    uint8 size = Scan_getScanResList(&menuScanRes);

    // Set the connection parameters
    BLEAppUtil_ConnectParams_t connParams =
    {
     .peerAddrType = menuScanRes[index].addressType,
     .phys = INIT_PHY_1M,
     .timeout = 1000
    };

    // Copy the selected address
    memcpy(connParams.pPeerAddress, menuScanRes[index].address, B_ADDR_LEN);
    status = BLEAppUtil_connect(&connParams);

    // Print the status of the connect call
    MenuModule_printf(APP_MENU_GENERAL_STATUS_LINE, 0, "Call Status: Connect = "
                      MENU_MODULE_COLOR_BOLD MENU_MODULE_COLOR_RED "%d" MENU_MODULE_COLOR_RESET,
                      status);

    // Go back to the last menu
    MenuModule_goBack();
}

Note that the call to BLEAppUtil_connect() serves as a wrapper to the GAP API that connects to the address and parameters specified in the BLEAppUtil_ConnectParams_t structure. Taking a closer look at the BLEAppUtil_connect() function will reveal the GAP API GapInit_connect().

Listing 69. bleapputil_init.c :: BLEAppUtil_connect() - Initiating connection in Central Role

bStatus_t BLEAppUtil_connect(BLEAppUtil_ConnectParams_t *connParams)
{
    return GapInit_connect(connParams->peerAddrType, connParams->pPeerAddress,
                           connParams->phys, connParams->timeout);
}

If the on-going connection attempt is intended to be canceled by either timeout or a user request (the application calling GapInit_cancelConnect() or BLEAppUtil_cancelConnect()), the stack notifies the application of the cancellation completion with a BLEAPPUTIL_CONNECTING_CANCELLED_EVENT.

Attention

When initiating timeout is set to 0 (wait indefinitely), the CC23xx will stay in initiator role until a connection is successfully established. If the peripheral device disappeared from the network before the connection is established, the only method for initiator to exit this state is to call GapInit_cancelConnect() or BLEAppUtil_cancelConnect().

GAP Central

The GAP Central role is demonstrated in app_central.c. The Central role demonstrates the use of the scanning and initiating states and supports connections to peripheral devices. The steps to use this module are as follows.

For configuration of the Bluetooth Low Energy stack features, see Developing with SDK CC23xx and Stack Configurations.

#. After the stack is initialized, the Central_start() function initializes all the handlers necessary to implement the Central role.

bStatus_t Central_start()
{
    bStatus_t status = SUCCESS;

    status = BLEAppUtil_registerEventHandler(&centralScanHandler);
    if(status != SUCCESS)
    {
        // Return status value
        return(status);
    }

    status = BLEAppUtil_scanInit(&centralScanInitParams);
    if(status != SUCCESS)
    {
        // Return status value
        return(status);
    }

    status = BLEAppUtil_setConnParams(&centralConnInitParams);
    if(status != SUCCESS)
    {
        // Return status value
        return(status);
    }

    // Return status value
    return(status);
}

GAP Connection State

A BLE device can be either in the Central or Peripheral role in the Connection State. After devices enter connection state, the devices exchange data under specific time within a specific time slot. This slot where the data is exchanged is called a Connection Event.

The beginning of the Connection Event is called an Anchor Point. During the connection event, the central and peripheral device will meet at the anchor point and the central will transmit the first packet, while the peripheral will have woken up to listen for the central devices transmitted packet.

Note

There is no limitation on the number of packet transactions per connection event other than MAX_NUM_PDU define in TI’s BLE5-Stack. It can either be one packet per direction or multiple packets per direction.

Connection Event Callback

Knowing what happened during the connection event can be beneficial for the system design. For example, by knowing which channels has higher CRC error, the application layer can decide to do a channelmap update to avoid those channels to ensure better communication.

TI’s BLE5-Stack provides the ability for application to obtain a detailed report of the connection event. The report will be sent at the end of the connection event and it contains status and statistics of the most recent connection event.

The report contains the following parameters:

• status - Status of the last connection event.

  status	Description
  GAP_CONN_EVT_STAT_SUCCESS	Both central and peripheral show up for the conenction event and exchange packets.
  GAP_CONN_EVT_STAT_CRC_ERROR	Packets were exchanged but the failed at the CRC checkout.
  GAP_CONN_EVT_STAT_MISSED	The peer device did not show up for the connection event.

• handle - Connection event handle which is used to identify the most recent connection event when there are multilple connections per device.

• channel - The RF channel which the most recent connection event used.

• phy - The PHY which the most recent connection event used.

• lastRssi - The RSSI value measured on the last packet of the most recent connection event.

• packets - Number of packets received during the most recent connection event.

• errors - Accumulated number of packets with CRC error for this connection handle.

• nextTaskType - The next task the link layer is going to run.

• nextTaskTime - The time to next task.

• eventCounter - The event counter of the most recent connection event.

• timeStamp - The anchor point of the most recent connection event.

• eventType - There are 3 types of events returning from BLE5-Stack.

  eventType	Description
  GAP_CB_CONN_ESTABLISHED	This event is returned when connection is established. When this returns, the eventCount will be 0.
  GAP_CB_PHY_UPDATE	This event is returned when last connection event received LL_PHY_UPDATE_IND packet.
  GAP_CB_CONN_EVENT_ALL	This event covers the above and rest of the scenarios.

To enable the application layer to receive connection report, you can use BLEAppUtil_registerConnNotifHandler() located in bleapputil_init.c.

The following code is an example of how to register connection event report for all types of event within certain connection.

Listing 70. Register for connection event report

// Assuming connHandle was assigned when the connection established.
uint16_t connHandle;

BLEAppUtil_registerConnNotifHandler(connHandle);

BLEAppUtil_registerConnNotifHandler() serves as a wrapper for Gap_registerConnEventCb() and defaults to all events. For finer control, a developer can call Gap_registerConnEventCb() directly with the bit mask desired or modify the function call directly within BLEAppUtil_registerConnNotifHandler().

The available bit masks may be found in gap.h.

Listing 71. Available Connection Event bit masks

/**
 * Connection Event type to register
 */
typedef enum
{
  GAP_CB_EVENT_INVALID                   = 0x00,   //!< Invalid event type
  GAP_CB_CONN_ESTABLISHED                = 0x01,   //!< Connection established, procedure 0
  GAP_CB_PHY_UPDATE                      = 0x02,   //!< PHY was updated, procedure 1
  GAP_CB_CONN_EVENT_ALL                  = 0xFF    //!< All connection Events
} GAP_CB_Event_e;

Listing 72. Register for connection event report directly

bStatus_t BLEAppUtil_registerConnNotifHandler(uint16_t connHandle)
{
    return Gap_RegisterConnEventCb(BLEAppUtil_connEventCB, GAP_CB_REGISTER, GAP_CB_CONN_EVENT_ALL, connHandle);
}

Whenever a connection event is received, BLEAPPUTIL_EVT_CONN_EVENT_CB will queued to the application.

Connection Parameters

This section describes the connection parameters which are sent by the initiating device with the connection request and can be modified by either device when the connection is established. These parameters are as follows:

• Connection Interval - In Bluetooth Low Energy connections, a frequency-hopping scheme is used. The two devices each send and receive data from one another only on a specific channel at a specific time. These devices meet a specific amount of time later at a new channel (the link layer of the Bluetooth Low Energy protocol stack handles the channel switching). This meeting where the two devices send and receive data is known as a connection event. If there is no application data to be sent or received, the two devices exchange link layer data with empty application payload to maintain the connection. The connection interval is the amount of time between two connection events in units of 1.25 ms. The connection interval can range from a minimum value of 6 (7.5 ms) to a maximum of 3200 (4.0 s). See Connection Event and Interval for more details.

Figure 70. Connection Event and Interval

Different applications may require different connection intervals. As described in Connection Parameter Considerations, these requirements affect the power consumption of the device. For more detailed information on power consumption, see the Measuring Bluetooth Smart Power Consumption Application Report (SWRA478).

• Peripheral Latency - Formerly known as ‘Slave Latency’. This parameter gives the Peripheral device the option of skipping a number of connection events. This ability gives the peripheral device some flexibility. If the peripheral does not have any data to send, it can skip connection events, stay asleep, and save power. The peripheral device selects whether to wake or not on a per connection event basis. The peripheral can skip connection events but must not skip more than allowed by the Peripheral latency parameter or the connection fails. See picture below for more details.

• Supervision Time-out - This time-out is the maximum amount of time between two successful connection events. If this time passes without a successful connection event, the device terminates the connection and returns to an unconnected state. This parameter value is represented in units of 10 ms. The supervision time-out value can range from a minimum of 10 (100 ms) to 3200 (32.0 s). The time-out must be larger than the effective connection interval (see Effective Connection Interval for more details).

Effective Connection Interval

The effective connection interval is equal to the amount of time between two connection events, assuming that the Peripheral skips the maximum number of possible events if Peripheral latency is allowed (the effective connection interval is equal to the actual connection interval if Peripheral latency is set to 0).

The Peripheral Latency value represents the maximum number of events that can be skipped. This number can range from a minimum value of 0 (meaning that no connection events can be skipped) to a maximum of 499. The maximum value must not make the effective connection interval (see the following formula) greater than 16 s. The interval can be calculated using the following formula:

Effective Connection Interval = (Connection Interval) * (1 + [Peripheral Latency])

Consider the following example:

• Connection Interval: 80 (100 ms)

• Peripheral Latency: 4

• Effective Connection Interval: (100 ms) * (1 + 4) = 500 ms

When no data is being sent from the Peripheral to the Central, the Peripheral transmits during a connection event once every 500 ms.

Connection Parameter Considerations

In many applications, the Peripheral skips the maximum number of connection events. Consider the effective connection interval when selecting or requesting connection parameters. Selecting the correct group of connection parameters plays an important role in power optimization of the Bluetooth Low Energy device. The following list gives a general summary of the trade-offs in connection parameter settings.

Reducing the connection interval does as follows:

• Increases the power consumption for both devices

• Increases the throughput in both directions

• Reduces the time for sending data in either direction

Increasing the connection interval does as follows:

• Reduces the power consumption for both devices

• Reduces the throughput in both directions

• Increases the time for sending data in either direction

Reducing the Peripheral latency (or setting it to zero) does as follows:

• Increases the power consumption for the peripheral device

• Reduces the time for the peripheral device to receive the data sent from a central device

Increasing the Peripheral latency does as follows:

• Reduces power consumption for the peripheral during periods when the peripheral has no data to send to the central device

• Increases the time for the peripheral device to receive the data sent from the central device

Connection Parameter Update

In some cases, the central device requests a connection with a peripheral device containing connection parameters that are unfavorable to the peripheral device. In other cases, a peripheral device might have the desire to change connection parameters in the middle of a connection, based on the peripheral application. The peripheral device can request the central device to change the connection parameters by sending a Connection Parameter Update Request. For Bluetooth 4.1, 4.2, 5.0 and 5.1-capable devices, this request is handled directly by the Link Layer. For Bluetooth 4.0 devices, the L2CAP layer of the protocol stack handles the request. The Bluetooth Low Energy stack automatically selects the update method.

The Connection Parameter Update Request contains four parameters:

• Minimum connection interval

• Maximum connection interval

• Peripheral latency

• Supervision time-out

These values represent the parameters that the peripheral device wants for the connection. The connection interval is given as a range. When the central device receives the Connection Parameter Update Request request, it can accept or reject the new parameters.

Sending a Connection Parameter Update Request is optional and it is not required for the central device to accept or apply the requested parameters. Some applications try to establish a connection at a faster connection interval to allow for a faster service discovery and initial setup. These applications later request a longer (slower) connection interval for optimal power usage.

Regardless of the roles (peripheral or central), connection parameter updates can be sent asynchronously with the GAP_UpdateLinkParamReq() command. The simple_peripheral application can be configured to automatically send a parameter update a certain amount of time after establishing a connection. For example, the simple_peripheral application uses the following symbols, defined in simple_peripheral.c:

#define DEFAULT_DESIRED_MIN_CONN_INTERVAL     80
#define DEFAULT_DESIRED_MAX_CONN_INTERVAL     800
#define DEFAULT_DESIRED_SLAVE_LATENCY         0
#define DEFAULT_DESIRED_CONN_TIMEOUT          1000
#define SP_SEND_PARAM_UPDATE_DELAY            6000

In simple_peripheral, six seconds after a connection is established the application automatically sends a GAP Update Link Parameter Request:

Listing 73. simple_peripheral.c :: SimplePeripheral_processParamUpdate() - Initiating parameter update request

  static void SimplePeripheral_processParamUpdate(uint16_t connHandle)
  {
    gapUpdateLinkParamReq_t req;
    req.connectionHandle = connHandle;
    req.connLatency = DEFAULT_DESIRED_SLAVE_LATENCY;
    req.connTimeout = DEFAULT_DESIRED_CONN_TIMEOUT;
    req.intervalMin = DEFAULT_DESIRED_MIN_CONN_INTERVAL;
    req.intervalMax = DEFAULT_DESIRED_MAX_CONN_INTERVAL;

    // Send parameter update
    bStatus_t status = GAP_UpdateLinkParamReq(&req);

When the peer device receives this update request, the GAP parameter GAP_PARAM_LINK_UPDATE_DECISION determines how it responds. See GAP Peripheral for an explanation of how this parameter is configured.

Connection Termination

Either the Central or the Peripheral can terminate a connection for any reason. One side initiates termination and the other side must respond before both devices exit the connected state. Use the GAP_TerminateLinkReq() command to terminate an existing connection.