Develop STM32 Projects with Visual Studio Code: Introduction

Okay, here’s a lengthy article (approximately 5000 words) detailing the introduction to developing STM32 projects with Visual Studio Code. This is a comprehensive guide, covering installation, configuration, and basic project setup.

Develop STM32 Projects with Visual Studio Code: Introduction

This comprehensive guide will walk you through the process of setting up Visual Studio Code (VS Code) as a powerful and versatile Integrated Development Environment (IDE) for STM32 microcontroller development. While traditional IDEs like Keil µVision and IAR Embedded Workbench have long been the standard, VS Code offers a modern, customizable, and cross-platform alternative that can significantly enhance your workflow. This introduction will focus on the fundamental steps required to get started, laying the groundwork for more advanced topics in subsequent parts.

Why Choose Visual Studio Code for STM32 Development?

Before diving into the technical details, it’s crucial to understand the advantages of using VS Code for STM32 projects:

Free and Open-Source: VS Code is completely free and open-source, eliminating the licensing costs associated with commercial IDEs. This makes it accessible to hobbyists, students, and professionals alike.
Cross-Platform Compatibility: VS Code runs seamlessly on Windows, macOS, and Linux, allowing you to work on your projects regardless of your operating system. This contrasts with some traditional IDEs that are often platform-specific.
Lightweight and Fast: Compared to some heavier IDEs, VS Code is known for its speed and responsiveness. It consumes fewer system resources, leading to a smoother development experience.
Extensible Architecture: VS Code’s power lies in its extension ecosystem. A vast library of extensions allows you to customize the IDE to your specific needs, adding support for various programming languages, debuggers, and tools.
Integrated Terminal: VS Code features a built-in terminal, providing easy access to command-line tools without leaving the editor. This is particularly useful for interacting with build systems and version control.
Powerful Editing Features: VS Code offers advanced code editing features like IntelliSense (code completion), syntax highlighting, code navigation, refactoring, and debugging capabilities, all contributing to a more efficient coding process.
Git Integration: VS Code has excellent built-in Git integration, making version control seamless and intuitive.
Large and Active Community: A vibrant community surrounds VS Code, providing ample support, tutorials, and extensions. You can readily find solutions to common problems and discover new tools.

Prerequisites

Before we begin the setup process, ensure you have the following prerequisites:

STM32 Microcontroller and Development Board: You’ll need a physical STM32 microcontroller and a corresponding development board (e.g., Nucleo, Discovery). This guide doesn’t focus on specific hardware, but the principles apply generally.
Basic Familiarity with C/C++: STM32 development primarily uses C or C++. A basic understanding of these languages is essential.
Understanding of Embedded Systems Concepts: Familiarity with embedded systems concepts like microcontrollers, peripherals, and memory organization will be beneficial.
Administrative Privileges (for some installations): Installing some tools may require administrative privileges on your operating system.

Step-by-Step Setup Guide

This section provides a detailed, step-by-step guide to setting up your VS Code environment for STM32 development.

1. Install Visual Studio Code

Download: Download the latest version of Visual Studio Code from the official website: https://code.visualstudio.com/
Installation: Follow the installation instructions for your operating system. The process is typically straightforward.
Launch: Once installed, launch VS Code.

2. Install Essential Extensions

VS Code’s functionality is extended through extensions. We’ll install several crucial extensions for STM32 development:

C/C++ (by Microsoft): Provides core language support for C and C++, including IntelliSense, debugging, and code formatting.
- Open VS Code.
- Click on the Extensions icon in the Activity Bar (the square icon on the far left).
- Search for “C/C++” in the Extensions Marketplace.
- Select the extension published by Microsoft and click “Install”.
Cortex-Debug (by marus25): Enables debugging of ARM Cortex-M microcontrollers using various debug probes (ST-Link, J-Link, etc.).
- In the Extensions Marketplace, search for “Cortex-Debug”.
- Select the extension and click “Install”.
ARM (by ARM): This provides assembly language support, definitions for ARM peripherals, and useful snippets.
- In the Extensions Marketplace, search for “ARM.”
- Select the extension and click “Install.”
(Optional) STM32-for-VSCode (by STM32 for VSCode Team): This extension is designed to integrate STM32CubeMX, STM32CubeProgrammer and the STM32CubeIDE project importer into VS Code. It’s an all in one solution that helps with project generation, building, and debugging. While optional, and potentially overlapping with other steps in this guide, it can streamline the workflow, especially for beginners. If you choose to use this, some of the later steps regarding manual configuration might be handled automatically by this extension.
- Search for “STM32-for-VSCode” in the Extensions Marketplace.
- Install the extension.

