btusb-13d3-3625-dkms

Linux Bluetooth fix for 13d3:3625 (MediaTek MT7922)

Temporary cross-distribution DKMS workaround for the IMC Networks / MediaTek MT7922 Bluetooth device 13d3:3625, found for example in the Mercusys MA80XE AX3000 adapter.

Does this match your system?

Check for the exact USB ID:

lsusb -d 13d3:3625

Affected systems typically report:

ID 13d3:3625 IMC Networks Wireless_Device
Bluetooth: hci0: Opcode 0x0c03 failed: -110
No default controller available

This workaround only targets USB ID 13d3:3625. Similar symptoms with another USB ID have a different cause.

On kernels that do not contain the device’s quirk-table entry, it reaches the generic btusb path without using the MediaTek initialization callbacks.

This project adds:

{ USB_DEVICE(0x13d3, 0x3625), .driver_info = BTUSB_MEDIATEK |
                                             BTUSB_WIDEBAND_SPEECH },

The device ID fix has been accepted into the Bluetooth maintainer tree as commit ddd25808d4c2. It may not yet be present in mainline or distribution kernels. Replacing an in-tree driver with DKMS should remain a temporary workaround until the running distribution kernel contains that commit or an equivalent backport.

How it works

For each target kernel, pre_build.sh:

1. verifies, when the target configuration is available, that btusb is a loadable module rather than built into or disabled in the kernel;
2. uses the target build tree selected by DKMS (including --kernelsourcedir);
3. prefers btusb.c and its local headers from the distribution’s kernel source tree, including a separate source tree used by O= builds;
4. otherwise derives the upstream release tag from the kernel build Makefile and downloads the matching files from kernel.org;
5. applies the strict patch, with an anchored fallback for harmless context changes;
6. verifies the device ID and the flags required by that kernel generation;
7. lets DKMS build and install only btusb.ko under updates/dkms.

The version mapping uses the kernel build metadata and handles versions such as:

• 7.0.0 -> upstream tag v7.0
• 7.0.12 -> upstream tag v7.0.12
• 7.1.0-rc3 -> upstream tag v7.1-rc3

Compatibility and limitations

The module is distribution-agnostic, but no out-of-tree replacement for a kernel driver can guarantee compatibility with every kernel build.

The target system must provide:

• Bash, DKMS, make, a compatible compiler, curl, patch, Perl and standard GNU utilities;
• the headers/development package matching the target kernel;
• CONFIG_BT_HCIBTUSB=m; a DKMS module cannot replace a built-in CONFIG_BT_HCIBTUSB=y driver;
• /lib/modules/<kernel>/build or /usr/lib/modules/<kernel>/build;
• network access to kernel.org when the full local kernel source is unavailable;
• an upstream release tag matching the distribution kernel’s base version.

Distribution and vendor kernels can carry btusb fixes that are absent from the matching upstream release tag. Install the exact distribution/vendor source tree whenever possible. If the kernel.org fallback is used, the build prints a warning because the resulting module will not contain distribution-specific btusb backports.

If 13d3:3625 is already present with the correct flags, the patch is skipped. DKMS still builds an unmodified target-version btusb.ko, because a successful DKMS build must produce its declared module. Remove this package once the running distribution kernel contains the fix; DKMS cannot safely uninstall itself during a kernel package transaction.

CI combines fixture tests for old and current source layouts, configuration states and safe download options with real DKMS builds against the packaged kernel headers from current Ubuntu, Debian, Fedora, Arch Linux and openSUSE images. It cannot test module loading, Bluetooth hardware, Secure Boot key enrollment or every release and vendor kernel.

Security and reproducibility

The kernel.org fallback downloads tagged source over HTTPS during the privileged DKMS build. This is convenient for a manual workaround, but it is not an offline or fully reproducible packaging model. A distribution package should instead provide the exact reviewed source as a package input and verify its checksum or signature before the build. Vendor kernels should provide their matching local source tree. Downloads are restricted to HTTPS, including redirects, and have bounded connection and transfer times; these transport controls do not cryptographically pin the source content.

