ST-Link connection

ST-LINK driver

To connect to an STM32 device through a debug interface using ST-LINK/V2, ST-LINK/V2-1, ST-LINK-V3, or ST-LINKV3Power, install the ST-LINK driver by running the stlink_winusb_install.bat file. This driver is provided with the release package and can be found under the Driver/stsw-link009_v3 folder.

Linux install

If you are using a USB port to connect to the STM32 device, install the libusb1.0 package by typing the following command:

sudo apt-get install libusb-1.0.0-dev

When using ST-LINK or J-Link probes, or USB DFU to connect to a target, copy the rules files located under the Driver/rules folder into /etc/udev/rules.d/ on Ubuntu:

sudo cp *.* /etc/udev/rules.d

Note

libusb1.0.12 version or higher is required to run STM32CubeProgrammer.

Docker and Ubuntu

When using USB DFU in a Docker context, it is often necessary to have the device rules installed on the host machine and create the container using the following flags:

-v /dev:/dev --device /dev:/dev
--net=host

The first flag gives the container access to the devices on the host machine. The second lets the container communicate udev host events.

VirtualBox

For optimal performance when using STM32CubeProgrammer in a VirtualBox VM context, it is recommended to switch the USB controller to the USB 3.0 (xHCI) controller in Settings > USB.

Fedora

To install the libusb package, execute the following command:

sudo dnf install libusb1

To install STM32CubeProgrammer on Linux, download and extract the zip package on your Linux machine from the STM32CubeProg-Linux part number on the website, then execute SetupSTM32CubeProgrammer-vx.y.z.linux to go through the installation process. In Ubuntu 20, the STM32CubeProgrammer icon is not enabled by default. To enable it, right-click the icon and choose Allow launching.

DFU driver

If you are using the STM32 device in USB DFU mode, install the STM32CubeProgrammer DFU driver by running the STM32 Bootloader.bat file. This driver is provided with the release package and can be found in the DFU driver folder.

If the DFUSE driver is already installed on your machine, first uninstall it, then reboot the machine and run the previously mentioned .bat file. When uninstalling, check the Delete the driver software for this device option to avoid reinstalling the old driver the next time a board is plugged in.

Fig. 150 Deleting the old driver software

Fig. 151 STM32 DFU device with DfuSe driver

Fig. 152 STM32 DFU device with STM32CubeProgrammer driver

Note

When using the USB DFU interface or the ST-LINK interface on a Windows 7 PC, ensure that all USB 3.0 controller drivers are up to date. Older driver versions can contain bugs that prevent access or cause connection problems with USB devices.

Target configuration panel

This is the first panel to look at before connecting to a target. It allows the user to select the target interface, either the debug interface using an ST-LINK or J-Link debug probe, or the bootloader interface over UART, USB, SPI, CAN, or I2C.

With the refresh button, the user can check the available interfaces connected to the PC. If this button is pressed while the ST-LINK or J-Link interface is selected, the tool checks the connected ST-LINK or J-Link probes and lists them in the Serial numbers combo box. If the UART interface is selected, it checks the available communication ports of the PC and lists them in the Port combo box. If the USB interface is selected, it checks the USB devices in DFU mode connected to the PC and lists them in the Port combo box. Each interface has its own settings to configure before connection.

ST-LINK settings

Fig. 153 ST-LINK configuration panel

• Serial number: this field contains the serial numbers of all connected ST-LINK probes. The user can choose one of them based on its serial number.

• Port: ST-LINK probe supports two debug protocols, JTAG and SWD.

  Note

  JTAG is not available on all embedded ST-LINK interfaces on STM32 Nucleo or Discovery boards.

• Frequency: the JTAG or SWD clock frequency.

• Access port: selects the access port to connect to. Most STM32 devices have only one access port, which is access port 0.

• Mode:

  • Normal: with Normal connection mode, the target is reset then halted. The reset type is selected using the Reset mode option.

  • Connect under reset: this mode enables connection to the target using a reset vector catch before executing any instructions. This is useful, for example, when the target contains code that disables the JTAG or SWD pins.

  • Hot plug: enables connection to the target without a halt or reset. This is useful for updating RAM addresses or IP registers while the application is running.

  • Power down: used to put the target in debug mode, even if the application has not started since target power-up. The hardware reset signal must be connected between ST-LINK and the target. This feature may not be fully effective on some boards such as MB1360, MB1319, MB1361, and MB1355 with STMPS2141 power switch.

  • hwRstPulse: the tool generates a reset pulse, then connects to the target. This connection mode does not prevent application launch before connection. It is used on some devices where under-reset mode is not available, such as STM32WB0x and STM32WL33.

• Reset mode:

  • Software system reset: resets all STM32 components except the Debug block through the Cortex-M application interrupt and reset control register (AIRCR).

  • Hardware reset: resets the STM32 device through the nRST pin. The RESET pin of the JTAG connector (pin 15) must be connected to the device reset pin.

  • Core reset: resets only the Cortex-M through the AIRCR.

