CachyOS / CachyOS/distribution

[Enhancement]: TL8761BU firmware: TP-Link UB500 supports BT 5.4 but linux-firmware only enables BT 5.1

Open
#526 1 comment 0 reactions 0 assignees View on GitHub
enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.