STM32CubeIDE for Visual Studio Code Documentation

Table Of Contents

- STM32CubeIDE for Visual Studio Code
- Introduction
  - Overview
  - System requirements
  - Release note
- Basic Concepts
  - User interface
  - Command-line tools
  - Visual Studio Code extension packs
  - Bundles
  - CMake
  - Toolchains
  - STMicroelectronics Arm Clang Toolchain for STM32
- Getting Started
  - Installation
  - First project creation
- Workspace and extension workflow
  - Workspace overview
  - Extension commands
  - Project files
  - Multi-project workspaces
- Tutorials
  - Migrating from STM32CubeIDE for Visual Studio Code extension 2.x to 3.x
  - Dual-core STM32 projects
  - Power management
  - RTOS-based STM32 projects
  - Firmware security and integrity
- Development
  - Projects
  - Editing
  - Build
  - Debug
  - API manual
  - Integration with external tools
  - Testing and validation
- Troubleshooting
  - Frequently asked questions
  - Known issues
  - Support

### On this page

- Project orientation
- Creating a new project
- Convert and import an Eclipse STM32CubeIDE project
- Project configuration
  - Managing project properties
- Project organization
  - Source folder Structure best practices
- Sharing projects
  - Using version control systems
  - Sharing configuration files
  - Using live share
  - Further reading
- Code freeze and release management
  - Code freeze
  - Release management
  - Further reading
- Updating bundles and components
  - Updating extensions

# Projects

## Project orientation

STM32CubeIDE for Visual Studio Code supports several types of projects. The following examples illustrate supported project types:

1. STM32CubeMX generated projects

   STM32CubeIDE for VS Code supports projects generated by STM32CubeMX, STMicroelectronics’ graphical configuration tool. These projects include hardware configuration, middleware, and peripheral initialization code tailored to the selected STM32 microcontroller.

   - Project structure: Auto-generated hardware abstraction layer code, middleware stacks (USB, TCP/IP, FATFS), and user application code.

   - Use case: Rapid prototyping and development with automatic initialization of peripherals and middleware.

   - Build system: Uses Makefile or CMake depending on project setup.

2. Bare-metal STM32 projects

   Users can create bare-metal projects from scratch or import existing projects. These projects directly control the STM32 hardware without relying on hardware abstraction layer or middleware.

   - Project structure: Startup files, linker scripts, CMSIS core files, and user-written source code.

   - Use case: Low-level programming, real-time applications, or when minimal overhead is required.

   - Build system: Typically Makefile or CMake based.

3. FreeRTOS-based projects

   STM32CubeIDE for VS Code supports projects that integrate the FreeRTOS real-time operating system.

   - Project structure: Includes FreeRTOS kernel source files, configuration headers, and user tasks.

   - Use case: Applications requiring multitasking, real-time scheduling, and inter-task communication.

   - Build system: Compatible with Makefile or CMake workflows.

4. STM32Cube middleware projects

   Projects that leverage STM32Cube middleware components such as USB device/host, TCP/IP stack (LwIP), file system (FATFS), graphics (TouchGFX), and more.

   - Project structure: Middleware libraries integrated with hardware abstraction layer and user application layers.

   - Use case: Complex applications needing advanced connectivity, storage, or graphical interfaces.

   - Build system: Managed via Makefile or CMake.

5. Example and template projects

   STM32CubeIDE for Visual Studio Code provides example projects and templates for various STM32 series and application domains.

   - Project structure: Pre-configured projects demonstrating peripheral usage, communication protocols, or real-time operating system integration.

   - Use case: Learning, prototyping, and reference for application development.

   - Build system: Predefined build configurations.

## Creating a new project

- First project creation: Start your STM32CubeIDE for Visual Studio Code journey here.

## Convert and import an Eclipse STM32CubeIDE project

Note

This operation is also available through the command-line interface. For more information, use the command:

    $ cube ide-project-convert --help

To convert an existing Eclipse-based STM32CubeIDE project to STM32CubeIDE for Visual Studio Code, navigate to the STM32Cube Key Actions section and select Convert Eclipse STM32CubeIDE project.

After selecting this option, a drop-down menu appears where you must select Project source and Project destination.

Project source: Navigate to and select the root folder of your Eclipse-based STM32CubeIDE project.

Project destination: Create a new folder or select a folder where you want the converted project to be located.

When both fields are filled, a third option appears: Convert project.

Click the Convert project button to invoke the STM32CubeIDE Eclipse exporter.

Once the process is complete, choose whether to open the converted project in the current Visual Studio Code window, open it in a new window, or add it to your workspace.

## Project configuration

Key components of project configuration include:

- Settings (`settings.json`) Configure editor behavior, formatting, linting, and other preferences specific to the project. These settings override user-level defaults when the workspace opens.

