.. _setup-cubemx-project:

Setup a CubeMx Project for your Ka-Ro board
===========================================

Developments for the Arm® Cortex®-M4 coprocessor normally start as a STM32CubeMx project.

STM32CubeMX is a graphical tool that allows a easy configuration of the processor chip pin configuration and clock tree,
as well as the generation of the corresponding initialization C code for the Arm® Cortex®-M4 coprocessor core and a partial
Linux device tree for Arm® Cortex®-A7 core, through a step-by-step process.

For download, install and further informations of the STM32CubeMx tool read: `STM32Cube initialization code generator <https://www.st.com/en/development-tools/stm32cubemx.html>`_.

.. admonition:: please note
	:class: tip

	For a quick starting point, Ka-Ro provides prepared CubeMx-Projects for its eval boards in the Ka-Ro download area. You need to be a registered customer to get access to our download area.

The STM32CubeMx project for the QSMP-1570-QSBASE1 can be downloaded here: https://www.karo-electronics.com/downloads/customer-area/customer-area-qsmp

After you have modified pin- and clock settings according to your project's needs, activate the "GENERATE CODE" - button to (re-)build the device trees
and to generate your basic Arm® Cortex®-M4 startup project.


.. admonition:: important
  :class: danger

  please save your formerly edited device tree files before you generate new code, as the STM32CubeMX tool overwrites - and partly deletes - your earlier edits.

The STM32CubeMX tool generates tf-a, u-boot and kernel- device tree files. These can be used by the OpenSTLinux yocto distribution.
Please note, these device tree files are not complete, to use them a lot of user edits are necesarry. To preserve your user edits when "GENERATE CODE",
it is important to edit them between between the comment lines:

.. code-block:: text

  /* USER CODE BEGIN ... */
     ...
     add your user edits here
     ...
  /* USER CODE END .. */

The STM32CubeMX tool also generates a startup project for the Arm® Cortex®-M4 coprocessor. This can be imported, build and debugged by the STM32CubeIDE.
For further informations, please read: `Integrated Development Environment for STM32 <https://www.st.com/en/development-tools/stm32cubeide.html>`_.