STM32CubeProgrammer

Applicable for

STM32MP13x lines, STM32MP15x lines, STM32MP21x lines, STM32MP23x lines, STM32MP25x lines

---

This article gives a short introduction to the official STM32CubeProgrammer tool:

• What are the flashing principles?
• Where to download the software? *

How to install it? How to use it?

1. STM32CubeProgrammer overview

STM32CubeProgrammer is the official STMicroelectronics tool for creating partitions into any Flash device available on STM32 platforms.
Once created, STM32CubeProgrammer allows populating and updating the partitions with the prebuilt binaries.

The connection between the host PC and the board can be done through UART or USB serial links.

Any Flash device supported on STM32MPU boards can be flashed using STM32CubeProgrammer. For example, for the STM32MP157 Evaluation board:

1. microSD^TM card
2. eMMC
3. NAND Flash memory
4. NOR Flash memory

During development, it is recommended to use a microSD card; you can then switch to eMMC or NAND Flash memory.

More details on supported Flash memory technologies and mapping can be found in Flash mapping articles, e.g. STM32 MPU Flash mapping.

OpenSTLinux generates flashlayout files only for USB programming mode. For UART usage, refer to Using_STM32Programmer_over_UART article to modify those files.

2. STM32CubeProgrammer installation

2.1. Installing the STM32CubeProgrammer tool

	STM32CubeProgrammer for Linux® host PC	STM32CubeProgrammer for Windows® host PC
Download	Version 2.5.0 To access the SetupSTM32CubeProgrammer link and follow instructions to download the package, you need a myST account. Download the archive file on your host PC in a temporary directory Uncompress the archive file to get the STM32CubeProgrammer installers: PC $>unzip en.stm32cubeprog.zip
Installation	Execute the Linux installer, which guides you through the installation process. $> ./SetupSTM32CubeProgrammer-2.5.0.linux The path to the STM32CubeProgrammer binary must be added to the PATH environment variable either in each Terminal program in which the STM32CubeProgrammer binary needs to be used, using the following command: $> export PATH=<my STM32CubeProgrammer install directory>/bin:$PATH or once for all by creating a link to the STM32CubeProgrammer binary in a directory already present in PATH. For example, if "/home/bin" is in the PATH environment variable, run the following command: $> ln -s <my STM32CubeProgrammer install directory>/bin/STM32_Programmer_CLI /home/bin/STM32_Programmer_CLI	Execute the Windows installer, which guides you through the installation process.
User manual	Instructions to follow for using the STM32CubeProgrammer can be found in user manual, UM2237 available from ST web site, or in STM32CubeProgrammer#How to flash with STM32CubeProgrammer article.
Detailed release note	Details about the content of this tool version are available from ST web site at Release Note .

2.2. Preparing the USB serial link for flashing

It is recommended to use the USB (in DFU mode) for flashing rather than the UART, which is too slow.

Below indications on how to install the USB in DFU mode under Linux and Windows OS, respectively.

• For Linux host PC or Windows host PC with VMWare:

The libusb1.0 package (including USB DFU mode) must be installed to be able to connect to the board via the USB port. This is achieved by typing the following command from the host PC terminal:

PC $>sudo apt-get install libusb-1.0-0

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

PC $>cd <your STM32CubeProgrammer install directory>/Drivers/rules 

PC $>sudo cp *.* /etc/udev/rules.d/

• For Windows host PC:

Run the “STM32 Bootloader.bat” file to install the STM32CubeProgrammer DFU driver and activate the STM32 microprocessor device in USB DFU mode. This driver (installed by STM32 Bootloader.bat) is provided within the STM32CubeProgrammer release package. It is located in the DFU driver folder, \Drivers\DFU_Driver.

In case of issue, refer to How to proceed when the DFU driver installation fails on Windows host PC.

To validate the installation, the DFU driver functionality can be verified by following the FAQ instructions provided in how to check if the DFU driver is functional.

STM32CubeProgrammer is now ready to use: to know more about this tool, continue reading; otherwise, jump to the Starter or Distribution Package article corresponding to your board: Category:Starter Package or Category:Distribution Package.

3. Flash programming principles

Flash programming consists in transferring the binaries stored on the host computer into the platform Flash memory(ies), via a serial interface.
This operation requires a communication interface between the STM32CubeProgrammer and an embedded programming service.

