.. |OLD_STACK_VER| replace:: |DEVICE| SDK 7.20
.. |NEW_STACK_VER| replace:: |DEVICE| SDK 7.40

|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.

.. _ble-porting-sdk-7-40:

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

The recommended method for porting an existing project from |OLD_STACK_VER|
to |NEW_STACK_VER| is to modify the ProjectSpec file to import the project as
a |NEW_STACK_VER| project.

Porting by modifying the CCS ProjectSpec file (``.projectspec``) can be done
when a ProjectSpec file has been updated and maintained throughout the
project's development. All example projects included in the SDK each come with
their own ProjectSpec file. During development, the included ProjectSpec file
should be updated to match any changes or additions made to the project. This
will make a project more easily package-able and ease migration efforts when
future SDK's are released. For example, the ProjectSpec file of the basic_ble
project is located in
``{SDK_INSTALL_DIR}/examples/rtos/{BOARD}/ble5stack/basic_ble/freertos/ticlang``

The following steps will detail the changes needed when porting a Basic BLE
project:

.. note::
   This porting method might be more complex for customer specific
   projects. The following steps are the minimum set of changes
   required to port a project from |OLD_STACK_VER| to |NEW_STACK_VER|.

#. Open the ProjectSpec file in a text editor and modify the product definition
   line to reflect the new SDK revision and the corresponding sysconfig
   revision.
   ``products="com.ti.SIMPLELINK_LOWPOWER_F3_SDK:x.xx.xx.xx;sysconfig:x.xx.x"``
   Also update line ``cgtVersion="TICLANG_x.x.x"`` if it exists in the file.
   Refer to the Dependencies section in the SDK release notes for the correct
   SysConfig (and compiler) version. The SDK release notes may be found in
   ``{SDK_INSTALL_DIR}/docs/simplelink_mcu_sdk/release_notes_coresdk_lpf3_x_xx_xx_xx.html``

