BLE-Stack 3.00.01 to BLE-Stack 3.01.00

This section will describe a way to migrate a project from BLE-Stack 3.00.01 to a BLE-Stack 3.01.00 project.

For this migration guide, simple_peripheral from BLE-Stack 3.00.01 will be ported over to BLE-Stack 3.01.00. Because the directory structure is nearly identical between the two releases, the recommended approach is to start with a BLE-Stack 3.01.00 project that contains the same base functionality as the porting target project and merge in any custom functionality.

  1. Choose a BLE-Stack 3.01.00 example project that contains your target project’s base functionality.

    For reference, see available sample projects that start with simple_peripheral

    In this example, we’re going to use simple_peripheral as the starting BLE-Stack 3.01.00 sample project.

  2. Transfer all modified application files from BLE-Stack 3.00.01 into the BLE-Stack 3.01.00 example project.

    In this example, the following files from BLE-Stack 3.00.01 were moved into simple_peripheral BLE-Stack 3.01.00 example:

    • simple_peripheral.c
    • simple_peripheral.h
    • simple_gatt_profile.c
    • simple_gatt_profile.h
  3. Replace includes of icall_apimsg.h and icall_api.h with icall_ble_api.h.

    #include "icall_ble_api.h"
    

    Make sure not to include any of the following files in your project: (They are already included in icall_ble_api.h.)

    • gap.h
    • hci.h
    • l2cap.h
    • gatt.h
    • gattserverapp.h
    • linkdb.h
    • att.h
  4. If your code contains any #ifdef USE_CORE_SDK, remove these.

  5. Modify main.c in the BLE-Stack 3.01.00 example if additional tasks were added in the BLE-Stack 3.00.01 project.

  6. Please do not add any DV42_FEATURES defines to build_config.opt in BLE-Stack 3.01.00. If you want to enable or disable Secure Connections, please use the GAPBOND_SECURE_CONNECTION parameter. (Secure Connections is enabled by default in BLE-Stack 3.01.00.)

    uint8_t gapbondSecure = GAPBOND_SECURE_CONNECTION_NONE;
    GAPBondMgr_SetParameter(GAPBOND_SECURE_CONNECTION, sizeof(uint8_t), &gapbondSecure);
    
  7. In BLE-Stack 3.01.00, heap management has been updated. Please see Dynamic Memory Allocation for details on how to optimize your heap.

  8. In BLE-Stack 3.01.00, OAD has been updated. Please see Over the Air Download (OAD).

  9. If you are using the GAPBondMgr, make sure a passcode callback function is defined and sent to the GAPBondMgr. This is mandatory in BLE-Stack 3.01.00.

    // GAP Bond Manager Callbacks
    // These are set to NULL since they are not needed. The application
    // is set up to only perform justworks pairing.
    static gapBondCBs_t simpleBLEPeripheral_BondMgrCBs =
    {
        (pfnPasscodeCB_t) SimpleBLEPeripheral_passcodeCB, // Passcode callback
        SimpleBLEPeripheral_pairStateCB                   // Pairing / Bonding state Callback
    };
    

    The passcode callback and handling can be done the following way:

    Define an event SBP_PASSCODE_NEEDED_EVT such that the SimpleBLEPeripheral_passcodeCB function can enqueue a message for the application task to handle.

    #define SBP_STATE_CHANGE_EVT                  0x0001
    #define SBP_CHAR_CHANGE_EVT                   0x0002
    #define SBP_PASSCODE_NEEDED_EVT               0x0003
    

    The callback function will push this event to application task so that the BLE-Stack API call can happen in the application context.

    // Forward Declaration
    static void SimpleBLEPeripheral_passcodeCB(uint8_t *deviceAddr, uint16_t connHandle, uint8_t uiInputs, uint8_t uiOutputs);
    
    // Definition
    /*********************************************************************
    * @fn      SimpleBLEPeripheral_passcodeCB
    *
    * @brief   Passcode callback.
    *
    * @return  none
    */
    static void SimpleBLEPeripheral_passcodeCB(uint8_t *deviceAddr, uint16_t connHandle, uint8_t uiInputs, uint8_t uiOutputs)
    {
        uint8_t *pData;
    
        // Allocate space for the passcode event.
        if ((pData = ICall_malloc(sizeof(uint8_t))))
        {
            *pData = uiOutputs;
    
            // Enqueue the event.
            SimpleBLEPeripheral_enqueueMsg(SBP_PASSCODE_NEEDED_EVT, 0);
        }
    }
    

    Lastly, take the dequeued message in SimpleBLEPeripheral_processAppMsg and call the appropriate BLE-Stack API.

    /*********************************************************************
     * @fn      SimpleBLEPeripheral_processAppMsg
     *
     * @brief   Process an incoming callback from a profile.
     *
     * @param   pMsg - message to process
     *
     * @return  None.
     */
    static void SimpleBLEPeripheral_processAppMsg(sbpEvt_t *pMsg)
    {
        switch (pMsg->hdr.event)
        {
        // . . .
            case SBP_PASSCODE_NEEDED_EVT:
            {
              // Use static passcode
              uint32_t passcode = 123456;
              // Send passcode to GAPBondMgr (assuming single connection)
              GAPBondMgr_PasscodeRsp(0, SUCCESS, passcode);
            }
            break;
    
        default:
            // Do nothing.
            break;
        }
    }
    
  10. If necessary, update the project to use the newer TI-RTOS drivers that are supplied with the SimpleLink CC2640R2 SDK.

    The following drivers have changed from BLE-Stack 3.00.01. Please see the changes to these drivers by comparing the supplied headers between those in simplelink_cc2640r2_sdk_1_30_00_25 and those in the SimpleLink CC2640R2 SDK.

    • ADC
    • NVS
    • Display

    Attention

    The display folder should in BLE-Stack 3.01.00 be included with the path <ti/display/Display.h>, not <ti/mw/display/Display.h>.

    #include <ti/display/Display.h>
    
  11. Refer to the Upgrade and Compatibility Information for additional information and the TI-RTOS examples included with SimpleLink CC2640R2 SDK.

    For additional information on how BLE-Stack 3.01.00 uses TI-RTOS see TI-RTOS Overview

    For any utilized TI Drivers, review TI-RTOS Kernel Users Guide and Driver APIs.

Micro BLE Stack

The micro BLE Stack API has changed from ub_ to uble_. For details, see uble.h.