TI BLE5-Stack Quick Start

This section serves as a road map for users developing applications and products using the TI SimpleLink CC23xx or CC27xx wireless MCU platform for Bluetooth Low Energy applications. Whether a seasoned developer or just getting started, TI has created a variety of resources to simplify development on the CC23xx or CC27xx platform. These resources will enhance your experience with the TI SimpleLink TI BLE5-Stack 3.03.04.00 from the out-of-the-box demo to production.

Using BLE5-Stack Projects with CCS

For BLE5-Stack projects, the CC23xx or CC27xx devices use FreeRTOS. The necessary FreeRTOS code is integrated into all FreeRTOS-based projects present in the CC23xx or CC27xx SDK. This means that importing a BLE5-Stack project will import a single project which has the FreeRTOS files located within the project itself. Additionally, this single project will also link to TI’s BLE5-Stack library files.

For more information about FreeRTOS, please reference the FreeRTOS (RTOS Kernel) Overview section of the User’s Guide.

For more details and how to change configurations look at the SimpleLink TI BLE5-Stack User’s Guide.

Import Project Using CCS Theia Import Project Tool

CCS Theia is an integrated development environment (IDE) which leverages the open source Theia IDE. The Theia IDE is a Virtual Studio Code like IDE framework, which can be used to edit, build and debug TI Embedded devices.

Note

CCS Theia is the future IDE for TI embedded devices. Some features that are currently supported in CCS Eclipse may not be supported in CCS Theia at this time. Please refer to the Release Notes for more details. As this is a new environment, TI encourages feedback. Please direct feedback to E2E.

This section describes how to import, build and flash an existing project. The section will reference the basic_ble project. All of TI BLE5-Stack projects included in the development kit will have a similar structure.

  1. Open the CCS Theia IDE from the Start Menu

  2. Create a workspace

    • Workspaces previously used with CCS Eclipse can be used on CCS Theia.

  3. Import a CCS Project

    • Open Import Wizard: FileImport

    • Click on Browse…

    • Navigate to the desired example:

      <SDK_INSTALL_DIR>/examples/rtos/LP_EM_CC2340R5/ble5stack/basic_ble or <SDK_INSTALL_DIR>/examples/rtos/LP_EM_CC2745R10/ble5stack/basic_ble

    • Select desired folder

    • Click Finish

    ../_images/cc2340_import_project_CCSTheia.png

    Figure 17. Import CCS Projects for CC2340R5

    ../_images/cc2745_import_project_CCSTheia.png

    Figure 18. Import CCS Projects for CC2745R10

  4. Wait for import process to complete

    • If everything is successful, the project will appear in the Project Explorer:

    ../_images/cc2340r_imported_projects_CCSTheia.png

    Figure 19. CC2340R5 Projects Imported into CCS

    ../_images/cc2745_imported_projects_CCSTheia.png

    Figure 20. CC2745R10 Projects Imported into CCS

Build and Flash Project

To build and flash Basic BLE project:

  1. Follow all steps contained within the Introduction to the SimpleLink Low Power F3 SDK guide. The guide describes the prerequisites and setup required to build and flash example projects for CC23xx or CC27xx platforms. Do not proceed until all the setup contained in the guide has been completed or the projects will not build.

  2. Build the Project

    • Right click on desired project

    • Select Build Project(s)

  3. Load the project

    • Select RunLoad

    • Click the project to flash

Note

You only need to program the HSM once unless a mass chip erase without retaining sectors occurs. In this case, the steps above must be followed.

Before beginning execution, open a terminal window with the following settings:

Table 1. Basic BLE UART Settings

UART Param

Default Values

Baud Rate

115200

Data length

8 bits

Parity

None

Stop bits

1 bit

Flow Control

None

When the debugging session is complete, click the blue start button to begin execution.

Import Project Using CCS Import Project Tool

A quick and easy way to start working with the SDK is to use the Import Project tool available in CCS.

This section describes how to import and build an existing project and references the basic_ble project. All of TI BLE5-Stack projects included in the development kit have a similar structure.

  1. Open the CCS IDE from the Start Menu.

  2. Create a workspace.

    Attention

    Ensure that the CCS workspace path does not contain a whitespace.

  3. Import a CCS Project using Import

    • Open Import Wizard: FileImport…

    • Expand Code Composer Studio

    • Click on CCS Projects and click Next

    • Ensure Select search-directory is checked.

    • Click on Browse… in the Select search-directory: section.

    • Navigate to the directory for your chosen example:

      <SDK_INSTALL_DIR>/examples/rtos/LP_EM_CC2340R5/ble5stack/basic_ble or <SDK_INSTALL_DIR>/examples/rtos/LP_EM_CC2745R10/ble5stack/basic_ble

    • Click Select Folder

    • Click Finish

    ../_images/cc2340_import_project.png

    Figure 21. Import CCS Projects for CC2340R5

    ../_images/cc2745_import_project.png

    Figure 22. Import CCS Projects for CC2745R10

  4. Wait for import process to finish

    • If everything is successful, the project should appear in Project Explorer: basic_ble_LP_EM_CC2340R5_freertos_ticlang or basic_ble_LP_EM_CC2745R10_freertos_ticlang

    ../_images/cc2340r_imported_projects.JPG

    Figure 23. CC2340R5 Projects Imported into CCS

    ../_images/cc2745_imported_projects.png

    Figure 24. CC2745R10 Projects Imported into CCS

