HPM SDK Explorer

简体中文

HPM SDK Explorer 是面向 HPMicro HPM SDK 的 VS Code 扩展。通过图形界面选择示例、开发板、运行模式和调试接口，减少手动修改 CMake 参数及调试配置的操作。

主要功能

搜索、收藏和快速切换 SDK 示例，按当前开发板隐藏明确不支持的示例。
从状态栏选择示例、开发板、HPM_BUILD_TYPE 和 Debug/Release。
自动检测 SDK 环境包，配置 GCC、ZCC 或 Andes 工具链及构建工具。
所有示例统一使用所选 SDK 根目录下的 build，相同配置支持增量构建。
按板卡信息更新芯片型号、OpenOCD 脚本、SVD、ELF 和 GDB 路径。
支持 J-Link、CMSIS-DAP、FT2232、nds_aice_micro 和自定义调试接口。
中英文界面全局切换，默认跟随 VS Code 界面语言。

使用前需要安装的插件

使用 VS Code 1.88 或更新版本，并按用途安装以下插件：

插件	扩展 ID	是否需要	用途
CMake Tools	`ms-vscode.cmake-tools`	配置和构建必需	执行 CMake 配置、切换构建类型并编译
Cortex-Debug	`marus25.cortex-debug`	使用生成的调试配置时需要	提供 `cortex-debug` 调试类型，对接 GDB 和探针服务端
C/C++	`ms-vscode.cpptools`	可选	提供 C/C++ 代码补全、导航等编辑功能

本扩展当前不会自动批量安装这些插件。请在扩展面板中搜索扩展 ID 并安装；缺少 CMake Tools 或 Cortex-Debug 时，对应配置页面也提供安装按钮，需要用户点击。

调试还需要支持目标 HPM 芯片的 RISC-V GDB，以及对应的 OpenOCD 或 J-Link 服务端。生成的配置使用 cortex-debug 类型；请使用与你的 HPM SDK、板卡和调试工具兼容的调试扩展版本。

Windows 环境获取

Windows 用户可以从 HPMicro sdk_env 获取开发环境，在其 Releases 中下载完整环境包并解压。环境包已包含 HPM SDK，以及配套工具链和 CMake、Ninja、Python、OpenOCD 等工具，无需再单独下载一份 SDK。

保留解压后的目录结构：

sdk_env*/
├── hpm_sdk/       ← 在 VS Code 中打开这个文件夹作为工作区
├── toolchains/
└── tools/

安装前述必需插件后，使用 VS Code 的“文件 → 打开文件夹”，选择环境包内的 hpm_sdk 目录（其中包含 boards、samples 和 cmake）。插件会自动检测并选择该环境包中的工具；环境完整且验证通过后自动保存，通常无需逐项填写路径。存在多个候选项或工具缺失时，再按环境配置页面的提示选择或补齐。

安装与快速开始

在 VS Code 扩展面板（Ctrl+Shift+X）搜索 HPM SDK Explorer 并安装。
安装上表中需要的插件。Windows 用户下载并解压上述 sdk_env 完整环境包，其他环境准备相应平台的 SDK 和工具。
使用“文件 → 打开文件夹”打开环境包中的 hpm_sdk 作为工作区，信任工作区，然后点击活动栏中的 HPM SDK Explorer 图标。
等待插件自动检测、选择并验证环境，全部通过后自动保存。只有存在多个候选项或缺项时，才需要打开 HPM_SDK环境配置 处理提示。
环境就绪后，选择开发板、示例、运行模式及 Debug/Release，点击“配置并编译”。

从 Marketplace 安装后即可使用，无需下载源码或自行打包。源码开发方式见下方“源码开发”。

SDK 环境配置

本扩展本身不包含 SDK、编译器或构建工具。Windows 用户使用上述 sdk_env 完整环境包即可获得 SDK 和配套工具，通常无需逐项安装；自动检测优先从同一个 sdk_env* 下的 toolchains 和 tools 查找工具，缺项再从已有配置、构建缓存及 PATH 查找。

