telink_9118_wifi_sdk 快速入门

概述

关于本文档

本文档旨在帮助您快速完成 telink_9118_wifi_sdk 开发环境的搭建、SDK 的获取、工程的构建与烧录，并成功运行第一个示例工程。

适用范围

telink_9118_wifi_sdk 适用于泰凌 TLSR9118 SoC 平台。

说明

关于支持的芯片型号、对应的开发板以及 SDK 版本信息，请参考官网介绍。

开发准备

硬件准备

硬件	说明
PC	Windows 10/11 或 Ubuntu 20.04 及以上版本（推荐使用 64 位 Linux）
开发板	TLSR9118 开发板
连接线	USB Type-C 数据线

硬件实物，请参考步骤一：连接硬件。

软件准备

软件	说明
开发环境	泰凌 VS Code 扩展（Windows/Linux） / 命令行（Linux）
工具链	TL32 ELF MCULIB V5 GCC 10.3
烧录工具	BDT (Burning and Debugging Tool)
Python 依赖	pycryptodome/imgtool
串口工具	推荐使用 Tera Term（Windows）/ Minicom（Linux）
SDK	Gitee/GitHub

选择开发环境

各操作系统支持的开发环境如下：

操作系统	泰凌 VS Code 扩展	命令行
Windows 10/11	✓	—
Linux	✓	✓

您可根据开发习惯选择其中一种开发方式。

泰凌 VS Code 扩展（Windows/Linux）命令行环境（Linux）

前提条件：请确保您的电脑上已安装最新版本的 VS Code。若 VS Code 版本过低，可能会导致泰凌 VS Code 扩展无法正常工作或功能异常。

安装泰凌 VS Code 扩展具体步骤：

1. 启动 VS Code。

2. 点击左侧活动栏的扩展图标，或使用快捷键 Ctrl+Shift+X。

3. 在搜索框中输入 Telink。

4. 在搜索结果中找到 Telink Development Tool，点击 Install。

安装完成后，在 VS Code 左侧活动栏中将显示 T 图标。

命令行环境无需安装 IDE，但需先安装以下系统依赖包 (以 Ubuntu 为例)。

sudo apt update
sudo apt install build-essential libncurses-dev
sudo apt install libevent-dev libnl-3-dev libnl-genl-3-dev

验证系统软件包是否安装成功：

dpkg -l | grep -E "build-essential|libncurses-dev|libevent-dev|libnl-3-dev|libnl-genl-3-dev"

所有包状态应为 ii（已安装）。

获取 SDK 与配置开发环境

下载 SDK

点击此 Gitee 或 GitHub 链接，下载最新版本的 SDK 并解压至本地。

SDK 目录概览

解压 SDK 后，进入 wits-sdk 目录。wits-sdk 为 SDK 根目录，其顶级目录包含以下子目录。

目录	描述
api	Telink Wi-Fi APIs
app	示例应用程序
configs	默认配置
hal	硬件抽象层
include	需要包含的头文件
kernel	带有 FreeRTOS 和 FreeBSD 的内核
lib	可能使用到的库模块
prebuilt	使用预定义配置构建的库
scripts	与构建相关的脚本

导入 SDK

泰凌 VS Code 扩展（Windows/Linux）命令行环境（Linux）

点击 VS Code 左上角的 File -> Open Folder...，进入 SDK 解压后的目录，选择导入 wits-sdk 文件夹。

命令行环境无需导入 SDK。

配置开发环境

下载工具链

泰凌 VS Code 扩展（Windows/Linux）命令行环境（Linux）

1. 点击 VS Code 左侧活动栏的 T 图标，展开 WIFI DEVELOPMENT 树状菜单。

2. 在 Tools and Settings 列表下选中 TL32 ELF MCULIB V5 GCC 10.3 工具链，点击该工具链右侧安装按钮，等待安装完成。

安装完成后，VS Code 窗口右下角会弹出如下安装成功的提示。

1. 在终端中，使用以下命令下载并解压工具链压缩包到 /opt/ 目录下：

# 切换到下载目录（Downloads，请替换为您的实际下载路径）
cd ~/Downloads

# 下载工具链压缩包
wget https://doc.telink-semi.cn/tools/vsc/linux/toolchains/V511_Linux.tar.xz

# 解压到 /opt/ 目录（需 sudo 权限）
sudo tar -xvJf ./V511_Linux.tar.xz -C /opt/ --strip-components=2

默认情况下，SDK 假定工具链路径为 /opt/nds32le-elf-mculib-v5/bin/。若解压至其他目录，需在构建前通过 make menuconfig 进入 Target platform -> NDSV5 architecture 菜单，修改交叉工具链的路径。

