Ti-Project-Assistant (TPA) 使用教程

1.前言

这篇文章是关于我的开源小项目 Ti-Project-Assistant（以下简称 TPA）的使用教程，主要是帮大家更快地开始M0芯片的开发，主要是面向电赛的同学们，无论你是新手还是老手，这个项目可以更快地帮你上手业务开发，并且按照最前沿、最现代的方式组织自己的项目，通过CMake和VSCode的结合，实现完全摆脱Keil和CCS Theia的束缚，使用现代化的开发方式进行全流程配置、开发、编译、烧录和调试。

我的项目已经开源在Github，可以通过PyPI一键安装：pip install ti-project-assistant。为了满足国内网络环境的需求，后续会迁移到Gitee上，大家可以通过网站获取完整开源项目。

2.项目介绍

这个项目用 Python 编写，已发布至 PyPI，可通过 pip install ti-project-assistant 一键安装。安装后 mspm0-init 命令全局可用。它通过环境变量配置读取 Sysconfig（TI 官方图形化芯片配置工具）和 M0SDK（TI 官方提供的 M0 芯片开发套件）的位置，通过读取 syscfg 配置文件，自动调用代码生成脚本 sysconfig cli，在生成必要配置代码的基础上，自动封装项目结构、编写 CMakelists 文件，通过符合现代工程实践的目录架构组织项目（分层 inc//src/，config/ 目录隔离自动生成代码），大家可以直接在 VSCode 中打开项目，然后在主程序的位置开始项目业务逻辑的开发或是底层驱动的编写。该脚本还会生成适用于 VSCode 的全套配置文件（launch.json / tasks.json / settings.json / c_cpp_properties.json）。

v1.0.0 经过完整重构，支持 SDK 中全部 58 款 MSPM0 芯片运行时自动发现（无需硬编码芯片型号），调试器支持 CMSIS-DAP / XDS110 / JLink / none 四种模式：

CMSIS-DAP / XDS110：通过 OpenOCD（选配，使用这两种调试器时必装）连接 GDB Server 进行烧录和调试
JLink：使用 Segger 原生 GDB Server，完全绕过 OpenOCD，烧录调试更稳定
none：不生成调试配置，纯编译环境

最新版本（v1.0.0）还支持：

一键安装：pip install ti-project-assistant，无需手动管理脚本
Git 自动初始化：检测到 Git 已安装时自动 git init + .gitignore
状态栏快捷按钮：配合 Task Buttons 插件，状态栏直接点击 SysConfig / Build / Flash / Clean
独立烧录任务：Flash MSPM0 任务一键烧录，无需进入调试模式
动态切换调试器：mspm0-init regenerate -d jlink 即可切换，支持 CMSIS-DAP / XDS110 / JLink / none
JLink 原生支持：使用 Segger GDB Server，无需 OpenOCD，--jlink-path 手动指定路径
工具路径灵活配置：CLI 参数 → 环境变量 → PATH 自动发现 → 平台路径兜底，五级优先级解析所有工具链
完整 CLI 覆盖：--sdk / --sysconfig / --jlink-path / --openocd / --gdb 手动指定各工具路径

这个项目的设计初衷是为了方便自己更轻松地配置项目结构，实现全流程Linux环境下的嵌入式开发。在完成后进行了简单的封装和Windows的适配，变成了现在这个可以供大家学习参考的开源工具，希望能在电赛中帮上大家的忙。

也就是说，你只需要安装最基本的开发依赖、配置芯片、运行脚本的“三步走”流程，就可以快速进入开发，直接享用VSCode带来的现代化开发体验。读者可以自行接入Claude或是Copilot等AI插件，实现全流程的智能开发体验。

3.使用教程

用前须知

大部分嵌入式开发者都是在Windows系统进行开发的，本项目针对Windows做了适配，所以大家是可以在Windows系统下直接使用的。

3.1 安装依赖

在 Windows 上使用这个项目，建议先把下面这些基础依赖准备好。它们分别负责脚本运行、交叉编译、构建系统、TI 官方配置生成，以及后续的下载和调试。

0）安装 ti-project-assistant

确保 Python 已安装后，首先通过 pip 安装项目本身：

1	pip install ti-project-assistant

安装完成后，mspm0-init 命令即可在终端中全局使用。无需手动下载或拷贝脚本。

可以运行mspm0-init --version（或 -V）查看版本信息，目前最新版本应该是 v1.0.0。

💡 建议：安装 TPA 后，立刻运行 mspm0-init --check 检查当前环境状态。它会列出所有依赖项的检测结果（哪些已就绪、哪些缺失），接下来按诊断结果逐项补齐即可——不必盲目安装全部工具。

一点碎碎念

TL;DR — 如果你已经了解嵌入式开发的编译-烧录-调试流程，可以直接跳过本节，进入依赖安装。

对于不太清楚编译、烧录、调试流程的同学，这一节我用最简单的方式讲解嵌入式开发的全流程，让你至少知道每一步在做什么。嵌入式开发通常经历四个阶段：

