CubeMX STM32 Adapter
Turn a CubeMX-generated STM32 project into one you can build, flash and debug
from VS Code — without giving up the ability to regenerate it in CubeMX.
The extension never edits the part of the Makefile that CubeMX owns. Every
change it makes lives in a separate cubemx-adapter.mk, pulled in by a single
-include line appended to the end of the file. Regenerate in CubeMX as often
as you like; if a regeneration drops that line, the extension notices and puts
it back, settings intact.
What it does
Parameterises the build. The toolchain directory, the OpenOCD binary, the
debug probe, the OpenOCD scripts and the flash address all become variables
you can override per invocation:
make TOOLCHAIN_PATH=/opt/gcc-arm/bin/ flashload
Adds flashing and debugging targets driven by OpenOCD: flashload,
flashbin, erase, reset and openocd-server.
Manages what gets compiled. Add or remove .c, .cpp and header files
from the Files tab. CubeMX-owned sources are excluded rather than deleted from
the CubeMX list, so regeneration keeps working. Headers contribute their
directory to the include path.
Compiles C++. Adding a .cpp file switches on the C++ rules, a
configurable -std=, and the C++ runtime in LDFLAGS.
Manages preprocessor defines from the Defines tab.
Writes the .vscode configuration — c_cpp_properties.json,
launch.json (Cortex Debug), tasks.json, settings.json and
extensions.json — from what it found in your project. Configurations you
wrote by hand, and the comments around them, are preserved.
Every operation backs up the files it touches and rolls all of them back if any
step fails. Before the hook is added for the first time, your original
Makefile is copied to Makefile.cubemx-adapter.bak.
Requirements
You need these on your machine; the extension does not install them.
| Tool |
Why |
arm-none-eabi-gcc toolchain |
Compiling and linking |
| GNU Make |
Running the build |
| OpenOCD |
Flashing and the GDB server |
| Cortex Debug |
Debugging with the generated launch.json |
They can be on PATH or pointed at through the settings below.
Getting started
- Open the folder containing your CubeMX project — the one with the
Makefile
and the .ioc beside it.
- Run CubeMX Adapter: Open Home from the Command Palette.
- On the Overview tab, set the toolchain and OpenOCD paths, pick your probe,
and press Adapt.
- Build with
make, flash with make flashload, debug with F5.
make adapter-info prints the configuration the generated makefile resolved to,
which is the fastest way to check a path or a probe setting.
Settings
| Setting |
Default |
Description |
cubemx-adapter.toolchainPath |
"" |
Directory holding the arm-none-eabi-* binaries, e.g. C:/gcc-arm/bin/. Empty resolves through PATH. |
cubemx-adapter.openOcdPath |
openocd |
Path to the OpenOCD executable. |
cubemx-adapter.programmer |
st-link |
Debug probe: st-link, stlink-dap, cmsis-dap or jlink. |
Commands
| Command |
Description |
CubeMX Adapter: Open Home |
Opens the home panel. |
CubeMX Adapter: Refresh Project State |
Re-analyses the workspace. |
What ends up in your project
your-project/
├── Makefile # CubeMX's, plus a 3-line -include at the end
├── Makefile.cubemx-adapter.bak # your original, kept from the first adapt
├── cubemx-adapter.mk # everything the extension manages
└── .vscode/ # IntelliSense, debugging and build tasks
cubemx-adapter.mk is regenerated on every change, so edit it through the
extension rather than by hand. It is readable on purpose — each section explains
what it does and why — so you can check exactly what was added to your build.
Notes and limits
- The file list shows files that exist on disk. Delete one outside the extension
and the next refresh drops it from the build automatically; an entry that
CubeMX still lists keeps its exclusion, because removing it would put a
missing file straight back into the link.
- A project whose
Makefile carries no CubeMX markers is still adapted, but the
extension says so — verify the build before flashing.
License
MIT — see the LICENSE file shipped with the extension.