Build and Flash Project

Note

The CC27xx has a new Hardware Security Module (HSM) that requires firmware to be flashed after a project flashed with a valid CCFG and SCFG. This process will have to be followed after every mass chip erase without retaining protoected sectors. This is not required for CC23xx.

To build and flash Basic BLE project:

  1. Follow all the steps contained in the Introduction to the SimpleLink Low Power F3 SDK guide . The procedure described in the above guide goes over all the prerequisites and setup required to build the example projects for the CC23xx or CC27xx platform. Do not proceed until all the setup contained in the guide has been completed or the projects will not build.

  2. Build the Application project.

    • Set the Application project as the active project.

    • Select ProjectBuild All to build the Application project.

    • As part of the prebuild process, SysConfig will run and generate code based on the .syscfg in the workspace. For more information on SysConfig, see the SysConfig chapter of the User’s Guide.

  3. Flash the Application project

    • Select RunDebug to download the application

  4. Flash the HSM firmware

    • Open UniFlash (see release notes for version information)

    • Select the correct CC27xx device

    • Select Settings & Utilities and go to the HSM Image section

    • Enter the path to the HSM binary
      • This will be located <sdk root>/bin/HSM.

    • Press Program HSM Image

Note

You only need to program the HSM once unless a mass chip erase without retaining sectors occurs. In this case go through the process above again.

Before beginning execution, open a terminal window with the following settings:

Table 2. Basic BLE UART Settings

UART Param

Default Values

Baud Rate

115200

Data length

8 bits

Parity

None

Stop bits

1 bit

Flow Control

None

When the debugging session opens, click the green start button to start execution.

Using BLE5-Stack Projects with IAR

When building with IAR, it is recommended to enable all build messages. This can be done by right-clicking in the Build window and selecting “All” as shown below:

../_images/ble5_iar_enable_build_messages.png

Figure 25. Enable All Build Messages

Note

The installation of the SysConfig tool is bundled with the SimpleLink Low Power F3 SDK. But if necessary the standalone SysConfig package can be downloaded here: SysConfig Standalone Installer Download Page and must be installed to the same location as specified by SYSCONFIG_ROOT.

Import Project Using Workspace

This section describes how to open and build an existing project and references the basic_ble project.

Warning

It is recommended to use the global argument variables for all TI BLE5-Stack examples in this version of the SimpleLink Low Power F3 SDK. Import or re-enable the global SDK argvars via Tools -> Configure Custom Argument Variables.

Below you can see how to add and enable the SDK-global argument variables:

../_images/iar_custom_argvars_menu.png

Figure 26. Select Configure Custom Argument Variables from the Tools menu

../_images/iar_custom_argvars_empty.png

Figure 27. Click on Import… with either the Workspace or Global namespace selected. For Global, the imported values will persist for other projects also.

../_images/iar_custom_argvars_file_f3_sdk.png

Figure 28. Find the Custom Argument Variables file under <SDK root>/tools/iar

../_images/iar_custom_argvars_selected_f3_sdk.png

Figure 29. Success! Change these paths if you have installed in a different location.

Applications that support the TI Over-the-Air Download (OAD) will also require the MCUboot project and for On-Chip OAD also the persistent application project. For more information on the TI OAD Profile and the MCUboot see the OAD Chapter of the BLE5-Stack User’s Guide.

  1. Open the IAR Embedded Workbench IDE from the Start Menu.

  2. Open an IAR workspace project: File -> Open -> Workspace…

    • For loading a CC23xx example, select <SDK_INSTALL_DIR>\examples\rtos\<LP>\ble5stack\basic_ble\freertos\iar\basic_ble_LP_EM_CC2340R5_freertos_iar.template.eww

    • For loading a CC27xx example, select <SDK_INSTALL_DIR>\examples\rtos\<LP>\ble5stack\basic_ble\freertos\iar\basic_ble_LP_EM_CC2745R10_freertos_iar.template.eww

  3. This will prompt you to select a folder location as a workspace for the project