1	编写代码 → 编译 → 烧录 → 调试

① 编写代码

这当然是我们最熟悉的阶段。在 VSCode 或其他 IDE 中写 C/C++ 代码，保存到 src/ 目录下即可。

② 编译 — 把代码变成芯片能懂的二进制

按下编译按钮后，编译器会把你的 C 代码翻译成机器可以读懂的二进制文件。这个过程实际上分为预处理、编译、汇编、链接等几个子步骤，但暂时不需要关心这些细节——你只需要知道：

编译器（arm-none-eabi-gcc） 把你写的代码变成 .elf 文件，里面是芯片可以执行的一串 0 和 1。

③ 烧录 — 把二进制文件写入芯片

编译器生成的 .elf 文件不能直接在电脑上运行——它是为芯片设计的。你需要一个烧录器（硬件）把它传输到芯片的闪存中去。

这个过程的参与角色有三个：

角色	是什么	例子
烧录器（硬件）	USB 连接电脑和芯片的物理设备	DAPLink、XDS110、JLink
烧录程序（软件）	电脑上与烧录器通信的程序	OpenOCD 或 JLink GDB Server
目标	你的 MSPM0 芯片	—

整个流程可以这样理解：

你点击”烧录” → VSCode 调用 烧录软件（OpenOCD 或 JLink GDB Server）→ 烧录软件通过 USB 把 .elf 文件发给烧录器 → 烧录器按芯片能懂的协议把数据写入芯片闪存。

烧录软件有两条路径：

CMSIS-DAP / XDS110：使用 OpenOCD——开源万能翻译官，支持多种烧录器协议
JLink：使用 Segger 原生 GDB Server——官方专用工具，更稳定，无需 OpenOCD

④ 调试 — 一步一步监控代码运行

代码烧进去之后，能看到运行结果。但如果你想一步一步跟踪代码、观察寄存器数据、设置断点——这就是调试。

调试的通信链路因调试器而异：

路径一：CMSIS-DAP / XDS110（通过 OpenOCD）

VSCode (你操作的界面)
  │  通过 MI 协议与 GDB 通信
  ▼
arm-none-eabi-gdb (调试客户端)
  │  发送调试命令（暂停、读取寄存器、设置断点...）
  ▼
OpenOCD (调试服务器)
  │  把命令翻译成烧录器能懂的协议
  ▼
烧录器 / 调试器 (硬件)
  │  通过 SWD/JTAG 与芯片通信
  ▼
你的 MSPM0 芯片

路径二：JLink（通过 Segger 原生 GDB Server，无需 OpenOCD）

VSCode (你操作的界面)
  │  通过 MI 协议与 GDB 通信
  ▼
arm-none-eabi-gdb (调试客户端)
  │  发送调试命令
  ▼
JLink GDB Server (Segger 原生调试服务器)
  │  直接与 JLink 硬件通信
  ▼
JLink 调试器 (硬件)
  │  通过 SWD/JTAG 与芯片通信
  ▼
你的 MSPM0 芯片

简单来说：

GDB 是”发号施令的人”——你想看什么、停在哪里，由它说了算。OpenOCD 或 JLink GDB Server 是”传话筒”——把 GDB 的指令翻译后交给硬件，再把芯片的响应传回来。区别在于 JLink 走自己的原生通道，更稳定、延迟更低。

⑤ 项目组织 & CMake

除了编译-烧录-调试这条线，项目结构同样重要。一个好的目录布局意味着代码易读、易维护、易复用——尤其在电赛这种高压环境下，高复用性就是速度。

为了管理项目结构和编译过程，我们使用 CMake：

CMake 不是编译器，而是”编译规则制定者”。你告诉它”源文件在哪、头文件在哪、用什么编译器”，它自动生成构建文件（如 Makefile 或 Ninja 文件），然后由 Ninja（或 make）按这份”运行指南”去调用编译器，最终生成可执行文件。

📋 角色速查表

角色	工具	一句话解释
编译器	`arm-none-eabi-gcc`	把 C 代码变成 `.elf` 二进制文件
构建系统	CMake	管理项目结构，生成构建规则
构建器	Ninja / `make`	按 CMake 的规则实际执行编译
烧录/调试服务器	OpenOCD（CMSIS-DAP/XDS110）	与烧录器通信，烧录 + 调试中转
烧录/调试服务器	JLink GDB Server（JLink）	Segger 原生 GDB Server，烧录 + 调试中转
调试客户端	`arm-none-eabi-gdb`	发调试命令、收芯片响应
图形化配置	SysConfig	TI 官方引脚/时钟/外设 GUI

好了，概念理清了，下面开始按顺序安装和配置。每一步都有了意义。

1）Python

需要安装 Python 3.9 及以上版本。脚本本身就是用 Python 编写的，所以这是最基础的运行环境。

推荐直接使用 python.org 的安装包，或者通过 winget 安装：

1	winget install Python.Python.3.12

安装完成后，记得在命令行中确认 python 和 pip 可用。