3. Install the ARM Toolchain

The ARM toolchain is a collection of tools necessary for compiling C/C++ code into executable files that can run on your STM32 microcontroller. We’ll use the GNU Arm Embedded Toolchain.

Download: Download the appropriate version of the GNU Arm Embedded Toolchain for your operating system from the Arm Developer website: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads
- Windows: Download the installer (.exe).
- macOS: Download the compressed archive (.tar.xz).
- Linux: Download the compressed archive (.tar.xz).
Installation:
- Windows: Run the installer and follow the on-screen instructions. Crucially, during installation, make sure to check the box that says “Add path to environment variable” (or similar wording). This ensures that the toolchain is accessible from the command line.
- macOS/Linux: Extract the downloaded archive to a suitable location (e.g., /opt/gcc-arm or ~/gcc-arm). Then, you need to add the bin directory of the extracted toolchain to your system’s PATH environment variable. This allows you to run the toolchain commands from any terminal. The exact method depends on your shell (bash, zsh, etc.).
  - Bash:
    1. Open your ~/.bashrc or ~/.bash_profile file in a text editor.
    2. Add the following line (adjust the path to your actual installation directory):
      bash export PATH="$PATH:/path/to/your/gcc-arm/bin"
    3. Save the file and either restart your terminal or run source ~/.bashrc (or source ~/.bash_profile) to apply the changes.
  - Zsh:
    1. Open your ~/.zshrc file in a text editor.
    2. Add the following line (adjust the path to your actual installation directory):
      zsh export PATH="$PATH:/path/to/your/gcc-arm/bin"
    3. Save the file and either restart your terminal or run source ~/.zshrc to apply the changes.
Verification: Open a new terminal (or command prompt on Windows) and type:
bash arm-none-eabi-gcc --version
You should see the version information of the installed GCC compiler. If you get a “command not found” error, the PATH environment variable is not set correctly. Double-check the installation steps and ensure the path is correct.

4. Install a Debugger (OpenOCD or ST-Util)

To debug your STM32 code, you’ll need a debugger. We’ll cover two common options: OpenOCD and ST-Util.

OpenOCD (Recommended): OpenOCD (Open On-Chip Debugger) is a versatile, open-source debugger that supports a wide range of debug probes and target microcontrollers.
- Windows:
  1. Download the latest Windows binaries from a reputable source like https://gnutoolchains.com/arm-eabi/openocd/ or build from source. Extract the downloaded archive.
  2. Add the bin directory of the extracted OpenOCD to your system’s PATH environment variable (similar to the ARM toolchain).
- macOS:
  1. Install OpenOCD using Homebrew (if you have it installed):
    bash brew install openocd
  2. Alternatively, download and build from source.
- Linux:
  1. Install OpenOCD using your distribution’s package manager (e.g., apt, yum, pacman). For example, on Debian/Ubuntu:
    bash sudo apt-get update sudo apt-get install openocd
  2. Alternatively, download and build from source.
- Verification: Open a terminal and type:
  bash openocd --version
  You should see the OpenOCD version information.
ST-Util (Windows Only – Alternative): ST-Util is a command-line utility provided by STMicroelectronics for interacting with ST-Link debug probes. It’s a simpler option but less flexible than OpenOCD.
- Download: ST-Util is typically included with the ST-Link driver package. Download and install the ST-Link driver from the STMicroelectronics website: https://www.st.com/en/development-tools/st-link-v2.html (look for the driver download).
- Location: ST-Util is usually installed in a directory like C:\Program Files (x86)\STMicroelectronics\st-utilities\st-link_cli. You may need to add this directory to your PATH environment variable.
- Verification: Open a Command Prompt and run:
  ST-LINK_CLI.exe -List
  If your ST-Link is connected, you should see it listed.

5. Install Make (Build System)

Make is a build automation tool that uses a Makefile to manage the compilation and linking process. It’s essential for building larger projects efficiently.

Windows:
- The easiest way to get make on Windows is to install it as part of a larger package like MSYS2 or MinGW. MSYS2 is generally recommended.
- MSYS2:
  1. Download and install MSYS2 from https://www.msys2.org/.
  2. Follow the installation instructions on the MSYS2 website.
  3. Open the MSYS2 MinGW 64-bit terminal (or 32-bit if you’re using a 32-bit system).
  4. Update the package database and install make:
    bash pacman -Syu pacman -S make
  5. Add the MSYS2 bin directory to the PATH. This is often done automatically, but you might need to add C:\msys64\usr\bin (or the corresponding directory if you installed it elsewhere) to your system environment variables.