With AUTOINSTALL="yes", a kernel upgrade performed offline can fail its DKMS post-install step when local kernel sources are unavailable. Restore network access and rerun the distribution’s kernel configuration/upgrade command, or install the exact local kernel source before retrying.

Prerequisites

Install DKMS, the matching kernel headers/devel package, a compiler toolchain, curl, patch and Perl. Package names vary by distribution.

Examples:

# Debian / Ubuntu
sudo apt install dkms build-essential linux-headers-$(uname -r) curl patch perl

# Arch Linux; use the matching headers package for custom kernels
sudo pacman -S --needed dkms base-devel linux-headers curl patch perl

# Fedora
sudo dnf install dkms gcc make kernel-devel-$(uname -r) curl patch perl

# openSUSE
sudo zypper install dkms gcc make kernel-devel curl patch perl

Install

git clone https://github.com/Lucenx9/btusb-13d3-3625-dkms.git
cd btusb-13d3-3625-dkms

version=1.1.3
sudo install -d "/usr/src/btusb-13d3-3625-${version}/patches"
sudo install -m 0644 dkms.conf \
  "/usr/src/btusb-13d3-3625-${version}/dkms.conf"
sudo install -m 0755 pre_build.sh \
  "/usr/src/btusb-13d3-3625-${version}/pre_build.sh"
sudo install -m 0644 patches/0001-btusb-add-13d3-3625.patch \
  "/usr/src/btusb-13d3-3625-${version}/patches/"

sudo dkms add -m btusb-13d3-3625 -v "${version}"
sudo dkms build -m btusb-13d3-3625 -v "${version}"
sudo dkms install -m btusb-13d3-3625 -v "${version}"

Reboot after installation. If no Bluetooth device is in use, the module can instead be reloaded immediately:

sudo modprobe -r btusb
sudo modprobe btusb

Verify

dkms status -m btusb-13d3-3625
modinfo -n btusb
bluetoothctl show

modinfo -n btusb should point inside updates/dkms. The compression suffix can be .ko, .ko.xz or .ko.zst, depending on the distribution.

A successful MediaTek initialization also appears in the kernel log:

journalctl -k -b | grep -E 'Bluetooth: hci|btusb|btmtk'

Secure Boot

When Secure Boot is enforced, the kernel must trust the DKMS signing key. Follow the distribution’s DKMS/MOK enrollment procedure. Do not disable Secure Boot solely to install this module.

Before rebooting, stop Bluetooth users and verify that the newly installed module can be loaded:

sudo modprobe -r btusb
sudo modprobe btusb

If loading fails, restore the in-tree module before rebooting:

version=1.1.3
sudo dkms remove -m btusb-13d3-3625 -v "${version}" --all
sudo depmod -a
sudo modprobe btusb

Upgrade

old_version=1.1.2 # Set this to the installed version, for example 1.1.1 or 1.0
sudo dkms remove -m btusb-13d3-3625 -v "${old_version}" --all
sudo rm -rf "/usr/src/btusb-13d3-3625-${old_version}"

Then install version 1.1.3 using the steps above.

Uninstall

version=1.1.3
sudo dkms remove -m btusb-13d3-3625 -v "${version}" --all
sudo rm -rf "/usr/src/btusb-13d3-3625-${version}"
sudo depmod -a

Reboot, or reload btusb, to switch the running kernel back to its in-tree module.

Upstream status

The fix is queued in bluetooth-next as commit ddd25808d4c2 and should not be submitted again. It still needs to flow through the networking and mainline trees before distribution kernels can pick it up normally.

Keep this DKMS package only while the running distribution kernel lacks the entry. When requesting a distribution backport, reference the accepted commit and include the original failure and successful initialization logs.

License

GPL-2.0-only. See LICENSE.