The selection of the binaries to download and the Flash memory destination is done through the flashlayout.tsv file.
The STM32Cubeprogrammer tool uses the Flashlayout.tsv file as an input.
The Flashlayout.tsv file includes a formal description of the partitions (ID, naming, type, offset) as well as the identification of the Flash memory to be populated.

Some default "tsv" files aligned with the STM32 Flash memory mapping (e.g.STM32_MPU_Flash_mapping) are provided in the STM32Cubeprogrammer tool. They can be used as a starting point and can be further adapted to specific application needs.

More examples as well as information on the description format are available in STM32CubeProgrammer flashlayout.

See AN5275: Introduction to USB DFU/USART protocols used in STM32MP1 and STM32MP2 MPU bootloaders for protocol details.

4. How to flash with STM32CubeProgrammer

Once the STM32CubeProgrammer has been installed, complete flashing procedures for STM32 boards are available in Starter Package and Distribution Package articles. Select the article corresponding to your STMicroelectronics platform.

The generic syntax of the STM32CubeProgrammer command is explained below.

• With Linux host PC, the main command is:

PC $>./bin/STM32_Programmer_CLI  + options given below

• With Windows host PC, the main command is:

PC $>./bin/STM32_Programmer_CLI.exe + options given below

The Linux related information provided below can be extrapolated for other host PC operating systems:

• Complete flashing command (for Linux host PC):

PC $> STM32_Programmer_CLI -c port=<DEVICE_PORT_LOCATION> -w [<file.tsv>]
where 
 w:
     Write
 <file.tsv>:PathToFlashlayout/flashlayout.tsv file (see above) 
         if Flashlayout and binaries are not in the same directory, then the path to the Flashlayout files must be precised.
 <DEVICE_PORT_LOCATION>:
         e.g. usb1 (case sensitive): for other options, refer to How to find the DEVICE_PORT_LOCATION parameter value for the USB link.

Populating all partitions can take a few minutes (depending mainly on the rootfs size).

5. FAQs

5.1. Where to find the STM32CubeProgrammer user manual

The user manual is available in ST deliveries under <STM32CubeProgrammer installation directory>/doc/UM2336.pdf (see Installing the STM32CubeProgrammer tool).

5.2. How to check if the DFU driver is functional

Prerequisites: STM32CubeProgrammer installation completed and STM32 board connected to the host PC.

First, activate the USB driver on Ubuntu on VMware Workstation Player (use VM Player menu "removable devices" to connect to STMicroelectronics DFU in HS mode), then execute the following command and check the result:

 PC $>STM32_Programmer_CLI -l usb

• If the DFU is functional, the result is similar to the following

     -------------------------------------------------------------------
                       STM32CubeProgrammer <tool version>                  
     -------------------------------------------------------------------

Total number of available STM32 device in DFU mode: 1

 Device Index           : USB1
 USB Bus Number         : 002
 USB Address Number     : 008
 Product ID             : USB download gadget@Device ID /0x500, @Revision ID /0x0000
 Serial number          : 0000000000
 Firmware version       : 0x0110
 Device ID              : 0x0500

• Otherwise, the DFU is not functional and the result is the following:

 ------------------------------------------------------------------
                      STM32CubeProgrammer <tool version>
 ------------------------------------------------------------------
 

  Warning: No STM32 device in DFU mode connected

5.3. How to proceed when the DFU driver installation fails on Windows host PC

Prerequisites: STM32CubeProgrammer installation completed.

The STM32 Bootloader.bat allows to install the DFU driver on a Windows PC (see Preparing the USB serial link for flashing). In case of failure, here is a typical error log:

c:\demo\MPU\stm32_programmer_package_v1.0.3_MPU\Drivers\DFU_Driver>"STM32 Bootloader.bat"
c:\demo\MPU\stm32_programmer_package_v1.0.3_MPU\Drivers\DFU_Driver>echo off Microsoft PnP Utility
Processing inf :            DFU_in_HS_Mode.inf
Failed to install the driver on any of the devices on the system : No more data is available.
Total attempted:              1
Number successfully imported: 0

This error occurs either because the STM32CubeProgrammer DFU driver is already installed or because the DFUSE driver is installed.

To verify if the STM32CubeProgrammer DFU driver is correctly installed on your Windows host PC, proceed as follow:

1. Connect the board to the Windows host PC.
2. Launch the Device Manager utility and execute the below action depending on your use case:

• The STM32CubeProgrammer DFU driver is not installed:

Execute the STM32 Bootloader.bat script to install it (see Preparing the USB serial link for flashing).

Figure 1: STM32CubeProgrammer’s DFU driver is not installed

• The DfuSe driver is installed and you must uninstall it.

Right click STM Device in DFU Mode and select Uninstall.

Figure 1: STM32 DFU Device with DfuSe Driver

• The STM32CubeProgrammer DFU driver is installed and ready to be used.

Figure 2: STM32 DFU Device with STM32_Programmer Driver

5.4. How to find the DEVICE_PORT_LOCATION parameter value for the USB link

Prerequisites: STM32CubeProgrammer installation completed and STM32 board connected to the host PC.

To find the value of the DEVICE_PORT_LOCATION corresponding to the USB link, use the following command:

PC $>STM32_Programmer_CLI -l usb
     -------------------------------------------------------------------
                       STM32CubeProgrammer <tool version>                  
     -------------------------------------------------------------------

Total number of available STM32 device in DFU mode: 1

 Device Index           : USB1
 USB Bus Number         : 002
 USB Address Number     : 008
 Product ID             : USB download gadget@Device ID /0x500, @Revision ID /0x0000
 Serial number          : 0000000000
 Firmware version       : 0x0110
 Device ID              : 0x0500

You can then report the value returned by the command line as explained in the How to flash with STM32CubeProgrammer chapter. Pay attention that the value must be written in lower case.

5.5. How to explore all the partitions of a populated microSD card

A populated microSD card can contain more than eight partitions, exceeding the number of partitions allowed by default in a Linux system.
At insertion step, you may get an 'Error mounting /dev/mmcblk0p9' or 'mount: cannot mount /dev/mmcblk0p9 read-only' error message.

By adding some options to modprobe, it is possible to allow more than eight partitions on a storage device:

PC $>echo 'options mmc_block perdev_minors=16' > /tmp/mmc_block.conf
PC $>sudo mv /tmp/mmc_block.conf /etc/modprobe.d/mmc_block.conf

5.6. How to update partitions

For partial Flash memory update, the flashlayout.tsv must be edited to select only the partition that needs to be updated (first column =1).
See STM32CubeProgrammer_flashlayout#Updating partitions for details and example, the rest of the procedure is the same.

On ST boards, if FSBL or SSBL partitions need to be updated, the Bin2boot fields must be configured with ST binaries, as described in STM32CubeProgrammer_flashlayout#Updating partitions using official bootloaders.

5.7. How to populate a microSD card inserted in a Linux host PC

STMicroelectronics distribution is delivered with the create_sdcard_from_flashlayout.sh script that allows to prepare and flash a microSD card image.

5.8. How to fuse OTP

STM32CubeProgrammer exports several capabilities that can be used to manage the OTP registers via the command line interface.

All STM32MP devices have OTP memory map that based on structure v2/v3.

Firmware program should be preceding installed which is necessary to expose the OTP partition having 0xF1 as partition ID.

there's two alternatives for easier OTP management :

1. Flash a TSV Flashlayout that contains the boot partitions 0x1 and 0x3 for testing.

2. Flash a simple TSV flashlayout basing on a single partition named STM32PRGFW_UTIL

5.8.1. Programming SAFMEM

Description: This command allows the user to program SAFMEM memory by modifying the OTP words. Able to write up to 96 words in the same command line.

Syntax: -otp write {lock} {word=[index] value=[val]…}

{lock} is optional to indicate that a lock was requested. If lock option is mentioned, all words passed in line will be locked. With lock: write the word then perform permanent lock. Without lock: update the word.

[index] The word index can be written in decimal or hex format.

[val] The value option should always accept hex values.

The tool will print the requests and the user can verify the operation before going head and It will prompt a confirmation message then the user can press yes/y or no/n to pursuit or stop the write operation.

Example STM32_Programmer_CLI.exe --connect port=usb1 –otp write word=52 value=0xAAAAAAA word=0x50 value=0xBBBBBBBB

Figure 1:OTP write command for OTP structure v2

5.8.2. Lock OTP command

Description: This command allows to permanent lock the mentioned words which are already written before. Able to write up to 96 words in the same command line.

Syntax: -otp lock {word=[index]…]

[index] word index can be written in decimal or hex format.

The tool will print the requested modifications and the user can verify the operation before going head (use yes/y or no/n to pursuit or stop)