2）ARM GCC 交叉编译工具链

这是用来编译 MSPM0 工程的编译器，建议安装 ARM GNU Toolchain 15.x，这个作为硬编码进脚本的默认编译器，暂时不支持其他编译器，后续会考虑支持更多编译器。

对于从来没有安装过 C/C++ 开发环境的用户来说，推荐先安装 MSys2，它自带了包管理器 pacman，后续安装 CMake、Ninja、Git 等工具都非常方便。对于有经验的用户，也可以从 STM32CubeIDE 或其他嵌入式开发环境中提取 arm-none-eabi-gcc 工具链，将其 bin/ 目录加到系统 PATH 中即可，确保能够从终端直接找到 arm-none-eabi-gcc。

这里提供几种安装方式：

方式一（推荐 — MSys2）：如果你已安装 MSys2，在 MSys2 终端中执行：
1
pacman -S mingw-w64-x86_64-arm-none-eabi-toolchain
选择全部安装即可，完成后将 MSys2 的 mingw64/bin/ 加入系统 PATH。
方式二（直接下载 — ARM 官网）：从 ARM 官网下载 .msi 安装包，安装时勾选”添加到系统 PATH”：
- ARM GNU Toolchain 15.3.rel1 for Windows (i686-mingw-w64)
- 安装完成后，在终端运行 arm-none-eabi-gcc --version 确认版本号。
方式三（已有其他 IDE）：如果你安装了 STM32CubeIDE、Keil 等，它们通常自带了 ARM GCC 工具链，找到对应的 bin/ 目录（如 C:\ST\STM32CubeIDE\...\arm-none-eabi\bin），将其加入系统 PATH 即可。

验证安装：

1	arm-none-eabi-gcc --version

3）CMake 与 Ninja

CMake 负责生成工程构建文件，Ninja 负责更快地完成构建。建议两者都安装，版本要求分别保持在 CMake 3.13 以上、Ninja 任意可用版本即可。

常见安装方式如下：

1 2	winget install Kitware.CMake winget install Ninja-build.Ninja

也可以使用MinGW或MSys2等包管理器安装，确保 cmake 和 ninja 命令在终端中可用。

4）TI MSPM0 SDK

这是 TI 官方提供的 MSPM0 软件开发套件，里面包含驱动库、启动文件、CMSIS 相关内容，以及项目构建所需的各种底层资源。

下载后一般解压到 C:\ti\，例如 C:\ti\mspm0_sdk_2_10_00_04。脚本会自动搜索，也可以通过环境变量手动指定。

⏳ 提示：SDK 安装包较大，下载和安装需要一些时间。在此期间你可以同时进行下一步 SysConfig 的下载、以及 OpenOCD/GDB（第 6 步）的 VSCode 插件安装，节省等待时间。

5）TI SysConfig

SysConfig 是 TI 官方的图形化配置工具，用来配置芯片型号、引脚复用、时钟和外设参数。脚本会调用它的 CLI 自动生成 ti_msp_dl_config.c/h 和链接脚本，所以这是必须安装的。

同样建议解压到 C:\ti\ 下，例如 C:\ti\sysconfig_1.27.1。

💡 路径建议：推荐将 SDK 和 SysConfig 放在同一个目录（如 E:\ti\ 或 C:\ti\）下，方便管理。如果你的 C 盘空间紧张，可以放到其他盘符——只要配置好环境变量，TPA 就能找到。注意安装路径不要包含中文。

6）OpenOCD 和 arm-none-eabi-gdb（CMSIS-DAP / XDS110 必装，JLink 用户可选）

⚠️ v1.0.0 重要变更：如果你使用 JLink 调试器，可以完全跳过 OpenOCD——JLink 使用 Segger 原生 GDB Server。如果你使用 CMSIS-DAP 或 XDS110，OpenOCD 仍然是必须的。

这两个工具主要用于烧录和调试。OpenOCD 负责和板子通信，GDB 负责源码级调试。

推荐方式：通过 TI 官方 VSCode 插件自动安装，插件会自动下载 TI 定制版 OpenOCD 和 GDB 并放置在特定目录中，TPA 脚本会自动发现。

操作：在 VSCode 插件市场搜索 TI Embedded Development For VS Code，安装完成后从侧边栏选择安装所有依赖，或从右下角弹窗中安装。

🌐 网络问题备选方案：如果你在 VSCode 插件中下载依赖时遇到网络问题（下载缓慢或反复失败），可以手动从 TI 官网下载 OpenOCD：

TI CCStudio OpenOCD 1.5.0 下载

下载对应平台的安装包，解压后将 bin/ 目录加入系统 PATH 即可

GDB 安装方式取决于你的 ARM GCC 来源：

ARM GCC 来源	GDB 安装方式
MSys2（pacman 安装）	在 MSys2 终端执行 `pacman -S mingw-w64-x86_64-gdb-multiarch`
ARM 官方 `.msi` 安装包	已随编译器一并安装，无需额外操作（`bin/` 目录下自带 `arm-none-eabi-gdb.exe`）
STM32CubeIDE / Keil 提取	检查对应 `bin/` 目录，通常已包含 `arm-none-eabi-gdb.exe`