环境项	填写内容
`HPM_SDK_BASE`	SDK 根目录，需包含 `cmake/application.cmake`
`GNURISCV_TOOLCHAIN_PATH`	GCC、ZCC 或 Andes 工具链根目录，通常包含 `bin`
`CMAKE`	CMake 程序或其所在目录
`NINJA`	Ninja 程序或其所在目录
`OPENOCD`	OpenOCD 程序或其所在目录；当前环境校验必填
`PYTHON3`	Python 3 程序或其所在目录，需安装 PyYAML
`HPM_SDK_TOOLCHAIN_VARIANT`	`gcc`、`zcc`、`nds-gcc` 或 `nds-llvm`

选择工具链目录后，按实际编译器自动识别类型；该类型也必须被当前 SDK 支持。根目录、bin 目录或编译器文件均可用于工具链识别。

七项全部通过验证后才保存，不会把缺项或无效配置部分写入。当前版本即使使用 J-Link，也需要补齐环境表中的 OpenOCD 项。调试所需的 J-Link 服务端和 GDB 可在“调试配置”的高级选项中指定。

手动修改的字段会被记住，再次检测或重启后保留。重新选择环境包时，会刷新对应工具路径，并保留当前 SDK 选择。自动检测和保存环境不会运行 CMake 构建或启动调试。

如果所选 Python 缺少 PyYAML，请使用同一个 Python 解释器安装：

python -m pip install PyYAML

选择示例与构建

可从侧栏搜索示例、按分类筛选、收藏常用工程，也可点击状态栏的示例名称快速选择。示例名称和路径保持原文；同名示例补充功能与模式，例如 SPI/DMA/master。长名称在状态栏中省略，悬停可查看完整路径。

切换开发板时，使用当前 SDK 的板卡能力检查规则重新筛选。明确不支持的示例默认隐藏；可勾选“显示不支持的示例”查看原因。检查失败或依赖未知的示例会保留并标记待验证。

侧栏中的选择：先暂存参数，点击“应用选择”“仅配置”或“配置并编译”后生效。
状态栏中的选择：选中后自动同步到 CMake Tools 并完成配置，随后可直接使用 CMake Tools 的构建按钮。
应用选择：只同步配置；仅配置：运行 CMake；配置并编译：配置后编译。

所有示例使用：

<SDK>/build/
<SDK>/build/output/<APP_NAME>.elf

APP_NAME 未指定时通常为 demo。切换示例、板卡或影响构建的配置时，旧的 SDK/build 会被清理后重新配置；相同配置继续增量编译。请将该目录仅用于可重新生成的构建产物。

调试接口与配置

状态栏提供“调试接口”和“调试配置”两个入口。未手动选择接口时，默认读取板卡 YAML 的 openocd-probe；用户手动选择后会保持该选择。接口菜单中的“使用板卡默认接口”可恢复自动跟随。

开启自动跟随板卡时，切换板卡会更新芯片、SoC/板卡脚本、SVD 和当前示例的 ELF/GDB 等路径。展开“高级与自定义配置”可调整速度、序列号、启动/附加方式、入口及自定义文件。

从状态栏选择接口，或在“调试配置”中新增自定义接口。
检查自动推导的目标参数和文件，按需保存高级配置。
打开 VS Code 的“运行和调试”，选择对应启动项，再按 F5 启动。

启动项按接口命名，例如 hpm_jlink_debug、hpm_cmsis_dap_debug、hpm_ft2232_debug、hpm_nds_aice_micro_debug。切换接口和保存配置本身不会启动调试或连接硬件。

插件只维护带自身标记的启动项；已有用户调试配置和注释保留。保存前备份原始 launch.json。

界面语言

新用户默认跟随 VS Code 界面语言：中文使用简体中文，其他语言使用 English。

只在侧栏顶部提供 EN/中切换入口，点击直接切换，对插件页面、状态栏和提示全局生效。手动选择会保留，重启后恢复。命令面板中的 HPM SDK: 选择界面语言 / Select Display Language 可以恢复“跟随 VS Code”。

也可以设置 hpmExplorer.language 为 auto、en 或 zh-cn。VS Code 原生命令及设置标题跟随 VS Code 语言；其他插件和构建工具的输出由对应工具控制。

本文档默认显示中文，点击顶部 English 可跳转到本页英文说明；文档语言和插件界面语言独立。