2. 在终端中，输入以下命令验证工具链是否安装成功：

/opt/nds32le-elf-mculib-v5/bin/riscv32-elf-gcc --version

应能正常输出版本信息，无 "command not found" 错误。

安装 Python 依赖

泰凌 VS Code 扩展（Windows/Linux）命令行环境（Linux）

构建过程中部分脚本依赖 Python 环境，请按以下步骤安装所需组件：

1. 点击 VS Code 左侧活动栏的 T 图标，展开 WIFI DEVELOPMENT 树状菜单。

2. 在 Tools and Settings 列表下点击 Python Environment for WiFi SDK，等待安装完成。

安装完成后，VS Code 窗口右下角会弹出如下安装成功的提示。

1. 构建过程中部分脚本依赖 Python 环境，请按以下步骤安装所需组件：

sudo apt install python3-pip
pip install pycryptodome
pip install imgtool

注意

自 Ubuntu 23.04 起默认启用了 PEP 668 (externally-managed-environment) 机制，直接在系统 Python 环境中执行 pip install 会报错 error: externally-managed-environment。此时请在 pip install 命令后追加 --break-system-packages 选项，例如：

pip install --break-system-packages pycryptodome
pip install --break-system-packages imgtool

若您的系统版本低于 23.04（如 Ubuntu 20.04/22.04），则无需该选项，直接执行命令即可。

2. 在终端中，输入以下命令验证 Python 依赖是否安装成功：

pip list | grep -E "pycryptodome|imgtool"

应能看到已安装的 pycryptodome 和 imgtool 及其版本号。

3. 由于这些软件包通常安装在 ~/.local/bin 目录下，请将该路径添加到 PATH 环境变量中。具体操作步骤：

(1) 打开并编辑 ~/.bashrc 文件：

nano ~/.bashrc

(2) 在文件末尾添加以下内容：

export PATH=$PATH:~/.local/bin

保存文件并退出 nano（按下 Ctrl+O，回车确认，再按 Ctrl+X 退出）

(3) 执行以下命令使配置生效：

source ~/.bashrc

(4) 验证 PATH 是否已包含 ~/.local/bin：

echo $PATH

(5) 验证 PATH 配置:

which imgtool

应返回 /home/用户名/.local/bin/imgtool 的完整路径。

构建与烧录第一个示例

本章将引导您完成从选择示例、代码编译，到最终烧录并运行的完整开发闭环。

选择示例

推荐选择 Command-line demo（命令行示例） 作为第一个运行的示例。该示例位于 app/cli/ 目录，启动后会打印 Hello world! 并进入命令行交互界面，是验证开发环境搭建是否成功的最简方式。

在默认配置（tlsr9xxxs_defconfig）中，Command-line demo 已默认启用（CONFIG_DEMO_CMDLINE=y），无需额外配置。

构建第一个示例

说明

首次烧录或 Flash 被擦除时，需要同时烧录引导加载程序与主固件：

wits.tlsrboot.bin
wits.mcuboot.bin

在引导加载程序和 Flash 布局未发生变化的情况下，后续仅修改应用程序时，只需重新构建并烧录主固件：

wits.mcuboot.bin。

泰凌 VS Code 扩展（Windows/Linux）命令行环境（Linux）

1. 在 VS Code 中导入该 SDK 后（详见导入 SDK），点击左侧栏的 T 图标，进入 WIFI DEVELOPMENT 分区。

2. 按以下顺序，点击对应的按钮进行构建。

(1) 构建引导加载程序：

a. 点击 Build Targets 下的 distclean 按钮清理残留文件。

b. 在 Select Targets 目录下选择 tlsr9xxxs_bl 配置。

c. 点击 Build Targets 下的 all 按钮开始构建。

构建完成后，可在 Build Files 目录下看到生成的 wits.tlsrboot.bin 文件，点击该文件右侧的文件夹图标，将其备份到其它任意目录。

(2) 构建主固件（Command-line demo）：

a. 点击 distclean 按钮清理残留文件，为构建做准备。

b. 在 Select Targets 目录下选择 tlsr9xxxs 配置。

c. （可选）如需调整默认配置，点击 Build Targets 下的 menuconfig 按钮打开配置界面。具体操作步骤请参考附录2：下载泰凌 VS Code 扩展辅助工具。

d. 点击 Build Targets 下的 all 按钮开始构建。

buildcommandlinedemo

构建完成后，可在 Build Files 目录下看到生成的 wits.mcuboot.bin 文件，点击该文件右侧的文件夹图标，将其备份到其它任意目录。