This workspace file is for the basic_ble project. When selected, the files associated with the workspace become visible in the Workspace pane on the left side of the screen. See Figure 30.

Build and Download Project

To build & download Basic BLE:

  1. Build the Application project.

    • Select the Application project.

    • Select Project -> Make to build the Application project.

    • As part of the prebuild process, SysConfig will run and generate code based on the .syscfg in the workspace. For more information on SysConfig, see the SysConfig chapter of the User’s Guide.

    Warning

    IAR 9.32.1 generates an error on the first build. Press Project -> Clean to clean the project and repeat the build two more times to finally overcome the error. This issue will be fixed in the next IAR version.

  2. Load the Application project

    • To download and debug: Select Project -> Download and Debug

    • To download without debugging: Select Project -> Download -> Download Active Application

Refer to the basic_ble for CC23xx, and basic_ble for CC27xx for more information about this project.

Before beginning execution, open a terminal window with the following settings:

Table 3. Basic BLE UART Settings

UART Param

Default Values

Baud Rate

115200

Data length

8 bits

Parity

None

Stop bits

1 bit

Flow Control

None

When the debugging session opens, click the start button to start execution. Continue on to the Running the Demo section for information about using Basic BLE.

Warning

When using IAR compiler, the Configuration file for BLE5-Stack is suffixed .xscfg. When using IAR compiler, modifying .cfg file has no effect.

Running the Demo

After hitting the play button, your terminal window should display the Basic BLE UART output as shown below:

../_images/CC2340R_Basic_BLE_UART.png

Figure 31. Basic BLE UART Output

This provides information about the address used for Basic BLE.

Choose the Central device from the list below to connect with:

Click to Expand BTool Instructions

Host Test Setup

The easiest way to connect to the Basic BLE example with another LaunchPad is by using BTool and a CC23xx LaunchPad (or similar). BTool allows you to send HCI commands to the LaunchPad to easily establish BLE communication with another device. In this case, we can use BTool to connect to the CC23xx or CC27xx device.

To use BTool, you must flash your second LaunchPad with the Host Test firmware from a compatible version of the TI BLE-Stack/BLE5-Stack. Import the host_test example into CCS or IAR, compile and flash the second LaunchPad.

If the second LaunchPad is a LAUNCHXL-CC26X2R1 device, then you must install the latest SIMPLELINK LOWPOWER F2 SDK. Once installed, the BTool software and firmware will be found in the SDK directory for the SIMPLELINK-LOWPOWER-F2-SDK.

UniFlash can be used to program the LaunchPad with the Host Test firmware:

../_images/ble5-uniflash-host-test.png

Figure 32. Flash Host Test using UniFlash

Open BTool from the tools\ble5stack\btool folder of the SDK install directory of the LAUNCHXL-CC26X2R1 SDK directory. Start BTool by double clicking Run_BTool.bat Select the XDS110 UART COM Port for your Host Test LaunchPad:

../_images/btool_serial_port.png

Figure 33. BTool Serial Port Settings

When BTool connects to the LaunchPad, it will issue several initialization commands. If the commands succeed, you will receive multiple HCI Events with a Status of “SUCCESS”.

Connect to BLE Basic

Scan for nearby advertising Bluetooth devices by selecting the Scan button in the Discovery window. Make sure your BLE Basic LaunchPad is connected to power and advertising.

Compare the device addresses in the Device Address dropdown with the address shown in the BLE Basic terminal window. Select the matching address and click “Establish” to connect to BLE Basic.

../_images/btool-scan-connect.png

Figure 34. Scanning & Connecting with BTool

After the connection has established, discover & read the current value of the services and characteristics available on BLE Basic by right-clicking on the Handle in the Connection Info section and selecting Read Values.

../_images/btool-read-values.png

Figure 35. BTool GATT Table Discovery

The bottom of the BTool GUI will display the device’s GATT Table to help you navigate and control the BLE Basic services.

../_images/CC2340r_SimplePeripheral_GATT_Table.JPG

Figure 36. BTool GATT Table Discovery

Using the Simple Profile Service

You can read and write multiple bytes of data by using the Data Service. Double click on the Value field of the String Char. You can write the new value directly in ASCII or you can choose a different type by selecting from the Value Type dropdown menu.

../_images/CC2340r5_Writing_Data_Service.JPG

Figure 37. Writing to the Data Service

Click to Expand Android/iOS Instructions

Download the latest version of the TI SimpleLink Connect App from your app store.

Apple App Store (Left QR code)

Google Play Store (Right QR code)

../_images/Apple_Google_QR_code.png

Figure 38. SimpleLink Connect App

When the download completes, open the app:

../_images/ble5_android_starter_app.png

Figure 39. SimpleLink Connect App

