BLE5-Stack SysConfig Features

Checking if SysConfig is used for BLE

Projects that are using SysConfig to configure BLE will have a green check mark next to BLE as shown in the green rectangle, while others will have a green check mark next to Custom, shown in the red rectangle.

../_images/ble5_sysconfig_enabled.png

Figure 222. Check for SysConfig enabled example applications

Note

Get started with SysConfig provides an overview of what SysCfg is and how to get started with it. Please take a look at this if you have not already.

After importing a BLE5-Stack SysCfg project into CCS, by double clicking on the *.syscfg file, a GUI will appear where the project can be configured more easily. A number of BLE5-Stack configurable features are included in this GUI. Figure 223. shows what this looks like when importing the multi_role example.

../_images/syscfg_after_import.png

Figure 223. After Import

Figure 223. Also shows many different configurable parameters for the project. The first few configurable options inside the Software -> BLE panel are as shown below. The generated file name for the BLE5-Stack feature is ti_build_config.opt.

../_images/ble5_sysconfig_stack_feature.png

Figure 224. Stack Feature

The Device Role configurable is an example of a drop down list where you can select the specific Device Role you wish to use. Device Role refers to the GAP Roles that the project operates as. This can be seen in Figure 225. There are many different options with different input methods available.

../_images/syscfg_role_combinations.png

Figure 225. Device Role

When you first open a SysConfig project all of the settings for that project will be at their default values that are known to work with that example. Providing this amount of quick and easy configuration for a project is powerful. However, as we know, with great power comes great responsibility. Any one specific example is not guaranteed to function properly with any and all permutations of the available configurable options. More specifically, BLE5-Stack projects are written to implement one (or more) specific Generic Access Profile (GAP) Role Combinations, so one should not switch this unless you know what you’re doing. As long as the files that are generated from your input compile, the project will build. Whether or not it performs to the same degree depends on what you changed the options to.

Furthermore, the options that are available to modify will depend on the GAP Roles that have been selected. Changing the Device Role may add or remove options below it. If changing the Device Role option is required, it is suggested to change this first so that you do not lose any work you have already done below.

Open the SysConfig output (see Viewing SysConfig Output). After selecting a file you will be able, in real-time, to identify how the changes in the GUI effect the generated files. This will help you review the relationship between the GUI and the code.

../_images/syscfg_code_review.png

Figure 226. Code Review

Note

Changes will appear as a diff in the code view. Changes will be applied when the project is rebuilt.

Additional Configuration Categories

Note

Remember that the following Configuration Categories will depend on the Role Combination (GAP Roles) you’ve chosen. Change Role Combination before changing any of the below options.

Radio

In this view you can configure the front end mode, the bias configuration and the default TX Power. When relevant (i.e. for CC13XXP/CC26XXP devices), you can select on which RF design your project is based. For CC26xx and CC1352R devices only one option is available and selected by default.

../_images/syscfg_rf_settings.png

Figure 227. Radio

In Radio you will also find the BLE Radio Configuration view. Some of the configurations made in BLE Radio Configuration Settings will show up in the generated ti_radio_config files and are not applicable for BLE projects. The Other Dependencies -> RF options control arguments in the RF Driver and the Power Driver config in the Board.c file. For normal operation they should be left unchanged.

../_images/syscfg_rf_settings_ble_radio_configuration.png

Figure 228. Radio - BLE Radio Configuration

Note

  • For CC2642R, CC2652R and CC2652P devices, TI recommends to keep the field RF Designation to its default value (Sensitivity).

  • For CC2642R-Q1, the engineer can choose to set the field RF Designation to Selectivity or Sensitivity.

  • For the other devices, the field RF Designation is not displayed and the device is automatically configured to use the most optimized radio configurations.

In BLE Configuration, you will find the RF view. The RF view can be used to select pins for custom antenna switching. The RF view can be also used to enable RF coexistence feature. A few remarks regarding the code generated by SysConfig:

  • When required, SysConfig will generate callback functions accordingly to the functionalities activated.

  • The callback functions are generated in ti_drivers_config.c.

  • Callback functions are only generated if user defined function name is valid (more than 0 characters, valid C identifier and not “NULL”).

  • All “sub-callback” used in the global callback functions are declared ‘weak’ for application to override.

  • Callback function with user defined name acts as a template, with description on how to create a new callback function, and how to filter on triggering events.

  • Callback function for antenna switching changes function body if custom antenna switching is enabled.

  • The antenna switching callback function’s code describes, with examples, how to handle pin interaction. It also contains function call to non-existing function with descriptive name, to attract attention at linker time and highlight that a new (‘strong’) definition of the function is required.

  • The coexistence (coex) feature, when enabled, will also provide a callback function to handle the signaling specifics of the feature. Please see Configuration Options, which describes the coex options you can configure with SysConfig.

../_images/SysConfig_RF_coex_antenna_switching.png

Figure 229. Radio - BLE Radio Configuration - RF

General Configurations

../_images/syscfg_general_configurations.png

Figure 230. General Configurations

Advanced Settings

In this category you will find settings that configure the application such as Power Management and Two Button Menu options. You can also configure whether to use RCOSC and/or PTM mode. You will also find ICall options. More information:

  1. Power Management

  2. HAL Assert Handling

  3. Stack Library Configuration

  4. Extended Stack Settings, see 32 Connections Design

  5. GAPBondMgr and SNV

  6. RCOSC: See Running Bluetooth Low Energy on CC2640 Without 32 kHz Crystal

    → For OAD enabled projects, RCOSC configuration should also be set in the CCFG file of the BIM project - see Using 32-kHz Crystal-Less Mode.

  7. Production and Direct Test Mode (PTM, DTM)

  8. ICall, see: Creating Additional ICall Enabled Tasks