按照以上步骤操作时，OUTPUT 区会实时输出日志信息，当出现 Process completed successfully （exit code: 0）时，表示该步骤成功完成。

1. 构建引导加载程序：

# 进入 SDK 根目录。将路径替换为 SDK 的实际路径。
cd path/to/telink_9118_wifi_sdk/wits-sdk/

# 清除上次构建的残留文件
make distclean

# 选择引导加载程序配置
make tlsr9xxxs_bl_defconfig

# 开始构建（启用多核并行编译）
make -j$(nproc)

构建完成后，将在 SDK 根目录下生成 wits.tlsrboot.bin（引导加载程序镜像）。由于 make distclean 命令会清除之前构建的固件，请在构建完成后及时备份固件至其它任意路径。

2. 构建主固件（Command-line demo）：

# 清除上次构建的残留文件
make distclean

# 选择默认配置（Command-line demo 已默认启用）
make tlsr9xxxs_defconfig

# （可选）如需调整配置，运行 menuconfig
make menuconfig

# 开始构建（启用多核并行编译）
make -j$(nproc)

构建完成后，在 SDK 根目录下生成 wits.mcuboot.bin（主固件镜像，包含 MCUBoot 头部），请及时备份。

烧录

步骤一：连接硬件

请按照以下逻辑连接 PC 与开发板：

PC <-> 开发板：使用 Type-C 数据线连接。若开发板 LED 灯正常点亮，表明开发板成功上电。

选择与您的操作系统对应的标签页：

WindowsLinux

打开 PC 端的设备管理器，若端口(COM 和 LPT)列表中出现了如下图所示的 CP210x 设备，表明开发板已被 PC 成功识别。

在终端中输入 lsusb 命令。

当出现如下图所示的信息，则表明开发板已被 PC 成功识别。

步骤二：安装 BDT

1. 下载 BDT：

WindowsLinux

下载链接：BDT (Windows)

下载链接：BDT (Linux)

2. 将下载的工具包解压到自定义的路径。

3. 进入解压后的发布目录。

WindowsLinux

双击运行 Telink BDT.exe 即可启动该工具。

（1）解压其中的 TGui-BDT-Linux-V1.0.2.tar.gz 压缩包，进入其解压目录中。

（2）双击其中的可执行文件 TGui 即可启动该工具。

步骤三：烧录固件

WindowsLinux

1. 双击运行 Telink BDT.exe，选择 9118 Programmer，程序会自动打开 EMI Tool 窗口。如下图所示：

如未自动打开 EMI Tool，请手动点击 Tool 菜单中的 EMI Tool。

2. 点击 Install Uart driver X64，并完成安装程序以安装 UART 驱动（仅首次需要）。

3. 在 EMI Tool 的 Firmware 页面中：

(1) 地址 0x80000000 行：点击文件夹图标，选择 wits.tlsrboot.bin

(2) 地址 0x80080000 行：点击文件夹图标，选择 wits.mcuboot.bin

(3) 在 Operation 分区中，选择开发板对应的 COM 端口，波特率设置为 2,000,000 bps。

(4) 点击 Download 按钮开始烧录。烧录完成后开发板自动重启。

烧录完成后，BDT 界面会有如下日志显示：

1. 配置串口权限：

为支持通过串口烧录固件及收发 CLI 命令，需将当前用户添加至 dialout 用户组：

sudo usermod -aG dialout $USER

执行后，需要注销并重新登录才能使权限生效。

2. 双击 TGui 文件打开 BDT 软件。

3. 点击上方的 9118 BDT 选项。

4. 在 Firmware 分区中：

地址 0x80000000 行：点击 Open，选择 wits.tlsrboot.bin（引导加载程序）
地址 0x80080000 行：点击 Open，选择 wits.mcuboot.bin（主固件）

5. 在 Operation 分区中，选择开发板对应的串口设备（如 /dev/ttyUSB0），波特率设置为 2,000,000。

说明

在终端中执行以下命令可列出所有 USB 串口设备。

ls /dev/ttyUSB*

若存在多个设备，可通过比较开发板接入前后该列表的变化，判断当前设备对应的串口号。

6. 点击 Download 按钮开始烧录。烧录完成后开发板自动重启。

烧录完成的 BDT 日志如下所示：

验证运行结果

通过串口工具打开开发板对应串口，并将比特率设置为 115,200 bps。按下开发板上的 RST 按键，使开发板重新启动。待启动完成后，确认串口工具是否输出 Hello world! 信息，以验证运行结果。

说明

以下分别以 Tera Term（Windows）和 minicom（Linux）为例进行详细说明，您也可根据自己习惯选择其他串口工具，但比特率必须设置为 115,200 bps。

WindowsLinux

