1.. _stm32cube_ide:
2
3STM32CubeIDE
4############
5
6STM32CubeIDE_ is an Eclipse-based integrated development environment from STMicroelectronics designed for the STM32 series of MCUs and MPUs.
7
8This guide describes the process of setting up, building, and debugging Zephyr
9applications using the IDE.
10
11A project must have already been created with Zephyr and west.
12
13These directions have been validated to work with version 1.16.0 of the IDE
14on Linux.
15
16Project Setup
17*************
18
19#. Before you start, make sure you have a working Zephyr development environment, as per the
20   instructions in the :ref:`getting_started`.
21
22#. Run STM32CubeIDE from your Zephyr environment.  Example:
23
24   .. code-block::
25
26      $ /opt/st/stm32cubeide_1.16.0/stm32cubeide
27
28#. Open your already existing project by going to
29   :menuselection:`File --> New --> STM32 CMake Project`:
30
31   .. figure:: img/stm32cube_new_cmake.webp
32      :align: center
33      :alt: Create new CMake project
34
35#. Select :guilabel:`Project with existing CMake sources`, then click :guilabel:`Next`.
36
37#. Select :menuselection:`Next` and browse to the location of your sources.  The
38   folder that is opened should have the ``CMakeLists.txt`` and ``prj.conf`` files.
39
40#. Select :menuselection:`Next` and select the appropriate MCU.
41   Press :guilabel:`Finish` and your project should now be available.
42   However, more actions must still be done in order to configure it properly.
43
44#. Right-click on the newly created project in the workspace, and select
45   :guilabel:`Properties`.
46
47#. Go to the :guilabel:`C/C++ Build` page and set the Generator
48   to ``Ninja``.  In :guilabel:`Other Options`, specify the target ``BOARD`` in
49   CMake argument format. If an out-of-tree board is targeted, the ``BOARD_ROOT``
50   option must also be set. The resulting settings page should look similar to this:
51
52   .. figure:: img/stm32cube_project_properties.webp
53      :align: center
54      :alt: Properties dialog for project
55
56   These options may or may not be needed depending on if you have an
57   out-of-tree project or not.
58
59#. Go to the :menuselection:`C/C++ General --> Preprocessor Include` page.
60   Select the :guilabel:`GNU C` language, and click on the
61   :menuselection:`CDT User Settings Entries` option.
62
63   .. figure:: img/stm32cube_preprocessor_include.webp
64      :align: center
65      :alt: Properties dialog for preprocessor options
66
67   Click :guilabel:`Add` to add an :guilabel:`Include File`
68   that points to Zephyr's ``autoconf.h``, which is located in
69   ``<build dir>/zephyr/include/generated/autoconf.h``. This will ensure
70   that STM32CubeIDE picks up Zephyr configuration options.
71   The following dialog will be shown.  Fill it in as follows:
72
73   .. figure:: img/stm32cube_add_include.webp
74      :align: center
75      :alt: Add include file dialog
76
77   Once the include file has been added, your properties page should look
78   similar to the following:
79
80   .. figure:: img/stm32cube_autoconf_h.webp
81      :align: center
82      :alt: Properties page after adding autoconf.h file
83
84#. Click :guilabel:`Apply and Close`
85
86#. You may now build the project using the :guilabel:`Build` button on the toolbar.
87   The project can be run using the :guilabel:`Run` button, as well as debugged
88   using the :guilabel:`Debug` button.
89
90Debugging only
91**************
92
93If you only want to use STM32CubeIDE to debug your project you can proceed as follows:
94
95#. First, make sure to compile your project and have the ``zephyr.elf`` available.
96
97#. Run STM32CubeIDE and import your project by going to :menuselection:`File --> Import...`:
98
99   .. figure:: img/stm32cube_menu_import.webp
100      :align: center
101      :alt: Import project
102
103#. Select :menuselection:`C/C++ --> STM32 Cortex-M Executable`, then click :guilabel:`Next`:
104
105   .. figure:: img/stm32cube_import_project.webp
106      :align: center
107      :alt: Import project selection
108
109#. Click on :guilabel:`Browse` to browse to your build folder and select your ``zephyr.elf``.
110
111#. Click on :guilabel:`Select` to select your MCU. If relevant, choose also your CPU and/or core.
112
113#. Click on :guilabel:`Finish`.
114
115#. The project can now be debugged using the :guilabel:`Debug` button.
116
117Troubleshooting
118***************
119
120When configuring your project you see an error that looks similar to:
121
122.. code-block::
123
124  Error message: Traceback (most recent call last):
125
126    File "/path/to/zephyr/scripts/list_boards.py", line 11, in <module>
127      import pykwalify.core
128
129  ModuleNotFoundError: No module named 'pykwalify'
130
131
132This means that you did not start the IDE in a Zephyr environment.  You must
133delete the ``config_default`` build directory and start STM32CubeIDE again,
134making sure that you can run ``west`` in the shell that you start STM32CubeIDE
135from.
136
137.. _STM32CubeIDE: https://www.st.com/en/development-tools/stm32cubeide.html
138