Skip to content

tl_ble_sdk Get Started

Overview

About this document

This document is to help you quickly set up the IDE, obtain the SDK, build the project, and successfully run your first example. To read this document, you need to have a basic understanding of C language and embedded development.

Applicable scope

tl_ble_sdk is applicable to Telink's TL721x, TL321x, TL322x, TLSR921x, TLSR922x, TLSR952x and other SoC series:

  • TL721x
  • TL321x
  • TL322x
  • TLSR921x
  • TLSR922x
  • TLSR952x

Notes

The information listed here may not be the latest. For detailed information on complete and accurate chip series, corresponding EVBs and platforms, and SDK versions, refer to the latest Release Notes. After opening Release Notes, use the dropdown list on the left to select the version of Release Notes corresponding to the SDK version you are currently using.

Preparation

Hardware checklist

Hardware Description
PC Windows 10/11 / Linux / macOS
EVB Select the appropriate Evaluation Board (EVB) based on the Release Notes
Programmer Programmer V3
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, see Release Notes
Programmer software Burning and Debugging Tool (BDT)
SDK GitHub

Choose the IDE

tl_ble_sdk supports the following two IDEs:

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

Install VS Code

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

  1. Launch VS Code.

  2. Click the Extensions icon in the left sidebar, or press Ctrl+Shift+X.

  3. Search for Telink.

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

Note

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 to validate whether Telink VS Code Extension has been installed successfully:

  1. Launch VS Code and confirm the software opens normally and that 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, the right side of the CMake also shows that 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 .zip file, run TelinkIoTStudio_V2025.2.exe, and follow the wizard to complete the installation.

  2. After installation, run TelinkIoTStudio Updater.exe to update the components.

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 toolchain's Cygwin Shell.

GjUSVdDz.png

Validate the IDE and the dependencies

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

Validate the IDE:

  1. Launch Telink IoT Studio and confirm that it loads normally and displays the main interface, with no error messages during startup.

  2. Click the top menu bar Telink and confirm that toolchain entries in the dropdown menu open 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 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 and begin SDK development.

Get the SDK

This chapter explains how to obtain the SDK, its top-level directory structure, and how to import SDK projects into the IDE.

Download the SDK

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

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

SDK directory overview

tl_ble_sdk/

├── algorithm/ # Algorithm libraries

├── application/ # General application handlers

├── boot/ # Boot code

├── common/ # Common utility functions

├── drivers/ # Peripheral drivers

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

├── stack/ # protocol stack

└── vendor/ # User application code

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

Import the project

Depending on the IDE you choose, import the project into VS Code or Telink IoT Studio.

Import the project into VS Code

tl_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 current project's directory structure, indicating the project has been successfully imported.

rzUUZn4v.png

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

QBUUihsH.png

After successfully importing the project, compile it in VS Code.

Follow the steps to import your project into Telink IoT Studio:

  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 Project Directory to import.

    rVIXdM3K.png

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

    z05jPCh8.png

After successful project import, the figure below is shown:

UsyTzLfm.png

After successfully importing the project, compiling it in TelinkIoT Studio.

Compile and run the first example

This chapter guides you from selecting examples and code compile to final programming and execution.

Select examples

It is recommended to use the officially provided acl_peripheral_demo as the first engineering example. This example features a streamlined feature with minimal dependencies, allowing quick verification of EVB basic connectivity functions as BLE peripheral. This example uses the TL321x EVB for demonstration.

For more examples, check the directory ..\tl_ble_sdk\tl_ble_sdk\vendor.

Compile the project

Depending on the IDE you choose, 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 Other targets directory, select acl_peripheral_demo project.

    LwLmaii7.png

  2. Click the Build Target button on the right to compile.

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

    ELF and BIN files can be found after compile under PROJECT OUTLINE. Take TL321x platform as an example, the output file is stored in ...\tl_ble_sdk\tl_ble_sdk\cmake_builds\TL_BLE_SDK_321X\TL32_ELF_MCULIB_V5_GCC12_2

    Compilation successful, seeing a similar output:

    aCE9xYR1.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 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 TL321x platform acl_peripheral_demo as an example, the compiled bin file is stored in the ...\tl_ble_sdk\tl_ble_sdk\build\TL321X\acl_peripheral_demo directory.

Flash the firmware

Firmware flashing is performed by the BDT.

Step 1: Connect the hardware

Before using the BDT, connect the PC, the programmer, and the EVB:

  • 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 ↔ EVB: Connect using the Dupont wire:

    • Power cable: VCC ↔ VCC; GND ↔ GND

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

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 applicable version based on the compatibility with the chip series

    When launching the BDT interface, it is recommended to select the programmer versions V1.0 ~ V3.0.

    bXIoTEeZ.png

Step 3: Flash the firmware

  1. Detect the device.

    Open the BDT. 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 EVB.

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

    HiXloTix.png

    Notes:

    • B91: Refers to TLSR921x and TLSR951x series chips;
    • B92: Refers to TLSR922x and TLSR952x series chips.

    b. Select the download mode as EVK.

    rhFFi2tI.png

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

    Note: 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 file. 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 EVB and the PC.

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

    Tu5y7O8v.png

    f. Click Activate, 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 programming successfully. 5nXxhBi6.png

    h. 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. ymJ63XmE.png

Verify the running results

After flashing the firmware, follow the steps below to verify whether the example is running properly on EVB.

Operation steps

  1. After flashing is complete, the EVB automatically resets; If it does not reset automatically, press the Reset button.

  2. Turn on Bluetooth on your phone, search for the BLE device named periphr_demo, and connect the device.

  3. Press the volume increase/decrease button on the EVB's matrix keyboard (the red box in the diagram) to observe if the phone's volume changes.

To check the GPIO pins corresponding to the buttons, refer to the configuration file TL321X_C1T331A20.h in the project.

OplbP7LC.jpg

Expected results

When the example runs normally, it should meet the following conditions:

  • The phone can detect and successfully connect to periphr_demo devices.

  • After successful connection, the LED indicator on the EVB lights up.

  • After pressing the volume up or down button on the matrix keyboard, the phone's volume can be increased or decreased in sync.

If all the above phenomena meet expectations, it means the example has run successfully, and the IDE, compilation, firmware flash, and Bluetooth communication functions have all been successfully verified.

References

Document Description
Telink tl_ble_sdk Developer Handbook Detailed software architecture, repository structure, and functional module descriptions

Appendix 1: Frequently Asked Questions

IDE installation failed

  • Possible reason: The installation path contains Chinese

  • Solution: Modify the installation path

  • Possible cause: Antivirus software was not turned off during installation and configuration

  • Solution: Close any antivirus software you have on your computer

Flashing failed

  • Possible cause: The EVB has not been activated or unlocked

  • Solution: Before each dowmload, you need to press activate + unlock

The phone cannot connect to the EVB

  • Possible cause: The EVB does not have an antenna installed

  • Solution: Install the antenna on the reserved antenna port