This page explains the typical structure of an STM32 project, lists the involved components, and outlines the most common errors that may prevent the project from working correctly.

Main Parts of an STM32 Project

A typical STM32 project consists of the following parts:

1. The STM32 HAL library containing implementations  for functions like HAL_GPIO_WritePin().
2. HAL configuration file. It is typically located in the project directory and is called stm32xxxx_hal_conf.h.
3. Startup file (startup_stm32xxxxx.c) that defines the interrupt vector table.
4. Project-specific code, such as the main() function and other functions it calls.
5. Other libraries and frameworks (e.g. FatFS).

Many strange problems with STM32 projects are caused by combining incompatible versions of those components. E.g. trying to use a newer HAL library with an older hal_conf.h file could result in build errors because the new library would be expecting some macros that are not present in the old file.

Before you begin troubleshooting any STM32-specific errors, ensure you locate each of those components in Solution Explorer and understand where they are physically located:

You can find the physical location of each file via the Properties window in Solution Explorer:Alternatively, you can open the mouse in the VS editor and hover the mouse over its tab header to find out the full path:

Regular STM32 Projects

When you create a regular project with the VisualGDB Embedded Project Wizard, VisualGDB will automatically download a copy of the STM32 library files (including the HAL library) and will store them under %LOCALAPPDATA%\VisualGDB. Those files will appear inside the Device-Specific Files folder in Solution Explorer. You can use the VisualGDB Project Properties -> Embedded Frameworks to add or remove the VisualGDB-managed copy of the HAL library:When you reference the any framework via VisualGDB Project Properties -> Embedded Frameworks, it will do the following:

• Automatically add the necessary sources to Solution Explorer under the Device-Specific Files. WARNING: this will override any manually added files there.
• Automatically add the related include directories and preprocessor macros to the stm32.props (or stm32.mak) file. They will be stored separately from the regular VS project properties, so you won’t accidentally overwrite them.

When you open the project on a different machine, VisualGDB would automatically download the STM32 BSP (including the HAL library) under %LOCALAPPDATA%, so you won’t need to copy those files along with your project. You can find out the currently installed version of the STM32 BSP via Tools->VisualGDB->Manage VisualGDB Packages:VisualGDB Custom Edition or higher allows installing multiple versions of the same BSP and selecting the version for each project via VisualGDB Project Properties -> Embedded Project.

WARNING: Each time you change any target-related settings in VisualGDB Project Properties, the list of files under the Device-Specific files folder will be overwritten. If you would like to manually add new files from the VisualGDB’s BSP to the project, make sure you add them outside the Device-Specific Files folder. If you want to remove some of the files that were automatically added, use the “Excluded From Build” flag instead:Files excluded from build will remain in Solution Explorer, but will be skipped when building the project. VisualGDB will not overwrite this flag when updating the list of files in Solution Explorer. Note that the flag works independently for each configuration.

Cloned STM32CubeMX Samples

If you create the project by cloning one of the STM32CubeMX samples via the VisualGDB Project Wizard, it will not reference the STM32 frameworks via the Embedded Frameworks mechanism. Instead, it will directly include just the files from the original ST sample. They will be located in the Shared sources folder outside Device-specific files:This project type is recommended for quickly exploring the STM32 code samples, however it may require non-trivial changes when upgrading to the newer STM32 BSP, or when trying to reference further libraries via VisualGDB Project Properties -> Embedded Frameworks.

Imported STM32CubeMX Projects

Similarly to the cloned STM32CubeMX samples, the imported projects generated by the STM32CubeMX generator will not reference the regular HAL library. Instead, they will include their own copy of the HAL files and will reference them directly. The only VisualGDB-managed file will be the startup_stm32xxxx.c file containing the interrupt vector table:

Stand-Alone Projects

If you are using VisualGDB Custom Edition or higher, you can convert any regular STM32 project to a stand-alone one. Stand-alone projects include their own copy of all the necessary files in the <ProjectDirectory>\BSP folder, but are completely detached from the regular STM32 BSP and do not allow referencing any further frameworks:

Project Type Summary

The following table lists the common STM32 project types, along with their advantages and disadvantages:

Project Type	Recommended Use	STM32 HAL Location	Remarks
Regular	Long-term projects	%LOCALAPPDATA%\VisualGDB\<…>	Can be relatively easy upgraded to newer STM32 BSP versions.
Cloned STM32CubeMX Samples	Quickly Exploring STM32 Examples	%LOCALAPPDATA%\VisualGDB\<…>	Upgrading the STM32 BSP, or referencing new frameworks may require manual changes to the project.
Imported STM32CubeMX Projects	Long-term projects that require changes via STM32CubeMX.	Per STM32CubeMX Settings	Some Embedded Frameworks may conflict with STM32CubeMX-supplied versions.
Stand-alone projects	Projects that require patches to the STM32 libraries	<Project Directory>\BSP	Including a separate copy of the STM32 files with the project considerably increases its size.

Troubleshooting Project Problems

Most problems with STM32 projects come from using multiple copies of the STM32 HAL (e.g. referencing one via VisualGDB Project Properties -> Embedded Frameworks on top of the one included with the STM32CubeMX project), or by using incompatible versions of components (e.g. using an older configuration file with a newer HAL).

In order to troubleshoot the build problems, make sure you understand which copy of the HAL libraries the project is supposed to use. E.g. if it was generated by STM32CubeMX, ensure it doesn’t reference the VisualGDB-supplied HAL library, or any other libraries. Also creating a new project of the same type from scratch, and comparing it to the broken project may help locating the root cause of the problems.

If nothing helps, try clearing the Additional Include Directories setting:If you were using VisualGDB header discovery, you might have inadvertently added incompatible include directories to the project (e.g. directories from the VisualGDB-supplied STM32 HAL to a project managed by STM32CubeMX, or vice versa).

If you are new to C/C++ and find the error messages confusing, check out this tutorial. It lists the common error messages and ways to fix them.