- Ask a related questionWhat is a related question?A related question is a question created from another question. When the related question is created, it will be automatically linked to the original question.
This page explains necessary steps to port projects from an older version of the TI Bluetooth(R) low energy software stack (BLE-Stack) v2.x SDK installer to a newer version. As always, it is recommended to make a backup copy of all changes prior to porting your project. In addition to making a backup of your project, TI recommends making a backup (zip) of the BLE-Stack SDK, typically installed to C:\ti\simplelink\ble_cc26xx_2_0x_0y_nnnnn, prior to developing your Bluetooth Smart application.
The procedures listed below assume the developer is familiar with the IDE and build environment concepts described in the CC2640 BLE SW Developer's Guide (SWRU393). A copy of the Developer's Guide can be found in the Documents folder of the BLE-Stack SDK installer.
See the Porting chapter of the software developer's guide.
The underlying ECC software used to generate the Public/Private Key pair and the DH Key check will lock the BLE-Stack task for approximately 160ms. This lock will occur twice during secure connections pairing. When using a LE Secure Connections pairing method, it is recommend to configure a supervision timeout of at least 165ms to prevent the link from dropping during ECDH key operations. Additionally the application should be prepared to be preempted/blocked during this time.
Note: This only affects stacks using the LE Secure Connections feature
This section will describe how to update from BLEv2.2.1 to BLE v2.2.2. Application source code previously developed or updated to BLE 2.2.1 can be ported to BLE 2.2.2 with minimal effort due to the fact that no BLE APIs were modified between these releases. Notable differences include:
1. Copy your project files, source files, and any modified BLE Stack source files from the 2.2.1 installer to the 2.2.2 installer, ensuring to merge any changes with common (non-application) SDK files.
2. Verify your application's .customargvars (IAR) / .cproject or .projectspec (CCS) point to resources in the TI-RTOS 2.21.01.08 & XDCTools default installation path. These can be inspected by importing an unmodified sample application from the BLE 2.2.2 SDK. These are the same parameters, but different values, as listed below for BLE 2.2.1.
3. Open/import your project in IAR 7.80.4 or CCS v7.4. Note that CCS projects now use the TI ARM Compiler 16.9.4.LTS and the RTSC option needs to specify the new TI-RTOS version.
=Porting BLEv2.2.0 Projects to BLEv2.2.1= This section will describe one way port a project from BLEv2.2.0 to BLE v2.2.1. It assumes that your project is constructed similar to the default stack projects. That is, the project files exist under $INSTALL$/examples/cc2650em/ and source files exist under the respective folder in $INSTALL$/src/. It also assumes that you are using the default .customargvars (IAR) / .cproject or .projectspec (CCS) which use the relative location of the IAR / CCS project files to point to BLE Stack components. If your project exists outside of the standard directory structure of the source installer and uses absolute paths for these variables, you’ll need to manually modify these to point to the respective directories in the 2.2.1 installer. In this case, the .cfg file in the application project will also need to be manually modified to point to the 2.2.1 .cfg ($INSTALL$/src/common/cc26xx/kernel/cc2640/config/cc2640.cfg)
1. Copy your project files, source files, and any modified BLE Stack source files from the 2.2.0 installer to the 2.2.1 installer, ensuring to merge any changes with common files.
2. Since many of the environment variables defined in the .customargvars / .project or .projectspec use the relative location of the project file, these should successfully be updated from step 1. However, the paths relating to the new RTOS need to be manually updated. The following should be used based on the type of project:
Argvars to be used for 2.2.1 installer
2.2.1 Environment Variables for CCS
3. Open in the new IAR (7.70.2) / CCS (6.2.0 Build 50 or later)
4.In the application project, under Drivers --> RF…remove RF.c and add $TI_RTOS_DRIVERS_BASE$\ti\drivers\rf\RFCC26XX_singleMode.c
5. In the application project, under Drivers, add a TRNG folder and add the following files:
6. In the stack project, add $SRC_BLE_CORE$/rom to preprocessor search path
7. Remove common_rom_init.c and rom_init.c from the Startup folder and add $ROM$\rom_jt.c
8. If building with the Secure Connections feature defined (-DBLE_V42_FEATURES=SECURE_CONNS_CFG or similar), add $SRC_EX$\host\sm_ecc.c to the Profiles folder:
The following tips for maximizing the amount of flash memory to the application is a supplement to Section 10.4 Optimizing Bluetooth low energy Stack Memory Usage from the BLE SW Developer's Guide (docID SWRU393 rev D).
BTool Procedure to Handle Connection Parameter Update Request
BLE Stack 2.2 is a major release that incorporates several bug fixes as well as new features from the BLE 2.2 specifications. See Software Developer's Guide(SDG)v2.2 for more details. The new features include:
New APIs associated with their respective APIs is described in the SDG. The following APIs have changed from 2.1 to 2.2:
void GAPBondMgr_SlaveReqSecurity(uint16 connHandle, uint8 authReq)bStatus_t GAP_Bond(uint16 connectionHandle, uint8 authenticated,
uint8 secureConnections, smSecurityInfo_t *pParams,
uint8 startEncryption)// Connection parameter update parameters.
static gapRole_updateConnParams_t gapRole_updateConnParams =
{
.paramUpdateEnable = FALSE,
.minConnInterval = DEFAULT_MIN_CONN_INTERVAL,
.maxConnInterval = DEFAULT_MAX_CONN_INTERVAL,
.slaveLatency = MIN_SLAVE_LATENCY,
.timeoutMultiplier = DEFAULT_TIMEOUT_MULTIPLIER
};
static bStatus_t gapRole_startConnUpdate(uint8_t handleFailure,
gapRole_updateConnParams_t *pConnParams);uint8_t authReq = ((gapSlaveSecurityReqEvent_t *)pMsg)->authReq;
GAPBondMgr_SlaveReqSecurity(connHandle, authReq);Most of these APIs changes are due to additional parameters that have been added to support new features.
Other than the new features, the major change in BLE SDK 2.2 is the new directory structure. In addition, a new naming convention is used to a common naming standard for file and folder names. See Section 2.4 Directory Structure in the Software Developer's Guide v2.2 for more information.
Note: To port from a release prior to BLE v2.1.1, we recommend following the porting guides incrementally up to this version.
To port from a project based on 2.1 to 2.2, we recommend manually adding the changes into the 2.2 directory files due to the extensive amount of changes incorporated in the 2.2 release.
Copying the reset vectors was removed from main.c since it is now configured in the RTOS configuration file. The options are set in the Pre-build command option: "--cfgArgs NO_ROM=1,OAD_IMG_E=1" to make RTOS automatically copy the reset vectors into RAM before main.c for OAD projects.
There is significant amount of change from the TI-RTOS used in BLE SDK v2.1 to v2.2. Some of the RTOS changes are detailed in this guide.
See the following watchdog consideration: https://e2e.ti.com/support/wireless_connectivity/bluetooth_low_energy/f/538/p/543091/1984008#1984008
A new display driver has been added. For example, to add the UART display to the Launchpad, define/modify these in preprocessor settings:
xDisplay_DISABLE_ALL
xBOARD_DISPLAY_EXCLUDE_UART
BOARD_DISPLAY_EXCLUDE_LCD
and open the display to use UART in simple_peripheral.c:
dispHandle = Display_open(Display_Type_UART, NULL);
To not use the display at all, define
Display_DISABLE_ALL
The Display_print() macros can be redefined in the project to output to another debug module. For example, in the SPP BLE project, it is routed to the UART via the DEBUG macro:
# define Display_print0(handle, line, col, fmt) DEBUG(fmt); \
DEBUG_NEWLINE()
# define Display_print1(handle, line, col, fmt, a0) DEBUG(fmt); \
DEBUG_NEWLINE()This section shows some examples of changes needed to port an existing project from v2.1 to v2.2.
The following files need to be added:
Note: Make sure to disable all displays since Launchpad does not include a display and the SDI uses the UART for sending data.
The following modifications has to be made:
# elif defined(SDI_USE_UART)
# define MRDY_PIN Board_BUTTON0
# define SRDY_PIN Board_BUTTON1
# endif#include <ti/drivers/Power.h>
#include <ti/drivers/power/PowerCC26XX.h>// set constraints for Standby and idle mode
Power_setConstraint(PowerCC26XX_SB_DISALLOW);
Power_setConstraint(PowerCC26XX_IDLE_PD_DISALLOW);if (!UARTCharsAvail(((UARTCC26XX_HWAttrsV1 const *)(uartHandle->hwAttrs))->baseAddr))
const uint8 NV_FLASH[FLASH_PAGE_SIZE] = {0xFF};
The BLE-Stack v2.1.1 release is a maintenance release to the existing v2.1.0 release. Most v2.1.1 changes are incorporated in library form, therefore porting from v2.1.0 uses a simplified procedure. For porting earlier v2.0 projects, it is recommended to first port to v2.1.0, then follow the below instructions to incorporate the v2.1.1 changes. For a detailed list of the changes in v2.1.1, please refer to the release notes included in the BLE-Stack v2.1.1 SDK installer.
==IAR & CCS Project Porting Directions==
1. Move (or Copy) the project files from $2.1.0_INSTALL$\Projects\ble\$PROJECT$ to $INSTALL\Projects\ble\$PROJECT$ where $2.1.0_INSTALL$ is the top level installation directory of the v2.1.0 stack, $INSTALL$ is the top level installation directory of the 2.1.1 stack, and $PROJECT$ is your project folder.
2. When porting from v2.1.0, the only source file required to be merged to a v2.1.1 based project is $INSTALL$\Projects\ble\ICall\Application\bleUserConfig.c. It can be accessed from the IDE in the Application project under the ICallBLE virtual folder. Under normal conditions, this file is not modified during project development. However, if you have made changes to bleUserConfig.c, merge your changes to the v2.1.1 bleUserConfig.c version.
3a. For IAR: Open the updated v2.1.1 project workspace from $PROJECT$\CC26xx\IAR.
3b. For CCS: Import the Application and Stack projects from $PROJECT$\CC26xx\CCS into your workspace using Project-->Import CCS Projects.
4. Rebuild & save your project.
1. Move (or Copy) the project files from $2.0.0_INSTALL$\Projects\ble\$PROJECT$ to $INSTALL\Projects\ble\$PROJECT$ where $2.0.0_INSTALL$ is the top level installation directory of the 2.0.0 stack, $INSTALL$ is the top level installation directory of the 2.1.0 stack, and $PROJECT$ is your project folder.
2. If you modified any files from anywhere outside of the application folder, such as in the profiles at $2.1.0_INSTALL$\Projects\Profiles, you will need to merge your changes with the new 2.1.0 version.
3. Open your project (now in the 2.1.0 folder) with IAR >= 7.40.2
4. When prompted, choose yes to convert for use with new IAR version.
5. The device information profile path has changed. If this is part of your project, remove the old file (devinfoservice.c) from the project (it will be in the PROFILES group). Then add the file from the correct path ($INSTALL\Projects\ble\Profiles\DevInfo\CC26xx\devinfoservice.c)
6. There are several files in the $PROJECT$\Config folder which need to be updated for 2.1.0. The easiest way to do this is to delete this folder and copy the Config folder from the SimpleBLEPeripheral sample project ($INSTALL$\Projects\ble\SimpleBLEPeripheral\CC26xx\IAR\Config) for use. Then, if there were any modifications to any of these files in the original 2.0.0 project, replicate the modifications here.
7. Similarly, the stack configuration file needs to be updated. The easiest way to do this is to replace the $PROJECT$\Stack\CC2640\buildConfig.opt file with $INSTALL\Projects\ble\SimpleBLEPeripheral\CC26xx\IAR\Stack\CC2640\buildConfig.opt. Then make any desired modifications.
8. The custom argument variables must be updated to use the new RTOS. The easiest way to do this is to replace the 2.0.0 .custom_argvars file in $PROJECT$ with the .custom_argvars from the simpleBLEPeripheral project: $INSTALL\Projects\ble\SimpleBLEPeripheral\CC26xx\IAR\SimpleBLEPeripheral.custom_argvars). Close and re-open the IAR workspace after changing these variables.
9. Delete the $PROJECT$\Application\CC2640\configPkg and $PROJECT$\CC26xx\IAR\Config\src folders to remove any remnants of the old RTOS.
10. Compile and save your project.
1. Move (or Copy) the project files from $2.0.0_INSTALL$\Projects\ble\$PROJECT$ to $INSTALL\Projects\ble\$PROJECT$ where $2.0.0_INSTALL$ is the top level installation directory of the 2.0.0 stack, $INSTALL$ is the top level installation directory of the 2.1.0 stack, and $PROJECT$ is your project folder.
2. If you modified any files from anywhere outside of the application folder, such as in the profiles at $2.1.0_INSTALL$\Projects\Profiles, you will need to merge your changes with the new 2.1.0 version.
3. Using CCS 6.1.0, import the application and stack projects from $PROJECT$\CC26xx\CCS into your workspace using Project-->Import CCS Projects. The relevant project folder in your folder will be referred to as $WORKSPACE$.
1. The device information profile path has changed. If this is part of your project, remove the old file (devinfoservice.c) from the project (it will be in the PROFILES group). Then add the file from the correct path ($INSTALL\Projects\ble\Profiles\DevInfo\CC26xx\devinfoservice.c)
2. There are several files in the $PROJECT$\CC6xx\CCS\Config folder which need to be updated for 2.1.0. The easiest way to do this is to delete this folder and copy the Config folder from the SimpleBLEPeripheral sample project ($INSTALL$\Projects\ble\SimpleBLEPeripheral\CC26xx\CCS\Config) for use. Then, if there were any modifications to any of these files in the original 2.0.0 project, replicate the modifications here.
3. In the project properties, under Resource->Linked Resources in the Path Variables tab, update the following names:
CC26XXWARE = C:\ti\tirtos_simplelink_2_13_00_06\products\cc26xxware_2_21_01_15600
TI_RTOS_DRIVERS_BASE = C:\ti\tirtos_simplelink_2_13_00_06\packages
4. Under General in the Main tab, select the TI v5.2.4 compiler
5. Under General in the RTSC tab, select the 2.13.0.06 TI-RTOS and choose version 3.31.1.33 of XDCTools from the drop down menu. Then reselect ti.platforms.simplelink:CC2640F128 from the Platforms dropdown menu.
6. Under Build->ARM Compiler->Advanced Options->Predefined Symbols, remove the __TI_COMPILER_VERSION=1 define
7. Clean out the old RTOS by deleting the $PROJECT$\CC25xx\CCS\Config\src and $WORKSPACE$\FlashROM\configPkg folders if they exist.
8. Remove all uncommented lines from the ccsLinkerDefines.cmd and ccsCompilerDefines.bcfg files. These are located under the TOOLS folder.
9. Do not compile yet.
1. The stack configuration file needs to be updated. The easiest way to do this is to replace the $PROJECT$\CC26xx\IAR\Stack\CC2640\buildConfig.opt file with $INSTALL\Projects\ble\SimpleBLEPeripheral\CC26xx\IAR\Stack\CC2640\buildConfig.opt. Then make any desired modifications.
2. In the project properties, under Resource->Linked Resources in the Path Variables tab, update the following name:
CC26XXWARE = C:\ti\tirtos_simplelink_2_13_00_06\products\cc26xxware_2_21_01_15600
3. Delete the pwrmon.c and pwrmon.h files from the project. They can be found in HAL\Target\CC2650\Drivers
4. Under General in the Main tab, select the TI v5.2.4 compiler
5. Under Build->ARM Compiler->Advanced Options->Predefined Symbols, remove the __TI_COMPILER_VERSION=1 define
8. Remove all uncommented lines from the ccsLinkerDefines.cmd and ccsCompilerDefines.bcfg files. These are located under the TOOLS folder.
1. Compile the Stack Project. If there is a Boundary error after the first compilation, compile again. See the Boundary Tool in the software developer's guide for more information.
2. Compile the Application Project.
3. Load the Application Project.
4. Load the Stack Project.
1. The following array elements of structures defined in att.h have changed from uint8 to uint16:
2. The GAP_RegisterForHCIMsgs() command has changed to GAP_RegisterForMsgs().
3. The gattService_t structure has an additional encKeySize field:
typedef struct
{
uint16 numAttrs; //!< Number of attributes in attrs
uint8 encKeySize;//!< Minimum encryption key size required by service (7-16 bytes)
/** Array of attribute records.
* NOTE: The list must start with a Service attribute followed by
* all attributes associated with this Service attribute.
*/
gattAttribute_t *attrs;
} gattService_t;Because of this, the GATTServApp_RegisterService() command has an additional encryption key size parameter:
4. The connection event callback command can now work with multiple connections. Therefore a connHandle parameter has been added:
5. The HCI_EXT_GetNumConnsCmd() command has been replaced with the HCI_EXT_GetConnInfoCmd() command. See the software developer's guide for more information.
6. A connection handle parameter has been added to the ggsAttrValueChange_t function type:
7. The read and write profile callback function types have been modified: the pLen and maxlen parameters have been changed from uint8 to uint16:
8. RSSI functionality has been moved from the GAPRole to the application. See the simpleBLEcentral project (and central GAPRole) for an example.
The BLE-Stack v2.2 comes with tirtos_cc13xx_cc26xx_2_18_00_03 and all the software testing was done with this combination. Therefore, it's not recommended to change TI-RTOS version if you want to use BLE-Stack. Here we are providing a workaround for users who would like to use the addition drivers which release in tirtos_cc13xx_cc26xx_2_20_00_06 or later.
Please noted, here we are using simple_peripheral launchpad as example. You can use the same guide to port the drivers to work with different board files.
1. Rename the PWM folder, driver files and board file folder in TI-RTOS 2.18(C:\ti\tirtos_cc13xx_cc26xx_2_18_00_03\products\tidrivers_cc13xx_cc26xx_2_16_01_13\packages\ti\drivers) to something different (optional, but recommended)
C:\ti\tirtos_cc13xx_cc26xx_2_18_00_03\products\tidrivers_cc13xx_cc26xx_2_16_01_13\packages\ti\boards
2. Rename the board files in BLE stack(C:\ti\simplelink\ble_sdk_2_02_00_31\src\boards)
3. Copy the needed driver and board files from TI-RTOS 2.20 over to TI-RTOS 2.18(we copied all the new drivers for convenience, so we don't need to do any more modification on the board files other than copy&paste)
From C:\ti\tirtos_cc13xx_cc26xx_2_20_00_06\products\tidrivers_cc13xx_cc26xx_2_20_00_08\packages\ti\drivers to C:\ti\tirtos_cc13xx_cc26xx_2_18_00_03\products\tidrivers_cc13xx_cc26xx_2_16_01_13\packages\ti\drivers
From C:\ti\tirtos_cc13xx_cc26xx_2_20_00_06\products\tidrivers_cc13xx_cc26xx_2_20_00_08\packages\ti\boards to C:\ti\tirtos_cc13xx_cc26xx_2_18_00_03\products\tidrivers_cc13xx_cc26xx_2_16_01_13\packages\ti\boards
4. Copy the needed board files from TI-RTOS 2.20 to BLE stack
From C:\ti\tirtos_cc13xx_cc26xx_2_20_00_06\products\tidrivers_cc13xx_cc26xx_2_20_00_08\packages\ti\boards to C:\ti\simplelink\ble_sdk_2_02_00_31\src\boards
Comment out the following line in the CC2650_LAUNCHXL.h(Only needed for the board files in BLE stack)
5. Import simple_peripheral to CCS, make sure the compiler version for both stack and app >= 5.2.6
6. Add virtual folders under the Drivers folder and drag the files into the new folders you made
7. Make sure the location of the files are relative to TI_RTOS_DRIVERS_BASE
8. In file main.c, add the following code
9. In int main(), add
10. Delete the FlashROM folder in app, then build stack and application.
5. Add virtual folders under the Drivers folder and drag the files into the new folders you made
6. Make sure the location of the files are relative to TI_RTOS_DRIVERS_BASE
7. In file main.c, add the following code
8. In int main(), add
9. Rebuild the cc2650lp_app