Enable location permissions to allow the app to function properly, if you deny it by error go to your phone application settings to allow it back.

Connect to BLE Basic

Open the SimpleLink Connect App on your device. The app should begin scanning for Bluetooth LE devices automatically after you click on Enable Bluetooth LE scan. Make sure your Basic BLE LaunchPad is nearby and advertising. Basic BLE project should appear in the Bluetooth low energy devices list:

../_images/App_Scanned_Devices.png

Figure 40. Discovering BLE Basic

Establish a connection to the Basic BLE project by clicking on the arrow next to its name in the devices list. The SimpleLink Connect Application will display the Basic BLE project service and allow the user to interact with these services.

../_images/basicBLE_ConnectionPage_Android.png

Figure 41. BLE Basic Services

Using the Simple Profile Service

The Simple Profile Service is the service with the UUID that begins with 0xFFF0 (TI Simple Peripheral Service). Tap the arrow next to the item and you will see five characteristics. The different characteristics can be used to read and write multiple bytes of data. You can do this by pressing Read characteristic to get data from Basic BLE project, Write characteristic to send multiple bytes of data to Basic BLE project and Notifications to know when a characteristic has changed its value.

../_images/basicBLEServices.png

Figure 42. List of Services in Basic BLE project

../_images/WritebasicBLECharacteristic.png

Figure 43. Writing to the Simple Profile Service

Learning More About TI BLE5-Stack

SimpleLink Academy provides a comprehensive set of training tools that allow users from beginners to experienced developers to learn about the SimpleLink MCU Platform.

Using introductory material and labs, learn the fundamentals of BLE and how to develop a custom BLE application.

SimpleLink Academy also contains modules written to demonstrate the rich debug environment and peripheral driver capability provided by the SDK.

This material teaches users who are new to FreeRTOS or any RTOS programming in general about how to use FreeRTOS and the BLE5-Stack included in the SDK.

Modules within the kernel training greatly expand the information presented in the FREERTOS Overview chapter in the TI BLE5-Stack User’s Guide.

Learn how the FreeRTOS provides the most optimal power management and design flexibly.

  • App Notes, Tools and other resources available on the CC2340R5 product page

  • This User’s Guide

Developing a New BLE5-Stack Based Application

Usage of the SimpleLink SDK, the Software User’s Guide and SysConfig is intended for programmers who are ready to start developing an end product using the CC23xx or CC27xx. To begin:

Get Familiar with the BLE5-Stack User’s Guide

This User’s Guide is meant to be used alongside the TI BLE5-Stack when developing an end product. It contains documentation on the stack architecture, APIs, and suggestions for developing applications.

Select an Example Project

The TI BLE5-Stack includes a basic set of projects to use as a starting point for development of your custom application. Click the links below to find out more information about each project:

Table 4. BLE examples available for the CC2340R5

Name

Description

basic_ble

Example project where device can be configured to operate as a Bluetooth LE peripheral, central, or both.

basic_ble_oad_offchip

Same as basic_ble above with OAD functionality to enable wireless firmware updates off chip.

basic_ble_oad_onchip

Same as basic_ble above with OAD functionality to enable wireless firmware updates on chip.

basic_ble_profiles

Same as basic_ble above with additional profiles (CGM and Glucose).

basic_ble_ptm

Same as basic_ble above with Production Test Mode (PTM) functionality.

connection_monitor

Example project that implements high level connection tracking.

data_stream

Example project which implements data stream profile to enable UART over BLE communication.

host_test

A network processor project that is interfaced with HCI and Vendor Specific HCI commands.

basic_persistent

Permanently resident application that implements OAD profile

Table 5. BLE examples available for the CC27xx platform

Name

Description

basic_ble

Example project where device can be configured to operate as a Bluetooth LE peripheral, central, or both.

data_stream

Example project which implements data stream profile to enable UART over BLE communication.

host_test

A network processor project that is interfaced with HCI and Vendor Specific HCI commands.

Troubleshooting Help

While developing your custom application, you may run into issues that require the use of a debugger. See the Debugging Chapter in the TI BLE5-Stack User’s Guide for guidance.

Enhance Your Project

Additional sample applications created to implement specific use cases and examples. These are made to work in conjunction with the SDK.

Examples of system designs containing complete hardware and software examples, using the CC23xx or CC27xx.

Bluetooth Qualification

The CC23xx and CC27xx TI BLE5-Stack is Bluetooth qualified.

To prepare the qualification process, Texas Instruments experts have written the How to Certify Your Bluetooth Product guide to assist you through this process.

Getting Support

A support community providing answers to questions relating to the CC23xx or CC27xx and other SimpleLink devices. You can browse questions from other developers or ask your own questions if you run into issues developing with TI BLE5-Stack 3.03.04.00.