.. _stm32-programmer-setup:

STM32CubeProgrammer
===================

Installing STM32CubeProgrammer [1]_
-------------------------------------

.. tip:: The CubeProgrammer is just one (slow) way to flash our STM32 based modules.
   Since *kirkstone* release version you can also use fastboot protocol to flash a module.

   For more read :ref:`stm-fast-flashing`


STM32CubeProgrammer requires 1.8 version of the Java platform.

.. prompt::
   :prompts: $

   sudo apt install openjdk-8-jre
   sudo update-alternatives --config java

Select the java-8-openjdk configuration.

Create a directory on your computer:

.. prompt::
   :prompts: $

   mkdir $HOME/STM32MPU_workspace/STM32MPU-Tools
   mkdir $HOME/STM32MPU_workspace/STM32MPU-Tools/STM32CubeProgrammer-2.4.0

Download the `STM32CubeProgrammer v2.4.0 <https://www.st.com/en/development-tools/stm32cubeprog.html#getsoftware-scroll>`_ to your computer.

Uncompress the archive file to get the STM32CubeProgrammer installers:

.. prompt::
   :prompts: $

   unzip SetupSTM32CubeProgrammer.zip

Execute the Linux installer, which guides you through the installation process. Select "$HOME/STM32MPU-Tools/STM32CubeProgrammer-2.4.0" as the installation directory, when it's requested by the installer.

.. prompt::
   :prompts: $

   ./SetupSTM32CubeProgrammer-2.4.0.linux

Add the STM32CubeProgrammer binary path to your PATH environment variable. So append the ``~/.bashrc`` with:

.. code-block:: text

   export PATH=$HOME/STM32MPU_workspace/STM32MPU-Tools/STM32CubeProgrammer-2.4.0/bin:$PATH

After this re-source ``~/.bashrc``:

.. prompt::
   :prompts: $

   source ~/.bashrc

Check that the STM32CubeProgrammer tool is properly installed and accessible:

.. prompt::
   :prompts: $

   STM32_Programmer_CLI --h

.. code-block:: text

   -------------------------------------------------------------------
                     STM32CubeProgrammer v2.4.0
   -------------------------------------------------------------------

USB serial link
--------------------

Install the libusb on your host computer:

.. prompt::
   :prompts: $

   sudo apt install libusb-1.0-0

To allow STM32CubeProgrammer to access the USB port through low-level commands, proceed as follows:

.. prompt::
   :prompts: $

   cd $HOME/STM32MPU_workspace/STM32MPU-Tools/STM32CubeProgrammer-2.4.0/Drivers/rules
   sudo cp *.* /etc/udev/rules.d/

Flash the eMMC
----------------

1. Enable the USB-bootmode on your Development Kit. If you need help see :ref:`enabling-bootmode`.

2. Plug-in the Development Kit to power it up.

3. Press the reset button.

4. Go to the directory where your Images have been deployed to, or you downloaded our precompiled images to.

The following directory is an example, in this case its from a Yocto deploy.

.. prompt::
   :prompts: $

   cd $HOME/yocto/karo-bsp/tmp/deploy/images/<machine-name>

5. Get the device port location for the USB link.

.. prompt::
   :prompts: $

   STM32_Programmer_CLI -l usb

.. code-block:: text

   -------------------------------------------------------------------
                     STM32CubeProgrammer v2.4.0
   -------------------------------------------------------------------

   =====  DFU Interface   =====

   Total number of available STM32 device in DFU mode: 1

   Device Index           : USB1 <--- see this
   USB Bus Number         : 001
   USB Address Number     : 005
   Product ID             : DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
   Serial number          : 0042001E3438511438333630
   Firmware version       : 0x0110
   Device ID              : 0x0500

6. Program the eMMC with the images in **flashlayout_<image-name>/** folder.


.. prompt::
   :prompts: $

   STM32_Programmer_CLI -c port=usb1 -w flashlayout_karo-image-weston/FlashLayout_emmc_stm32mp157c-qsmp-1570-basic.tsv

.. tip:: After the setup has run you can disable bootmode USB and reset your board. You eventually have to fit your **U-Boot environment** to let the image boot. See below.

.. note:: The ``.tsv`` flashlayout documentation is available at https://wiki.st.com/stm32mpu/wiki/STM32CubeProgrammer_flashlayout

.. [1] From https://wiki.st.com/stm32mpu/index.php/Getting_started/STM32MP1_boards/STM32MP157C-DK2/Let%27s_start/Populate_the_target_and_boot_the_image


U-Boot Environment
-------------------

Since we are not able to program the U-Boot environment with the ``STM32_Programmer_CLI``, you will have to change it to boot your module.

With :ref:`uuu` you can do this via the script, and can ignore further steps.


1. Resetting the environment to default.

.. prompt::
   :prompts: U-Boot>

   env default -a
   saveenv

2. Resetting the board to get the uuid of the RootFS automatically loaded.

.. prompt::
   :prompts: U-Boot>

   reset

Break into U-Boot prompt again by hitting any key.

3. Set correct init for systemd images:

.. prompt::
   :prompts: U-Boot>

   setenv append_bootargs init=/sbin/init
   saveenv

4. Boot the module:

.. prompt::
   :prompts: U-Boot>

   boot