- Tasks (`tasks.json`) Define automated tasks such as build, test, or deploy procedures. Execute tasks directly from the Visual Studio Code interface or integrate them into debugging workflows.

- Launch configurations (`launch.json`) Set debugging options, including environment variables, program arguments, and runtime settings for different languages and frameworks.

- Extensions recommendations (`extensions.json`) Recommend extensions useful for the project to help team members maintain a consistent development setup.

- Workspace configuration (`*.code-workspace`) Use a workspace file to group multiple folders and their configurations into a single project workspace.

These configuration files enable Visual Studio Code to tailor the development environment to the specific needs of the project, improving productivity and consistency across teams.

For more information, see Visual Studio Code documentation.

### Managing project properties

Managing project properties in Visual Studio Code involves the following aspects:

- Workspace settings Visual Studio Code stores workspace settings in the .vscode/settings.json file to configure project-specific options such as formatting rules, linting, and editor preferences.

- Tasks configuration The .vscode/tasks.json file defines custom build, test, and deployment tasks that can be executed within the editor.

- Launch configurations Debugging settings are managed through .vscode/launch.json, where you specify how to run and debug applications with different environments and parameters.

- Extensions and language support Project-specific configurations may depend on extensions, which add their own settings to workspace configuration files to tailor the development experience.

- Version control integration Visual Studio Code integrates with Git and other version control systems, enabling project-level source control management.

Managing project properties in Visual Studio Code centers on editing JSON configuration files within the .vscode folder, providing flexibility and customization for diverse development workflows.

For detailed customization, see Visual Studio Code documentation.

## Project organization

Effective project organization in Visual Studio Code streamlines development workflows and improves productivity. Visual Studio Code provides tools and features to structure projects efficiently.

Managing project organization in Visual Studio Code involves the following aspects:

- Workspace and folder structure Organize source code, assets, and configuration files into logical folders. Visual Studio Code supports single-folder workspaces and multi-root workspaces for managing multiple folders in one window.

- .vscode folder This hidden folder contains project-specific configuration files such as settings.json, tasks.json, and launch.json, which customize editor behavior and tooling per project.

- Source control integration Visual Studio Code integrates with Git and other version control systems, enabling branch management, commits, and diffs within the editor.

- File and symbol navigation Use features such as Explorer, Outline view, and Go to Definition to navigate large codebases efficiently.

- Extensions for organization Use extensions such as project managers, file explorers, and code linters to enhance project structure and maintain code quality.

- Workspace settings Customize settings at the workspace level to tailor the development environment to the needs of each project.

Organizing projects within Visual Studio Code maintains clarity, reduce complexity, and fosters collaboration across development teams.

For more details, see Visual Studio Code documentation.

### Source folder Structure best practices

Organizing the source folder structure is essential for maintainability, scalability, and collaboration in software projects.Visual Studio Code is flexible and agnostic about folder layouts. However, following best practices streamlines development and improves clarity.

Managing best practices for source folder structure involves the following aspects:

- Logical separation of concerns Group files by their roles or features. For example, use src/ for source code, tests/ for unit tests, docs/ for documentation, and assets/ for images or other resources.

- Consistent naming conventions Use clear and consistent folder and file names to reflect their purpose. This approach makes navigation intuitive for all team members.

- Feature-based organization For large projects, organize code by feature or module instead of by file type. This method improves modularity and ease of maintenance.

- Configuration and build files Place configuration files, such as .vscode/, package.json, Makefile, at the root or in dedicated folders to separate them from source code.

- Avoid deep nesting Limit folder depth to reduce complexity and make files easier to locate.

- Use `.vscode` folder for project settings Store project-specific settings, tasks, and launch configurations in the .vscode folder to keep them organized and version-controlled.

- Version control considerations Ensure that the folder structure aligns with your version control system. Include appropriate .gitignore files to exclude unnecessary files.

By following these best practices, you create a clean, maintainable, and scalable project structure that enhances productivity and collaboration in Visual Studio Code.

For further guidance, see Visual Studio Code documentation.

## Sharing projects

Sharing projects with colleagues in Visual Studio Code streamlines collaboration and ensures that everyone is worki with the same setup. This guide outlines steps to share your projects effectively.

### Using version control systems

Version control systems, such as Git, are essential for sharing projects and collaborating with colleagues. Git enables you to track changes, manage versions, and collaborate on code.

1. Initialize a Git repository:

   - Open your project in Visual Studio Code.

   - Open the terminal and run:

     `git init`

2. Add and commit files:

   - Stage your files for commit:

     `git add .`

   - Commit your changes:

     `git commit -m "Initial commit"`

3. Push to a remote repository:

   - Create a repository on a platform such as GitHub, GitLab, or Bitbucket.

   - Add the remote repository to your local Git repository:

     `git remote add origin <repository-url>`

   - Push your changes:

     `git push -u origin master`

### Sharing configuration files

