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
90Troubleshooting
91***************
92
93When configuring your project you see an error that looks similar to:
94
95.. code-block::
96
97  Error message: Traceback (most recent call last):
98
99    File "/path/to/zephyr/scripts/list_boards.py", line 11, in <module>
100      import pykwalify.core
101
102  ModuleNotFoundError: No module named 'pykwalify'
103
104
105This means that you did not start the IDE in a Zephyr environment.  You must
106delete the ``config_default`` build directory and start STM32CubeIDE again,
107making sure that you can run ``west`` in the shell that you start STM32CubeIDE
108from.
109
110.. _STM32CubeIDE: https://www.st.com/en/development-tools/stm32cubeide.html
111