6cf1ecbeff
Add documentation to use STM32CubeIDE for debug only. Signed-off-by: Guillaume Gautier <guillaume.gautier-ext@st.com>
138 lines
4.7 KiB
ReStructuredText
138 lines
4.7 KiB
ReStructuredText
.. _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
|