验证 GDB 安装：

1	arm-none-eabi-gdb --version

6.5）JLink 驱动与工具（JLink 用户必装）

如果你使用 JLink 调试器，需要安装 Segger 官方 JLink 软件包（版本 ≥ 7.70 推荐）：

SEGGER JLink 下载
安装后需手动将 JLink 的 bin\ 目录（如 C:\Program Files\SEGGER\JLink\) 加入系统 PATH
也可通过 --jlink-path 参数或 JLINK_DIR 环境变量手动指定，避免修改 PATH

验证安装：

1 2	JLinkGDBServerCL -version # Windows JLinkGDBServer -version # Linux

7）Tasks Buttons 插件（推荐）

为了在 VSCode 状态栏获得一键编译、烧录、调试的快捷按钮，推荐安装 Tasks Buttons 插件：

在 VSCode 插件市场搜索 Tasks Buttons 并安装。TPA 生成的项目已预置了 tasks.json 和 settings.json，安装该插件后状态栏会自动出现 SysConfig / Build / Flash / Clean 等快捷操作按钮。

其他推荐安装的 VSCode 插件还包括 C/C++ 插件和 Git 相关插件，可按需在插件市场搜索安装。

8）Git（可选，推荐）

如果你需要进行版本控制和多人协作开发，建议安装 Git：

1	winget install --id Git.Git -e --source winget

安装完成后验证：

1	git --version

TPA 在创建项目时会自动检测 Git 是否已安装——如果可用，自动执行 git init 并生成 .gitignore。如果你确定不需要 Git，可以在创建项目时添加 --no-git 参数跳过。

9）推荐的环境变量

全部可选。不设置时，TPA 会从 PATH 自动发现可执行工具，或搜索 TI 工具默认目录。

变量	Windows 默认值	说明
`MSPM0_SDK`	`C:\ti\mspm0_sdk_*`	MSPM0 SDK 根目录
`SYSCONFIG_DIR`	`C:\ti\sysconfig_*`	SysConfig 安装目录
`TI_ROOT`	`C:\ti`	所有 TI 工具的根目录
`OPENOCD_DIR`	PATH → TI 插件缓存	OpenOCD 目录（PATH 优先）
`GDB_DIR`	PATH → TI 插件缓存	GDB 目录（PATH 优先）
`JLINK_DIR`	PATH → `C:\Program Files\SEGGER\JLink`	JLink 安装目录（PATH 优先）

快速设置示例（PowerShell）：

$env:MSPM0_SDK = "C:\ti\mspm0_sdk_2_10_00_04"
$env:SYSCONFIG_DIR = "C:\ti\sysconfig_1.27.1"
$env:TI_ROOT = "C:\ti"
# 以下仅在自动发现失败时手动指定
# $env:OPENOCD_DIR = "C:\ti\ccs_base\DebugServer"
# $env:GDB_DIR = "C:\ti\ccs_base\DebugServer\bin"
# $env:JLINK_DIR = "C:\Program Files\SEGGER\JLink"

新手提示：环境变量配置是很多新手最容易卡住的地方。在 Windows 上，可以通过”系统属性 → 环境变量”图形界面添加，也可以在 PowerShell 中使用 $env: 前缀临时设置（仅当前终端窗口有效）。推荐使用图形界面设置系统环境变量，这样所有终端窗口都生效。

工具解析优先级

所有可执行工具（OpenOCD、GDB、JLink）遵循统一的 5 级优先级：

1. CLI 参数          (--openocd / --gdb / --jlink-path)    ← 最高优先级，显式指定
2. 环境变量          (OPENOCD_DIR / GDB_DIR / JLINK_DIR)    ← 手动配置
3. PATH              (系统 PATH 自动发现)                    ← 跨平台通用，推荐
4. TI 插件缓存       (~\.config\Texas Instruments\...)       ← VSCode 插件自动安装位置
5. 遗留路径          (TI_ROOT / CCS_BASE)                    ← 最后兜底

实际使用中：如果你把工具都加入了 PATH（安装时勾选”添加到 PATH”），绝大多数情况下不需要设置环境变量，TPA 会自动找到它们。环境变量和 CLI 参数主要解决”多个版本共存，想指定某个版本”的场景。

10）一行装完基础工具

如果你想先把非 TI 工具一口气准备好，可以直接执行：

winget install Python.Python.3.12
winget install Kitware.CMake
winget install Ninja-build.Ninja
winget install --id Git.Git -e --source winget

3.2 配置项目

自检

在配置项目之前，建议先进行自检，确保所有依赖项都已正确安装并配置。
在命令行中运行以下命令：

1 2	mspm0-init --check # 会输出各个依赖的检测结果，请在确保没有错的情况下进行下一步

创建新项目