自定义 SDK、示例与板卡

设置	说明
`hpmExplorer.sdkPath`	指定所用 SDK，可与当前工作区目录不同
`hpmExplorer.sampleRoots`	示例扫描目录，默认 `samples` 和 `unit_test`，支持额外目录
`hpmExplorer.boardSearchPaths`	额外板卡根目录，结构为 `<根目录>/<板卡名>/<板卡名>.yaml`
`hpmExplorer.pythonPath`	SDK 板卡检查使用的 Python
`hpmExplorer.openocdPath`	调试使用的 OpenOCD 程序

扫描只收录直接调用 find_package(hpm-sdk ...) 的应用入口；没有 app.yaml 的示例也可发现。自定义板卡同名时优先于 SDK 内置板卡。

工作区配置与恢复

保存环境或应用选择时，插件会在工作区的 .vscode/settings.json 中写入所需 CMake/SDK 配置，原配置先备份。SDK 环境供 CMake 配置和构建共同继承，不修改系统环境变量。

CMake 设置备份：.vscode/hpm-explorer.settings-backup.json。
调试配置备份：.vscode/hpm-explorer.launch-backup.<时间>.<标识>.jsonc。
从“构建目录与工具”或命令面板执行“恢复接管前的 CMake 设置”，可恢复插件管理的设置项。

多个工作区文件夹时可选择 SDK 所在文件夹，工程设置写入所选文件夹；CMake Tools 的窗口级选项按工作区作用域管理。工作区必须受信任；虚拟工作区不受支持。当前主要验证环境为 Windows 桌面版 VS Code。

源码开发

源码仓库：RCSN/vscode-hpm-sdk-explorer。克隆后，用 VS Code 打开插件根目录；源码可独立放在 SDK 目录之外。

git clone https://github.com/RCSN/vscode-hpm-sdk-explorer.git
cd vscode-hpm-sdk-explorer

项目没有 npm 运行时依赖，无需先执行 npm install。使用 Node.js 18 或更新版本运行单元测试：

npm test

按 F5 启动扩展开发宿主，在提示框中填写本机的 HPM SDK 根目录，即可预览插件功能。开发宿主中同样需要前文列出的插件和 SDK 工具。

本地打包使用仓库中的脚本：

npm run package

当前打包脚本依赖 Windows PowerShell。普通用户从 Marketplace 安装即可，不需要执行这些开发命令。

问题反馈与许可

欢迎通过 GitHub Issues 反馈问题，或提交 Pull Request。反馈时请提供 VS Code/扩展/SDK 版本、开发板、工具链类型、复现步骤及相关输出。

本项目采用 MIT License，完整许可见源码根目录的 LICENSE。

English

简体中文 | English

HPM SDK Explorer is a VS Code extension for the HPMicro HPM SDK. Select examples, boards, memory modes and debug interfaces through a graphical interface instead of editing CMake and debug settings by hand.

Features

Search, favorite and switch SDK examples; hide examples explicitly unsupported by the selected board.
Select the example, board, HPM_BUILD_TYPE and Debug/Release from the status bar.
Detect SDK environment packages and configure GCC, ZCC or Andes toolchains and build tools.
Share one build directory under the selected SDK, with incremental builds for unchanged configurations.
Update device information, OpenOCD scripts, SVD, ELF and GDB paths from board metadata.
Use J-Link, CMSIS-DAP, FT2232, nds_aice_micro or custom debug interfaces.
Switch the entire extension between English and Simplified Chinese, following the VS Code display language by default.

Required extensions

Use VS Code 1.88 or later and install the extensions needed for your workflow:

Extension	Extension ID	Requirement	Purpose
CMake Tools	`ms-vscode.cmake-tools`	Required to configure and build	Runs CMake configuration, selects the build type and builds the project
Cortex-Debug	`marus25.cortex-debug`	Required to use the generated debug profiles	Provides the `cortex-debug` debug type and connects to GDB and probe servers
C/C++	`ms-vscode.cpptools`	Optional	Provides C/C++ code completion, navigation and editing features