1. 打开 Tera Term 工具，在弹出的新建连接窗口中选择串口(E)，并在端口(R)下拉列表中选择开发板所在的 COM 口（可在设备管理器的"端口（COM 和 LPT）"中查看 CP210x 设备所在的端口）然后点击确定。

2. 点击设置，选择串口(E)...，选择比特率为 115,200。

3. 切换到终端页面，设置接收(R) 为 AUTO，发送(M) 为 LF。

4. 按下开发板上的 RST 按键（按键位置请参考硬件连接图红框位置），开发板会自动重启。

待重启完成后，若在 Tera Term 页面输出如下串口信息，则说明示例程序已成功运行。

1. 在终端输入以下命令安装 minicom：

sudo apt install minicom

2. 打开串口：

minicom -D /dev/ttyUSB0 -b 115200

注意

请将上方终端命令中的 /dev/ttyUSB0 替换为设备实际对应的串口号。

3. 设置自动换行与回车字符（推荐）：

为便于查看串口输出，建议开启 minicom 的自动换行及回车字符功能：

按 Ctrl+A，再按 W，切换自动换行（Line Wrap）。开启后，超出一行宽度的输出会自动折行显示，不会截断。
按 Ctrl+A，再按 T，切换加入回车字符（Add Carriage Return）。开启后，终端在接收到换行符 \n 时自动补上回车符 \r，避免输出内容出现"阶梯状"错位显示。

4. 按下开发板 RST 按键，重启开发板。

待重启完成后，若在串口终端输出如下串口信息，则说明示例程序已成功运行。

附录1：常见问题

烧录失败

可能原因：串口端口选择错误或 UART 驱动未正确安装。

解决办法：

WindowsLinux

检查 USB 数据线连接是否正常，RST 按键旁的 LED 灯是否点亮。
在 BDT 中确认选择的 COM 端口正确。
打开 BDT -> EMI Tool，点击 Install Uart driver X64 按钮重新安装配套驱动。

检查 USB 数据线连接是否正常，RST 按键旁的 LED 灯是否点亮。
在 BDT 中确认选择的 COM 端口正确。

串口无输出或输出异常

可能原因：串口终端参数设置不正确，或固件未正确烧录。

解决办法：

WindowsLinux

确认串口端口正确且波特率为 115,200。
重新执行烧录流程，确认烧录日志显示成功。
烧录完成后手动复位开发板。
调整串口软件的串口通信配置，确保终端配置页中的接收(R) 为 AUTO，发送(M) 为 LF，如下图所示：

确认串口端口正确且波特率为 115,200；
检查终端参数：数据位 8、停止位 1、无校验、无硬件流控（按 Ctrl+A + Z 打开帮助菜单，或按 Ctrl+A + O 进入配置界面检查）；
关闭硬件流控（Hardware Flow Control），避免因开发板未连接流控线导致数据卡顿；
重新执行烧录流程，确认烧录日志显示成功；
烧录完成后手动复位开发板。

构建失败：找不到工具链（Linux）

可能原因：工具链可能未正常配置。

解决办法：检查 /opt/nds32le-elf-mculib-v5/ 目录，确保目录下的文件情况如下所示。

附录2：下载泰凌 VS Code 扩展辅助工具

以 MenuConfig 为例：

1. 点击 VS Code 左侧活动栏的 T 图标，展开 WIFI DEVELOPMENT 树状菜单。

2. 在 Tools and Settings 列表下选中 MenuConfig，右键单击，在弹出的菜单中点击 Install。

安装完成后，VS Code 窗口右下角会弹出如下安装成功的提示。

说明

安装完成后，点击 Build Targets 列表中的 menuconfig 即可在 VS Code 中调用该工具。

目标	阅读文档
学习 Wi-Fi 功能开发	软件开发指南
学习外设驱动开发	设备驱动开发指南
学习低功耗开发	低功耗开发指南
学习 OTA 固件更新	设备固件更新指南
学习 AT 指令	AT 指令
查看版本变化	Release Notes

telink_9118_wifi_sdk 快速入门

概述

关于本文档

适用范围

开发准备

硬件准备

软件准备

选择开发环境

获取 SDK 与配置开发环境

下载 SDK

SDK 目录概览

导入 SDK

配置开发环境

下载工具链

安装 Python 依赖

构建与烧录第一个示例

选择示例

构建第一个示例

烧录

步骤一：连接硬件

步骤二：安装 BDT

步骤三：烧录固件

验证运行结果

相关参考文档

附录1：常见问题

烧录失败

串口无输出或输出异常

构建失败：找不到工具链（Linux）

附录2：下载泰凌 VS Code 扩展辅助工具