To ensure that colleagues have the same development environment, share relevant configuration files with your project.

1. Extensions - List the extensions used in your project and share the list with colleagues. They can install the same extensions from the Extensions Marketplace.

2. Settings - Share workspace settings by including the .vscode/settings.json file in your project. This file contains custom settings specific to your project.

3. Tasks and launch configurations - Include the .vscode/tasks.json and .vscode/launch.json files in your project to share build tasks and debugging configurations.

### Using live share

The Live Share extension in Visual Studio Code enables real-time collaboration. It allows you to share your project, terminal, and debugging sessions instantly.

1. Install Live Share - Install the Live Share extension from the Extensions Marketplace.

2. Start a Live Share session: - In the status bar, click the Live Share icon. - Sign in wihh a Microsoft or GitHub account. - Click “Start Collaboration Session” to generate a shareable link

3. Join a Live Share session: - Share the generated link with colleagues. - Colleagues can join the session by clicking the link and opening it in Visual Studio Code.

### Further reading

Sharing projects in Visual Studio Code enhances collaboration and ensures consistency. By using version control systems, sharing configuration files, and leveraging Live Share, you create a seamless collaborative environment.

For more detailed information, see Visual Studio Code documentation.

## Code freeze and release management

Managing code freeze and release processes in Visual Studio Code ensures stability and quality in software development. This guide outlines specific actions to take in Visual Studio Code.

### Code freeze

1. Create a code freeze branch:

   - Open your project in Visual Studio Code.

   - Open the integrated terminal (shortcut: Ctrl+backtick).

   - Create a new branch for code freeze:

         git checkout -b code-freeze

2. Commit and push changes:

   - Ensure all changes are committed. Use the Source Control view (`Ctrl+Shift+G`) to stage, commit, and push changes:

       - Stage all changes: Click the “+” icon next to the changes.

       - Commit changes: Enter a commit message and click the checkmark icon.

       - Push changes: Click the “…” menu and select “Push”.

3. Restrict changes to critical bug fixes:

> - Communicate with the team to ensure only critical bug fixes are made in the `code-freeze` branch. Use the Source Control view to manage commits related to critical bug fixes.

4. Review and merge changes:

> - Use the GitLens extension or the built-in Git features to review and merge necessary changes into the `code-freeze` branch:

>     - Open the Command Palette (`Ctrl+Shift+P`).

>     - Type “Git: Merge Branch” and select the branch to merge.

### Release management

1. Create a release branch:

   - Open the integrated terminal (shortcut: Ctrl+backtick).

   - Create a new branch for the release:

         git checkout -b release-v1.0

2. Tag the release:

   - Tag the release to mark it in the repository:

         git tag -a v1.0 -m "Release version 1.0"
         git push origin v1.0

3. Build and test:

   - Use Visual Studio Code tasks to build and test the project: - Open the Command Palette (`Ctrl+Shift+P`). - Type “Tasks: Run Task” and select the build or test task. - Monitor the terminal output for build or test issues.

4. Prepare release notes:

   - Use the Markdown editor in Visual Studio Code to prepare release notes:

       - Create a new file (`Ctrl+N`) and save it as `RELEASE_NOTES.md`.

       - Document the changes, features, and bug fixes included in the release.

5. Deploy to production:

   - Use deployment extensions or integrated terminal commands to deploy the release: - For example, use the Azure App Service extension to deploy to Azure, or use terminal commands for other deployment platforms.

6. Monitor and support:

   - Use the integrated terminal and extensions to monitor the release:

       - Open the terminal (shortcut: Ctrl+backtick) to run monitoring scripts.

       - Use extensions such as Docker or Kubernetes to manage and monitor deployments.

### Further reading

Handling code freeze and release management effectively in Visual Studio Code ensures the stability and quality of software releases. By following these actions, you can manage the process efficiently and deliver reliable software to users.

For more detailed information, see Visual Studio Code documentation.

## Updating bundles and components

Keeping your development environment up to date is crucial for maintaining productivity and taking advantage of the latest features and improvements. This guide outlines the steps to update bundles and components in Visual Studio Code (VS Code).

### Updating extensions

Extensions add functionality to Visual Studio Code and are a key component of bundles. Regularly updating extensions ensures you have the latest features, bug fixes, and security updates.

1. Check for extension updates:

   - Open the Extensions view (`Ctrl+Shift+X`).

   - Click the “…” menu in the top right corner.

   - Select “Check for Updates”.

2. Update extensions:

   - If updates are available, an “Update” button appears next to each extension.

   - Click the “Update” button to install the latest version of the extension.

3. Automatic updates:

   - Visual Studio Code can automatically update extensions. To enable this: - Open the Command Palette (`Ctrl+Shift+P`). - Type “Preferences: Open Settings (UI)” and select it. - Search for “Extensions: Auto Update” and ensure it is enabled.