Bond Manager Configurations

These settings control all the bond manager parameters and generate the function setBondManagerParameters() in ble_config.c. This function sets all the bond manager parameters as configured by SysConfig, and should be called from the main application.

../_images/syscfg_bond_manager_configurations.png

Figure 231. Bond Manager Configurations

Note

Currently, there is a limitation when using SysConfig to configure the number of bonds. SysConfig will only successfully configure up to 10 bonds. If the user configures more than 10 bonds in SysConfig, the first 10 connections will bond and pair successfully while the remaining connections will pair successfully, but fail bonding. Please refer to GAPBondMgr and SNV for information on how to configure more than 10 bonds.

Peripheral Configuration

../_images/syscfg_peripheral_configurations.png

Figure 232. Peripheral Configurations

Broadcaster Configuration

  1. GAP Roles

  2. Advertisements

    For each advertisement set, the advertisement parameters (Advertisment Type, Channels, TX Power…), the advertisement data and the scan response can be set. The TX Power parameter will not affect Legacy Advertisement sets.

../_images/syscfg_broadcaster_configurations.png

Figure 233. Broadcaster Configurations

Central Configuration

../_images/syscfg_central_configurations.png

Figure 234. Central Configurations

Observer Configuration

../_images/syscfg_observer_configurations.png

Figure 235. Observer Configurations

Custom GATT Builder

Currently, the GATT Builder Tool is in preview and can only be found in the simple_peripheral_gatt_builder_preview project. With the GATT Builder Tool, you will be able to add your own services and characteristics. For more information on GATT services and characteristics, please reference the following:

Enable the GATT Builder tool by checking Custom GATT. After enabling the GATT Builder tool, the Services section will appear as shown in the figure below.

../_images/syscfg_enable_custom_gatt.png

Figure 236. Enabling Custom GATT

To add a new service and characteristic, modify the Service window to add the Service Name, Service UUID Size, Service UUID, Write attribute CB function, and Read attribute CB function. After completing the service information, modify the Characteristics window as shown in the figure below.

../_images/syscfg_gatt_builder_characteristic.png

Figure 237. GATT Builder - Service and Characteristic

Modify the Characteristic window to add the Characteristic Name, Characteristic Description, Characteristic UUID Size, Characteristic UUID, Value Length (bytes), Value, Properties, and Permissions (for ATT requests).

../_images/syscfg_gatt_builder_characteristic_info.png

Figure 238. GATT Builder - Characteristic Window

Implement the Write and Read callback functions directly within simple_gatt_profile.c/.h. These callback functions should be identical to the ones that were used to fill out the Write attribute CB function and Read attribute CB function fields of the Service window within SysConfig. For reference on how to create the callbacks, please refer to the functions simpleProfile_WriteAttrCB and simpleProfile_ReadAttrCB within simple_gatt_profile.c. Once the new Write and Read callbacks are implemented, remove simpleProfile_WriteAttrCb and simpleProfile_ReadAttrCb to prevent build errors.

Note

The implemented write and read callback function names must be identical to the names used for the Write attribute CB function and Read attribute CB function fields. If the write and read CB functions are not implemented or the names do not match, the returning value from the callbacks will always be SUCCESS.

Due to SysConfig generating additional service files (ti_services.c/.h) based on the user’s inputs, remove and replace specific function calls, structs, and defines before building to avoid build errors.

The following functions will be generated:

  • <Your service name>_AddService

  • <Your service name>_RegisterAppCBs

  • <Your service name>_SetParameter

  • <Your service name>_GetParameter

The following defines will be generated:

  • <Your service name>_UUID define

  • <Your service name>_<Your characteristic name> define

  • <Your service name>_<Your characteristic name>_UUID define

  • <Your service name>_<Your characteristic name>_LEN define

The following struct will be generated:

  • <Your service name>CBs_t

Note

The user input for Service Name and Characteristic Name within SysConfig will determine the prefix of the generated code. For example, if your service name is exampleProfile and and your characteristic name is exampleCharacteristic the following will be generated:

  • exampleProfile_AddService

  • exampleProfile_exampleCharacteristic_UUID

  • exampleProfileCBs_t

The following section will go over which functions should be replaced with the generated functions. To properly demonstrate the changes, the examples will use the prefixes exampleProfile and exampleCharacteristic as shown in the note above. The two files that will need to be modified are Application/simple_peripheral.c and Profiles/simple_gatt_profile.c.

  • Anywhere simpleProfileCBs_t is used, replace with exampleProfileCBs_t

  • Anywhere simpleProfile_AppCBs is used, replace with exampleProfile_AppCBs

  • Anywhere simpleProfile_AddService is called, replace with exampleProfile_AddService

  • Anywhere simpleProfile_RegisterAppCBs is called, replace with exampleProfile_RegisterAppCBs

  • Anywhere simpleProfile_SetParameter is called, replace with exampleProfile_SetParameter

  • Anywhere simpleProfile_GetParameter is called, replace with exampleProfile_SetParameter

  • Remove the defines SIMPLEPROFILE_ defines and replace them with the respective service or characteristic define.

Build your project.