STM32CubeIDE

.. _stm32cube_ide:

STM32CubeIDE ############

STM32CubeIDE_ is an Eclipse-based integrated development environment from STMicroelectronics designed for the STM32 series of MCUs and MPUs.

This guide describes the process of setting up, building, and debugging Zephyr applications using the IDE.

A project must have already been created with Zephyr and west.

These directions have been validated to work with version 1.16.0 of the IDE on Linux.

Project Setup

#. Before you start, make sure you have a working Zephyr development environment, as per the instructions in the :ref:getting_started.

#. Run STM32CubeIDE from your Zephyr environment. Example:

.. code-block::

  $ /opt/st/stm32cubeide_1.16.0/stm32cubeide

#. Open your already existing project by going to :menuselection:File --> New --> STM32 CMake Project:

.. figure:: img/stm32cube_new_cmake.webp :align: center :alt: Create new CMake project

#. Select :guilabel:Project with existing CMake sources, then click :guilabel:Next.

#. Select :menuselection:Next and browse to the location of your sources. The folder that is opened should have the CMakeLists.txt and prj.conf files.

#. Select :menuselection:Next and select the appropriate MCU. Press :guilabel:Finish and your project should now be available. However, more actions must still be done in order to configure it properly.

#. Right-click on the newly created project in the workspace, and select :guilabel:Properties.

#. Go to the :guilabel:C/C++ Build page and set the Generator to Ninja. In :guilabel:Other Options, specify the target BOARD in CMake argument format. If an out-of-tree board is targeted, the BOARD_ROOT option must also be set. The resulting settings page should look similar to this:

.. figure:: img/stm32cube_project_properties.webp :align: center :alt: Properties dialog for project

These options may or may not be needed depending on if you have an out-of-tree project or not.

#. Go to the :menuselection:C/C++ General --> Preprocessor Include page. Select the :guilabel:GNU C language, and click on the :menuselection:CDT User Settings Entries option.

.. figure:: img/stm32cube_preprocessor_include.webp :align: center :alt: Properties dialog for preprocessor options

Click :guilabel:Add to add an :guilabel:Include File that points to Zephyr's autoconf.h, which is located in <build dir>/zephyr/include/generated/autoconf.h. This will ensure that STM32CubeIDE picks up Zephyr configuration options. The following dialog will be shown. Fill it in as follows:

.. figure:: img/stm32cube_add_include.webp :align: center :alt: Add include file dialog

Once the include file has been added, your properties page should look similar to the following:

.. figure:: img/stm32cube_autoconf_h.webp :align: center :alt: Properties page after adding autoconf.h file

#. Click :guilabel:Apply and Close

#. You may now build the project using the :guilabel:Build button on the toolbar. The project can be run using the :guilabel:Run button, as well as debugged using the :guilabel:Debug button.

Debugging only

If you only want to use STM32CubeIDE to debug your project you can proceed as follows:

#. First, make sure to compile your project and have the zephyr.elf available.

#. Run STM32CubeIDE and import your project by going to :menuselection:File --> Import...:

.. figure:: img/stm32cube_menu_import.webp :align: center :alt: Import project

#. Select :menuselection:C/C++ --> STM32 Cortex-M Executable, then click :guilabel:Next:

.. figure:: img/stm32cube_import_project.webp :align: center :alt: Import project selection

#. Click on :guilabel:Browse to browse to your build folder and select your zephyr.elf.

#. Click on :guilabel:Select to select your MCU. If relevant, choose also your CPU and/or core.

#. Click on :guilabel:Finish.

#. The project can now be debugged using the :guilabel:Debug button.

Troubleshooting

When configuring your project you see an error that looks similar to:

.. code-block::

Error message: Traceback (most recent call last):

File "/path/to/zephyr/scripts/list_boards.py", line 11, in <module>
  import pykwalify.core

ModuleNotFoundError: No module named 'pykwalify'

This means that you did not start the IDE in a Zephyr environment. You must delete the config_default build directory and start STM32CubeIDE again, making sure that you can run west in the shell that you start STM32CubeIDE from.

.. _STM32CubeIDE: https://www.st.com/en/development-tools/stm32cubeide.html