Skip to content

tc_ble_sdk Get Started

Overview

About this document

This document is to help you quickly set up the tc_ble_sdk development environment, obtain the SDK, build and flash the project, and successfully run your first example project. Reading this document requires a basic understanding of C language and embedded development concepts.

Applicable scope

tc_ble_sdk is applicable to Telink Semiconductor's TLSR825x, TLSR827x, TC321x, TC123x and other SoC series:

Notes

The information listed here may not be the latest version. For detailed information on complete and accurate chip series, corresponding EVBs, development platforms, and SDK versions, refer to the latest Release Notes. Open the Release Notes page, and select the Release Notes corresponding to your current SDK version from the dropdown list on the left.

Preparation

Hardware checklist

Hardware Description
PC Windows 10/11 / Linux / macOS (This document uses Windows as an example)
EVB Select the appropriate Evaluation Board (EVB) based on the Release Notes
Programmer Programmer V3 (recommended)
USB cable Connect your PC and the programmer
Dupont wire Connect the EVB and the programmer

For physical hardware, refer to the section Connect the hardware.

Software checklist

Software Description
IDE Telink VS Code Extension or Telink IoT Studio
Toolchain For toolchain information, see Release Notes
Programmer software BDT (Burning and Debugging Tool)
SDK GitHub / Gitee

Choose the IDE

tc_ble_sdk supports the following two development methods:

Choose one based on your development habits. Both methods do not require simultaneous installation.

Install VS Code

Before installing the extension, make sure your computer has the latest version of Visual Studio Code installed. Telink VS Code Extension updates are based on the latest version of VS Code. If the VS Code version is too old, the extension may not work properly or may have abnormal functionality.

  1. Launch VS Code.
  2. Click the Extensions icon in the left sidebar, or press Ctrl+Shift+X.
  3. Enter Telink in the search box.

  4. Find Telink Development Tool in the search results and click Install.

    xYNUBhlc.png

After installation, the Telink DEVELOPMENT icon appears in the left sidebar of VS Code.

Install the toolchain

In Telink VS Code Extension, download the compiler toolchain and auxiliary tools on demand via the built-in manager.

1. In the Telink DEVELOPMENT view on the left side of VS Code, expand the DEVELOPMENT TOOLS tree menu.

RMNXUyMv.png

2. Click the toolchain you need, then click Install Toolchain on the right.

3. Click CMake, then click Install Toolchain on the right.

4. After successful installation, a corresponding completion notification pops up in the bottom right corner of the VS Code window.

hy4A0lQZ.png

Info

If you want to use the toolchain in the command line, right-click and select Open Terminal from the pop-up menu.

Validate the IDE and the dependencies

After installation, follow the steps below to validate whether Telink VS Code Extension has been installed successfully:

  1. Launch VS Code, confirm the software opens normally, and there are no error messages during startup.
  2. In the left sidebar, confirm the Telink icon appears, and click it to enter the Telink DEVELOPMENT view.
  3. In the DEVELOPMENT TOOLS tree menu, confirm that the required toolchain has been installed.
  4. At the same time, confirm that the auxiliary tool CMake also shows it has been installed.

If all the above checks are normal, Telink VS Code Extension and its dependencies have been successfully installed and configured, and you can start downloading the SDK to begin SDK development.

Download the installation package corresponding to your operating system. The demonstration uses Windows as an example:

Install Telink IoT Studio:

Windows:

  1. Extract the downloaded .zip file, run TelinkIoTStudio_V2025.2.exe, and follow the wizard to complete the installation.
  2. After installation, you must run TelinkIoTStudio Updater.exe to get the latest component updates.

Linux:

  1. Grant installation package execution permissions to the runtime environment.
  2. Run Telink_IoT_Studio_2025.2_Installer.run and follow the prompts in the terminal to complete the installation.

Toolchain description

Telink IoT Studio offers an all-in-one standalone installation package with all the components required built in, eliminating the need for additional toolchain installation. All required toolchains are installed synchronously when installing the IDE. By clicking Telink in the top menu bar, open the corresponding toolchain's Cygwin Shell.

GjUSVdDz.png

Validate the IDE and the dependencies

After installation, follow the steps below to validate whether Telink IoT Studio has been successfully installed.

Validate the IDE installation:

  1. Launch Telink IoT Studio, confirm the program loads normally and displays the main interface, and there are no error messages about missing dependency libraries during startup.
  2. Click Telink in the top menu bar, confirm that toolchain entries such as Cygwin Shell in the dropdown menu can be opened normally.

If the above conditions are met, Telink IoT Studio has been successfully installed and configured.

Validate the dependencies:

SDK compilation and version management rely on the following tools. Run the corresponding commands in the system terminal to validate.

Dependencies Validation commands Expected versions
Python python --version or python3 --version Python 3.8 or higher (recommended 3.8~3.12)
Git git --version Git 2.30 or higher

After confirming that all the above dependencies have been correctly installed, you can start downloading the SDK to begin SDK development.