Example STM32_Programmer_CLI.exe --connect port=usb1 –otp lock word=20 word=0x30

5.8.3. Display command

Description: This command allows the user to display all or parts of the OTP structure.

Syntax: -otp displ {word=[index]…}

{word=[index]…}  : is optional, able to display up to 96 specific words in the same command, The index value used to indicate the OTP word ID: value in decimal or hex format.

-otp displ  : Display all OTP words {version + Global State + OTP words}. Highlight the status word containing a state information {prog lock, read lock, read error, invalid}

Example
STM32_Programmer_CLI.exe --connect port=usb1 –otp displ word=8 word=0x10
STM32_Programmer_CLI.exe --connect port=usb1 –otp displ

Figure 1:Display all OTP words for structure v2

5.8.4. Download file command

Description: to fuse a binary file from a start word ID

Syntax: -otp fwrite {lock} [path.bin] word=[index]

{lock} : is optional to indicate the operation type, update, or permanent lock.

[path.bin] : is 32-bits aligned file, the tool makes padding values if the file is not aligned {warning message will be displayed}

[index] : value in hex/dec format {from 0 to 95 in decimal}

Example Program a PKH binary file starting from word number 24
STM32_Programmer_CLI.exe --connect port=usb1 -otp fwrite lock /user/home/pkh.bin word=24

It is possible also to manage the OTP registers through the UI using the OTP panel.

Figure: STM32CubeProgrammer OTP UI

5.9. How to program STPMIC NVM

Available on STM32MP15, STM32MP13 and in Trusted boot mode. It is not possible to program, with the STM32CubeProgrammer, the STPMIC NVM in OP-TEE based solution.

STM32CubeProgrammer requires to be connected to U-Boot in order to access STPMIC NVM alternate (0xF4).

Refer to #How to fuse STM32MP15x OTP chapter and follow same procedure to flash only the 2 first "boot" partitions with GUI.
Then disconnect from GUI and switch to CLI in a terminal.

This is procedure to modify NVM values.

• Read partition of PMIC and load it into a .bin file via USB

PC $>STM32_Programmer_CLI -c port=usb1  -rp 0xf4 0x0 0x8 $MySelectedPATH\PMIC_NVM_read.bin

• Read partition of PMIC and load it into a .bin file via UART

PC $>STM32_Programmer_CLI -c port=COM11 -rp 0xf4 0x0 0x8 $MySelectedPATH\PMIC_NVM_read.bin

• Backup it by creating a copy PMIC_NVM_write.bin
• Use a binary editor in HEX format ( eg "vi -b file.bin" then :%!xxd ) to edit the copy PMIC_NVM_write.bin with new values.
  

The binary format display the shadow register from 0xF8 to 0XFF. Refer to STPMIC1 DataSheet DS12792.

00000000: EE92 C002 F280  0233                      .......3
respectively SHR address :  F8F9 FAFB FCFD FEFF

• Program back the STPMIC with modified NVM via USB using following command:

PC $>STM32_Programmer_CLI -c port=usb1 -pmic "PMIC_NVM_write.bin"

• Program back the STPMIC with modified NVM via UART using following command:

PC $>STM32_Programmer_CLI -c port=COM11 -pmic "PMIC_NVM_write.bin"

It is possible also to manage the PMIC NVM registers through the UI using the PMIC panel.

Figure: STM32CubeProgrammer PMIC UI

Flash memory shortened to gain space in titles, tables and block diagrams

Universal asynchronous receiver/transmitter

Former spelling for e•MMC ('e' in italic)

Flash memories combine high density and cost effectiveness of EPROMs with the electrical erasability of EEPROMs. For this reason, the Flash memory market is one of the most exciting areas of the semiconductor industry today and new applications requiring in system reprogramming, such as cellular telephones, automotive engine management systems, hard disk drives, PC BIOS software for Plug & Play, digital TV, set top boxes, fax and other modems, PC cards and multimedia CD-ROMs, offer the prospect of very high volume demand.

Linux^® is a registered trademark of Linus Torvalds.

Device firmware upgrade

Operating system

High speed (MIPI^® alliance DSI standard)

Microprocessor unit

System trace module

First stage boot loader

Second stage boot loader

One time programmed

Public key hash, used for secure boot - NEW

User interface

Non volatile memory, like a flash memory

Open portable trusted execution environment

Das U-Boot -- the universal boot loader (see U-Boot)

Graphical user interface

Power management integrated circuit