tl_platform_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.

Applicable scope

tl_platform_sdk is applicable to Telink's TL322x, TL323x, TL721x, TLSR921x, TLSR951x, TLSR922x, TLSR952x and other SoC series:

Notes

The information listed here may not be the latest. For detailed information on complete and accurate chip series, corresponding EVBs, toolchains, and SDK versions, refer to the Release Notes of the corresponding version.

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) or JTAG
SDK	Gitee or GitHub

Choose the IDE

tl_platform_sdk supports the following two IDEs:

Telink VS Code Extension
Telink IoT Studio

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

Telink VS Code Extension

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.

Install Telink VS Code Extension

Launch VS Code.
Click the Extensions icon in the left sidebar, or press Ctrl+Shift+X.
Search for Telink.
Find Telink Development Tool in the search results and click Install.

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.

In the Telink DEVELOPMENT view, expand the DEVELOPMENT TOOLS tree menu.
Click the toolchain you need, then click Install Toolchain on the right.
After successful installation, a corresponding completion notification pops up in the bottom right corner of the VS Code window.

Note

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

Install auxiliary tools

In the tool list, select CMake, right-click, and select Install from the pop-up menu.
In the tool list, select Jtag_burn, right-click, and select Install from the pop-up menu.
In the tool list, select ICEman, right-click, and select Install 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:

Launch VS Code and confirm the software opens normally and that there are no error messages during startup.
In the left sidebar, confirm the Telink icon appears and click it to enter the Telink DEVELOPMENT view.
In the DEVELOPMENT TOOLS tree menu, confirm that the required toolchain has been installed.
At the same time, confirm that the auxiliary tools CMake, Jtag_burn, and ICEman also show that they have 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 begin SDK development.

Telink IoT Studio

Download and install Telink IoT Studio

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

Windows : TelinkIoTStudio_V2025.2.zip
Linux : Telink_IoT_Studio_2025.2_Installer.run

Install Telink IoT Studio:

Windows:

Extract the .zip file, run TelinkIoTStudio_V2025.2.exe, and follow the wizard to complete the installation.
After installation, run TelinkIoTStudio Updater.exe to update the components.

Linux:

Grant installation package execution permissions to the runtime environment.
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 and auxiliary tools are installed synchronously when installing the IDE. By clicking Telink in the top menu bar, open the toolchain's Cygwin Shell.

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:

Launch Telink IoT Studio and confirm that it loads normally and displays the main interface, with no error messages during startup.
Click the top menu bar Telink and confirm that toolchain entries such as Cygwin Shell 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 begin SDK development.

Get and import 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 Gitee or GitHub or run the following git clone command to clone the repository locally:

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

SDK directory overview

Directory	Description
`3rd-party/`	Third-party components
`chip/`	Chip-related code
`common/`	Common utility functions
`demo/`	Examples
`doc/`	Official documentation
`project/`	Project files
`tools/`	Development tools
`CMakeLists.txt/`	Main build entry

For the full directory structure and the function of each directory, refer to the Telink Driver SDK Developer Manual.

Import the project

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

Import the project into VS Code

tl_platform_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.

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

After successful conversion, the result is displayed in the bottom right corner:

Import the project into Telink IoT Studio

If you choose to use Telink IoT Studio as the main IDE, follow the steps to import the project:

Click File -> import in the top menu bar.
In the pop-up dialog box, expand General directory, select Existing Projects into Workspace, and click Next.
Select the project directory to import.
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.

After successful project import, the figure below is shown:

Compile and run the first example

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

Select the example

It is recommended to use the officially provided debug_demo as the first engineering example. This example features streamlined code logic with minimal dependencies and does not involve complex wireless protocol stacks. This example uses the TL322x: C1T371A20 EVK for demonstration.

For more examples, check the directory ...\tl_platform_sdk\demo\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

In the left sidebar of VS Code, find PROJECT OUTLINE, and select the project to compile and its corresponding Target.
Click the build 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. Taking the TL322x platform Debug_Demo as an example, the compiled .elf, .bin, and .ls files are stored in the ...\tl_platform_sdk\cmake_builds\TL_PLATFORM_SDK_322X\TL32_ELF_MCULIB_V5F_GCC12_2 directory.

Compilation successful, seeing a similar output:

Compile the project in Telink IoT Studio

In the Project Explorer on the left, select the project you want to compile.
Click the small dropdown arrow next to the Build button (hammer icon) on the top toolbar.
Select the configuration you want to compile from the dropdown menu, and the system begins compiling.
Observe the console output; if there are no error messages and Build Finished is displayed, the compilation is successful.

