Development of embedded systems based on microcontrollers STM32 requires not only knowledge of the ARM Cortex-M architecture, but also knowledge of specialized tools. STM32 CubeIDE - official integrated development environment from STMicroelectronics, which combines a code generator STM32CubeMX, GCC compiler, GDB debugger and advanced analysis tools. This IDE has become the de facto standard for professionals working with the family of STM32, thanks to deep integration with the hardware capabilities of the chips and an extensive HAL/LL library.

However, many engineers encounter difficulties when they first get acquainted: from non-obvious project settings to problems with debugging through ST-Link or J-Link. In this article we will look at unique features of CubeIDE that are missing in alternatives like Keil or IAR, - for example, automatic code generation for peripherals taking into account clock conflicts or a built-in power consumption analyzer. You will learn how to avoid common errors when configuring the clock frequency, why the debugger sometimes freezes, and how to speed up the compilation of large projects by 30% due to the correct settings Makefile.

What is STM32 CubeIDE and why is it better than alternatives

STM32 CubeIDE is not just a shell for writing code, but a full-fledged tool that automates routine tasks when working with microcontrollers STM32. Unlike universal environments like VS Code with plugins or Eclipse, CubeIDE was initially developed taking into account the specifics STM32:

  • 🔧 Integrated STM32CubeMX: visual configuration of peripherals (timers, ADC, DMA, etc.) with code generation for HAL/LL libraries.
  • 📡 Supports all STM32 families: from budget STM32F0 to high performance STM32H7 with FPU and cache.
  • 🐞 Debugger with SWO support: Outputs debug messages over a single wire (no UART), which is critical for devices with limited pins.
  • ⚡ Optimized toolchain: GCC compiler with pre-configured flags for STM32, resulting in 10-15% smaller firmware size compared to Keil.

The main advantage of CubeIDE over Keil MDK or IAR Embedded Workbench — free and no restrictions on code size. However, it also has disadvantages: for example, slower indexing of large projects (100+ files) or a less convenient interface for working with RTOS (compared to TrueSTUDIO, which CubeIDE replaced).

⚠️ Attention: When importing projects from STM32CubeMX versions older than 6.0 in CubeIDE 1.13+ may cause code generation errors for peripherals ETH And USB. Before migrating, update CubeMX to the latest version or use the option "Force regenerate" in the project settings.

Installing STM32 CubeIDE: step-by-step instructions for Windows, Linux and macOS

CubeIDE officially supports three platforms, but the installation process is different. On Windows just download the installer from the website STMicroelectronics and follow the master, whereas on Linux And macOS You will need to manually configure access rights to USB devices (to work with debuggers).

