SysConfig Migration¶

If you have an existing CC13x2 or CC26x2 software project and you want to start developing with SysConfig, follow the steps below. This guide assumes you have a stack project from the SimpleLink CC13x2 or CC26x2 2.40 SDK or newer. If this is not the case, please look at the Stack Porting Guides to see how to update to SimpleLink CC13x2 or CC26x2 2.40 SDK.

Note

If you are starting development with a fresh project, you don’t need to migrate from non-SysConfig to SysConfig-enabled project. In SimpleLink CC13x2 / 26x2 SDK v. 2.40 and later, SysConfig-enabled projects are found in the syscfg_preview folder.

1. Add a .syscfg File to Your Project¶

In this guide, we will start with a BLE5-Stack project, then apply necessary changes to start using SysConfig.

You can use the standalone SysConfig tool to make this file. Please see the SysConfig Standalone Installer Download Page.

Choose the “Start a new Design” option. Choose your device, part and package. For the product path, add the following for your SDK: {SDK_INSTALL_DIR}\.metadata\product.json.
Add an RF stack according to your existing project (BLE5-Stack). Add any TI Drivers configuration that your project requires. If applicable, add one or more Radio Configuration. You can find guidelines for configuring each of these in the Get started with SysConfig chapter.
Save the file and add it to your project.

If you are using CCS, you can add the file by dragging it into your CCS workspace. When you add the file, the following dialog box will appear and allow you to add SysConfig to your project:

If you are using IAR, follow the steps in Using SysConfig with IAR Workbench before you add the .syscfg file. The steps for adding the file are as follows:

Include the .syscfg file you want to use in the project (right click on the project → Add Files → Navigate to the .syscfg file and add it).
Create a custom build step: Right click on project → Options → Custom Build → Populate the following:

Option	Populate with the following:
File Name Extensions	.syscfg
Command Line	$SYSCONFIG_ROOT$/nw/nw.exe $SYSCONFIG_ROOT$/dist/cli.js -o $PROJ_DIR$ -s “$ COM_TI_SIMPLELINK_CC13X2_26X2_SDK_INSTALL_DIR$/.metadata/product.json” –compiler iar $FILE_PATH$
Output files (one per line)	SysConfig_Generated_Files.ipcf
Run this tool before all other tools	Checked

2. Add SysConfig Options¶

If you are using CCS, open the Project Properties and do the following:

In System Configuration Tool → Basic Options → Name of the board file (-b, –board), set it to /ti/boards/.meta/<BOARD_NAME>. (E.g., if you are using a CC1312R LaunchPad, set the name to /ti/boards/.meta/CC1312R1_LAUNCHXL). It is not necessary to set the name of the device.
In System Configuration Tool → Basic Options → Root system config meta data file in a product or SDK (-s, –product), add ${COM_TI_SIMPLELINK_CC13X2_26X2_SDK_INSTALL_DIR}/.metadata/product.json.

3. Remove Board Files From Your Project¶

These are not needed as the board configuration is done in SysConfig. E.g. if you are using a CC1352R LaunchPad, delete the Board.h, CC1352R1_LAUNCHXL.h, and CC1352R1_LAUNCHXL.c from the project. If your project contains board files ending with *_fxns.c or *.cmd, don’t delete them.

You can see how to configure your board files and TI driver instances with SysConfig in Configure The Board Files with SysConfig. If you’re not exactly sure what peripherals are on your board and you have a TI development board, you can check the .syscfg file from an existing syscfg project for your board. E.g. if you’re using a CC26X2R LaunchPad board, you can check the .syscfg file in one of the projects in ${COM_TI_SIMPLELINK_CC13X2_26X2_SDK_INSTALL_DIR} /examples/rtos/CC26X2R1_LAUNCHXL.

4. Migrate `build_config.opt`¶

build_config.opt contains build configuration settings. These settings can all be set by SysConfig. The associated settings are found in the main BLE view in SysConfig.

When you have configured these parameters in SysConfig, delete the build_config.opt file from your project.

When you have eventually built the project with SysConfig enabled, you will find the SysConfig-built version of build_config.opt in the output folder of the project.

5. Migrate `project_name_app.opt`¶

project_name_app.opt contain user-configurable pre-processor defines. The file name is formed by the project name. For example, in the multi_role example project this file is called multi_role_app.opt and simple_peripheral_app.opt in the simple_peripheral example. These defines will now be located in the SysConfig generated files ble_app_config.opt and ble_config.h.