#. In the ProjectSpec file, perform the following changes:

   1.  In the ``compilerBuildOptions=`` string, remove the following entries:
      
      *  ``@${PROJECT_LOC}/${ConfigName}/syscfg/ti_ble_app_config.opt``
      *  ``@${PROJECT_LOC}/${ConfigName}/syscfg/ti_build_config.opt``
      *  ``-I${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/devices/cc23x0r5/settings``
      *  ``-I${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/boards/cc23x0r5``
      *  ``-I${FREERTOS_INSTALL_DIR}/FreeRTOS/Source/include``
      *  ``-I${FREERTOS_INSTALL_DIR}/FreeRTOS/Source/portable/GCC/ARM_CM0``

   2.  In the ``compilerBuildOptions=`` string, add the following entries:
      
      *  ``-I${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/bleapp/profiles/health_thermometer``
      *  ``-I${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/bleapp/services/health_thermometer``
      *  ``-I${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/third_party/freertos/include``
      *  ``-I${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/third_party/freertos/portable/GCC/ARM_CM0``
   
   3. In the ``linkerBuildOptions=`` string, remove the following:
      
      *  ``-l${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/third_party/spiffs/lib/ticlang/m0p/spiffs.a``
      *  ``-l${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/drivers/rcl/lib/ticlang/m0p/rcl_cc23x0r5.a``
      *  ``-l${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/drivers/lib/ticlang/m0p/drivers_cc23x0r5.a``
      *  ``-l${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/display/lib/ticlang/m0p/display_cc23x0r5.a``
      *  ``-l${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/third_party/ecc/lib/ticlang/m0p/ecc.a``
      *  ``-l${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/devices/cc23x0r5/rf_patches/lib/ticlang/lrf_cc23x0r5.a``
      *  ``-l${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble5stack_flash/lib_projects/CC2340R5/OneLib/lib/ticlang/m0p/OneLib.a``
      *  ``-l${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble5stack_flash/lib_projects/CC2340R5/StackWrapper/lib/ticlang/m0p/StackWrapper.a``
      *  ``-I${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/third_party/freertos/portable/GCC/ARM_CM0``
   
   4. In the ``linkerBuildOptions=`` string, make the following replacements:
      
      *  Replace ``--diag_wrap=off`` with ``-Wl,--diag_wrap=off``
      *  Replace ``--display_error_number`` with ``-Wl,--display_error_number``
      *  Replace ``-x`` with ``-Wl,-x``
      *  Replace ``-c`` with ``-Wl,-c``
      *  Replace ``-lti/devices/cc23x0r5/driverlib/lib/ticlang/driverlib.a`` with ``-lti_utils_build_linker.cmd.genlibs``

   5. In the ``postBuildStep=`` string, make the following replacements:
      
      *  Replace ``${CG_TOOL_HEX} -order MS --memwidth=8 --romwidth=8 --intel -o ${ProjName}.hex ${ProjName}.out`` 
         with ``${CG_TOOL_ROOT}/bin/tiarmobjcopy -O ihex ${BuildArtifactFileName} ${BuildArtifactFileBaseName}.hex``

   6. Remove the following file include option:
      
      *  ``<file path="${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/boards/cc23x0r5/rcl_settings_ble.c" openOnCreation="false" excludeFromBuild="false" action="link" targetDirectory="Startup">
         </file>``


#. In the ``basic_ble.syscfg`` file, make the following changes:
   
   1. Add the following code snippets:
      
      * Add an RCL module as shown below:

         .. code-block:: js

            /* ======== RCL ======== */
            const RCL = scripting.addModule("/ti/drivers/RCL");
      
      * Add an RF Design module as shown below:

         .. code-block:: js
         
            /* ======== RF Design ======== */
            var rfDesign = scripting.addModule("ti/devices/radioconfig/rfdesign");
            const rfDesignSettings = system.getScript("/ti/common/lprf_rf_design_settings.js").rfDesignSettings;
            for(var setting in rfDesignSettings)
            {
               rfDesign[setting] = rfDesignSettings[setting];
            }
            const radioSettings = system.getScript("/ti/ble5stack/ble_common.js").getRadioScript(rfDesign.rfDesign,system.deviceData.deviceId);
            const bleRfDesignSettings = radioSettings.rfDesignParams;
            for(var setting in bleRfDesignSettings)
            {
               rfDesign[setting] = bleRfDesignSettings[setting];
            }

      * Add a GPIO module as shown below:
         
         .. code-block:: js

            /* ======== LEDS ======== */
            const GPIO        = scripting.addModule("/ti/drivers/GPIO");
            const GPIO2       = GPIO.addInstance();
            GPIO2.$hardware   = system.deviceData.board.components.LED_GREEN;
            GPIO2.$name       = "CONFIG_GPIO_LED_GREEN";
            const GPIO3       = GPIO.addInstance();
            GPIO3.$hardware   = system.deviceData.board.components.LED_RED;
            GPIO3.$name       = "CONFIG_GPIO_LED_RED";
            
   2. Remove the code snippets:
      
      * In the BLE module, remove the duplicate filter entry shown below:
         
         .. code-block:: js
            
            ble.dupFilter = "SCAN_FLT_DUP_DISABLE";
         


#. Afterwards, the project may be re-imported using the new ProjectSpec file.
   The newly imported project is now configured to use |NEW_STACK_VER| instead
   of |OLD_STACK_VER|.

To learn more information about ProjectSpec files, please
reference `ProjectSpec Documentation <https://software-dl.ti.com/ccs/esd/documents/ccs_projectspecs.html>`_.

If necessary, additional details are provided in
:ref:`noteworthy-ble-migration-sdk-7-40`.

Legacy Porting
--------------

.. warning::
   The following section covers a legacy porting method. Current SDK porting
   does not require this process and should instead see
   :ref:`ble-porting-sdk-7-40`.

For this guide, a peripheral project from |OLD_STACK_VER| will be
ported over to |NEW_STACK_VER|. The recommended approach is to start with the
Basic BLE project on |NEW_STACK_VER| and modify the base configuration to
match the peripheral configuration used in the |OLD_STACK_VER| project.
Afterwards, the custom application code should be transferred to the new
project.

#. Import a |NEW_STACK_VER| Basic BLE project.

#. Change the default Basic BLE project configuration options in the BLE Module
   present in SysConfig to match the configuration used in the |OLD_STACK_VER| project.

#. Transfer all custom application logic from the |OLD_STACK_VER| into the
   |NEW_STACK_VER| Basic BLE project.

#. Move any profiles and services that the application is using to the
   |NEW_STACK_VER| project.

#. Transfer the SysConfig settings either visually through the GUI or open both
   the old and the new project ``.syscfg`` files and copy-paste the desired
   settings.

#. If necessary, update the project to use the newer TI drivers that are
   supplied with the |SDK|. Additional details are provided
   in :ref:`noteworthy-ble-migration-sdk-7-40`.

#. Refer to the Core SDK release notes for additional information and the
   FreeRTOS examples included with |SDK|. The Core SDK release notes may be
   found in
   ``{SDK_INSTALL_DIR}/docs/simplelink_mcu_sdk/release_notes_coresdk_lpf3_x_xx_xx_xx.html``

   For additional information on how |NEW_STACK_VER| uses FreeRTOS see
   :ref:`sec-freertos-overview`.

   For any utilized TI Drivers, review |TI_DRIVERS_API|.

.. _noteworthy-ble-migration-sdk-7-40:

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.
Please refer to the specific example you need to port and do a compare between
the old and new project files. Please refer to the |STACK| Release Notes for
all the details.

*  Bug fixes
*  FreeRTOS installation included with SDK (no external FreeRTOS installation required)
*  Health Thermometer service/profile added to ``basic_ble_profiles`` example.
