vscode cmake project template for xl32f001 mcu.
  • C 99.5%
  • Assembly 0.2%
  • CMake 0.2%
  • Linker Script 0.1%
Find a file Use this template
ithilelda e62e35f27c Move the HAL config header notes from CONVERT to README
The configuration header is project setup, not conversion history: it is
where the HAL module switches and clock constants live, and how every
driver reaches them. README is the setup guide; CONVERT keeps the
conversion and hardware-check notes.
2026-10-25 14:32:02 +08:00
.vscode init template by muse. 2026-10-25 11:32:05 +08:00
cmake init template by muse. 2026-10-25 11:32:05 +08:00
Drivers init template by muse. 2026-10-25 11:32:05 +08:00
inc Clean up includes and quiet the IncludeCleaner false positives 2026-10-25 14:26:19 +08:00
linker init template by muse. 2026-10-25 11:32:05 +08:00
src Clean up includes and quiet the IncludeCleaner false positives 2026-10-25 14:26:19 +08:00
startup Restructure template around src/inc and split up the docs 2026-10-25 13:06:57 +08:00
.clangd Clean up includes and quiet the IncludeCleaner false positives 2026-10-25 14:26:19 +08:00
.gitignore Restructure template around src/inc and split up the docs 2026-10-25 13:06:57 +08:00
CMakeLists.txt Restructure template around src/inc and split up the docs 2026-10-25 13:06:57 +08:00
CMakePresets.json init template by muse. 2026-10-25 11:32:05 +08:00
CONVERT.md Move the HAL config header notes from CONVERT to README 2026-10-25 14:32:02 +08:00
README.md Move the HAL config header notes from CONVERT to README 2026-10-25 14:32:02 +08:00

XL32F001 — minimum VS Code + CMake template

A minimal, free-toolchain starting point for XL32F001 firmware (Cortex-M0+, 24 MHz, 24 KiB Flash / 3 KiB RAM), built with VS Code + CMake + Ninja + arm-none-eabi-gcc + OpenOCD + Cortex-Debug. No Keil, no PlatformIO, no STM32CubeIDE.

The template is deliberately small: it builds one working bring-up image that initialises the HAL, sets the clock, initialises the LED pin and USART1, prints hello at 115200 baud on USART1 TX (PB4), then sits in an empty loop. That hello is the first hardware test: if it arrives, the clock, USART pins, baud calculation, startup file and linker script are all basically right.

What this template aims to be:

  • Free tools only. Every part of the build and debug path is open source.
  • Minimal, but honest. One working bring-up, not a HAL rewrite. The vendor code is carried over unchanged so you can see what the chip actually does.
  • Vendor code stays vendor code. Drivers/ is the PY32F002B CMSIS and HAL exactly as it came from the original project; the template does not patch it.
  • One convention for your code. Every user .c file lives in src/ and every user .h file lives in inc/. Vendor headers are the only exception.
  • Plain CMake. No generated build system and no hidden magic: the source list, flags and linker script are all readable in CMakeLists.txt.
  • Known limits are written down. The build is verified, but the chip behaviour is inherited from PY32F002B and has not been validated on XL32F001 hardware here. The exact assumptions to check are in CONVERT.md.

Requirements

  • arm-none-eabi-gcc (for example Ubuntu: sudo apt install gcc-arm-none-eabi)
  • CMake 3.22 or newer, and Ninja
  • OpenOCD and an SWD probe (ST-Link, DAPLink, or J-Link) for flashing
  • VS Code extensions: CMake Tools, clangd, Cortex-Debug (VS Code suggests them from .vscode/extensions.json)

Build and flash

From VS Code

  1. Open this folder in VS Code.
  2. CMake Tools asks for a kit/preset: pick the debug preset.
  3. Build with the CMake Tools build button, or the task CMake: configure + build.
  4. Flash with the task Flash: OpenOCD + ST-Link (try stm32f0x target first). Before the first flash, run Flash: OpenOCD, probe only (check the chip answers before flashing) first.
  5. Open a serial terminal at 115200 baud, 8N1, on USART1 TX (PB4). You should see: hello

From a terminal

cmake --preset debug
cmake --build --preset debug

To flash:

openocd -f interface/stlink.cfg -f target/stm32f0x.cfg \
  -c "program build/xl32f001.elf verify reset exit"

To only check that the probe and target answer:

openocd -f interface/stlink.cfg -f target/stm32f0x.cfg \
  -c "init; halt; flash probe 0; exit"

Build outputs

Everything lands in build/:

  • xl32f001.elf — the debug/flash image
  • xl32f001.bin, xl32f001.hex — generated next to the .elf
  • xl32f001.map — linker map
  • compile_commands.json — used by clangd for IntelliSense

build/ is gitignored; it is safe to delete and rebuild.

Project layout

src/        all user C sources (main, user modules, PY32 project files)
inc/        all user headers, plus py32f002b_hal_conf.h (HAL config)
Drivers/    vendor CMSIS + PY32F002B HAL, verbatim — do not edit
startup/    GCC startup file and vector table
linker/     xl32f001_flash.ld (24 KiB Flash / 3 KiB RAM)
cmake/      arm-none-eabi toolchain file
.vscode/    build/flash tasks, Cortex-Debug launch, clangd settings
CMakeLists.txt, CMakePresets.json

The rule for adding code is simply:

  • a new .c file goes in src/ and is added to the add_executable list in CMakeLists.txt;
  • a new .h file goes in inc/, which is already on the include path.

The HAL configuration header

inc/py32f002b_hal_conf.h is not application code. It is the HAL's configuration header (the PY32F002B equivalent of ST's stm32f0xx_hal_conf.h), and it must keep that exact name and stay on the include path; inc/ is already there.

Every HAL driver reaches it through the umbrella header, and py32f0xx.h includes that umbrella because USE_HAL_DRIVER is defined in CMakeLists.txt:

py32f0xx_hal.h -> py32f002b_hal_conf.h -> the enabled py32f002b_hal_*.h

The HAL_<X>_MODULE_ENABLED switches near the top choose which peripheral drivers are pulled in. The rest of the file holds the clock constants (HSE_VALUE, HSI_VALUE, ...) and USE_FULL_ASSERT.

To disable a module, comment out its switch and remove its driver .c from CMakeLists.txt: the driver gets its types from the umbrella and will not compile once its header is no longer included.

The #include "py32f002b_hal_*.h" lines at the bottom are module selection, not direct dependencies of this file. Because they are side-effect includes, clangd's unused-include check is disabled for this file in .clangd; deleting them, as its warning suggests, would break the HAL.

Tooling notes

  • IntelliSense comes from clangd, reading build/compile_commands.json. The Microsoft C/C++ extension's IntelliSense is disabled in .vscode/settings.json, because the two engines fight over the same files. Keep it disabled.
  • The CMake preset is called debug and uses Ninja plus cmake/arm-none-eabi.cmake. To configure by hand, pass -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi.cmake.
  • The build uses -Og -g3 -Wall -Wextra with -ffunction-sections -fdata-sections and --gc-sections, so unused HAL functions are dropped at link time.
  • .bin and .hex are produced by a post-build step, so they always match the .elf.

Troubleshooting

  • Build fails with "arm-none-eabi-gcc not found": install the toolchain and make sure it is on PATH before opening VS Code, or CMake Tools will cache a host compiler.
  • Linker error "section will not fit": your code outgrew 24 KiB Flash / 3 KiB RAM, or your chip is smaller than the linker script assumes. Check the memory-size item under CHECK in CONVERT.md before editing the script.
  • Warnings about _close, _fstat, _isatty, _lseek, _read not implemented: expected. They come from nosys.specs and only matter if you use file I/O beyond printf (which uses _write(), implemented in src/User_USART1.c). The vendor HAL also emits a few unused-parameter warnings; they are in the original code and are harmless.
  • Build succeeds, but the board stays silent or prints garbage: that is a hardware assumption, not a build problem. See the bring-up section of CONVERT.md.

Background and hardware caveats

The template was converted from a Keil project that targeted a PY32F002B-class part; no XL32F001 datasheet was available. The build is verified, but the chip's trim addresses, pinout, clock tree, register map, flash algorithm and option bytes are still assumptions.

CONVERT.md records:

  • what the original project did and what was removed (the 433 receiver);
  • how to restore the 433 receiver later;
  • the original pin map and clock setup;
  • where every file came from, and what was translated rather than copied;
  • the CHECK list — every XL32F001 assumption you should verify against your datasheet and board;
  • hardware bring-up troubleshooting;
  • the build verification snapshot.