macOS:
- make is usually included with Xcode Command Line Tools. If you don’t have them installed, open a terminal and type:
  bash xcode-select --install
Linux:
- make is almost always available by default. If not, install it using your distribution’s package manager. For example, on Debian/Ubuntu:
  bash sudo apt-get install make
Verification: Open a terminal and type:
bash make --version
You should see the version information for GNU Make.

6. (Optional, but Recommended) Install STM32CubeMX

STM32CubeMX is a graphical configuration tool provided by STMicroelectronics. It simplifies the process of configuring peripherals, clock settings, and generating initialization code for your STM32 microcontroller. While you can write all the initialization code manually, STM32CubeMX significantly speeds up development and reduces errors.

Download: Download STM32CubeMX from the STMicroelectronics website: https://www.st.com/en/development-tools/stm32cubemx.html
Installation: Follow the installation instructions for your operating system.
Launch: Run STM32CubeMX.

7. (Optional) Install STM32CubeProgrammer

STM32CubeProgrammer is a tool provided by ST for flashing (programming) your compiled code onto the STM32 microcontroller. It can also be used for reading memory, erasing the flash, and other operations. While OpenOCD can handle flashing, STM32CubeProgrammer is the official tool and sometimes offers more specialized features.

Download: Download STM32CubeProgrammer from: https://www.st.com/en/development-tools/stm32cubeprog.html
Installation: Follow the instructions for your operating system.
Usage: STM32CubeProgrammer can be used from its GUI or from the command line. We’ll be using the command line through VS Code’s integrated terminal for a seamless workflow.

Creating a Simple STM32 Project (Example using STM32CubeMX and Makefile)

Now that we have the environment set up, let’s create a simple “blinky” project to test our configuration. This example will use STM32CubeMX to generate the initialization code and a Makefile to manage the build process.

1. Project Generation with STM32CubeMX

Launch STM32CubeMX.
Create a New Project: Click on “Access to MCU Selector” or “Start My Project from ST board”.
Select your MCU or Board: Select the exact STM32 microcontroller or development board you are using.
Configure Peripherals:
- In the “Pinout & Configuration” tab, locate the LED pin on your board (consult your board’s documentation). This is usually a GPIO pin.
- Configure the LED pin as a “GPIO_Output”.
- Configure the System Clock (RCC): Go to the “Clock Configuration” tab and set up the clock frequencies according to your board’s requirements. For a simple blinky, you can often use the default settings.
Project Settings:
* Go to the “Project Manager” tab.
* Project Name and Location: Choose a name for your project and a location to save it.
* Toolchain / IDE: Select “Makefile” as the Toolchain/IDE. This is crucial!
* Code Generator: Under the “Code Generator” tab, in the “Generated files” section make sure that the option “Copy all used libraries into the project folder” is selected.
Generate Code: Click on “Generate Code” (the gear icon). STM32CubeMX will generate the initialization code and project files in the specified location.

2. Project Structure

After generating the code, your project directory will have a structure similar to this:

my_blinky_project/ ├── Core/ │ ├── Inc/ │ │ ├── main.h │ │ └── ... │ ├── Src/ │ │ ├── main.c │ │ ├── stm32xxxx_it.c (Interrupt handlers) │ │ └── ... │ └── Startup/ │ └── startup_stm32xxxx.s (Assembly startup file) ├── Drivers/ │ ├── CMSIS/ │ └── STM32xxxx_HAL_Driver/ ├── Makefile └── ... (Other files generated by CubeMX)

Core/Inc: Contains header files, including main.h, which holds your project-specific definitions.
Core/Src: Contains the source files, including main.c (your main program) and interrupt handlers.
Core/Startup: Contains the assembly startup file, which initializes the microcontroller before calling your main function.
Drivers/CMSIS: Contains the Cortex Microcontroller Software Interface Standard (CMSIS) files, providing standard definitions and functions for ARM Cortex-M processors.
Drivers/STM32xxxx_HAL_Driver: Contains the STM32 Hardware Abstraction Layer (HAL) drivers, providing a high-level API for interacting with peripherals.
Makefile: The build script that controls the compilation and linking process.

3. Modify main.c

Open the Core/Src/main.c file in VS Code. You’ll find the generated initialization code. Add the following code inside the while (1) loop in the main function:

“`c
/ USER CODE BEGIN WHILE /
while (1)
{
/ USER CODE END WHILE /

/* USER CODE BEGIN 3 */
    HAL_GPIO_TogglePin(GPIOB, GPIO_PIN_7); // Replace GPIOB and GPIO_PIN_7 with your LED's port and pin
    HAL_Delay(500); // Delay for 500 milliseconds

}
/ USER CODE END 3 /
“`

Important: Replace GPIOB and GPIO_PIN_7 with the actual GPIO port and pin number connected to your LED. You can find this information in your board’s documentation or in the STM32CubeMX Pinout view.

4. Understanding the Makefile

The generated Makefile contains instructions for building the project. It defines variables, compiler flags, linker settings, and dependencies. You might need to adjust some settings depending on your specific microcontroller and toolchain. Let’s look at some key parts:

Compiler and Linker: The Makefile specifies the compiler (arm-none-eabi-gcc) and linker (arm-none-eabi-ld) to be used.
Include Paths: It defines the include paths (-I) for the compiler to find header files (e.g., Core/Inc, Drivers/CMSIS/Include).
Source Files: It lists the source files (.c, .s) to be compiled.
Compiler Flags: It sets compiler flags (-mcpu, -mthumb, -O, etc.) to control optimization, target architecture, and other compilation options.
Linker Flags: It sets linker flags to specify the linker script (-T), memory layout, and other linking options.
Build Targets: It defines targets like all (to build the project), clean (to remove compiled files), and flash (to program the microcontroller).

5. Build the Project in VS Code
1. Open the Project Folder: In VS Code, go to “File” -> “Open Folder…” and select your project directory (my_blinky_project).
2. Open the Integrated Terminal: Press Ctrl+ (backtick) or go to “View” -> “Terminal” to open the integrated terminal.
3. Build: In the terminal, type make and press Enter. This will execute the Makefile and build your project.
4. Check for Errors: If there are any compilation errors, they will be displayed in the terminal. Carefully review the error messages and fix any issues in your code.
5. If the build is successful, a .elf file (the executable), a .hex file (Intel HEX format), and a .bin file (raw binary) will be generated in the build/ subdirectory (this directory may need to be created if the Makefile doesn’t do so automatically).

6. Flash the Code to the Microcontroller
There are several ways to program the compiled code onto the STM32 microcontroller. Here are two approaches, using OpenOCD and STM32CubeProgrammer.

Using OpenOCD (Recommended):
1. Create a .cfg file for OpenOCD: Create a new file in your project directory named openocd.cfg (or a similar name). This file contains configuration commands for OpenOCD. Add the following lines, adjusting them for your specific board and debug probe:
  source [find interface/stlink.cfg] transport select hla_swd source [find target/stm32f4x.cfg] #Change to the correct file for your microcontroller reset_config srst_only
  - interface/stlink.cfg: This line specifies the interface configuration file for the ST-Link debugger. OpenOCD includes configuration files for many common debug probes. If you are using a different probe (e.g., J-Link), you’ll need to use the appropriate configuration file (e.g., interface/jlink.cfg).
  - target/stm32f4x.cfg: This line specifies the target configuration file for your STM32 microcontroller. Change stm32f4x.cfg to the correct file for your specific microcontroller. OpenOCD includes configuration files for various STM32 families (e.g., stm32f1x.cfg, stm32l4x.cfg). You can usually find these files in the OpenOCD installation directory (e.g., share/openocd/scripts/target).
2. Flash the Code: In the VS Code terminal, run the following command:
  bash openocd -f openocd.cfg -c "program build/your_project_name.elf verify reset exit"
  - -f openocd.cfg: Specifies the configuration file you created.
  - -c "...": Executes a series of OpenOCD commands:
    - program build/your_project_name.elf: Programs the .elf file (replace your_project_name with the actual name of your project’s .elf file) to the microcontroller’s flash memory.
    - verify: Verifies that the programming was successful by comparing the flashed data with the .elf file.
    - reset: Resets the microcontroller to start running the newly programmed code.
    - exit: Exits OpenOCD.
3. Observation: After flashing, your LED should start blinking.
Using STM32CubeProgrammer (Alternative):
1. Command Line: In the VS Code terminal, navigate to your project directory and run a command similar to the following:
  bash "C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin\STM32_Programmer_CLI.exe" -c port=SWD -w build/your_project_name.hex 0x08000000 -rst
  - "C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin\STM32_Programmer_CLI.exe": This is the path to the STM32CubeProgrammer command-line interface. Adjust this path if you installed STM32CubeProgrammer in a different location.
  - -c port=SWD: Specifies the connection interface (SWD).
  - -w build/your_project_name.hex 0x08000000: Writes (-w) the .hex file (replace your_project_name with your project’s .hex file) to the flash memory starting at address 0x08000000. This is the typical starting address for STM32 flash memory.
  - -rst: Resets the microcontroller after programming.

