 |
The Dolphin Emulator Wiki needs your help! Dolphin can play thousands of games, and changes are happening all the time. Help us keep up! Join in and help us make this the best resource for Dolphin. |
Bluetooth Passthrough
Since 5.0-910, Dolphin has the ability to passthrough a Bluetooth adapter for emulated Wii software. This is a powerful option that allows for perfect Wii Remote behaviors on Dolphin, given a powerful enough Bluetooth adapter. Unlike standard Bluetooth emulation, Bluetooth Passthrough supports pairing third party Wii Remotes, Wii Remote audio, and can more accurately communicate fine motions. However, because Bluetooth Passthrough gives the Bluetooth adapter directly to the emulated software, there are heaps of limitations that make it only worthwhile for certain situations.
Limitations
- Requires a specialized driver on Windows, and on Linux requires a udev rule. The Operating System will not be able to access the Bluetooth adapter while it is in use.
- The functionality and stability of the connection heavily depends on the compatibility of the Bluetooth adapter used.
- Even though most Bluetooth adapters can be used in passthrough mode, perfect compatibility is only guaranteed with the Bluetooth modules from Wii consoles.
- Many features do not work. Netplay, input recordings will be limited. The Wii Remote may disconnect if Dolphin is running too fast or too slow. If the Bluetooth adapter is disconnected from your computer, Dolphin may crash.
- Save states made in Bluetooth Passthrough mode can't be loaded on "Emulate a BT Adapter" mode, nor vice-versa.
- Wii Remote connection state dictates whether save states made in Bluetooth Passthrough mode will work or not:
When saving state When loading state Works? One or more Wii Remotes connected One or more Wii Remotes connected on the same session[1] Yes One or more Wii Remotes connected One or more Wii Remotes connected on a different session[1] No One or more Wii Remotes connected Some or all Wii Remotes disconnected Yes[2] No Wii Remotes connected One or more Wii Remotes connected No No Wii Remotes connected No Wii Remotes connected Yes
- [1] Same session: for instances where Wii Remotes haven't been disconnected and emulation hasn't been stopped during anywhere between saving and loading of a save state.
Different session: when any one of these has been intervened. - [2] First (re)connection will fail, subsequent connections will work. Depending of the Bluetooth adapter, it might be necessary to connect then disconnect the Wii Remotes before loading the saved state.
- [1] Same session: for instances where Wii Remotes haven't been disconnected and emulation hasn't been stopped during anywhere between saving and loading of a save state.
Setting up
Linux
A udev rule has to be installed so Dolphin can use a Bluetooth adapter without having to get root privileges.
1. Paste the following into /etc/udev/rules.d/52-dolphin.rules (/lib/udev/rules.d/52-dolphin.rules if making a package). Replace 'YOURVID' and 'YOURPID' with the Vendor ID and Product ID respectively.
SUBSYSTEM=="usb", ATTRS{idVendor}=="YOURVID", ATTRS{idProduct}=="YOURPID", TAG+="uaccess"
2. Reload udev rules with:
sudo udevadm control --reload-rules
3. Reinsert the adapter.
Dolphin should be able to automatically unload the USB Bluetooth kernel module (assuming you have permission to; you typically need to be in the plugdev group). If not, unload it with modprobe -r btusb.
Windows
WARNING: While a libusb driver is installed, other programs/devices will not be able to use your Bluetooth device. This can be easily reverted in Windows Device Manager and instructions are provided below.
Download and open Zadig as Administrator, then:
- In the "Options" menu in Zadig, make sure "List All Devices" is enabled.
- Look through the devices for the radio to passthrough.
- On the right column, select "libusbK", then click "Replace Driver". Select "Yes" to modify the system driver.
If you wish to return your Bluetooth drivers back to normal, start "Device Manager" and locate "libusbK" devices in the list. Right-click the device you wish to restore and select 'Uninstall Device'. Upon plugging it in next time, Windows will install the default Bluetooth driver and it will resume normal functions. NOTE: If you used the winUSB driver instead, it will be located under "Universal Serial Bus Devices." Same instructions apply otherwise.
If this does not revert your device driver, you may right click on the Bluetooth device in Device Manager, select "Update Driver", "Browse my computer for drivers", then select "Let me pick from a list of available drivers on my computer". From there, select the latest version of the driver that appears in the list (it may be listed as "Generic Bluetooth Adapter"). This should permanently revert your Bluetooth driver.
If Dolphin is unable to use your Bluetooth device after doing this, it may not have the necessary hardware features. You can attempt to use the "winUSB" driver from Zadig as a last ditch effort.
usbdk
As of 5.0-10617 usbdk is no longer supported.
Some users who wish to maintain use of their Bluetooth Device and use it in Dolphin without swapping drivers have opted to use usbdk. When Dolphin starts up, you will lose control of your Bluetooth Device and regain it when Dolphin shuts down. While this cuts down on the work you need to use your Bluetooth device across many controllers, usbdk has many bugs; the worst of which is that any ES_Launch will immediately crash/freeze the game due to usbdk losing control of the Bluetooth.
macOS
There is currently no way to use this feature on versions newer than 10.9, because Apple removed the ability to unload the Bluetooth kernel module.
A potential solution would be to force the OS to ignore the adapter with a codeless .kext, but this hasn't been tried yet.
Android
This feature is not supported on Android.
Using passthrough mode in Dolphin
In Dolphin, open the Controller Configuration dialog, then select the "Passthrough a Bluetooth adapter" option in the Wii Remotes section.
While a game is running:
- Wii Remotes can be synced and paired to Dolphin by using the Sync button.
- All saved Wii Remote pairings can be reset by using the Reset button. This will also disconnect all currently connected Wii Remotes.
Advanced usage
Sync button hotkey
It is possible to use the "Press Sync Button" hotkey as an alternative to the buttons in the controller configuration dialog.
You will need to map "Press Sync Button" to a key or combination of keys. This can be done within Dolphin by left clicking on the "Hotkey Settings" tab under "Options" to bring up the appropriate configuration menu. You must then left click on the "Wii and Wii Remote" tab and left click on the box for "Press Sync Button" to map this hotkey.
"Press Sync Button" is designed to work just like the Wii's red sync button:
- Pressing the hotkey will trigger a sync.
- Holding the hotkey for 10 seconds will clear all saved pairings.
Manually specifying a Bluetooth adapter
If after the setup your adapter isn't detected, you can manually force Dolphin 2503a-296 and newer to use it by selecting it on "Adapter" dropdown, found in the Controller settings panel when "Passthrough a Bluetooth Adapter" is selected. If your adapter still doesn't show up on the list, and on older Dolphin versions where there's no GUI for selecting an adapter, you can force a specific device by editing Dolphin's configuration file (User/Config/Dolphin.ini). In the [BluetoothPassthrough] section, set VID and PID to your adapter's vendor ID and product ID. These values should have a 0x prefix, for example a VID of "057E" should be inputted as 0x057E.
Manually providing a firmware binary for Realtek adapters
Starting with 2506-330, Dolphin can now properly load the firmware required to use Realtek adapters with Bluetooth Passthrough. Upon launching a Wii title for the first time while using a Realtek adapter, you'll be prompted to download the required firmware binary for that adapter. Dolphin should ask you and, upon agreement, automatically handle everything, but if for any reason you want to provide a different firmware binary, you can do that by manually placing the binaries on User/Load/Firmware/rtl_bt (more specifically, *_fw.bin and *_config.bin).
Using a RTL8761B adapter as an example, the complete path would be User/Load/Firmware/rtl_bt/rtl8761bu_fw.bin and User/Load/Firmware/rtl_bt/rtl8761bu_config.bin.
Please note that Realtek adapters relying on EPATCH v2 firmware format (e.g. RTL8851, RTL8852, RTL8922, among others) are still not supported at the moment and won't work in Bluetooth Passthrough mode.
Troubleshooting
"Failed to open Bluetooth device: LIBUSB_ERROR_ACCESS"
This error means that Dolphin doesn't have permission to use the Bluetooth adapter.
If on Linux, make sure the udev rule is set up correctly.
"Failed to open Bluetooth device: LIBUSB_ERROR_NOT_SUPPORTED"
On Windows, this typically means that the libusb/WinUSB driver was not installed for the adapter.
"Failed to detach kernel driver for BT passthrough"
Dolphin tried to automatically unload the Bluetooth USB kernel module and failed to. Unload the module manually before starting a game to avoid this issue.
Wii Remotes do not stay paired after closing the game
This means that your adapter is likely buggy and does not remember Wii Remote link keys properly. Use a different adapter to avoid this issue, or try Dolphin 2506-171 or newer, which has improved Bluetooth Passthrough support.
This may also happen if your SYSCONF is corrupted or if you changed to a Dolphin version which doesn't have BT passthrough. If your adapter is listed as working or if you're sure it supports pairings (by having checked the HCI command replies), you can try deleting Wii/shared2/sys/SYSCONF and Wii/btdinf.bak.
Black screen on boot
Games send a reset command to the Bluetooth adapter when they start and wait for it to be acknowledged. If you are getting a black screen for a long time (more than 10 seconds), your adapter may be stuck in a broken state and is unable to respond to any commands. Unplug the adapter and try again.
No usable adapter found
This can happen with some adapters. You'll need to manually specify a Bluetooth adapter.
Adapter test results
Attention: starting with Dolphin 2506-171, several improvements were made to Bluetooth Passthrough. As such, the "Remember Pairings" column is deprecated, not relevant anymore and might get dropped in the future, as any Bluetooth adapter that works with Bluetooth Passthrough mode should keep Wii Remotes paired on 2506-171 or newer.
| Adapter | Type | BT | VID | PID | Rev | Works? | Stable? | Audio | |
|---|---|---|---|---|---|---|---|---|---|
| Asus AR9462 Wi-Fi Card | mPCIe | 4.0 | 0B05 | 17D0 | 0001 | Yes | |||
| Asus QCA6174A Wi-Fi Card | M.2 | 4.1 | 0B05 | 1825 | 0001 | Yes | Limited [3] | Yes | |
| Asus USB-BT400 [BCM20702] | USB | 4.0 | 0B05 | 17CB | ? | Yes (Specified) | Limited [2] | No | Yes |
| Asus USB-BT400 [BCM20702] | USB | 4.0 | 0B05 | 17CF | ? | Yes (Specified) | Limited [3] | Limited [8] | Yes |
| Asus USB-BT500 [RTL8761B] | USB | 5.0 [15] | 0B05 | 190E | ? | Yes (Firmware) | Yes | ||
| Asus USB-BT500 | USB | ? | 0B05 | 1BF6 | ? | Yes | ? | Yes | |
| Azio BTD-V201 [CSR8510] | USB | 2.1 | 0A12 | 0001 | ? | Yes | |||
| Belkin Mini Bluetooth Adapter (F8T065BF) [BCM20702] | USB | 4.0 | 050D | 065A | ? | Yes (Specified) | Limited [1] | No | Yes |
| Buro BU-BT40B [BCM20702] | USB | 4.0 | 0A5C | 21EC | ? | Yes (Specified) | Limited [3] | Yes | |
| CSL USB Bluetooth Nano Adapter (BSN23996) [CSR8510] | USB | 4.0 | 0A12 | 0001 | 8891 | Yes | Limited [2] | Yes | |
| E-Blue Mini Nova (EBA012V00) [CSR8510] | USB | 2.1 | 0A12 | 0001 | ? | Yes | No | Yes | |
| Foxconn T77H114.32 Bluetooth Module [BCM2070] | USB [14] | 2.1 | 0489 | E00F | 0596 | No | |||
| Foxconn T77H348.02 Wi-Fi Card [AR9462] | mPCIe | 4.0 | 0489 | E04E | 0001 | Yes | Limited [1] | No | Yes |
| Gembird BTD-MINI5 [CSR8510] | USB | 4.0 | 0A12 | 0001 | 8891 | Yes | Limited [1] | No | Yes |
| Generic Bluetooth Adapter [BR8651A01] | USB | 5.0 | 0A12 | 0001 | 8891 | No | |||
| Generic Bluetooth Adapter [CSR8510] | USB | ? | 0A12 | 0001 | 2520 | No | |||
| Generic Bluetooth Adapter [CSR8510] | USB | ? | 0A12 | 0001 | 3164 | Yes | No | Yes | |
| Generic Bluetooth Adapter [CSR8510] | USB | 4.0 | 0A12 | 0001 | 8891 | Yes | Limited [2] | Limited [7] | Yes |
| Generic Bluetooth Adapter [IS1032N] | USB | 2.0 | 1131 | 1004 | 0373 | Yes | Limited [5] | Limited [7] | Limited |
| GMYLE Ultra-Mini USB CSR4.0 [CSR8510] | USB | 4.0 | 0A12 | 0001 | 8891 | Yes | Limited [1] | No | Limited |
| Hama Bluetooth USB Adapter (00077026) [CSR8510] | USB | 2.0 | 0A12 | 0001 | 1958 | Yes | Limited [6] | Yes | |
| Intel Dual Band Wireless-AC 3160 | M.2 | 4.0 | 8087 | 07DC | 0001 | Yes | Limited [6] | Yes | |
| Intel Dual Band Wireless-AC 3165 | M.2 | 4.2 | 8087 | 0A2A | 0001 | Yes | Limited [6] | Limited [7] | Yes |
| Intel Dual Band Wireless-AC 3168 | M.2 | 4.2 | 8087 | 0AA7 | 0001 | Yes | Limited [6] | Limited [7] | Yes |
| Intel Dual Band Wireless-AC 7260 | M.2 | 4.0 | 8087 | 07DC | 0001 | Yes | Limited [6] | Yes | |
| Intel Wireless-AC 9260 | M.2 | 5.1 | 8087 | 0025 | 0002 | Yes | Limited [6] | Limited [7] | Yes |
| Intel Wireless-AC 9462 | M.2 [12] | 5.2 [13] | 8087 | 0AAA | 0002 | Yes | Limited [6] | Limited [7] | Yes |
| Intel Wi-Fi 6 AX201 | M.2 [12] | 5.2 [13] | 8087 | 0026 | 0002 | Yes | Limited [6] | Limited [7] | Yes |
| IOGear GBU421 [BCM2046] | USB | 2.1 | 0A5C | 2148 | ? | Yes (Specified) | Limited [6] | Limited [7] | Yes |
| IOGear GBU521 [BCM20702] | USB | 4.0 | 0A5C | 21E8 | 0112 | Yes (Specified) | Yes | No | Yes |
| Kinivo BTD-300 [BCM2070] | USB | 3.0 | 0A5C | 2198 | 0391 | Yes | Limited [1] | Yes | Limited |
| Kinivo BTD-400 [BCM20702] | USB | 4.0 | 0A5C | 21E8 | 0112 | Yes (Specified) | Limited [1] | Yes | Limited |
| Lite-On WCBN806A Wi-Fi Card [QCA9377] | M.2 | 4.1 | 04CA | 3015 | 0001 | Yes | Limited [7] | Yes | |
| Lite-On WCBN807A Wi-Fi Card [QCA6174A] | M.2 | 5.0 | 04CA | 3016 | 0001 | Yes | Limited [7] | Yes | |
| Mayflash DolphinBar (W010) | USB | N/A | Not supported [10] | ||||||
| NoteShip Bluetooth Adapter [CSR8510] | USB | ? | 0A12 | 0001 | 0100 | Yes | ? | ||
| Nintendo Wii Bluetooth Module (WML-C43) [BCM2045] | USB [11] | 2.0 | 057E | 0305 | 0100 | Yes | |||
| Nintendo Wii Bluetooth Module (J27H002) [BCM2045] | USB [11] | 2.0 | 057E | 0305 | 0100 | Yes | |||
| Orico BTA-403 [CSR8510] | USB | 4.0 | 0A12 | 0001 | 8891 | Yes | Limited [6] | Yes | |
| Orico BTA-408 [BCM20702] | USB | 4.0 | 0A5C | 21EC | ? | Yes (Specified) | Limited [3] | Yes | |
| Orico BTA-508 [RTL8761B] | USB | 5.1 [15] | 0BDA | 8771 | 0200 | Yes (Firmware) | ? | ||
| Plugable USB-BT4LE Bluetooth Adapter [BCM20702] | USB | 4.0 | 0A5C | 21E8 | 0112 | Yes (Specified) | Limited [3] | Yes | |
| Qualcomm Atheros AR5B22 Wi-Fi Card [AR9462] | mPCIe | 4.0 | 0CF3 | 3004 | 0001 | Yes | Limited [4] | Yes | |
| Qualcomm Atheros QCA9377 Wi-Fi Card | M.2 | 5.0 | 0CF3 | E500 | 0001 | Yes | Limited [7] | Yes | |
| Realtek RTL8822CE Wi-Fi Card | M.2 | 5.0 [15] | 0BDA | 385A | 0000 | No [9] | |||
| Realtek RTL8852AE Wi-Fi Card | M.2 | 5.2 [15] | 0BDA | 4852 | 0000 | No [9] | |||
| Rocketfish Micro Bluetooth Adapter (RF-MRBTAD) [BCM2046] | USB | 2.1 | 0461 | 4D75 | ? | Yes (Specified) | No | ? | |
| Sena Networks Parani-UD100 [CSR8510] | USB | 4.0 | 0A12 | 0001 | 8241 | Yes | Limited | ||
| Silicon Wave Bluetooth Wireless Adapter | USB | 2.1 | 0C10 | 0000 | 1915 | Yes | Limited [2] | Yes | ? |
| SoundBot SB340 [CSR8510] | USB | 4.0 | 0A12 | 0001 | ? | Yes | ? | Yes | |
| TP-Link Bluetooth 4.0 Nano USB Adapter (UB400 v1) [CSR8510] | USB | 4.0 | 0A12 | 0001 | 8891 | Yes | Limited | ||
| TP-Link Bluetooth 4.0 Nano USB Adapter (UB400 v2) [RTL8761B] | USB | 5.0 [15] | 2357 | 0604 | ? | Yes (Firmware) | ? | ||
| TP-Link Bluetooth 5.0 Nano USB Adapter (UB500 v1) [RTL8761B] | USB | 5.0 [15] | 2357 | 0604 | ? | Yes (Firmware) | Yes | ||
| TP-Link Bluetooth 5.3 Nano USB Adapter (UB500 v2) [RTL8761B] | USB | 5.3 [15] | 2357 | 0604 | ? | Yes (Firmware) | ? | ||
| Trendnet TBW-106UB [CSR8510] | USB | 4.0 | 0A12 | 0001 | 8891 | Yes | ? | No | Limited |
| Trust Bluetooth 3.0 Adapter [AR3011] | USB | 3.0 | 0CF3 | 3002 | 0001 | Yes | Limited [4][6] | No | Yes |
| UGREEN Bluetooth 5.0 Adapter (CM390) [RTL8761B] | USB | 5.1 [15] | 2B89 | 8761 | 0200 | Yes (Firmware) | Yes | ||
| UGREEN USB Bluetooth 4.0 Adapter (CM109) [CSR8510] | USB | 4.0 | 0A12 | 0001 | 8891 | Yes | Limited [7] | Yes | |
| UNITEK USB Bluetooth 5.3 Adapter (B105B) [RTL8761B] | USB | 5.3 [15] | 0BDA | A729 | 0200 | Yes (Firmware) | ? | ||
- Unknown. Not enough information to classify.
- Incompatible. Does not work or has significant limitations.
- Partially compatible. Works well in most cases, but there may be some issues.
- Fully compatible. Works well in all cases and will give the same experience as a Wii Bluetooth adapter.
Stability
- [1] May stop working after HCI resets (stopping, resetting emulation or going back to the system menu).
- [2] Has issues with games which send a lot of commands (including New Super Mario Bros. Wii and The Legend of Zelda: Skyward Sword before you get in game).
- [3] Starts having lag issues after ~30 minutes. Reconnecting the Wii remote is required.
- [4] May stop working after HCI resets on Windows, works fine on Linux and macOS.
- [5] Randomly stop working on Windows, works fine on Linux and macOS.
- [6] Has issues connecting multiple Wii Remotes.
Pairing
- [7] Has issues reconnecting multiple Wii Remotes.
- [8] Remembers only one Wii Remote.
- [9] Realtek EPATCH v2 firmware format currently not supported. Might start working if Dolphin gets the ability to upload firmware binaries in that format to the adapter.
Other
- [10] Doesn't expose its internal Bluetooth adapter, can't be used with Bluetooth Passthrough in any capacity.
- [11] Must be modified before use, refer to this forum thread.
- [12] CNVi card, must be paired with a compatible Intel CPU and chipset to work.
- [13] Supported Bluetooth version may vary depending of the chipset model paired with this card.
- [14] Proprietary 10-pin BTB connector, usually found in older laptops (2010 and earlier).
- [15] This is the Bluetooth version supported out of the box, with no drivers installed, can be temporarily upgraded/downgraded depending of the firmware binary provided.