CachyOS / CachyOS/distribution
[Enhancement]: TL8761BU firmware: TP-Link UB500 supports BT 5.4 but linux-firmware only enables BT 5.1
- Dominant language
- No language data
- Stars
- 27
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
### Problem / Motivation
The TP-Link UB500 Bluetooth adapter uses the Realtek RTL8761BU chipset
(USB VID:PID 2357:0604). The hardware supports Bluetooth 5.4, but the
firmware blob shipped in `linux-firmware-realtek` (package version
1:20260622-1) only enables Bluetooth 5.1.
Current output:
$ bluetoothctl show
Version: 0x0a (10) # = Bluetooth 5.1
$ journalctl -k | grep "fw version"
Bluetooth: hci0: RTL: fw version 0xdfc6d922
The chip is capable of BT 5.4 but the open-source firmware blob from
Realtek is limited to BT 5.1 due to licensing restrictions. This means
all CachyOS users with this very popular adapter (~$10, one of the
best-selling BT dongles on Amazon) are stuck on an older Bluetooth
version despite their hardware supporting the latest.
This affects:
- TP-Link UB500 (all hardware versions V1-V3, same RTL8761BU chip)
- TP-Link UB500 Plus
- TP-Link UB5A
- Any other RTL8761BU-based USB Bluetooth adapter
### Proposed Solution
Create an opt-in package (e.g., `rtl8761bu-bt54-firmware` in AUR or
CachyOS repos) that:
1. Downloads the TP-Link UB500 V3 Windows driver package from the
official TP-Link website at install time:
https://static.tp-link.com/upload/driver/2025/202503/20250314/UB500_V3_Win10_Win11.zip
2. Extracts the firmware blob:
rtl8761b_mp_chip_bt40_fw_asic_rom_patch_new.dat
(located in: BT/plugins/Driver Files/Driver/Windows_11_64bit/)
3. Compresses it with XZ CRC32 (kernel requirement) and installs it to:
/lib/firmware/rtl_bt/rtl8761bu_fw.bin.xz
4. Includes a pacman hook (PostTransaction) that re-applies the firmware
after any linux-firmware update, since the package update overwrites
it back to the BT 5.1 version.
The btrtl kernel module already supports both firmware formats
("Realtech v1" and "RTBTCore v2") - no kernel changes needed.
The resulting Bluetooth version after applying the Windows firmware:
$ bluetoothctl show
Version: 0x0d (13) # = Bluetooth 5.4
$ journalctl -k | grep "fw version"
Bluetooth: hci0: RTL: fw version 0xddd5c761
### Alternatives Considered
1. Manual workaround (what I currently use):
- Download Windows driver, extract firmware, replace linux-firmware
version, reload btusb module
- Works perfectly but needs to be redone after every kernel/firmware
update
2. Pacman hook for auto-restore:
- I created a local hook at /etc/pacman.d/hooks/99-ub500-bt54.hook
that runs after linux-firmware updates to restore the BT 5.4 firmware
- This works but is a per-user hack, not a systemic solution
3. AUR package rtl8761b-firmware:
- Exists but contains OLDER firmware (described as "old firmware for
rtl8761b, new firmware have stability problems when used with xbox
controller")
- This goes in the opposite direction
4. Request upstream linux-firmware to include the newer blob:
- Not possible due to Realtek licensing - the Windows firmware is
proprietary and cannot be redistributed
The cleanest solution is option 1 (opt-in package that fetches from
TP-Link at install time) since the firmware cannot be included in repos
due to licensing.
### Additional Context
## Technical Details
- btrtl kernel module supports both firmware formats (no kernel patch needed)
- The Windows firmware uses "RTBTCore v2" format, Linux uses "Realtech v1"
- Both formats are parsed by drivers/bluetooth/btrtl.c in the kernel
- The firmware is uploaded to the chip via HCI vendor commands on every
USB plug-in (chip has no persistent storage)
## My Working Configuration
- Distro: CachyOS (Arch-based)
- Kernel: 7.1.5-1-cachyos
- Adapter: TP-Link UB500 V3 (RTL8761BU)
- Package: linux-firmware-realtek 1:20260622-1
- Before: BT 5.1 (fw version 0xdfc6d922)
- After: BT 5.4 (fw version 0xddd5c761)
- All paired devices work: Xbox Wireless Controller, Baseus Inspire XH1
## Files Involved
- Firmware source: rtl8761b_mp_chip_bt40_fw_asic_rom_patch_new.dat
(from TP-Link Windows driver, NOT redistributable)
- Target path: /lib/firmware/rtl_bt/rtl8761bu_fw.bin.xz
- Config path: /lib/firmware/rtl_bt/rtl8761bu_config.bin.zst (unchanged)
- Compression: xz --check=crc32 (kernel XZ decoder requires CRC32)
## Reference
Blog post documenting the same firmware upgrade for TP-Link UB600:
https://myshell.co.uk/blog/rtl8761bu-firmware-linux-ub600/
That post confirms btrtl supports both firmware formats and the Windows
blob enables the chip's full capability (BT 5.4 for UB500, BT 6.0 for
UB600).
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reviewing the proposed TP-Link driver URL, the source blob path `BT/plugins/Driver Files/Driver/Windows_11_64bit/rtl8761b_mp_chip_bt40_fw_asic_rom_patch_new.dat`, and the existing target `/lib/firmware/rtl_bt/rtl8761bu_fw.bin.xz`. Check the pacman hook approach and licensing constraints, then verify completion with `bluetoothctl show` and `journalctl -k | grep "fw version"`, which should report Bluetooth 5.4 and firmware version `0xddd5c761`.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- linux
- Domain
- operating-systems, release
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100