Guide for STLINK-V3MODS: Resolve BRG_ERROR issue on macOS

[akospasztor]

Hi there,

First of all, huge thanks for your project, it's awesome! I decided to create this issue to help the folks like me who are dealing with BRG_ERROR issues on macOS.

Note: I tried the exact test below on a freshly configured raspberry pi and it worked out-of-the-box. The issue is related to macOS.

Setup

• STLINK-V3MODS
• MacBook Pro M3 Max running the latest macOS (Sequoia 15.3.1)

The STLINK is original, appears properly in macOS, running ioreg -p IOUSB -l -w 0 gives the expected results, and of course it functions properly using the STM32CubeProgrammer software.

Issue

TL;DR: scroll down for the solution.

Consider the following python script:

import stbridge as st
...
dev = st.USBInterface.list_devices()[0]

Running the script resulted in the following error:

❯ python demo.py
libusb: warning [ep_to_pipeRef] no pipeRef found with endpoint address 0x06.
libusb: error [submit_bulk_transfer] endpoint not found on any open interface
libusb: warning [ep_to_pipeRef] no pipeRef found with endpoint address 0x06.
libusb: error [submit_bulk_transfer] endpoint not found on any open interface
Traceback (most recent call last):
  File "/Users/akos/Projects/redacted/demo.py", line 11, in <module>
    main()
  File "/Users/akos/Projects/redacted/demo.py", line 7, in main
    dev = st.USBInterface.list_devices()[0]
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
RuntimeError: BRG_ERROR: 3

No matter what I tried - installing it via pip, compiled it from source, I always faced this exact issue. BRG_ERROR: 3 corresponds to BRG_USB_COMM_ERR, which is an "USB Communication error".

After searching for a solution unsuccessfully, I stumbled upon an answer on StackOverflow to a libusb-related problem on macOS, specifically that if a device is also recognized by another driver (from Apple), then it cannot be accessed. Before starting pointlessly unloading drivers with kextunload, I saw a mass storage driver in the kextstat output that gave me the lightbulb-moment.

I realized that the STLINK in question also mounts itself as a mass storage device (allowing to copy binaries onto that will be flashed into the target MCU). Simply unmounting the storage did not resolve the problem. However, I remembered that the default behavior (Debug + VCP + Mass Storage + Bridge) can be changed via the STM32CubeProgrammer software.

Solution

• Connect the STLINK and open the STM32CubeProgrammer tool.
• Click on the Firmware upgrade button on the right panel, then click on the Open in update mode button in the popup window.
• Tick the Change Type checkbox and change the option to: STM8/STM32 Debug + 2VCP + Bridge.
• Click on Upgrade.

Running the above demo code immediately started working.

Conclusion

The default mode of the STLINK device (Debug + VCP + Mass Storage + Bridge) mounts the STLINK in mass storage mode as well. The MSC (Mass Storage Class) driver from macOS seems to block the bridge access to the device. Reconfiguring the device to use 2 VCPs instead of the default VCP+MSC resolves the issue.

[dragonlock2]

Nice find thanks! I use 2 VCP mode myself so have never come across this issue. Will leave this ticket open in case future users have the same issue.