Get the SDK

This chapter introduces how to obtain the official Telink SDK, the top-level directory structure of the SDK, and how to import the SDK project into the IDE.

Download the SDK

Download the latest SDK via GitHub / Gitee, or run the following git clone command to clone the repository locally:

git clone https://github.com/telink-semi/tc_ble_sdk.git

or

git clone https://gitee.com/telink-semi/tc_ble_sdk.git

SDK directory overview

tc_ble_sdk/

├── algorithm/ # Algorithm library

├── application/ # General application programs

├── boot/ # Boot code

├── common/ # Common utility functions

├── drivers/ # Peripheral drivers

├── proj_lib/ # Core library (protocol stack, PM, etc.)

├── stack/ # Protocol stack

└── vendor/ # User application code

For the full directory structure and the function of each directory, refer to the Developer Handbook.

Import the project

Depending on your development environment, choose to import the project in VS Code or Telink IoT Studio.

Import the project in VS Code

tc_ble_sdk is a standard Telink VS Code Extension project. Click File -> Open Folder... in the VS Code menu bar, select the root directory of the project, and load it.

After loading, click the Telink icon in the left sidebar to enter the Telink Extension view. At this point, the PROJECT OUTLINE panel displays the directory structure of the current project, indicating the project has been successfully imported.

adfee325-9e78-460e-8071-0f9e04afc90b.png

After loading, if the PROJECT OUTLINE panel is empty, it means the current project is an older version of Telink IoT Studio project, and a conversion operation is required.

d91778c1af2b59e12f052ee9d7550ee5.png

After successful project import, compile the project in VS Code.

If you choose to use Telink IoT Studio as the development environment, follow the steps below to import the project:

  1. Click File -> import in the top menu bar.
  2. In the pop-up dialog box, expand General directory, select Existing Projects into Workspace, and click Next.

  3. Select the project directory to import.

    rVIXdM3K.png

  4. Select the project you have already downloaded from Browse, select the project on the corresponding chip platform, and click Finish. The project is successfully imported.

    z05jPCh8.png

After successful project import, the figure below is shown:

UsyTzLfm.png

After successful project import, compile the project in Telink IoT Studio.

Compile and run the first example

This chapter guides you through the complete development loop: from selecting an example and code compilation to final flashing and execution.

Select examples

It is recommended to use the officially provided acl_peripheral_demo as the first example project. This example features streamlined functionality with minimal dependencies, allowing quick verification of the basic connection function of the development board as a BLE Peripheral. This example uses the TC321x development board for demonstration.

For more examples, refer to ...\tc_ble_sdk\tc_ble_sdk\vendor.

Compile the project

Depending on your development environment, choose to compile the project in VS Code or Telink IoT Studio.

Compile the project in VS Code

  1. In the left sidebar of VS Code, find PROJECT OUTLINE, and under the Other targets directory, select the acl_peripheral_demo project.

    561484490512ae7683a7de336577d774.png

  2. Click the build button on the right to compile.

    After compilation, output files (.elf, .bin, .ls) are generated, with ELF format files used for debugging and BIN format files for flashing.

    ELF and BIN files can be found under PROJECT OUTLINE after compilation. Taking the TL321x platform acl_peripheral_demo as an example, the storage path is ...\tc_ble_sdk\tc_ble_sdk\cmake_builds\TC_BLE_SDK_321X\TC32_ELF_MCULIB_V5_GCC12_2

    Compilation successful, seeing a similar output:

    801fe00e126c3814a4e84d13e1aa3d78.png

  1. In the Project Explorer on the left, select the project you want to compile.
  2. Click the small dropdown arrow next to the Build button (hammer icon) on the top toolbar.

  3. Select the configuration you want to compile from the dropdown menu, and the system begins compiling.

    KeDG960i.png

  4. Observe the console output; if there are no error messages and Build Finished is displayed, the compilation is successful.

    t9bUXdep.png

Taking the TC321x platform acl_peripheral_demo as an example, the compiled bin file is stored in the ...\tc_ble_sdk\tc_ble_sdk\build\TC321X\acl_peripheral_demo directory.

Flash the firmware

Firmware flashing is performed using the BDT tool.

Step 1: Connect the hardware

Before using the BDT tool, connect the PC, the programmer, and the target board as follows:

  • PC ↔ Programmer: Connect via USB cable. If the green indicator light on the programmer stays on, it indicates the programmer has been successfully recognized by the PC.

  • Programmer ↔ Target board: Connect using the Dupont wire:

    • Power cable: VCC ↔ VCC; GND ↔ GND

    • Data cable (Single-wire SWM bus): Connect the programmer's SWM pin to the target board's SWS (Swire) pin.

zQuliQjg.png