For Windows 10/11:

  1. Download the installer from official website (version no lower than 1.13.0).
  2. Run the installer with administrator rights. Select components:
    • ✅ STM32CubeIDE (required)
    • ✅ STM32CubeMX (integrated version)
    • ✅ Drivers for ST-Link (if you are using the ST debugger)
  • After installation, add the path to the toolchain to the environment variable PATH: 
    C:\ST\STM32CubeIDE_1.13.0\STM32CubeIDE\plugins\com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.11.3.rel1.win32_1.0.0.202309121326\tools\bin

    • For Linux (Ubuntu/Debian):

    • Install dependencies: 
      sudo apt install libncurses5 libudev1
    • Unzip the archive from CubeIDE to /opt/ and assign permissions: 
      sudo chmod +x /opt/STM32CubeIDE_1.13.0/stm32cubeide
    • Add a rule to access ST-Link: 
      sudo usermod -a -G plugdev $USER

      sudo cp /opt/STM32CubeIDE_1.13.0/STM32CubeIDE/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.linux64_2.0.0.202309121326/resources/rules/99-stlink-v*.rules /etc/udev/rules.d/
      

      sudo udevadm control --reload-rules

    📊 What OS do you use to develop on STM32?
    • Windows
    • Linux
    • macOS
    • Another

    Creating the first project: from clock configuration to code generation

    Let's start with the most critical stage - setting the clock frequency. Errors here will lead to unstable operation of the peripherals (for example, USART will transmit data with distortions). In CubeIDE this process is as automated as possible, but requires an understanding of the basic principles.

    Steps to create a project from scratch:

    1. Launch CubeIDE and select File → New → STM32 Project.
    2. In the window Target Selection indicate the MK model (for example, STM32F407G-DISC1* for development board STM32F4 Discovery).
    3. In the section Pinout & Configuration:
      • 🕒 Customize Clock Configuration: Select clock source (HSI, HSE, PLL) and target frequency (e.g. 84 MHz for STM32F4).
      • ⚙️ Activate peripherals (e.g. USART2 in mode Asynchronous).
      • 🔌 Assign pins on the diagram (for example, PA2 for USART2_TX).
  • Generate code using button GENERATE CODE.

    • After generation, pay attention to the files:

    • main.c — entry point with HAL initialization.
    • stm32f4xx_hal_conf.h — configuration of HAL libraries.
    • STM32F407G-DISC1.ioc — CubeMX project file (can be opened separately for editing).

    Make sure that the PLL frequency does not exceed the maximum for the core (for example, 180 MHz for STM32H7)|Check that the peripheral pins do not conflict with JTAG/SWD|Enable optimization -O2 in compiler settings|Disable unused modules in CubeMX to reduce the size of the firmware -->

    ⚠️ Attention: If after generating the code in the file main.c no call HAL_Init(), the project will not compile. This is a bug in CubeIDE 1.12–1.13, which can be fixed by manually adding a line before SystemClock_Config().

    CubeIDE supports three main debugging methods:

    Method Benefits Disadvantages Supported devices
    ST-Link Built into most ST development boards, no additional drivers required Limited speed (up to 4 MHz), no trace support STM32F0/F1/F3/F4/F7/H7/G0/G4
    J-Link (SEGGER) High speed (up to 12 MHz), support RTT and SWO Paid software for commercial use All STM32 as well as other ARM Cortex-M
    OpenOCD Open source, flexible customization Complex configuration, possible stability problems Any debuggers that support CMSIS-DAP

    To configure debugging via ST-Link:

    1. Connect the debugger to the board and PC.
    2. In CubeIDE select Run → Debug Configurations.
    3. Create a new type configuration STM32 Cortex-M C/C++ Application.
    4. Tab Debugger:
      • Select ST-Link (OpenOCD) or ST-Link (ST-Link GDB Server).
      • Specify the port (usually 3333 for OpenOCD).
      • In the field Config options add -f interface/stlink.cfg -f target/stm32f4x.cfg (replace f4x for your series).
    💡

    If the debugger does not detect the MK, try manually resetting the board with the button NRST or give a command monitor reset halt in the GDB console.

    Project optimization: reducing firmware size and speeding up compilation

    By default, CubeIDE generates code with conservative compiler settings, which results in bloated firmware. For example, a project for STM32F103 with a basic USART and GPIO configuration it can take up to 30 KB of Flash, although 8–12 KB is realistically sufficient. Here are the key optimization methods:

    1. Compiler settings:

    • 🔹B Project Properties → C/C++ Build → Settings → Tool Settings → MC Settings install:
      • Optimization: -Os (size optimization) instead -O0.
      • Debug information level: -g2 instead of -g3.
      • Add a flag -ffunction-sections -fdata-sections And --gc-sections into the linker.
    • 🔹 Disable unnecessary HAL modules in CubeMX (for example, if you don't use I2C, uncheck Middleware).

    2. Replacing HAL with LL (Low Layer):

    Library HAL adds abstraction overhead. For speed-critical areas (for example, interrupt handlers), use LL-drivers. Replacement example:

    // HAL (медленнее, но проще)

    HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
    


    // LL (быстрее, но требует ручного контроля)
    

    LL_GPIO_TogglePin(GPIOA, LL_GPIO_PIN_5);

    💡

    Using LL instead of HAL can reduce code execution time by 20-40%, but requires a deep understanding of peripheral registers.

    Common mistakes and their solutions

    Even experienced developers encounter problems with CubeIDE. Here are the most common ones and how to fix them:

    • 🚨 "No ST-Link detected":
      • Check the debugger connection (the power indicator should be on).
      • Update drivers via STSW-LINK009 (utility from ST).
      • For Linux: make sure the user is in a group plugdev.
    • 🚨 "HardFault Handler" at startup:
      • Check that the timing is correct (a common cause is incorrect PLL configuration).
      • Disable optimization (-O0) for debugging.
      • Use Registers View in the debugger to analyze the values HFSR, CFSR.
    • 🚨 "Flash download failed":
      • Reduce the programming speed in the debugger settings (for example, from 4000 kHz to 1800 kHz).
      • Check if Flash is write protected (bits WRPR in Option Bytes).
    How to Diagnose HardFault

    1. In the debugger, look at the register value SCB->HFSR. If bit FORCED installed, problem is manual call NVIC_SystemReset().

    2. Check SCB->CFSR:

    - Bit DACCVIOL — data access error.

    - Bit UNSTKERR - stack overflow.

    3. Use arm-none-eabi-objdump -d -S your_elf.elf to analyze disassembled code at the crash site.

    Advanced features: power analyzer, RTOS and SWO tracing

    CubeIDE includes tools that beginners rarely use, but are critical for professional projects:

    1. Power Consumption Calculator:

    • 📊 Available in CubeMX (tab Power Consumption).
    • Allows you to estimate current consumption in modes Run, Sleep, Stop taking into account the active periphery.
    • 🔹 Example: For STM32L4 with active LPUART And RTC in mode Stop 2 the current will be ~3 µA.

    2. Integration with FreeRTOS:

    • 🛠️ B CubeMX select Middleware → FreeRTOS and configure parameters (stack size, task priorities).
    • 🔹 Important: To work correctly with STM32H7 enable the option "Use Newlib nano" in the linker settings.
    • 📌 Use the plugin for debugging FreeRTOS Thread Awareness (install via Help → STM32Cube Extension Manager).

    3. Tracing via SWO:

    • 📡 Requires a SWO-enabled debugger (e.g. ST-Link V3 or J-Link).
    • 🔧 Setting: 
      // В main.c

      #include "core_cm4.h" // или core_cm7.h для STM32H7
      

      void ITM_SendChar(uint8_t ch) {
      

      ITM->PORT[0].u8 = ch;
      

      while (ITM->PORT[0].u8 == ch);
      

      }

    • 🖥️ To view the data, use STM32CubeMonitor or plugin SWO Viewer in CubeIDE.

    FAQ: answers to frequently asked questions

    Can CubeIDE be used for STM8?

    No, CubeIDE only supports ARM Cortex-M (STM32) based microcontrollers. For STM8 use STM8CubeIDE or IAR for STM8.

    How to transfer a project from Keil to CubeIDE?

    Importing directly is not supported, but you can:

    1. Export code from Keil in the format .c/.h.
    2. Create a new project in CubeIDE and manually copy the sources.
    3. Customize Makefile for compatibility with GCC (replace the Keil compiler switches with analogues for arm-none-eabi-gcc).

    Why does CubeIDE take a long time to index a project?

    This is a known issue when working with large projects (100+ files). Solutions:

    • Disable Indexer in Window → Preferences → C/C++ → Indexer (will speed up the work, but disable auto-completion).
    • Break the project into several smaller libraries.
    • Use an SSD to store projects.

    How to update CubeIDE without losing settings?

    When updating via Help → Check for Updates the settings are saved. If you are installing a new version from scratch:

    1. Copy the folder workspace (contains projects and configurations).
    2. Export settings via File → Export → General → Preferences.
    3. After installation, import the settings and specify the path to the old one workspace.

    Where can I find example projects for CubeIDE?

    Official examples:

    • Included STM32CubeF4 (or another package for your series) in the folder Projects.
    • On the ST website: STM32Cube MCU Packages.
    • On GitHub: repositories STMicroelectronics (For example, STM32CubeH7).