When you have configured these parameters in SysConfig, delete the simple_peripheral_app.opt file from your project.

6. Changes in Application File¶

For this section, the example project Simple Peripheral will be used as an example.

Include `ble_config.h` in the application file¶

ble_config.h is where most of the parameters defined by SysConfig are stored. Add the following to you application file (in this case simple_peripheral.c):

#include "ble_config.h"

Remove default application parameter defines¶

Most of these parameters are now configured in SysConfig.

For Simple Peripheral, the following parameter defines should be removed in the CONSTANTS section of simple_peripheral.c:

    // Address mode of the local device
    // Note: When using the DEFAULT_ADDRESS_MODE as ADDRMODE_RANDOM or
    // ADDRMODE_RP_WITH_RANDOM_ID, GAP_DeviceInit() should be called with
    // it's last parameter set to a static random address
    // #define DEFAULT_ADDRESS_MODE                  ADDRMODE_RP_WITH_PUBLIC_ID

    // General discoverable mode: advertise indefinitely
    // #define DEFAULT_DISCOVERABLE_MODE             GAP_ADTYPE_FLAGS_GENERAL

    // Minimum connection interval (units of 1.25ms, 80=100ms) for parameter update request
    // #define DEFAULT_DESIRED_MIN_CONN_INTERVAL     80

    // Maximum connection interval (units of 1.25ms, 104=130ms) for  parameter update request
    // #define DEFAULT_DESIRED_MAX_CONN_INTERVAL     104

    // Slave latency to use for parameter update request
    // #define DEFAULT_DESIRED_SLAVE_LATENCY         0

    // Supervision timeout value (units of 10ms, 300=3s) for parameter update request
    // #define DEFAULT_DESIRED_CONN_TIMEOUT          300

    // Pass parameter updates to the app for it to decide.
    // #define DEFAULT_PARAM_UPDATE_REQ_DECISION     GAP_UPDATE_REQ_PASS_TO_APP

    // How often to perform periodic event (in ms)
    #define SP_PERIODIC_EVT_PERIOD               5000

    // How often to read current current RPA (in ms)
    // #define SP_READ_RPA_EVT_PERIOD               3000

    // Delay (in ms) after connection establishment before sending a parameter update request
    // #define SP_SEND_PARAM_UPDATE_DELAY           6000

If your application is setting the following parameters in any other way, make sure they are instead configured in SysConfig.

Remove the initialization of advertisement data and other local variables¶

Advertisement data is set in the Broadcaster Configuration section of SysConfig. (Only applicable for BLE Peripherals and BLE Broadcasters.)

For Simple Peripheral, the following lines of code should be removed from the LOCAL VARIABLES section of simple_peripheral.c.

    /*********************************************************************
    * LOCAL VARIABLES
    */

    // ....

    // GAP GATT Attributes
    // static uint8_t attDeviceName[GAP_DEVICE_NAME_LEN] = "Simple Peripheral";

    // Auto connect Disabled/Enabled {0 - Disabled, 1- Group A , 2-Group B, ...}
    uint8_t autoConnect = AUTOCONNECT_DISABLE;

    // Advertisement data
    // static uint8_t advertData[] =
    // {
    //   0x03,
    //   GAP_ADTYPE_LOCAL_NAME_SHORT,
    //   'S',
    //   'P',
    //   0x02,   // length of this data
    //   GAP_ADTYPE_FLAGS,
    //   DEFAULT_DISCOVERABLE_MODE | GAP_ADTYPE_FLAGS_BREDR_NOT_SUPPORTED,

    // service UUID, to notify central devices what services are included
    // in this peripheral
    //   0x03,   // length of this data
    //   GAP_ADTYPE_16BIT_MORE,      // some of the UUID's, but not all
    //   LO_UINT16(SIMPLEPROFILE_SERV_UUID),
    //   HI_UINT16(SIMPLEPROFILE_SERV_UUID)
    // };

    // Scan Response Data
    // static uint8_t scanRspData[] =
    // {
      // complete name
    //   17,   // length of this data
    //   GAP_ADTYPE_LOCAL_NAME_COMPLETE,
    //   'S',
    //   'i',
    //   'm',
    //   'p',
    //   'l',
    //   'e',
    //   'P',
    //   'e',
    //   'r',
    //   'i',
    //   'p',
    //   'h',
    //   'e',
    //   'r',
    //   'a',
    //   'l',

      // connection interval range
    //   5,   // length of this data
    //   GAP_ADTYPE_SLAVE_CONN_INTERVAL_RANGE,
    //   LO_UINT16(DEFAULT_DESIRED_MIN_CONN_INTERVAL),   // 100ms
    //   HI_UINT16(DEFAULT_DESIRED_MIN_CONN_INTERVAL),
    //   LO_UINT16(DEFAULT_DESIRED_MAX_CONN_INTERVAL),   // 1s
    //   HI_UINT16(DEFAULT_DESIRED_MAX_CONN_INTERVAL),

      // Tx power level
    //   2,   // length of this data
    //   GAP_ADTYPE_POWER_LEVEL,
    //   0       // 0dBm
    // };

