Foolproof Guide: How to Use the All-in-One Development Tool STM32CubeIDE

STM32CubeIDE is based on the Eclipse framework and inherits some features unique to Eclipse that users may not be familiar with, such as perspectives and workspaces.

Workspace: STM32CubeIDE manages projects through a workspace. When opening STM32Cube, it creates a default workspace, but users can also choose a different folder as a workspace using the Browse button. Projects created or imported afterward belong to the chosen workspace. Projects under the same workspace have the same IDE-level configuration (set in Window→Preferences), such as display and editing style settings. From the file system perspective, a workspace is a folder containing multiple project folders and a folder named “.metadata”. The “.metadata” folder contains information about all projects within that workspace. Users can switch between different workspaces through the File→Switch Workspace menu.

Perspective: A perspective is a combination of a series of windows related to a specific function. Common ones include C/C++ Editing Perspective, Debug Perspective, and CubeMX Configuration Perspective.

The C/C++ Editing Perspective includes the Project Explorer, Editing Window, Outline Window, etc. In the Project Explorer, you can view and manipulate all projects in the current workspace. Double-clicking a file in the project opens its content in the editing window, where it can be edited. The rightmost Outline Window lists all functions, variables, and macros defined in the currently opened file.

You can open and close the windows that need to be displayed in the C/C++ Editing Perspective through the Window Show View menu.

You can switch between different perspectives using the icons in the upper right corner; for example, clicking the bug icon switches to the Debug Perspective. When you click the Debug button in the C/C++ Editing Perspective toolbar, it will also automatically switch to the Debug Perspective.

Using STM32CubeIDE, users can start a new project in various ways. The welcome interface of STM32CubeIDE lists quick access points for creating/importing projects, corresponding to the following four scenarios. You can also achieve the same functions through the New and Import options in the File menu. • Start a new STM32 project from scratch • Create an STM32 project based on an existing STM32CubeMX configuration file (*.ioc file) • Convert an existing SW4STM32 or TrueSTUDIO project to an STM32CubeIDE project • Create a new project based on examples in the STM32Cube library

STM32CubeIDE has two types of project structures, as shown in the figure below.

Single-core MCUs have a flat structure.

For dual-core architecture MCUs or secure MCUs, such as the STM32H7, STM32L5, and STM32MP1 series, the STM32CubeIDE project has a layered structure. Taking the STM32H7 as an example, after creating or importing an STM32H7 project, the Project Explorer shows a three-layer project structure: the top layer is the “root” project, followed by two “sub” projects corresponding to the CM7 and CM4 cores, and the project files are below the “sub” projects. These two CM7 and CM4 “sub” projects are the actual compilable and debuggable projects, while the “root” project serves merely as a “container” that includes the CM7 and CM4 “sub” projects. AN5361, AN5394, AN5360, and AN5564 describe how to create, import, compile, and debug STM32H7 dual-core, STM32L5, STM32MP1, and STM32WL projects in STM32CubeIDE.

In the Project Explorer window, you can see all the projects in the current workspace. Users can open/close/delete/import/export/rename any project here. For specifics, please refer to “Basic Operations of Projects” (coming soon, stay tuned).

STM32CubeIDE integrates some functionalities of STM32CubeMX, allowing users to directly select chip/development board models or choose examples to generate a new project. The drivers and example codes required for generating projects in STM32CubeIDE come from the firmware libraries of various STM32 series.

In Help→Manage Embedded Software Packages, you can manage all STM32 firmware libraries and other plugins (install/delete firmware libraries).

Users can use the Install Now button to let STM32CubeIDE automatically download and install from the network or use the From Local button to install firmware libraries that have already been downloaded.

By using the Remove Now button, users can delete the selected firmware library.

In the Window Preferences window under the STM32Cube Firmware Updater tab, users can set the installation path and update methods for firmware libraries.

By default, STM32CubeIDE will attempt to connect to the network when opening and creating projects. Users can choose “Offline Mode” to prevent STM32CubeIDE from going online. However, they will need to use the From Local button in the Embedded Software Packages Manager window to install firmware libraries that have already been downloaded; otherwise, code generation for new STM32 projects cannot occur automatically.

Clicking the Check Connection button will check the current network connection status. If a red × appears after the check, it indicates a network configuration issue that needs to be addressed in the Network Connection page.

In addition to actively checking the network status, if there is a firmware download failure, please also check whether the STM32CubeIDE network configuration is correct.

Configuration steps are shown in the figure below: 1. Go to the Window Preferences menu, select the General Network Connections tab 2. Choose Manual mode 3. Select HTTP, double-click to open the edit window, and set the network connection parameters.

STM32CubeIDE is based on Eclipse, and some commonly used shortcuts and editing techniques in Eclipse are also applicable to STM32CubeIDE. Mastering these small tricks can improve development efficiency, making programming tasks much easier.

In the Project Explorer, select a project, right-click to enter the properties menu, where you can configure the compilation options. For details on commonly used configuration operations, please refer to “STM32CubeIDE Project Property Configuration Tips”.

Once configuration is complete, you can proceed to compile. Users can start the compilation through the following three methods: • Method 1: Select the project, right-click, and choose “Build Project” • Method 2: Select the project, go to the Project menu, and choose “Build Project” • Method 3: Select the project and click the Build icon in the toolbar

By enabling parallel compilation, you can improve the compilation speed of STM32CubeIDE. Select the project, right-click to enter the properties menu, choose “C/C++ Build”, and in the Behavior tab, check the “Enable parallel build” option.