先创建项目目录，比如ti-project，然后打开Sysconfig软件，通过图形化界面配置芯片型号、引脚复用、时钟和外设参数，保存为 ti-project.syscfg 文件。

mspm0-init 已通过 pip 全局安装，直接在命令行中进入该目录，运行以下命令：

# 最简单：在只有 .syscfg 的目录下直接运行
mspm0-init
# 自动发现当前目录 .syscfg，原地创建项目

# 自动发现当前目录的 .syscfg，指定项目名称
mspm0-init new -n my_project

# 手动指定 syscfg 文件和调试器类型
mspm0-init new myboard.syscfg -n my_project -d xds110

# 无 syscfg，纯裸机起点
mspm0-init new --device MSPM0G3507 --package "LQFP-48(PT)" -n bare_start

# 跳过 Git 自动初始化
mspm0-init new -n my_project --no-git

# 手动指定 SDK 或 SysConfig 路径（多版本共存时使用）
mspm0-init new -n my_project --sdk C:\ti\mspm0_sdk_2_10_00_04 --sysconfig C:\ti\sysconfig_1.27.1

# 手动指定 JLink 路径
mspm0-init new -n my_project -d jlink --jlink-path "C:\Program Files\SEGGER\JLink"

# 预览模式：仅显示将创建的文件，不实际写入
mspm0-init new -n my_project --dry-run

# 跳过构建验证（仅生成文件，不编译）
mspm0-init new -n my_project --no-build

全部参数速查

mspm0-init new [syscfg] -n NAME [选项]

  -n, --name NAME        项目名称（必填）
  -o, --output DIR       输出目录（默认 ./<name>/）
  -s, --sdk PATH         MSPM0 SDK 路径（手动指定）
  --sysconfig PATH       SysConfig 安装目录（手动指定）
  -d, --debugger TYPE    cmsis-dap（默认）| xds110 | jlink | none
  --jlink-path PATH      JLink 安装路径（可选，PATH 优先）
  --device DEVICE        手动指定芯片，如 MSPM0G3507
  --package PACKAGE      手动指定封装，如 LQFP-48(PT)
  --dry-run              预览模式，不创建文件
  --no-build             跳过 cmake 构建验证
  --no-git               禁用 Git 自动初始化

mspm0-init regenerate [项目目录] [选项]

  -d, --debugger TYPE    更换调试器：cmsis-dap | xds110 | jlink | none
  --jlink-path PATH      JLink 安装路径（可选，PATH 优先）
  --no-build             跳过重编译
  --no-backup            不备份旧文件
  --dry-run              预览模式
  --no-git               禁用 Git 自动初始化

更多参数和选项参考项目 readme 或是运行 mspm0-init --help 查看。

重新生成配置

如果项目编写到一半需要修改引脚定义或是外设配置，可以在Sysconfig中修改后保存，然后在项目目录下运行：

1 2	mspm0-init regenerate # 在项目目录内执行 mspm0-init regenerate /path/to/proj # 指定项目路径

就可以自动重新生成代码。regenerate 会自动将旧配置文件备份到 .sysconfig_backup/ 目录，不影响你已经写好的业务代码（src/ 下的内容完全安全）。如果你不需要备份，可以加 --no-backup 跳过。

更换调试器也无需重建项目：

1
2
3

mspm0-init regenerate -d xds110        # 从 CMSIS-DAP 切换到 XDS110
mspm0-init regenerate -d jlink         # 切换到 JLink（Segger 原生 GDB Server）
mspm0-init regenerate -d none          # 移除调试器配置（纯编译环境）

3.3 编写项目

主程序放在 src/main.c，可以直接在VSCode中打开项目，编写业务逻辑。
初始项目结构如下：

my_project/
├── CMakeLists.txt              # CMake 构建定义
├── .gitignore                  # Git 忽略规则（自动生成）
├── my_project.syscfg           # 原始 SysConfig 配置
├── config/
│   ├── ti_msp_dl_config.h      # 自动生成 — 请勿手动编辑
│   ├── ti_msp_dl_config.c      # 自动生成 — 请勿手动编辑
│   ├── device_linker.lds       # 链接脚本
│   └── device.opt              # 编译选项
├── inc/
│   ├── main.h                  # 应用头文件
│   ├── app/                    # 应用层头文件
│   ├── driver/                 # 驱动头文件
│   ├── modules/                # 功能模块头文件
│   └── utils/                  # 工具头文件
├── src/
│   ├── main.c                  # 应用入口（在此写代码）
│   ├── app/                    # 应用层实现
│   ├── driver/                 # 驱动实现
│   ├── modules/                # 功能模块实现
│   └── utils/                  # 工具实现
├── lib/                        # 本地静态库
├── excluded/                   # 不参与编译的 SysConfig 产物
├── build/                      # 构建输出（ELF / HEX / BIN / MAP）
└── .vscode/
    ├── launch.json             # 调试配置（CMSIS-DAP / XDS110 / JLink）
    ├── tasks.json              # 构建任务 + 打开 SysConfig + Flash 烧录
    ├── settings.json           # Task Buttons 状态栏快捷按钮
    └── c_cpp_properties.json   # IntelliSense 配置

