中文使用手冊 | English

Holtek HT32 VS Code Extension

A VS Code extension for Holtek HT32 series Cortex-M microcontrollers (M0+/M3/M4). Converts Keil uVision and HT32-IDE projects to a Makefile workflow, or creates new projects from scratch — with one-click build, flash, and debug via the bundled OpenOCD and e-Link32 probe.

Features

Requirements

GCC toolchain: Auto-detected on startup; installed automatically via winget if not found, or set manually in settings.
OpenOCD: Bundled — no separate installation needed.
Extension dependencies: Cortex-Debug and Holtek HT32 Configuration Wizard are installed automatically.

Installation

Option A — From VSIX

1. VS Code → Extensions → ... → Install from VSIX...
2. Select ht32-vscode-x.x.x.vsix

Option B — From Marketplace

1. Search Holtek HT32 VS Code Extension in the Extensions view
2. Click Install

Interface Overview

After installation, the HT32 icon appears in the Activity Bar. Click it to open the HT32 panel.

When no project is open: shows Create / Open / Convert buttons, plus a Recent Projects list below for quick access.

Toolbar buttons (visible when a project is loaded):

Project File Tree (bottom of the HT32 panel) shows source groups — the same group concept as Keil uVision.

Right-click menu:

Getting Started

Create a New Project

Requires HT32 FWLib downloaded from the Holtek website.

1. Click the HT32 icon in the Activity Bar → Create Project (the + button)
2. Follow the wizard:

Generated File Structure

<workspace>/
├── .clangd
├── src/
│   ├── main.c
│   ├── ht32fxxxx_it.c
│   ├── system_ht32fxxxx.c
│   ├── ht32fxxxx_conf.h
│   └── ht32_op.c
└── .vscode/
    ├── tasks.json
    ├── launch.json
    ├── compile_commands.json
    └── build-gen/
        ├── Makefile
        ├── linker_script.ld
        ├── startup_ht32fxxxx_gcc_xx.s
        ├── ht32_syscalls.c
        ├── ht32_retarget_gnu.c
        └── *.json

49x series (HT32F490x / 491x / 493x): src/ includes board support files (ht32fXXXxX_board.c/h) instead of ht32_op.c.

Convert a Keil uVision Project

1. Click Convert uVision Project in the HT32 panel
2. Select the .uvprojx (single project) or .uvmpw (multi-project workspace) file

For .uvmpw, all sub-projects are converted at once, each into its own .vscode/build-gen-{project-name}/ directory.

Auto-generated:

• Makefile (MCU, compiler flags, source files)
• linker_script.ld (converted from Keil scatter file)
• startup_xxx_gcc.s (converted from Keil startup)
• compile_commands.json / tasks.json / launch.json

Single .uvprojx — output to .vscode/build-gen/

.uvmpw multi-project — one directory per sub-project, e.g. Project_IAP.uvprojx + Project_AP.uvprojx:

.vscode/
├── tasks.json
├── launch.json
├── build-gen-iap/
│   ├── Makefile
│   ├── linker_script.ld
│   └── *.json
└── build-gen-ap/
    ├── Makefile
    ├── linker_script.ld
    └── *.json

Conversion warnings (e.g. prebuilt .lib files that cannot be used with GCC) appear in the VS Code Problems panel.

Convert an HT32-IDE Project

1. Click Convert HT32-IDE Project in the HT32 panel
2. Select the project folder containing .project / .cproject (Eclipse CDT format)

If the folder contains multiple sub-projects, all are converted at once, each into its own build-gen-{suffix}/ directory. Conversion warnings appear in the VS Code Problems panel.

Build

• Click Build in the HT32 toolbar
• Or press Ctrl+Shift+B to access VS Code tasks (Build, Build All, Clean, Download)

A Post-Build command can be configured in Settings to run automatically after a successful build (e.g. CRC calculation).

Clean

• Click Clean in the HT32 toolbar
• Deletes all compiled output under .vscode/build-gen/build/

Flash Firmware

Requires Holtek e-Link32 Pro or e-Link32 Lite connected.

1. Confirm the e-Link32 is connected and the driver is working
2. Click Download in the HT32 toolbar
3. Firmware is flashed automatically; progress is shown in the Terminal

Flash Settings (configured in HT32 Settings)

Debug

Cortex-Debug is a dependency and is installed automatically.

Full Debug Flow

1. Click Debug in the HT32 toolbar
2. The extension compiles, flashes, and starts an OpenOCD + GDB debug session

Attach Mode (connect to an already-running target)

Use this when the target board is already running and you don't need to reflash.

1. Confirm the target board is powered and running
2. Press F5 or open Run and Debug (Ctrl+Shift+D)
3. Select HT32 OpenOCD Attach from the dropdown, then press ▶

Attach does not compile or flash — it connects directly via OpenOCD and halts the CPU.

HT32 Settings

Open via the Settings button in the HT32 toolbar. The panel has three tabs. Settings auto-save 3 seconds after any change and are stored in .vscode/build-gen/project.settings.json.

Compiler Tab

Debugger Tab

Build Tab

Toolchain paths are stored in VS Code User Settings and shared across all projects.

Configuration Wizard

The Holtek HT32 Configuration Wizard extension (installed automatically) provides a visual editor for HT32 firmware configuration files, compatible with Keil MDK Configuration Wizard syntax.

Supported files:

How to open:

• Editor title button (recommended): Open a supported .h / .c / .s file, then click the Preview button in the editor title bar. Click Go to File to switch back to text editing.
• Right-click menu: Right-click the file in Explorer → Open in Holtek HT32 Configuration Wizard
• Command Palette: Ctrl+Shift+P → HT32: Open in Holtek HT32 Configuration Wizard

Control types:

Changes are written back to the source file immediately; only the modified value is updated — all comments and surrounding code are preserved.

IntelliSense (clangd)

After conversion or project creation, the extension auto-generates:

• .clangd (workspace root) — include paths, compiler flags
• .vscode/compile_commands.json — merged for clangd

Recommended: install the clangd extension (llvm-vs-code-extensions.vscode-clangd) and disable the built-in C/C++ IntelliSense to avoid conflicts.

Output Structure

After conversion or project creation:

<workspace>/
├── .clangd                       ← clangd config (workspace root)
├── src/                          ← User source files
│   ├── main.c
│   ├── ht32fxxxx_it.c
│   └── ...
└── .vscode/
    ├── tasks.json
    ├── launch.json
    ├── compile_commands.json     ← Merged for clangd
    └── build-gen/
        ├── Makefile
        ├── linker_script.ld
        ├── startup_xxx.s
        ├── ht32_syscalls.c
        ├── ht32_retarget_gnu.c
        ├── compile_commands.json
        ├── sources.list
        ├── project.meta.json
        ├── project.settings.json
        └── build.meta.json

Commands (Ctrl+Shift+P → "HT32")

Supported Devices

141 HT32 devices across 6 series:

Flash/download support (via bundled OpenOCD + HLM loaders) is available for ~100 devices. Devices without an MCU cfg file can still be built and debugged with a custom OpenOCD configuration.

Bundled Assets

Third-Party Licenses

See THIRD_PARTY_LICENSES.md for license information for bundled components (OpenOCD, GNU Make, HT32 DFP, fast-xml-parser).

License

MIT — see LICENSE