• Speed (Cortex-M33 only):

  • Reliable: allows the user to connect in slow mode.

  • Fast: allows the user to connect in fast mode.

• Shared: enables shared mode allowing connection of two or more instances of STM32CubeProgrammer or another debugger to the same ST-LINK probe.

• Debug in low-power mode (STM32U5/WB/L4 series only): sets the bits in DBGMCU_CR to 1.

• External loader: displays the name of the external memory loader selected in the External loaders panel accessible from the main menu (Hamburger menu).

• Target voltage: target voltage is measured and displayed.

• Firmware version: displays the ST-LINK firmware version. The firmware upgrade button allows you to upgrade the ST-LINK firmware.

Log messages

• Starting Automatic Mode…

  Indicates that the system successfully entered the automatic process.

• More than one ST-LINK probe detected! Keep only one ST-LINK probe!

  Automatic mode cannot be used if more than one ST-LINK probe is connected to the computer when using JTAG or SWD interfaces. A message is displayed asking the user to keep only one ST-LINK probe connected to continue using this mode.

• More than one ST-LINK Bridge detected! Keep only one ST-LINK Bridge!

  Automatic mode cannot be used if more than one ST-LINK bridge is connected to the computer when using the SPI, CAN, or I2C bootloader interfaces. A message is displayed asking the user to keep only one ST-LINK bridge connected to continue using this mode.

• More than one ST-LINK USB DFU detected! Keep only one USB DFU!

Connect command

-c, --connect

Description: Establishes the connection to the device. This command allows the host to open the chosen device port (UART/USB/JTAG/SWD/JLINK/SPI/CAN/I2C).

Syntax:

-c port=<Portname> [noinit=<noinit_bit>] [options]

Common parameters

• port=<Portname>: Interface identifier, for example COMx on Windows, /dev/ttySx on Linux, usbx for USB, or SPI, I2C, and CAN for the corresponding interfaces.

• [noinit=<noinit_bit>]: Sets No Init bits, value in {0, 1}, default 0. noinit=1 can be used if a previous connection is already active.

ST-LINK options

CLI location by platform:

• macOS x86_64: STM32CubeProgrammer.app/Contents/MacOs/bin/STM32_Programmer_CLI

• macOS aarch64: STM32CubeProgrammer.app/Contents/Resources/bin/STM32_Programmer_CLI

• Windows: ..\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin\STM32_Programmer_CLI.exe

• Linux: ../STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/STM32_Programmer_CLI

Supported connection options:

• [freq=<frequency>]: Frequency in kHz used for connection. Default is 4000 kHz for SWD and 9000 kHz for JTAG.

• [reset=<mode>]: Reset mode. Possible values are SWrst, HWrst, and Crst. The default value is SWrst. When using UR connection mode, the reset mode is HWrst.

  • HWrst: Hardware reset. Performed by the ST-LINK, which physically drives the MCU NRST pin. The ST-LINK NRST pin must be connected to the MCU.

  • SWrst: Software reset through Cortex registers.

  • Crst: Core reset through Cortex registers.

Note

Entered frequency values are rounded to the values supported by the ST-LINK probe.

• [index=<index>]: Debug probe index. Default value is 0.

• [sn=<serialNumber>]: Serial number of the debug probe. Use this when you need to connect to a specific ST-LINK probe. Do not use this option together with index in the same connect command.

• [mode=<mode>]: Connection mode. Values are NORMAL, UR, HOTPLUG, POWERDOWN, and hwRstPulse. Default is NORMAL.

  • NORMAL: The target is reset, then halted. The reset type is selected using the Reset mode option.

  • UR: Connect Under Reset mode enables connection to the target using a reset vector catch before executing any instruction. This is useful, for example, when the target contains code that disables the JTAG or SWD pins.

  • HOTPLUG: Hot Plug mode enables connection to the target without a halt or reset. This is useful when updating RAM addresses or IP registers while the application is running.

  • POWERDOWN: Puts the target in debug mode even if the application has not started since power-up. The hardware reset signal must be connected between ST-LINK and the target. This feature might not be fully effective on boards such as MB1360, MB1319, MB1361, and MB1355 with STMPS2141 power switch.

  • hwRstPulse: The tool generates a reset pulse and then connects to the target. This mode does not prevent application launch before connection. It is used on devices where under-reset mode is not available, such as STM32WB0x and STM32WL33.

• [ap=<accessPort>]: Access port index. Default value is 0.

• [speed=]: Connection speed. Default is Reliable. Available only for Cortex-M33.

  • Reliable: Allows the user to connect in slow mode.

  • Fast: Allows the user to connect in fast mode.

• [shared]: Enables shared mode, allowing connection of two or more instances of STM32CubeProgrammer or another debugger to the same ST-LINK probe.

• [tcpport=<Port>]: Selects the TCP port to connect to an ST-LINK server. The shared option must be selected. The default value is 7184.