Run examples

Build and run the example projects provided in the STM32Cube MCU Package to see the software components in action.

Refer to the STM32Cube Software Examples documentation for detailed information about the STM32Cube Software Examples.

Note

Ensure that the required toolchains and drivers are installed for the development environment to build and run the example projects. Verify that the device is supported in the integrated development environment and that the correct board is connected to the computer before building and running the example projects.

Folder structure and tools behavior

The STM32Cube MCU Package uses the STM32Cube MCU Package folder structure , where example projects share dependencies (DFP, HAL, middleware, part drivers, utilities). This shared structure means a change in one dependency affects all projects that depend on it.

Tool-specific behavior:

  • ST tools (STM32CubeMX2, STM32CubeIDE for Visual Studio Code): Always convert projects to standalone structure (no shared dependencies) when opening or creating projects. When opening from the package structure, the tool extracts and migrates the project to a separate location.

  • Other vendors tools (IAR Embedded Workbench® for Arm®, Keil® MDK for Arm®): Work in place. Projects are used “as is” without any automatic conversion or extraction.

For detailed information, refer to the section of the STM32Cube Software Examples documentation explaining the folder structures and tool behaviors.

Run examples with STM32CubeIDE for Visual Studio Code

The example projects are not meant to be used with STM32CubeIDE for Visual Studio Code directly from the package, they need to be imported.

  1. From STM32CubeIDE for Visual Studio Code, select the STM32Cube MCU Package: Use ‘import example’ menu to select the package.

  2. Select an example project: from the list offered by STM32CubeIDE for Visual Studio Code, pick up an example matching the hardware.

  3. Import the project: STM32CubeIDE for Visual Studio Code will generate a new cmake project, including all necessary configurations.

Note

A STM32CubeIDE for Visual Studio Code project can also be generated using STM32CubeMX2 by opening the provided .ioc2 file located in the board folder. See dedicated sections below.

Run examples with IAR Embedded Workbench® for Arm® or Keil® MDK for Arm®

  1. Select an example project: Navigate to the examples folder in the STM32Cube MCU Package and choose an example that matches the hardware and development environment.

  2. Open the project in IDE: Depending on the chosen development environment, open the corresponding project file located in the board and IDE’s folder as described in the Package content.

Note

The project structure in the STM32Cube MCU Package is not intended to be a starting point for new projects. For a new project, start from the STM32CubeMX2 ioc2 project file and generate a new IAR or Keil MDK project. New projects can also be created using STM32CubeMX2. See dedicated sections below.

Warning

Windows only: 260-character path length limit can break some IAR Embedded Workbench® for Arm® builds

On Windows systems, the total build path length must not exceed 260 characters . The STM32Cube MCU Package folder structure with nested middleware, board, and IDE subdirectories can create paths that exceed this limit, causing IAR Embedded Workbench® for Arm® build failures.

Example problematic path: 

C:/[installation_folder]/examples/middleware/usbx/device_hid_mouse_cdc_acm_uart_freertos/[board_name]/.cube/ewarm/usbx_device_hid_mouse_cdc_acm_uart_freertos/debug_IAR+[board_name]/Obj/USBX Controllers Driver.Device_7956158897306095167.dir/ux_dcd_stm32_endpoint_create.o

where:

  • [installation_folder] is the path to the STM32Cube MCU Package installation (for example, C:\STM32Cube\)

  • [board_name] is the name of the board used in the example (for example, NUCLEO-C562RE)

Solution: Separate source from build artifacts

Configure IAR Embedded Workbench® for Arm® to place build artifacts (object files, executables, listings) in a separate top-level directory with a shorter path:

  1. In IAR Embedded Workbench® for Arm®, open Project → Options → Build.

  2. Update the output directories to point to a shared build location outside the project hierarchy:

    <option>
   <name>ExePath</name>
   <state>$PROJ_DIR$/../../../../../../../../build_tmp/$PROJ_FNAME$/$CONFIG_NAME$/Exe</state>
</option>
<option>
   <name>ObjPath</name>
   <state>$PROJ_DIR$/../../../../../../../../build_tmp/$PROJ_FNAME$/$CONFIG_NAME$/Obj</state>
</option>
<option>
   <name>ListPath</name>
   <state>$PROJ_DIR$/../../../../../../../../build_tmp/$PROJ_FNAME$/$CONFIG_NAME$/List</state>
</option>
<option>
   <name>BrowseInfoPath</name>
   <state>$PROJ_DIR$/../../../../../../../../build_tmp/$PROJ_FNAME$/$CONFIG_NAME$/BrowseInfo</state>
</option>

  3. This creates a shallow build_tmp folder structure at the installation top level folder (for example, C:\STM32Cube\build_tmp\), keeping source files and project configurations in place while moving build artifacts to a location with a significantly shorter path.

  4. Rebuild the project: the build should now complete successfully without path length errors.

Open examples with STM32CubeMX2

  1. Select an example project: Navigate to the examples folder in the STM32Cube MCU Package and choose an example that matches the hardware and development environment.

  2. Open the `.ioc2` file: In the board folder of the selected example, open the provided .ioc2 file using STM32CubeMX2.

  3. Generate the project: In STM32CubeMX2, configure the project settings as needed and generate the project for the desired IDE (IAR, Keil MDK, STM32CubeIDE for Visual Studio Code, etc.).

After following these steps, the example project can be built and run on STM32 hardware.

Working in offline mode

The example projects can be built and run in offline mode, without an internet connection. However, when opening the STM32CubeMX2 project for the first time, the required software components may need to be downloaded if they are not already available locally.

STM32CubeMX2 does not use the software components from the STM32Cube MCU Package, but instead relies on packs installed in the local STM32CubeMX2 environment. There are two ways to get the required software components:

  • Let STM32CubeMX2 download the required software components automatically when opening the project. This requires an internet connection and may take some time depending on the number of components needed.

  • Use STM32 Package Creator to download a software package in the STM32CubeMX2 package format. This package can then be imported into STM32CubeMX2, so that the required software components are available locally, enabling offline project generation and building.