.. |OLD_STACK_VER| replace:: |DEVICE| SDK 9.11
.. |NEW_STACK_VER| replace:: |DEVICE| SDK 9.14

|OLD_STACK_VER| to |NEW_STACK_VER|
==================================

This section will describe how to port a project from |OLD_STACK_VER| to
a |NEW_STACK_VER| project.

.. note:: Vulnerability reports and mitigations can be found on `Report potential product security vulnerabilities <https://www.ti.com/PSIRT>`_.

.. _ble-porting-sdk-9-14:

Porting Bluetooth LE Projects
-----------------------------

The recommended method for porting an existing project from |OLD_STACK_VER|
to |NEW_STACK_VER| is to modify the project using only the Code Composer Studio interface.
The following steps will detail the changes needed when porting an out of the box
example from the SDK such as ``basic_ble``:

1. Import the project into Code Composer Studio.

2. In order to modify the SDK version, corresponding SysConfig version, as well as the compiler version, 
right-click on the imported project folder inside the Project Explorer and select ``Properties``.

3. In ``General``, select ``Compiler`` and choose the correct version. Refer to the Dependencies section
in the SDK release notes

  .. figure:: ./resources/8.40_to_9.10_compiler.png
      :align: center

      Code Composer Studio - Change Compiler Version.

4. Go to ``Dependencies`` and double-click on ``SimpleLink Low Power F3 SDK`` and choose the correct version.
Then double-click on ``SysConfig`` and do the same. Refer to the Dependencies Section in the SDK release notes
for the correct versions.

  .. figure:: ./resources/8.40_to_9.10_sdk.png
      :align: center

      Code Composer Studio - Change SDK and SysConfig Version.

5. Add the necessary files to `common->lib_opt` folders. Right click on the `lib_opt` folder 
and select `Add Files/Folders`. 

  .. figure:: ./resources/9_11_to_9_14_addFiles_Libopt.png
      :align: center

      Code Composer Studio - Add Files to CCS Project.

6. Click the `+` button on the top right of the pop up screen. Next navigate to the `lib_opt` folder in the 9.14 SDK. 
Select the ellipses `...` button and navigate to the `lib_opt` folder in the 9.14 SDK. 

  .. figure:: ./resources/9_11_to_9_14_selectfilpathsearch.png
      :align: center

      Code Composer Studio - Select File Path Selection.

7. Navigate to `COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR/source/ti/ble/stack_util/lib_opt/src` and select all 
the files in the folder. These include `ctrl_opt_dmm_dynamic_priority.c`, `ctrl_opt_dmm.c`, `ctrl_opt_ext_vendor_specific_cmd.c`, 
`ctrl_opt_past_receiver.c`, `ctrl_opt_past_sender.c`, `ctrl_opt_pawr_scan.c` , and `ctrl_opt_vendor_specific_cmd.c`. 

8. Follow steps 5-7 for the `HealthToolKit->inc` and `HealthToolKit` folders. Add files `ble_sys_stat.h` within the  
`COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR/source/ti/ble/stack_util/health_toolkit` folder, and `ble_sys_stat.c`
within `COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR/source/ti/ble/stack_util/health_toolkit/src` folder. 

9. The HSM firmware version has been updated from 3.0.0 to 3.1.1 for the |NEW_STACK_VER| SDK release. 
Update the HSM firmware using Uniflash or Code Composer Studio. 

If the newest SDK is not available, it will need to be actualized. To do this, go to ``File`` => ``Preferences`` 
=> ``Code Composer Studio Settings``, and select ``Products``. Inside the ``Products`` tab, press the refresh
button, which should discover the latest version of the SDK that was installed.

A Few Noteworthy Changes from |OLD_STACK_VER| to |NEW_STACK_VER|
----------------------------------------------------------------

You can follow the guide above without addressing these updates; they are listed
for your information only. All fine grained details might not be mentioned.  

API Changes include: 
 * Connection Monitor Role: 
    * Connection Monitor API `CMS_GetConnDataSize(void)` returns uint8_t instead of uint16_t. 
    * Connection Monitor API `CMS_GetConnData(uint16_t connHandle, uint8_t *pData)` adds `uint32_t accessAddr` to the 
      `CMS_GetConnData` structure. 
    * `adjustmentEvtTries` and `cmConnectionMaskRole_e connRole` removed from `cmStartMonitorParams_t` structure.
    * `cmDataSize` within `cmStartMonitorParams_t` has been changed from uint32_t to uint8_t. 
    * `cmReportEvt_t` now contains two packets, with either `CM_PKT_STATUS_NOT_RECEIVED`, 
      `CM_PKT_VALID_CENTRAL`, `CM_PKT_VALID_PERIPHERAL` or `CM_PKT_STATUS_UNDETERMINED` status. 
    * The size of Connection Monitor data is now 56 bytes. 

 * GapBondMgr: 
    * `gapBondMgrReadBondRec` has changed to `GapBondMgr_readBondFromNv`. 
       * The function now takes four inputs instead of nine. 
       * **pSavedBondRec** now contains all of the export bonding information. 
       * See :ref:`extract_bonding_information` for more details. 

 * Channel Sounding: 
    * `CS_writeRemoteFAETable(CS_writeRemoteFAETableParams_t *pParams)` has changed to 
      `CS_writeCachedRemoteFAETable(CS_writeCachedRemoteFAETableParams_t *pParams)` within `cs.h`. 
    * `ChannelSounding_writeRemoteFAETable(ChannelSounding_writeRemoteFAETableParams_t *pParams)` 
      has been changed to `ChannelSounding_writeCachedRemoteFAETable(ChannelSounding_writeCachedRemoteFAETable *pParams)`
      within `app_cs.h` and `app_cs.c`.
    * Function `CS_WriteCachedRemoteSupportedCapabilities(CS_writeCachedRemoteSupportedCapabilitiesParams_t *pParams)` 
      has been added to `cs.h`.
    * Function `ChannelSounding_writeCachedRemoteSupportedCapabilities
      (ChannelSounding_writeCachedRemoteSupportedCapabilitiesParams_t *pParams)` 
      has been added into `app_cs.c`.
    
.. note:: When porting to CC2744R7-Q1, the NVS region must be changed to reflect the flash size decrease from CC2745R10-Q1 to CC2744R7-Q1. If 
          the NVS region is not altered, the application will enter the exception handler. 

Please refer to the |STACK| Release Notes for all the details.