Taking the TL322x platform debug_demo as an example, the compiled bin file is stored in the ...\tl_platform_sdk\project\tlsr_riscv\tl322x\Debug_Demo directory.

Flash the firmware

Telink supports firmware flashing via BDT (a no-installation burning and debugging tool) or JTAG (with the ICEman simulation service). Choose based on your hardware environment.

Flash the firmware via BDT

Step 1: Connect the hardware

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

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): Connects the programmer's SWM pin to the target board's SWS (Swire) pin.

Step 2: Install the BDT

The Telink Burning and Debugging Tool (BDT) is used to flash the compiled firmware to the target chip or development board.

Download BDT.

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

Extract the toolkit.

The BDT tool is a green no-installation version that can be used after extraction.

Take Windows as an example:

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

b. Enter the extracted release directory, for example C:\Telink\BDT\release_v5.9.2.

c. Double-click and run Telink BDT.exe to launch the tool.

Choose the applicable version based on the compatibility with the chip series

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.

Step 3: Flash the firmware

Detect the device.

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

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.
Configure and flash.

a. Select the chip series of the target board.

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

!!! infor "Notes"
```
  - B91: Refers to TLSR921x and TLSR951x series chips;
  - B92: Refers to TLSR922x and TLSR952x series chips.
```
b. Select the download mode as EVK.

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.

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.

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

g. Click Download button and wait for the log window to prompt programming successfully.

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.

Flash the firmware via JTAG

JTAG flashing requires the backend service process ICEman.

Flash the firmware via JTAG in VS Code

After the project is successfully compiled, find the generated .bin firmware file in the project directory tree. Click the JTAG burn icon on the right side of the file to bring up the Telink JTAG Burn With ICEman page.

In the Telink JTAG Burn With ICEman page, configure the paths and parameters:
- Enter the local executable file paths for ICEman and Jtag_Burn.
- Configure the correct target chip series and flash start address.
- Configure the communication interface type and corresponding port number for ICEman.
Click Start ICEman button. The system prompts you to select a connection startup mode:
- Default mode: JTAG uses the default four-wire connection method (recommended).
- SDP 2-wire mode: ICEman is launched with -I aice_sdp.cfg, and JTAG uses a two-wire connection method. Ensure that the hardware supports it.
- H mode: ICEman is launched with the -H option. After a successful connection, a reset-and-hold operation is immediately performed on the target chip.

Observe the log. When ICEman is ready to use appears, the connection is successful. After configuring the parameters for Jtag_Burn execution, click the Burn button to start the flash, and confirm the flashing result through the subsequent scrolling log.

Flash the firmware via JTAG in Telink IoT Studio

Click Telink -> Jtag Burn (SPI Burn) in the top menu bar to bring up the JTAG configuration page.

In the pop-up page, verify that the .bin firmware to be flashed is correct.
Configure the runtime parameters for Jtag_Burn as annotated in the figure below, then click Start ICEman.
When you see ICEman is ready to use in the console output, it indicates that the hardware backend connection is successful. Click the Burn button on the right to start firmware flashing.

Verify the running results

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

Operation steps

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.
Observe the status of the LED indicators on the development board.

Expected results

Taking the TL322x development board as an example, the phenomenon when running successfully is as follows:

The blue, red, green, and white LEDs blink simultaneously.

If the above phenomenon is observed, it means the IDE, compilation, firmware flash, and operation have all been successfully verified. You have completed running the first example.

References

Document	Description
Telink Driver SDK Developer Manual	Detailed software architecture, repository structure, and functional module descriptions

Appendix 1: Frequently Asked Questions

IDE installation failed

When installing ICEman and other development tools from the DEVELOPMENT TOOLS in the VS Code Telink Development Extension, the installation process fails.
Solution: Use the offline installation method instead. Download and follow the instructions in Offline Installation Package to complete the installation.

Compilation failed

When compiling a demo project using VS Code, the compilation fails.
Solution: Check whether the project path contains Chinese characters (such as Chinese folder names, Chinese usernames, etc.).

Flashing failed

When flashing via JTAG, the error message "Burning failed due to target errors" is displayed.
Solution: Check whether the JTAG wiring is correct. Pay special attention to the VTREF pin, which must be connected to the JTAG I/O power supply (i.e., reference voltage) of the target board.
When flashing via BDT, the error message "DUT command execute error" is displayed.
Solution: Before Download, click Activate to activate the chip. After "Activate MCU ok" appears, proceed with the Download operation to flash.