diff --git a/doc/develop/tools/img/stm32cube_add_include.webp b/doc/develop/tools/img/stm32cube_add_include.webp new file mode 100644 index 0000000000000..ce48090c59098 Binary files /dev/null and b/doc/develop/tools/img/stm32cube_add_include.webp differ diff --git a/doc/develop/tools/img/stm32cube_autoconf_h.webp b/doc/develop/tools/img/stm32cube_autoconf_h.webp new file mode 100644 index 0000000000000..8a8f154b8d5ed Binary files /dev/null and b/doc/develop/tools/img/stm32cube_autoconf_h.webp differ diff --git a/doc/develop/tools/img/stm32cube_new_cmake.webp b/doc/develop/tools/img/stm32cube_new_cmake.webp new file mode 100644 index 0000000000000..dd192cc1f2f75 Binary files /dev/null and b/doc/develop/tools/img/stm32cube_new_cmake.webp differ diff --git a/doc/develop/tools/img/stm32cube_preprocessor_include.webp b/doc/develop/tools/img/stm32cube_preprocessor_include.webp new file mode 100644 index 0000000000000..75ebe90f5d613 Binary files /dev/null and b/doc/develop/tools/img/stm32cube_preprocessor_include.webp differ diff --git a/doc/develop/tools/img/stm32cube_project_properties.webp b/doc/develop/tools/img/stm32cube_project_properties.webp new file mode 100644 index 0000000000000..d3717b41c2969 Binary files /dev/null and b/doc/develop/tools/img/stm32cube_project_properties.webp differ diff --git a/doc/develop/tools/index.rst b/doc/develop/tools/index.rst index 304a9bb811d0b..4114fdcae227a 100644 --- a/doc/develop/tools/index.rst +++ b/doc/develop/tools/index.rst @@ -8,4 +8,5 @@ Tools and IDEs clion.rst coccinelle.rst + stm32cubeide.rst vscode.rst diff --git a/doc/develop/tools/stm32cubeide.rst b/doc/develop/tools/stm32cubeide.rst new file mode 100644 index 0000000000000..73e160ee1ebe6 --- /dev/null +++ b/doc/develop/tools/stm32cubeide.rst @@ -0,0 +1,110 @@ +.. _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 + ``/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. + +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 + 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