3.4 依赖关系一览

下图展示了 TPA 与各工具之间的依赖关系，帮助你理解整个工具链的层次结构：

mspm0-init
├── SysConfig 1.x ────────────── 生成 ti_msp_dl_config.c/h、链接脚本
├── MSPM0 SDK 2.x
│   ├── driverlib.a ──────────── 硬件抽象层
│   ├── startup_*.c ──────────── 中断向量表 + 启动代码
│   ├── CMSIS Core ───────────── Cortex-M0+ 寄存器定义
│   └── DeviceFamily.h ──────── 芯片系列宏（运行时动态发现 58 款芯片）
├── arm-none-eabi-gcc ────────── 交叉编译
├── CMake + Ninja ───────────── 构建系统
├── OpenOCD 1.3.x (可选) ────── GDB Server + 烧录（cmsis-dap / xds110 必装）
├── JLink 7.x+ (可选) ───────── 原生 GDB Server + 烧录（jlink 模式，推荐 ≥ 7.70）
├── arm-none-eabi-gdb 14.x ──── 源码级调试
├── Git ──────────────────────── 版本控制（自动初始化）
└── VS Code + Cortex-Debug ──── IDE 集成

关键路径：CMSIS-DAP / XDS110 用户走 OpenOCD 路径；JLink 用户走 Segger 原生 GDB Server 路径。两条路径最终都通过 arm-none-eabi-gdb 对接 VSCode，对用户透明。

4. Linux 下的安装和使用指南

本项目的设计初衷就是面向 Linux 开发环境，脚本本身也是在 Linux 下编写和测试的。相比 Windows，Linux 环境下的依赖安装和工具链配置更加简单直接，且天然适合命令行工作流。本章将完整介绍如何在 Linux（以 Ubuntu/Debian 系为例）上搭建整套 MSPM0 开发环境。

4.1 与 Windows 的关键差异

