HT32 Project Assistant for VS Code

A complete ARM embedded development environment for Holtek HT32 microcontrollers inside VS Code. 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

• OS: Windows x64 (bundled OpenOCD and GNU Make are Windows x64 binaries)
• Toolchain: arm-none-eabi-gcc — auto-detected from common install locations, or set manually in settings
• Debug probe: Holtek e-Link32 Pro or e-Link32 Lite (recommended); J-Link and ST-Link also supported
• FWLib: HT32 Firmware Library required for Create Project; not needed for Convert

Getting Started

Create a New Project

1. Open VS Code with an empty folder as workspace
2. Click the HT32 icon in the Activity Bar → Create Project (the + button)
3. Follow the wizard:
   • Select the HT32 FWLib root folder
   • Choose MCU model
   • Choose output type: Application or Library
   • (Application only) Choose printf: Standard newlib-nano or eyalroz/printf (float support)
   • Enter project name and folder
4. The extension generates src/, .vscode/build-gen/Makefile, tasks.json, launch.json, and clangd config

Convert a Keil uVision Project

1. Click Convert uVision Project in the HT32 panel
2. Select the .uvprojx or .uvmpw file
3. All Makefile, linker script, sources list, and VS Code config files are generated under .vscode/build-gen/

Convert an HT32-IDE Project

1. Click Convert HT32-IDE Project in the HT32 panel
2. Select the .project file (Eclipse CDT format)
3. Same output as uVision conversion

Build, Flash & Debug

Toolbar buttons (visible when a project is loaded)

Keyboard shortcuts

Use Ctrl+Shift+B to access VS Code tasks (Build, Build All, Clean, Download).

HT32 Settings

Open via the gear icon in the HT32 panel toolbar. Configurable per-project:

Settings are stored in .vscode/build-gen/project.settings.json and take effect after saving (auto-saves after 3 seconds, or manually via the Save button).

Printf Support (eyalroz/printf)

When creating a new Application project, you can opt in to bundle eyalroz/printf instead of relying on newlib-nano's printf:

• Why: newlib-nano's %f/%g float formatting requires -u _printf_float, which adds ~15–20 KB. eyalroz/printf includes full float support in ~5–8 KB.
• How it works: printf.c and printf.h are copied into src/. A small ht32_putchar.c bridges the output to the existing HT32 retarget layer (_write() → SERIAL_PutChar()). The compile flag -DPRINTF_ALIAS_STANDARD_FUNCTION_NAMES_HARD=1 makes printf(), sprintf(), snprintf() etc. resolve to the eyalroz implementation at link time — no source code changes needed.
• For existing (converted) projects, you can manually add printf.c, printf.h, and ht32_putchar.c to src/, add PRINTF_ALIAS_STANDARD_FUNCTION_NAMES_HARD=1 to Extra CFLAGS in Settings, and add printf.c and ht32_putchar.c to sources.list.

Supported Devices

141 HT32 devices across 6 series, including:

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

Output Structure

After conversion or project creation:

<workspace>/
├── src/                          ← User source files
│   ├── main.c
│   ├── ht32fxxxx_it.c
│   └── ...
└── .vscode/
    ├── tasks.json
    ├── launch.json
    ├── .clangd
    ├── compile_commands.json     ← Symlink / 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

Extension Settings

All project-specific settings (optimization, float ABI, debug interface, etc.) are stored in .vscode/build-gen/project.settings.json, not in VS Code workspace settings.

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

Third-Party Licenses

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

License

MIT — see LICENSE