These extensions are not installed automatically as a bundle. Search for their extension IDs in the Extensions view and install them. The environment and debug configuration pages also offer installation buttons when CMake Tools or Cortex-Debug is missing; you need to click those buttons.

Hardware debugging also requires a RISC-V GDB and an OpenOCD or J-Link server that support your target HPM device. Generated profiles use the cortex-debug type; use a debugger extension version compatible with your HPM SDK, board and debug tools.

Windows development environment

Windows users can obtain the development environment from HPMicro sdk_env. Download and extract a complete environment package from its Releases. It already includes the HPM SDK, a matching toolchain, and tools such as CMake, Ninja, Python and OpenOCD, so a separate SDK download is not needed.

Keep the extracted directory structure:

sdk_env*/
├── hpm_sdk/       ← Open this folder as the VS Code workspace
├── toolchains/
└── tools/

After installing the required extensions above, use File → Open Folder in VS Code and select hpm_sdk inside the environment package (containing boards, samples and cmake). The extension detects and selects tools from that package automatically, then saves the environment once all checks pass. You normally do not need to enter each path manually. If several candidates are found or a tool is missing, follow the environment page prompts to select or complete the required items.

Install and get started

Open the VS Code Extensions view (Ctrl+Shift+X), search for HPM SDK Explorer and install it.
Install the required extensions above. On Windows, download and extract the complete sdk_env package described above; on other platforms, prepare the SDK and tools for that platform.
Use File → Open Folder to open hpm_sdk inside the package as your workspace, trust it and select the HPM SDK Explorer activity bar icon.
Wait for automatic environment detection, selection and validation. Valid settings are saved automatically. Open HPM_SDK Environment only if multiple candidates or missing items need your attention.
Once the environment is ready, select a board, example, memory mode and Debug/Release, then click Configure and Build.

A Marketplace installation is ready to use without downloading the source or building an extension package. See Source development below if you want to work on the extension itself.

SDK environment

The extension itself does not bundle the SDK, compiler or build tools. On Windows, the complete sdk_env package above provides the SDK and matching tools, so you normally do not need to install each component separately. Detection first looks in toolchains and tools under one sdk_env* package, then checks existing settings, the build cache and PATH for missing tools.

Field	Value
`HPM_SDK_BASE`	SDK root containing `cmake/application.cmake`
`GNURISCV_TOOLCHAIN_PATH`	GCC, ZCC or Andes toolchain root, usually containing `bin`
`CMAKE`	CMake executable or its directory
`NINJA`	Ninja executable or its directory
`OPENOCD`	OpenOCD executable or its directory; required by the current environment validator
`PYTHON3`	Python 3 executable or its directory, with PyYAML installed
`HPM_SDK_TOOLCHAIN_VARIANT`	`gcc`, `zcc`, `nds-gcc` or `nds-llvm`

The toolchain type is detected from its compiler and must also be supported by the selected SDK. You can select the toolchain root, its bin directory or a compiler executable.

All seven fields must pass validation before saving; incomplete or invalid settings are not partially written. The current version requires the OpenOCD environment field even when using J-Link. Specify a J-Link server executable and GDB in the advanced debug settings when needed.

Fields you change manually are remembered across detection and restarts. Selecting another environment package refreshes its tool paths while keeping the selected SDK. Automatic environment detection and saving do not configure/build the project or start a debug session.

If PyYAML is missing, install it using the same Python interpreter selected in the environment page:

python -m pip install PyYAML

Examples and builds

Search examples, filter by category and save favorites in the sidebar, or click the current example in the status bar for quick selection. Example names and paths remain unchanged. Duplicate names include context such as SPI/DMA/master; long status labels are shortened, with the full path available on hover.

Changing the board applies the current SDK's board capability checks. Explicitly unsupported examples are hidden by default; enable Show Unsupported Examples to inspect the reason. Examples with unknown dependencies or failed checks remain visible as unchecked.

Sidebar selections are staged until you click Apply Selection, Configure Only or Configure and Build.
Status bar selections synchronize with CMake Tools and configure the project automatically; you can then use the native CMake Tools build button.
Apply Selection updates settings; Configure Only runs CMake; Configure and Build configures and builds.

All examples use:

<SDK>/build/
<SDK>/build/output/<APP_NAME>.elf