After the project compilation is complete, the “Build Analyzer” window shows all memory regions and sections defined in the link file, including load addresses, run addresses, how many bytes are occupied, and how many bytes are remaining.

The “Static Stack Analyzer” window displays the usage of the static stack.

STM32CubeIDE also provides Headless Build functionality, allowing compilation through the command line without opening the CubeIDE graphical interface.

Once the STM32CubeIDE project is compiled successfully without any errors, debugging and downloading can proceed.

In the C/C++ perspective toolbar, there are three buttons related to downloading and debugging: Debug, Run, and External Tools.

By clicking the small triangle next to the “Debug” button, you can open the Debug Configurations menu to configure debugging parameters, such as selecting the debugger, setting GDB connection, ST-LINK settings, and external Flash Loader settings, and then start debugging.

The “Run” button allows you to download the program without starting debugging.

The “External Tools” button can invoke external command-line tools.

For content related to debugging parameter configuration and debugging tips, please refer to “STM32CubeIDE Project Debugging Configuration and Tips” (coming soon, stay tuned).

STM32CubeIDE uses GDB for debugging, supporting STLink and SEGGER J-Link debuggers, and connecting to target MCUs via SWD or JTAG interfaces.

After compiling the STM32CubeIDE project, you can start debugging by clicking the bug icon in the toolbar or by selecting Run–>Debug from the menu.

If it is your first time debugging the current project, STM32CubeIDE will first compile the project and then open the debugging configuration window. The debugging configuration window includes options for selecting the debugging interface, STLink settings, reset settings, and external flash loader settings, where users can check or modify various configurations. Once all configurations are confirmed to be correct, click OK to start debugging.

Then STM32CubeIDE will download the program to the MCU and execute it starting from the entry point specified in the link file (*.ld). The program defaults to start executing from Reset_Handler and will pause at the first line of the main function, waiting for subsequent debugging instructions.

Once debugging starts, STM32CubeIDE will automatically switch to the Debug Perspective, where the debugging operation buttons are listed in the toolbar, as shown in the figure below.

STM32CubeIDE also supports Eclipse plugins.

You can search for and install plugins in the Eclipse Marketplace through the Help menu under “Eclipse Marketplace”; or install plugins from a specified URL through “Install New Software” in the Help menu.

Now let’s walk through a simple LED blinking example to experience the software development process using STM32CubeIDE.

The example uses the NUCLEO-H743ZI development board and starts a new project from scratch using STM32CubeIDE. This project implements a simple function: the onboard LED1 toggles automatically at 500ms intervals. Through this example, you will understand the following: • Create a new STM32CubeIDE project • Configure the STM32 chip • Add user code and compile • Set debugging parameters • Debug the code (view variables and registers) • Set breakpoints

First, select File–>New–>STM32 Project, and STM32CubeIDE will open the MCU selection window. In this window, you can choose a specific chip model, an ST development board, or an example. Here we enter STM32H743ZI in the search box to select this chip directly, and then click Next.

In the next pop-up window, set the project name, type, and save location. By default, the new project will be saved in the current workspace, but users can uncheck “Use default location” and customize the project save location as shown below. Note that if you attempt to place two projects in the same path, you may encounter errors during the creation process. Therefore, you can add the project name to the path to distinguish different projects.

After setting is complete, click Finish, and STM32CubeIDE will create a project for us and open the chip configuration interface, which is the same as that of STM32CubeMX.

During this process, a prompt may pop up indicating that the CubeMX configuration perspective will be opened; simply click Yes.

Next, in the chip configuration interface, configure the clock, GPIO, peripherals, middleware, etc., according to functional requirements. In this example, we only use PB0 to control LED1 output, so we only need to configure it. The clock will use the default configuration.

In the Pinout view, you can quickly find the pin to configure on the chip package diagram using the search bar.

Select the pin, right-click, and choose GPIO_Output function.

Then go to the System view, click on the GPIO module, and you will see the configured PB0 pin. In this window, you can further adjust other parameters of PB0, such as pull-up/pull-down, speed, etc. You can also define a user label LDE1 for it, making it easier to reference in the code.

After all configurations are complete, select Project–>Generate Code to regenerate the code. At this point, STM32Cube will switch to the C/C++ perspective, where you can add user files or modify a specific C file.

Here, we add a piece of code to toggle PB0. Note that all user-added code must be placed between the declarations “USER CODE BEGIN xxx” and “USER CODE END xxx.” This way, when regenerating code again, this part of the code will not be lost.

Once the code is added, click “Build” to start compiling.

If the compilation ends without any errors, you can click Debug to start debugging.

When starting debugging for the first time, the debugging parameter configuration window will pop up. After confirming that all parameters are correct, click OK, and STM32CubeIDE will automatically switch from the editing interface to the debugging interface, as shown in the figure below.

In the debugging interface, you can perform step-by-step debugging using the operation buttons in the toolbar.

Double-click the mark area on the leftmost side of a line of code to add a breakpoint at that line.

On the right, multiple debugging windows will open, including: local variables, breakpoints, global variables, and registers, etc. These windows can be opened or closed in the Window–>Show View menu.

When you first open STM32CubeIDE, the “Information Center” page is displayed first. This page provides quick access to create projects and entry points for using STM32CubeIDE documentation. Users do not need to read all these documents before using STM32CubeIDE, but can use this as an entry point to search for relevant documentation when needed.