Remove advertisement sets parameter initializations¶

GapAdv_params_t advParamLegacy and GapAdv_params_t advParamLongRange are not set in the SysConfig generated file ble_config.c. These must not be initialized in the main application source file. (Only applicable to BLE broadcasters (peripheral, broadcaster, multirole.)).

For example, in SimplePeripheral_init(), the following lines should be removed:

// Temporary memory for advertising parameters for set #1. These will be copied
// by the GapAdv module
// GapAdv_params_t advParamLegacy = GAPADV_PARAMS_LEGACY_SCANN_CONN;
...
// Use long range params to create long range set #2
// GapAdv_params_t advParamLongRange = GAPADV_PARAMS_AE_LONG_RANGE_CONN;

Replace GAP Bond Manager configuration block with SysConfig function¶

The GAP Bond manager parameters are now configured by SysConfig and generated in the ble_config.c file along with the setBondManagerParameters() function that initialize all the bond manager parameters. This function should to be called from the application.

Also the defines that were removed from the CONSTANTS section of the application are used throughout the application. If you don’t remove these code lines you will get compiler errors.

For example, in SimplePeripheral_init(), The complete Bond Manager configuration block should be replaced by the setBondManagerParameters() function call:

/*********************************************************************
    * @fn      SimplePeripheral_init
    *
    * @brief   Called during initialization and contains application
    *          specific initialization (ie. hardware initialization/setup,
    *          table initialization, power up notification, etc), and
    *          profile initialization/setup.
    */
    static void SimplePeripheral_init(void)
    {

    // ...

    // Setup the GAP Bond Manager. For more information see the GAP Bond Manager
    // section in the User's Guide:
    // https://software-dl.ti.com/lprf/ble5stack-latest/
    {
    // Don't send a pairing request after connecting; the peer device must
    // initiate pairing
    // uint8_t pairMode = GAPBOND_PAIRING_MODE_WAIT_FOR_REQ;
    // Use authenticated pairing: require passcode.
    // uint8_t mitm = TRUE;
    // This device only has display capabilities. Therefore, it will display the
    // passcode during pairing. However, since the default passcode is being
    // used, there is no need to display anything.
    // uint8_t ioCap = GAPBOND_IO_CAP_DISPLAY_ONLY;
    // Request bonding (storing long-term keys for re-encryption upon subsequent
    // connections without repairing)
    // uint8_t bonding = TRUE;

    // GAPBondMgr_SetParameter(GAPBOND_PAIRING_MODE, sizeof(uint8_t), &pairMode);
    // GAPBondMgr_SetParameter(GAPBOND_MITM_PROTECTION, sizeof(uint8_t), &mitm);
    // GAPBondMgr_SetParameter(GAPBOND_IO_CAPABILITIES, sizeof(uint8_t), &ioCap);
    // GAPBondMgr_SetParameter(GAPBOND_BONDING_ENABLED, sizeof(uint8_t), &bonding);
    }
    setBondManagerParameters(); // Add this function call.

The GAPBondManager can be configured in the Bond Manager section of SysConfig.

Change the name of certain parameters¶

Some parameters have been moved from the application into SysConfig. Please make sure you are using the correct name of these parameters.

New Name	Old Name	SysConfig Section
READ_RPA_PERIOD	SP_READ_RPA_EVT_PERIOD SC_READ_RPA_PERIOD	General Configuration
SEND_PARAM_UPDATE_DELAY	SP_SEND_PARAM_UPDATE_DELAY	Peripheral Configuration
DEFAULT_SCAN_INTERVAL	SCAN_PARAM_DFLT_INTERVAL	Observer Configuration
DEFAULT_SCAN_WINDOW	SCAN_PARAM_DFLT_INTERVAL	Observer Configuration