When APP_NAME is not specified, it is usually demo. Changing the example, board or a build-affecting setting cleans the old SDK/build directory before configuration. Unchanged configurations keep incremental build output. Use this directory only for reproducible build artifacts.

Debug interfaces and configuration

The status bar has two debug controls: Debug Interface and Debug Configuration. By default, the interface follows openocd-probe in the board YAML. A manual selection is remembered. Select Use the board default interface to restore automatic selection.

With automatic board following enabled, changing the board updates the device, SoC/board scripts, SVD and the current example's ELF/GDB paths. Expand Advanced and Custom Settings to edit speed, serial number, launch/attach behavior, entry point and custom files.

Select an interface in the status bar or add a custom interface in Debug Configuration.
Review the inferred target settings and files, and save any advanced changes.
Open VS Code Run and Debug, select the matching launch profile and press F5.

Profiles are named for the interface, for example hpm_jlink_debug, hpm_cmsis_dap_debug, hpm_ft2232_debug and hpm_nds_aice_micro_debug. Selecting an interface or saving its configuration does not start debugging or connect to hardware.

Only extension-owned launch profiles are managed. Existing user debug profiles and comments are preserved, and the original launch.json is backed up before saving.

Display language

New users follow the VS Code display language automatically: Chinese uses Simplified Chinese; other languages use English.

The EN/中 control appears only at the top of the sidebar. Click it to switch all extension pages, status items and messages. Your choice is remembered across restarts. Use HPM SDK: Select Display Language in the Command Palette to return to Follow VS Code.

You can also set hpmExplorer.language to auto, en or zh-cn. Native command and settings titles follow the VS Code display language. Other extensions and build tools control their own output language.

The main extension description opens in Chinese. Use its English link to jump to the English section. Documentation language is independent of the extension UI language.

Custom SDKs, examples and boards

Setting	Purpose
`hpmExplorer.sdkPath`	SDK to use; it may be outside the current workspace directory
`hpmExplorer.sampleRoots`	Example scan roots; defaults to `samples` and `unit_test` and supports additional directories
`hpmExplorer.boardSearchPaths`	Additional board roots containing `<root>/<board>/<board>.yaml`
`hpmExplorer.pythonPath`	Python used by SDK board checks
`hpmExplorer.openocdPath`	OpenOCD executable used for debugging

Only applications directly calling find_package(hpm-sdk ...) are included. Examples without app.yaml can also be discovered. Custom boards take precedence over SDK boards with the same name.

Workspace settings and restoration

Saving the environment or applying a selection writes the required CMake/SDK settings to the workspace's .vscode/settings.json, after backing up the original configuration. SDK environment variables are shared by CMake configuration and builds; system environment variables are not changed.

CMake settings backup: .vscode/hpm-explorer.settings-backup.json.
Debug configuration backup: .vscode/hpm-explorer.launch-backup.<time>.<id>.jsonc.
Use Restore Original CMake Settings under Build Directory and Tools or in the Command Palette to restore extension-managed settings.

In a multi-root workspace, select the SDK folder; project settings are scoped to that folder, while window-level CMake Tools options use workspace scope. Workspaces must be trusted. Virtual workspaces are not supported. Windows desktop VS Code is the primary validation environment.

Source development

Source repository: RCSN/vscode-hpm-sdk-explorer. Clone it and open the extension root in VS Code. The extension source may be kept outside the SDK.

git clone https://github.com/RCSN/vscode-hpm-sdk-explorer.git
cd vscode-hpm-sdk-explorer

There are no npm runtime dependencies, so npm install is not required before development. Run unit tests with Node.js 18 or later:

npm test

Press F5 to launch an Extension Development Host and enter your local HPM SDK root when prompted. The development host also needs the extensions and SDK tools listed above.

To create a local package using the repository script:

npm run package

The current packaging script requires Windows PowerShell. Marketplace users do not need to run these development commands.

Feedback and license

Report problems through GitHub Issues, or submit a pull request. Include your VS Code, extension and SDK versions, board, toolchain type, reproduction steps and relevant output when reporting a problem.

This project uses the MIT License. The complete license is in LICENSE at the source root.