7. Debugging with Cortex-Debug
1. Create a launch.json file: In VS Code, go to the “Run and Debug” view (click the bug icon on the Activity Bar).
2. Create Configuration: Click on “create a launch.json file”. Select “Cortex-Debug” from the list of debuggers. This will create a .vscode folder in your project directory containing a launch.json file.
3. Configure launch.json: Modify the launch.json file to match your setup. Here’s an example configuration for using OpenOCD:

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Cortex Debug (OpenOCD)",
            "type": "cortex-debug",
            "request": "launch",
            "servertype": "openocd",
            "configFiles": [
                "openocd.cfg" // Your OpenOCD configuration file
            ],
            "executable": "build/your_project_name.elf", // Path to your ELF file
            "svdFile": "${workspaceFolder}/path/to/your/device.svd", // Optional: Path to SVD file
            "preLaunchTask": "build" // Optional: Run 'make' before debugging
        }
    ]
}
```

*   `"name"`: A descriptive name for your debug configuration.
*   `"type"`:  Specifies the debugger type ("cortex-debug").
*   `"request"`: Set to "launch" to start a new debugging session.
*   `"servertype"`:  Specifies the debug server ("openocd").
*   `"configFiles"`:  An array of OpenOCD configuration files.  This should include the `openocd.cfg` file you created earlier.
*   `"executable"`: The path to your project's `.elf` file.
*   `"svdFile"`:  (Optional) The path to an SVD (System View Description) file for your microcontroller.  SVD files provide detailed information about the microcontroller's peripherals, allowing you to view register values during debugging.  You can often find SVD files from your microcontroller vendor or in the CMSIS packs.
* `"preLaunchTask": "build"`: This is an optional task which will run before debugging starts. We will create the `build` task next.
4.  **Create a `tasks.json` file (for preLaunchTask)** Create a `tasks.json` file in the `.vscode` directory. This is used for defining tasks.

```json
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "type": "shell",
            "command": "make",
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": [
                "$gcc" // Use the GCC problem matcher
            ]
        }
    ]
}

```
    *   `label`: "build" is the label matching what is called from the `launch.json` file.
    *   `type`: "shell" means we'll run this in the shell.
    *   `command`: "make" will run `make` in the terminal.
    *   `group`: Marks this task as part of the "build" group.
    *   `problemMatcher`: "$gcc" will parse the output of the `make` command and highlight any errors or warnings in the VSCode editor.

5. **Start Debugging:**

    *   Set breakpoints in your code by clicking in the gutter next to the line numbers.
    *   Press `F5` or click the green "Start Debugging" button in the "Run and Debug" view.
    *   VS Code will build the project (if you included the "preLaunchTask"), flash the code (using OpenOCD), and start the debugging session.
    *   You can now step through your code, inspect variables, view registers (if you have an SVD file), and use other debugging features provided by Cortex-Debug.

Troubleshooting

“arm-none-eabi-gcc: command not found”: The ARM toolchain is not installed correctly or not added to your PATH.
“openocd: command not found”: OpenOCD is not installed correctly or not added to your PATH.
“make: command not found”: make is not installed or not in your PATH.
OpenOCD connection errors: Check your wiring, ensure your debug probe is connected correctly, and verify the OpenOCD configuration file (openocd.cfg). Make sure you have the correct interface and target configuration files.
STM32CubeProgrammer errors: Ensure STM32CubeProgrammer is installed correctly and that the path to STM32_Programmer_CLI.exe is correct. Check your connection settings (port, interface).
Cortex-Debug issues: Verify your launch.json configuration, ensure you have the correct server type, executable path, and configuration files.

Conclusion

This comprehensive introduction has covered the essential steps for setting up Visual Studio Code for STM32 development. You’ve learned how to install the necessary tools, configure extensions, create a basic project, build, flash, and debug your code. VS Code provides a powerful and flexible environment that can greatly enhance your STM32 development workflow. This guide serves as a solid foundation for exploring more advanced topics, such as using more complex peripherals, implementing RTOS (Real-Time Operating System) features, and optimizing your code. Remember to consult the documentation for VS Code, the extensions, the ARM toolchain, OpenOCD, STM32CubeMX, and your specific STM32 microcontroller and development board for further details and troubleshooting.

Leave a Comment Cancel Reply