方面	Windows	Linux
脚本安装	`pip install ti-project-assistant`	`pip install ti-project-assistant`
工具链安装	需手动下载安装包或使用 winget	`apt` 一行搞定核心工具链
TI 工具默认路径	`C:\ti\`	`~/ti/`
SysConfig CLI	`sysconfig_cli.bat`	`sysconfig_cli.sh`
OpenOCD/GDB	从 PATH 自动发现，或 TI VSCode 插件	从 PATH 自动发现，或 TI VSCode 插件
JLink	SEGGER 安装包 → 需手动添加 `bin\` 到 PATH	`.deb` 自动加入 PATH / `.tar.gz` 需手动添加 `bin/` 或设 `JLINK_DIR`
调试器权限	即插即用	需配置 udev 规则

4.2 安装依赖

Linux 下的依赖安装远比 Windows 简洁。核心工具链一行命令即可完成，TI 官方工具只需下载解压。

1）Python

大多数 Linux 发行版已预装 Python 3。确认版本：

1	python3 --version # 需要 ≥ 3.8

如果版本过低或未安装：

1	sudo apt install python3 python3-pip

2）ARM GCC 交叉编译工具链

Ubuntu/Debian 官方仓库自带 gcc-arm-none-eabi，版本可能稍旧但仍可用。推荐从 ARM 官网下载最新 15.x 版本以获得最佳兼容性。

方式一（推荐）：从 ARM 官网下载

从 ARM GNU Toolchain Downloads 下载 arm-gnu-toolchain-15.x.x-x86_64-arm-none-eabi.tar.xz，解压后将其 bin/ 目录加入 PATH：

# 示例：解压到 /opt
sudo tar -xf arm-gnu-toolchain-15.x.x-x86_64-arm-none-eabi.tar.xz -C /opt
export PATH="/opt/arm-gnu-toolchain-15.x.x-x86_64-arm-none-eabi/bin:$PATH"
# 建议写入 ~/.bashrc 或 ~/.zshrc 持久化

方式二：使用 apt（版本可能偏旧）：

1	sudo apt install gcc-arm-none-eabi

验证安装：

1	arm-none-eabi-gcc --version

3）CMake 与 Ninja

1	sudo apt install cmake ninja-build

验证：

1 2	cmake --version # ≥ 3.13 ninja --version

4）TI MSPM0 SDK

从 TI MSPM0 SDK 下载 Linux 版本，解压到 ~/ti/：

mkdir -p ~/ti
# 假设下载的安装包为 mspm0_sdk_2_10_00_04-linux.zip
unzip mspm0_sdk_2_10_00_04-linux.zip -d ~/ti/
# 解压后路径为 ~/ti/mspm0_sdk_2_10_00_04/

5）TI SysConfig

从 TI SysConfig 下载 Linux 版本，同样解压到 ~/ti/：

1
2
3

# 下载 .tar.gz 安装包后
tar -xzf sysconfig_1.27.1.tar.gz -C ~/ti/
# 解压后路径为 ~/ti/sysconfig_1.27.1/

这里的 sysconfig_cli.sh 就是脚本将会调用的 CLI 入口（Windows 上的 .bat 对应物）。

6）OpenOCD 和 arm-none-eabi-gdb（CMSIS-DAP / XDS110 必装，JLink 用户可选）

⚠️ v1.0.0 重要变更：如果你使用 JLink 调试器，可以完全跳过 OpenOCD。

Linux 下的 OpenOCD 和 GDB 推荐通过 VSCode 的 TI 插件自动安装：

在 VSCode 插件市场安装 TI Embedded Development For VS Code，然后在侧边栏选择”安装所有依赖”。TI 定制版 OpenOCD 和 GDB 会被安装到：

1 2	~/.config/Texas Instruments/ti-embedded-debug/openocd/<version>/ ~/.config/Texas Instruments/ti-embedded-debug/gdb/<version>/

TPA 脚本在 Linux 下会优先搜索这些路径，无需手动配置。

🌐 网络问题备选方案：如果你在 VSCode 插件中下载依赖遇到网络问题，可以手动从 TI 官网下载 OpenOCD：

TI CCStudio OpenOCD 1.5.0 下载

下载 Linux 版本，解压后将 bin/ 目录加入 PATH 即可

备选方案：使用系统包管理器

1	sudo apt install openocd gdb-multiarch

注意：系统仓库的 openocd 可能不含 TI 定制补丁，推荐优先使用 TI 官方版本。

6.5）JLink 驱动与工具（JLink 用户必装）

如果你使用 JLink 调试器，需要安装 Segger 官方 JLink 软件包（版本 ≥ 7.70 推荐）：

SEGGER JLink 下载
下载 .deb 包安装（自动加入系统 PATH，无需额外配置），或解压 .tar.gz 到 /opt/SEGGER/JLink/（需手动将 bin/ 加入 PATH 或设 JLINK_DIR）

1 2	# 验证安装 JLinkGDBServer -version

7）一行装完基础工具

1	sudo apt install python3 gcc-arm-none-eabi cmake ninja-build

再加上 TI 官方工具（SDK + SysConfig）的解压，环境就准备完成了。

4.3 环境变量配置

全部可选。不设置时，TPA 会从 PATH 自动发现可执行工具，或搜索 TI 工具默认目录。

变量	Linux 默认值	说明
`MSPM0_SDK`	`~/ti/mspm0_sdk_*`	MSPM0 SDK 根目录
`SYSCONFIG_DIR`	`~/ti/sysconfig_*`	SysConfig 安装目录
`TI_ROOT`	`~/ti`	所有 TI 工具的根目录
`OPENOCD_DIR`	PATH → `~/.config/.../openocd/*`	OpenOCD 目录（PATH 优先）
`GDB_DIR`	PATH → `~/.config/.../gdb/*`	GDB 目录（PATH 优先）
`JLINK_DIR`	PATH → `/opt/SEGGER/JLink*`	JLink 安装目录（PATH 优先）

推荐在 ~/.bashrc 或 ~/.zshrc 中写入环境变量：

# TI 工具链根目录
export TI_ROOT=~/ti
# MSPM0 SDK 路径
export MSPM0_SDK=~/ti/mspm0_sdk_2_10_00_04
# SysConfig 安装路径
export SYSCONFIG_DIR=~/ti/sysconfig_1.27.1
# 以下仅在自动发现失败时手动指定
# export OPENOCD_DIR=/path/to/openocd
# export GDB_DIR=/path/to/gdb
# export JLINK_DIR=/opt/SEGGER/JLink

如果你使用 ARM 官网下载的工具链（而非 apt 版本），还需将编译器加入 PATH：

1	export PATH="/opt/arm-gnu-toolchain-15.x.x-x86_64-arm-none-eabi/bin:$PATH"

工具解析优先级（所有可执行工具统一）：

1. CLI 参数          (--openocd / --gdb / --jlink-path)    ← 最高优先级，显式指定
2. 环境变量          (OPENOCD_DIR / GDB_DIR / JLINK_DIR)    ← 手动配置
3. PATH              (shutil.which)                          ← 跨平台自动发现
4. TI 插件缓存       (~/.config/Texas Instruments/...)       ← VSCode 插件自动安装位置
5. 遗留路径          (TI_ROOT / CCS_BASE)                    ← 最后兜底

如果不配置任何环境变量，TPA 会在 ~/ti/ 下自动搜索并匹配最新版本。明确指定可以避免多版本共存时的歧义。

4.4 安装 ti-project-assistant

通过 pip 一键安装，mspm0-init 命令全局可用：

1	pip install ti-project-assistant

安装后，在任意目录下都可以直接运行：

1 2	mspm0-init --help mspm0-init --check

如果你偏好从源码安装（开发模式）：

1
2
3

git clone git@github.com:AndyYang12345/Ti-Project-Assistant.git
cd ti-project-assistant
pip install -e .

4.5 调试器权限配置（重要）

在 Linux 下，USB 调试器（CMSIS-DAP、XDS110 等）默认只有 root 用户才能访问。直接使用会导致 OpenOCD 报权限错误。需要配置 udev 规则授予普通用户访问权限。

通用方法：添加 udev 规则

创建 /etc/udev/rules.d/99-ti-debuggers.rules：

sudo tee /etc/udev/rules.d/99-ti-debuggers.rules > /dev/null << 'EOF'
# CMSIS-DAP / DAPLink
SUBSYSTEM=="usb", ATTRS{idVendor}=="0d28", ATTRS{idProduct}=="0204", MODE="0666"
SUBSYSTEM=="usb", ATTRS{idVendor}=="c251", ATTRS{idProduct}=="f001", MODE="0666"

# XDS110 (TI 官方调试器)
SUBSYSTEM=="usb", ATTRS{idVendor}=="0451", ATTRS{idProduct}=="bef3", MODE="0666"

# JLink (SEGGER 调试器)
SUBSYSTEM=="usb", ATTRS{idVendor}=="1366", ATTRS{idProduct}=="0101", MODE="0666"
SUBSYSTEM=="usb", ATTRS{idVendor}=="1366", ATTRS{idProduct}=="0105", MODE="0666"

# 通用 CMSIS-DAP v2 (HID 设备)
SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE="0666"

# 通用规则：将所有 USB 串口和 HID 调试设备的权限放开
SUBSYSTEM=="tty", ATTRS{idVendor}=="0451", MODE="0666"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0451", MODE="0666"
EOF

# 重新加载 udev 规则
sudo udevadm control --reload-rules
sudo udevadm trigger

替代方案：加入 dialout / plugdev 组

如果你的 Linux 发行版用组权限管理 USB 设备（如 Ubuntu），将当前用户加入 dialout 和 plugdev 组：

1 2	sudo usermod -a -G dialout,plugdev $USER # 注销重新登录后生效

配置完成后，重新插拔调试器，OpenOCD 即可正常访问设备。

4.6 配置和创建项目

依赖安装和权限配置就绪后，后续操作（SysConfig 图形化配置、运行 mspm0-init、VSCode 调试）与 Windows 完全一致。

自检

1 2	mspm0-init --check # 确保所有依赖项均显示 ✓ 正常（Git 为可选）

创建项目

# 在包含 .syscfg 文件的目录下直接运行
mspm0-init

# 或手动指定
mspm0-init new myboard.syscfg -n my_project -d cmsis-dap

更换调试器

1
2
3

mspm0-init regenerate -d xds110        # 切换到 XDS110
mspm0-init regenerate -d jlink         # 切换到 JLink（Segger 原生 GDB Server）
mspm0-init regenerate -d none          # 移除调试器配置（纯编译环境）

构建和调试

# 命令行构建（充分利用多核）
cmake --build build -j$(nproc)

# 在 VSCode 中打开，按 F5 启动调试
code .

Linux 特有优势：$(nproc) 会自动使用全部 CPU 核心并行编译，比 Windows 下的 Ninja 默认并发数更快。同时 Linux 的文件系统性能更好，regenerate 操作的 IO 开销更低。

4.7 Linux 下的已知问题与解决

SysConfig CLI 无执行权限

从 .tar.gz 解压的 sysconfig_cli.sh 可能缺少执行权限：

1	chmod +x ~/ti/sysconfig_1.27.1/sysconfig_cli.sh

SysConfig GUI 无法启动（无头服务器）

如果纯命令行环境（无 GUI）下需要图形化配置 SysConfig：

# 方法一：安装 X11 转发所需依赖
sudo apt install libgtk-3-0 libwebkit2gtk-4.0-37

# 方法二：在本地 Windows 上运行 SysConfig GUI，编辑后将 .syscfg 传到 Linux

多版本 SDK/SysConfig 共存

如果你安装了多个版本的 SDK 或 SysConfig，不设环境变量时脚本会自动选择最新版本。如需指定特定版本，通过环境变量或命令行参数 --sdk、--sysconfig 精确指定。

4.8 小结

Linux 环境下的安装流程总结：

① pip install ti-project-assistant
② sudo apt install gcc-arm-none-eabi cmake ninja-build
③ 下载 MSPM0 SDK + SysConfig → 解压到 ~/ti/
④ (可选) 安装 JLink（如使用 JLink 调试器）
⑤ (可选) 在 ~/.bashrc 设置环境变量
⑥ 配置 udev 调试器权限
⑦ mspm0-init --check → mspm0-init → code . → F5

v1.0.0 完整支持 SDK 中全部 58 款 MSPM0 芯片和 CMSIS-DAP / XDS110 / JLink / none 四种调试模式。相比 Windows，Linux 不仅工具链安装简便，而且从根本上就是本项目的最佳运行环境——没有路径转义问题、天然支持并行编译、脚本执行效率更高。如果你日常使用 Linux 进行开发，推荐直接以 Linux 作为 MSPM0 的主开发平台。