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

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

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

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

4. Modify the linkerBuildOptions to add in any linker File Search Path if needed.

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

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.

1. Includes

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

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

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

4. Event

   Please refer to bleapputil_process.c, which contains event callback for GAP, GATT, HCI, L2CAP.

5. ICall

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

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

   Listing 13. freertos differences - SysConfig

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