.. _sec-freertos-migration-cc23xx:

Migrating TI-RTOS examples to use FreeRTOS
------------------------------------------

There are significant project setting modifications required to migrate from a
TI-RTOS example to one that supports FreeRTOS, such as modifying the toolchain,
adding include paths, and managing predefined symbols. For this reason, the
recommended approach to port an example from TI-RTOS to FreeRTOS is to create a
new projectspec file. A projectspec, or project specification file, is used to
create a new project based on predefined settings. For more information on
projectspec files, see the `ProjectSpecs in CCS <https://software-dl.ti.com/ccs/esd/documents/ccs_projectspecs.html>`_
page. 

Most embedded applications are built the same way: a main loop that receives
messages from the iCall or from the application itself. This "loop" is
implemented and located inside the examples in the SDK. The developer can reference these examples meaning, 
the majority of the application code can be reused with slight modifications.

In this section, we will be using the code found in our examples as a guide
to convert any project to FreeRTOS.

Modify the Project Properties to support FreeRTOS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The goal of this section is to inherit the project configuration settings from
an existing example project that is already setup for FreeRTOS.

When modifying the projectspec as shown below, we inherit the example project's
*toolChain*, *cgtVersion* and all project's compiler and linker settings. The
majority of the changes below should be additions, i.e. adding your project
files/content to the projectspec.

#. Setup the new project folder. Create a new project folder inside the 
   examples directory (located in ``{SDK_INSTALL_DIR}\examples\rtos\DEVICE_NAME\ble\``)
   by copying an example project folder and renaming it to 
   a new name of your choice.

.. note::
   SDK 9.10 has changed the ble5stack directory to ble. 

#. Open the projectspec file inside the new project directory and rename the
   project by modifying the *title* and the *name* field.

#. Modify the *compilerBuildOptionsinclude* paths to include the path to your
   custom project directory.

#. Modify the *linkerBuildOptions* to add in any linker `File Search Path` if
   needed.

#. Add any custom project files to the project using the <file path></file>
   tags. Use the existing example projectspec file as a template.

.. _sec_freertos_migration_cc23xx_application:

Modify the application code to support FreeRTOS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This section describes the changes to the application code that are necessary to
support FreeRTOS. It is recommended to import a Project using FreeRTOS
and search for the predefined symbol ``FREERTOS``. This will reveal the
modifications to the Project application that were done. 

An overview of the changes applied to the Project example (FreeRTOS + TICLANG) to 
support FreeRTOS. These changes should be applied to your custom example.

#. Includes

   .. code-block::
      :caption:  FreeRTOS - INCLUDES

      #include <FreeRTOS.h>
      #include <task.h>
      #include "ti_ble_config.h"
      #include <ti/bleapp/ble_app_util/inc/bleapputil_api.h>
      #include <ti/bleapp/menu_module/menu_module.h>
      #include <app_main.h>

#. Stack
   
   Please refer to bleapputil_stack_callback.c, which contains stack messages callback, 
   pairing states callback, passcode callback, connection event callback, scan event callback, 
   advtertise event callback.

#. Task
   
   Please refer to bleapputil_task.c for the main task of the stack. For operation relates to 
   BLE roles, please refer to app_main.c and check app_broadcaster.c/app_central.c/app_observer.c/app_peripheral.c 
   based on BLE roles.
    
#. Event
   
   Please refer to bleapputil_process.c, which contains event callback for GAP, GATT, HCI, L2CAP.

#. ICall
   
   Please refer to files under iCall folder. Predefined symbol ``FREERTOS`` could
   guide the differences.

#. Modify the .syscfg file of your custom project using a text editor to change
   the target rtos to freertos.

   .. code-block:: diff
      :caption:  freertos differences - SysConfig

      */
      -// @cliArgs --board /ti/boards/CC26X2R1_LAUNCHXL --rtos tirtos
      +// @cliArgs --board /ti/boards/CC26X2R1_LAUNCHXL --rtos freertos

      /*
      *  
      Example.syscfg
      */

..
   .. caution:: 
      **Workaround for Button Debouncing**

      There exists a known issue with FreeRTOS projects in the |BLE5_STACK| (see
      Release Notes for more information). This issue affects only the usage of the
      example application's two button menu. To workaround this, manually add a
      delay inside board_key.c::Board_keyCallback, as opposed to starting a
      FreeRTOS timer. Below is an example of the modification:

      .. code-block:: diff
         :caption: Reworking the Pin debounce timer

         +//define this outside the function
         +#define CPU_convertMsToDelayCycles(milliseconds) \
         +   (((uint32_t)(milliseconds)) * (48000 / 3))
         
         +//Place the below changes at the end of Board_keyCallback
                  keysPressed |= KEY_RIGHT;
         }
         #endif

         +#ifdef FREERTOS
         +/* 100 ms delay */
         +CPUdelay(CPU_convertMsToDelayCycles(100));

         +// Notify the application
         +(*appKeyChangeHandler)(keysPressed);
         +#else
         Util_startClock(&keyChangeClock);
         +#endif
   