Step 2: Install the BDT

  1. Download BDT.

    Visit Telink Developer Center - Development Tools and download the corresponding toolkit according to your operating system.

    zQuliQjg.png 2. Extract the toolkit. (The BDT tool is a green no-installation version that can be used after extraction.)

    Take Windows as an example:

    First, extract the downloaded toolkit to a custom path, such as C:\Telink\BDT.

    Then, enter the extracted release directory, for example C:\Telink\BDT\release_v5.9.2.

    Finally, double-click and run Telink BDT.exe to launch the tool.

    vEJjDVYV.png 3. Choose the programmer version and chip compatibility

    Telink provides four versions of programmers (Programmer). When launching the BDT interface, it is recommended to select the Programmer V1.0 ~ V3.0 programmer version.

    bXIoTEeZ.png

Step 3: Flash the firmware

  1. Detect the device.

    Open the BDT software. Before firmware flashing, ensure the tool has detected the programmer, as shown in the figure below.

    PtCQKTDc.png

    • If the BDT does not find the device, click Refresh to view available devices.
    • If the BDT finds multiple devices, all of them will be listed. After clicking Refresh, the first device is activated by default, and you can also manually switch target devices from the list.

  2. Configure and flash

    a. Select the chip series of the target board.

    In the chip dropdown menu at the top, select the target chip for your development board, such as TC321x.

    HiXloTix.png

    Info

    B91 includes TLSR951x and TLSR921x, B92 includes TLSR952x and TLSR922x, B80/B80B includes TLSR8208 and TLSR8373, B85 includes TLSR825x and TLSR8359, B87 includes TLSR827x and TLSR8355.

    b. Select the download mode as EVK.

    rhFFi2tI.png

    c. Click Setting button to open the configuration window and switch to the Flash tab. In the Download Addr bar, set the initial offset address for firmware, with the default value 0x000000.

    Info

    You can download the target firmware to the SRAM or OTP target area by configuring the SRAM or OTP tab

    VQVyClPH.png

    d. Click File -> Open/Reopen in the menu bar and select the .bin firmware you compiled. After successful loading, the full file path is displayed at the bottom of the main interface.E9Cvzp8V.png j7oxcdEg.png

    e. Check the connection status between the target board and the PC.

    • If the connection status is normal, the bottom left corner of the main interface displays evk device: ok.
    • If the bottom left corner of the main interface displays usb device: not found, it means the target board is not properly connected to the PC.

    Tu5y7O8v.png

    f. Click Activate first, then click Unlock button or check the auto unlock option to remove Flash's write protection.

    If flash is in write protection, the Download will fail, so before downloading firmware to flash, ensure flash is programmable. nFWjaksi.png

    g. Click Download button and wait for the log window to prompt flashing successful. 5nXxhBi6.png

    h. You can set the reset mode to auto mode before flashing, or switch to manual mode after flashing and click the Reset button to manually reset the MCU to run the program. ymJ63XmE.png

Verify the running results

After firmware flashing is complete, follow the steps below to verify whether the example program is running properly on the development board.

Operation steps

  1. After flashing is complete, the development board automatically resets; if it does not reset automatically, press the Reset button on the development board to reset.
  2. Enable Bluetooth on your phone, search for a BLE device named periphr_demo and complete the connection.
  3. Press the volume up/down button on the matrix keyboard of the development board (red box position in the figure), and observe whether the phone volume changes.

For the GPIO pins corresponding to the buttons, refer to the configuration file TC321X_C1T357A20.h in the project.

OplbP7LC.jpg

Expected results

When the program runs normally, the following conditions should be met:

  • The phone can search for and successfully connect to the periphr_demo device.
  • After successful connection, the LED indicator on the development board lights up.
  • After pressing the volume up/down button on the matrix keyboard, the phone volume can be synchronously increased or decreased.

If all the above phenomena meet expectations, it indicates the example program is running successfully, and the development environment, program compilation, firmware flashing, and Bluetooth communication functions have all been verified successfully.

References and resources

Document navigation

Document Description
Telink tc_ble_sdk Developer Handbook Learn SDK functions and specific usage methods

Community and resources

Resource Description
Telink Official Forum Technical exchange and support
Telink Official Website Product center and documentation center
GitHub / Gitee SDK source code repository

Appendix 1: Frequently Asked Questions

Environment installation failed

  • Possible reason: The installation path contains Chinese characters.
  • Solution: Modify the installation path.
  • Possible reason: Antivirus software was not closed during installation.
  • Solution: Close the antivirus software running on your computer.

Unable to generate the required .bin file when compiling with CMake in VS Code

  • Possible reason: The .elf file name generated by CMake does not match the .elf file name expected by the script tl_check_fw.sh, causing the script execution to fail and thus unable to generate the final .bin file.
  • Solution: Check and ensure that the .elf file name output in the CMake configuration is exactly the same as the .elf file name referenced in the tl_check_fw.sh script. If any inconsistency is found, modify both to the same file name, then recompile.

Flashing failed

  • Possible reason: The development board has not been Activated or Unlocked.
  • Solution: You need to Activate + Unlock again before each download.

Phone cannot connect to the board

  • Possible reason: The development board does not have an antenna installed.
  • Solution: Install an antenna at the reserved antenna connector.