the
1. Overview[edit source]
PRG-TOOLBOX-DFU is an open-source tool provided by STMicroelectronics. This tool automates the preparation of STM32 MPU devices through the USB DFU protocol, with the purpose to fuse OTP memory, and to run U-Boot in Fastboot mode.
The tool achieves the startup of the Fastboot mode without requiring any manual hardware setting. It is based on the U-Boot script.
The tool is a wrapper of dfu-util. It is specifically designed for STM32 MPU devices.
PRG-TOOLBOX-DFU provides a source application with the following characteristics:
- Language: Native C++ 11
- IDE: Qt® Creator
- Cross-platform: Windows®, Linux®
- Dependency: dfu-util
- Copyright: STMicroelectronics
- License: GPL v2.0
The functional chart of the tool, describing all involved components, is available below:
2. Prerequisites[edit source]
The tool is available in console mode. The next subsections present a few important points to keep in mind before preparing your development environment.
2.1. Hardware prerequisites[edit source]
- Check the boot pins to establish a connection in DFU mode (Refer to "Boot related switches" sections of hardware description articles for STM32MP1 series' boards
).
- Make sure that the STM32 MPU device used is supported by the tool.
2.2. Software prerequisites[edit source]
- Use the OpenSTLinux distribution software v5.0.3 release (or later). Refer to OpenSTLinux distribution software v5.0.3 release.
- Make sure to use firmware binaries that correspond to the specific board you are using; Otherwise, an error occurs.
- Activate U-Boot compiled with Fastboot. Refer to How to configure U-Boot to support Fastboot mode.
- Prepare a TSV flashlayout file describing the partitions and the memory map (refer to STM32CubeProgrammer flashlayout).
- Note that OTP management is only possible when U-Boot is running in DFU mode. Once the Fastboot mode is active, OTP management is no longer possible.
- It is possible to manage the OTP memory using STM32PRGFW-UTIL.
- STM32PRGFW-UTIL is not intended for activating the Fastboot mode.
2.3. Linux host environment[edit source]
To ensure that PRG-TOOLBOX-DFU has read and write access to the USB DFU devices exposed by the STM32 MPU device, you must install "udev" rules. This can be done by copying the rules file located in the /rules folder to the /etc/udev/rules.d/ directory.
Example on Ubuntu®</sup:
cd /PRG-TOOLBOX-DFU/rules
sudo cp *.* /etc/udev/rules.d
2.4. dfu-util[edit source]
PRG-TOOLBOX-DFU includes the "dfu-util" program in the project tree for Windows® platforms only.
For Linux® machines, the tool uses the dfu-util program already installed on the system. Install "dfu-util" yourself if it is not already installed on your system (refer to https://dfu-util.sourceforge.net).
sudo apt-get install dfu-util
At the start of execution, PRG-TOOLBOX-DFU checks whether" dfu-util" is installed and can be run.
If there is an issue with the execution of "dfu-util", an error message is displayed (refer to source file Src/DFU.cpp):
dfu-util is not installed or cannot be found. Please install it and try again.
3. License[edit source]
PRG-TOOLBOX-DFU is released under the GNU General Public License version 2.
A copy of the GNU General Public License version 2 is delivered with the source code of the tool.
4. How to build the PRG-TOOLBOX-DFU project[edit source]
The package provides a preconfigured Qt® project (see .pro file). There are three ways to compile the project:
- 1- Qt® Creator IDE: Open the project in the IDE, configure your kit compiler, and run the build.
- 2- Qmake: It is possible to compile the project in the command line without using the Qt® Creator IDE by following the next steps:
- Run the qmake command: qmake PRG-TOOLBOX-FB.pro
- Run the make command to build your project: make (or "mingw32-make.exe" on Windows®)
- 3- Makefile: First create your own Makefile to be able to build the project without the need to install Qt® Creator. Then execute the "make" command.
If you do not intend to use the Qt® Creator IDE on your Linux® machine, you can simply install the qmake component along with its Qt® libraries. To do so, execute the following commands in the terminal before launching qmake:
sudo apt update sudo apt install qtbase5-dev sudo apt install qt5-qmake qttools5-dev-tools
Make sure that a C++ compiler is already installed on your machine, or install it if it is not the case.
sudo apt install build-essential
Once the build process is complete, an executable file is generated in the same directory as the .pro file. On Windows®, you must install Qt® Creator on your machine.
5. Command usage[edit source]
The tool includes a set of command lines that enable users to easily configure and manage their STM32 MPU devices.
If an error occurs during the execution of an operation, the return code is set to 1 (EXIT_FAILURE) and exit follows immediately.
However, if the command operation is executed successfully, the return code is set to 0 (EXIT_SUCCESS), indicating a successful operation.
5.1. Help[edit source]
To show the help menu:
Syntax: -?, -h, --help
5.2. Version[edit source]
To display the version of the tool in format x.y.z [Major.Minor.Patch]:
Syntax: -v, --version
5.3. Download[edit source]
To download the boot partitions and prepare the device to switch to Fastboot mode:
Syntax: -d, --download <filePath.tsv> <fastboot=0/1>
- <filePath.tsv>: Indicates the TSV file path describing the flash memory layout.
- <fastboot=0/1>: Optional flag. If it is equal to 1, the tool initiates the programming process and launches Fastboot. If the argument is equal to 0, the tool initiates the programming process, but Fastboot is not be launched, and the device remains in DFU mode (this is the case to manage the OTP partition in the next step). If this option is not specified, the tool operates with fastboot=1 by default.
Example for STM32MP157F-EV1 Evaluation board :
PRG-TOOLBOX-DFU -d FlashLayout_emmc_stm32mp157f-ev1-fastboot.tsv fastboot=1
The tool makes several checks and follows a specific sequence to program the boot partitions and to establish the Fastboot mode. At the end of the programming process, the tool displays the total elapsed time in the following format: [x] minutes, [y] seconds, [z] milliseconds.
- Start U-Boot in Fastboot mode
PRG-TOOLBOX-DFU -d FlashLayout_sdcard_stm32mp157c-dk2-optee.tsv
[Output example] ----------------------------------------- TSV DFU downloading... TSV path : FlashLayout_sdcard_stm32mp157c-dk2-optee.tsv Partitions number : 2 U-Boot script size : 106 Bytes Start Fastboot : Yes Boot Application : U-Boot ----------------------------------------- [Info]: No U-Boot in Fastboot mode is running ! can't get debug descriptor: No such file or directory STM32 device ID = 0x500 DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -l [Info]: U-Boot in DFU mode is not running ! Partition index : 1 Firmware path : mp15-dk2-otp/tf-a-stm32mp157c-dk2-usb.stm32 DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -a 1 -D mp15-dk2-otp/tf-a-stm32mp157c-dk2-usb.stm32 Warning: Invalid DFU suffix signature A valid DFU suffix will be required in a future dfu-util release OUTPUT: dfu-util 0.11 Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. Copyright 2010-2021 Tormod Volden and Stefan Schmidt This program is Free Software and has ABSOLUTELY NO WARRANTY Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ Opening DFU capable USB device... Device ID 0483:df11 Device DFU version 0110 Claiming USB DFU Interface... Setting Alternate Interface #1 ... Determining device status... DFU state(2) = dfuIDLE, status(0) = No error condition is present DFU mode device DFU version 0110 Device returned transfer size 1024 Copying data from PC to DFU device Download [=========================] 100% 226117 bytes Download done. DFU state(7) = dfuMANIFEST, status(0) = No error condition is present DFU state(2) = dfuIDLE, status(0) = No error condition is present Done! Phase ID 1 : Download Done . . . Opening DFU capable USB device... Device ID 0483:df11 Device DFU version 0110 Claiming USB DFU Interface... Setting Alternate Interface #0 ... Determining device status... DFU state(2) = dfuIDLE, status(0) = No error condition is present DFU mode device DFU version 0110 Device returned transfer size 4096 Detach Done U-Boot in Fastboot mode is running ! Time elapsed to start fastboot: 00:14:513!
- Start U-Boot in DFU mode
PRG-TOOLBOX-DFU -d FlashLayout_sdcard_stm32mp157c-dk2-optee.tsv fastboot=0
----------------------------------------- TSV DFU downloading... TSV path : FlashLayout_sdcard_stm32mp157c-dk2-optee.tsv Partitions number : 2 U-Boot script size : 106 Bytes Start Fastboot : No Boot Application : U-Boot ----------------------------------------- [Info]: No U-Boot in Fastboot mode is running ! can't get debug descriptor: No such file or directory STM32 device ID = 0x500 DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -l [Info]: U-Boot in DFU mode is not running ! Partition index : 1 Firmware path : mp15-dk2-otp/tf-a-stm32mp157c-dk2-usb.stm32 DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -a 1 -D mp15-dk2-otp/tf-a-stm32mp157c-dk2-usb.stm32 Warning: Invalid DFU suffix signature A valid DFU suffix will be required in a future dfu-util release OUTPUT: dfu-util 0.11 Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. Copyright 2010-2021 Tormod Volden and Stefan Schmidt This program is Free Software and has ABSOLUTELY NO WARRANTY Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ Opening DFU capable USB device... Device ID 0483:df11 Device DFU version 0110 Claiming USB DFU Interface... Setting Alternate Interface #1 ... Determining device status... DFU state(2) = dfuIDLE, status(0) = No error condition is present DFU mode device DFU version 0110 Device returned transfer size 1024 Copying data from PC to DFU device Download [=========================] 100% 226117 bytes Download done. DFU state(7) = dfuMANIFEST, status(0) = No error condition is present DFU state(2) = dfuIDLE, status(0) = No error condition is present Done! Phase ID 1 : Download Done . . . Opening DFU capable USB device... Device ID 0483:df11 Device DFU version 0110 Claiming USB DFU Interface... Setting Alternate Interface #0 ... Determining device status... DFU state(2) = dfuIDLE, status(0) = No error condition is present DFU mode device DFU version 0110 Device returned transfer size 1024 Detach Done DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -l U-Boot in DFU mode is running ! Time elapsed to launch U-Boot in DFU mode: 00:12:296
5.4. OTP[edit source]
Read and write from and to the OTP partition.
Syntax: -otp, --otp <operationType> <filePath.bin>
- <operationType>: read/write
- <filePath.bin>: Indicates the binary file path including the OTP contents (input binary for write operation and output binary for read operation).
Note that to manage the OTP memory, an OTP partition must be exposed in DFU mode. If this partition is not available, the command fails.
![]() |
To properly manage the OTP partition, it is essential that the embedded application being used is capable of exposing the OTP partition [0xF2] and supporting fuse operations. |
The tool can program the STM32PRGFW-UTIL and handle the OTP partition without activating the Fastboot mode “fastboot=0” (-d FlashLayout_STM32PRGFW_UTIL.tsv fastboot=0 -otp read otp_memory_mp15.bin).
PRG-TOOLBOX-DFU -otp read otp_read_mp15_dk.bin [Output example] ----------------------------------------- DFU reading... OTP partition : 0xF2 Output file path : otp_read_mp15_dk.bin ----------------------------------------- STM32 device ID = 0x500 DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -l OTP partition name="@OTP/0xf2/1*776Be" U-Boot in DFU mode is running ! DFU-UTIL command: dfu-util.exe -d 0483:df11 -a "@OTP/0xf2/1*776Be" -U otp_read_mp15_dk.bin Read OTP partition is done successfully !
Refer to this wiki page to obtain all the necessary information regarding the write operation and specifications of the fuse: STM32CubeProgrammer OTP management.
PRG-TOOLBOX-DFU -otp write otp_mp15_dk.bin ----------------------------------------- DFU downloading... OTP partition : 0xF2 Input file path : otp_mp15_dk.bin ----------------------------------------- STM32 device ID = 0x500 DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -l OTP partition name="@OTP/0xf2/1*776Be" U-Boot in DFU mode is running ! DFU-UTIL command: dfu-util.exe -d 0483:df11 -a "@OTP/0xf2/1*776Be" -D otp_mp15_dk.bin Warning: Invalid DFU suffix signature A valid DFU suffix will be required in a future dfu-util release Write OTP partition is done successfully !
6. How to get PRG-TOOLBOX-DFU[edit source]
Refer to the following link to find the PRG-TOOLBOX-DFU GitHub repository.
7. FAQ[edit source]
- What are the supported STM32 MPU products?
It is a generic code for all STM32 MPU devices, but you must use the corresponding binaries. Consider that the boot sequence to install U-Boot may be different from one STM32 MPU series to another. (refer to Install U-Boot).
- Can I manage the OTP partition using U-Boot?
Yes, it is possible if U-Boot implements the management of the OTP partition.
- Is it possible to select the STM32 DFU device by its serial number?
The current version does not have the capability to select a USB device by its serial number. Instead, the tool automatically selects the first STM32 USB device that is plugged in and has a Product ID of 0x483 and a Vendor ID of 0xDF11.