蓝牙
蓝牙是一种用于手机、电脑和其他电子设备之间短距离无线互联的标准。在 Linux 中，蓝牙协议栈的标准实现是 BlueZ。
安装
- 安装 bluez 包，该包提供蓝牙协议栈。
- 安装 bluez-utils 包，该包提供 bluetoothctl 工具。另外，安装 bluez-deprecated-tools 以便也包含已弃用的 BlueZ 工具。
- 通用的蓝牙驱动程序是
btusb内核模块。检查该模块是否已加载。如果未加载，则加载该模块。 - 启动/启用
bluetooth.service。
- 一些蓝牙适配器与 Wi-Fi 卡捆绑在一起（例如，较旧的 Intel Centrino 卡）。这些卡要求首先启用 Wi-Fi 卡（通常是笔记本电脑上的键盘快捷键），才能使蓝牙适配器对内核可见。
- 一些蓝牙卡（例如 Broadcom）与网络适配器冲突。因此，您需要确保您的蓝牙设备在网络服务启动之前连接。
- hcitool 和 hciconfig 等工具已被上游弃用，并且不再包含在 bluez-utils 中。由于这些工具将不再更新，建议更新脚本以避免使用它们。如果您仍希望使用它们，请另外安装 bluez-deprecated-tools。有关更多信息，请参阅 FS#53110 和 Bluez 邮件列表。
- 自 bluez-obex 和 bluez-mesh 已从 bluez 中分离出来（截至 2024）。因此，如果您打算通过蓝牙传输文件，则需要安装 bluez-obex 并且需要启用用户服务
obex.service。
前端
控制台
- bluetoothctl — 从 shell 配对设备是最简单、最可靠的选项之一。
- bluetui — 用于管理蓝牙设备的 TUI。
- bluetuith — 通过终端用户界面提供蓝牙管理器，便于配对和设备/适配器管理，支持 OBEX 文件传输和鼠标。
echo -e "command1\ncommand2\n" | bluetoothctl 或 bluetoothctl -- command。图形界面
以下软件包支持图形化界面来定制蓝牙。
- GNOME Bluetooth — GNOME 的蓝牙工具。
- gnome-bluetooth-3.0 提供后端（gnome-bluetooth 已过时）
- gnome-shell 提供状态监视器小部件
- gnome-control-center 提供可以通过输入“蓝牙”在活动概览中访问的配置前端 GUI，或者使用
gnome-control-center bluetooth命令访问。 - 您也可以直接运行
bluetooth-sendto命令将文件发送到远程设备。 - nautilus-bluetoothAUR 在 Nautilus 的右键菜单中添加了“通过蓝牙发送”选项
- 要接收文件，请打开蓝牙设置面板；只有在蓝牙面板打开时才能接收。
- 要在 Thunar 的文件属性菜单中的“发送到”菜单中添加蓝牙条目，请参阅此处的说明。（需要配置的命令是
bluetooth-sendto %F）。
- Bluedevil — KDE 的蓝牙工具。如果在 Dolphin 和系统托盘中没有可见的蓝牙图标，请在系统托盘选项中启用它或添加一个窗口小部件。通过点击图标，您可以配置 Bluedevil 并检测蓝牙设备。也可以从 KDE 系统设置中访问一个界面。
- Blueberry — Linux Mint 从 GNOME Bluetooth 分离出来的项目，可在所有桌面环境中工作。Blueberry 不支持通过 Obex Object Push 接收文件。
- Blueman — 功能齐全的蓝牙管理器。
- ObexFTP — 用于与任何支持 OBEX 的设备之间传输文件的工具。
- Overskride — 一个简单而强大的蓝牙客户端。
- btctl — 一个简单的蓝牙连接管理器，适用于 fuzzel 和其他启动器。
配对
本节将通过 bluetoothctl(1) 命令行工具直接配置 bluez，如果您使用的是替代的前端工具（如 GNOME Bluetooth），则可能不需要。
具体过程取决于涉及的设备及其输入功能。以下是使用 bluetoothctl 配对设备的一般 outline。
启动 bluetoothctl 交互式命令。输入 help 获取可用命令列表。
- （可选）使用
select MAC_address选择默认控制器。 - （可选）如果设备设置为关闭状态，请输入
power on以打开控制器电源。它默认是开启的；请参阅#默认适配器电源状态。 - 输入
devices获取要配对的设备的 MAC 地址。 - 如果设备尚未在列表中，请使用
scan on命令进入设备发现模式。 - 使用
agent on启动代理，或选择特定代理：如果在agent之后按两次 Tab 键，您应该会看到可用代理的列表。蓝牙代理负责管理蓝牙“配对码”。它可以响应传入的“配对码”，也可以发出配对码。在大多数情况下，default-agent应该适用。[1] - 输入
pair MAC_address进行配对（Tab 键补全可用）。 - 如果使用没有 PIN 码的设备，可能需要手动信任该设备才能成功重新连接。输入
trust MAC_address来执行此操作。 - 输入
connect MAC_address来建立连接。
一个示例会话可能看起来像这样
$ bluetoothctl
[NEW] Controller 00:10:20:30:40:50 hostname [default] [bluetooth]# agent KeyboardOnly Agent registered [bluetooth]# default-agent Default agent request successful [bluetooth]# power on Changing power on succeeded [CHG] Controller 00:10:20:30:40:50 Powered: yes [bluetooth]# scan on Discovery started [CHG] Controller 00:10:20:30:40:50 Discovering: yes [NEW] Device 00:12:34:56:78:90 device name [CHG] Device 00:12:34:56:78:90 LegacyPairing: yes [bluetooth]# pair 00:12:34:56:78:90 Attempting to pair with 00:12:34:56:78:90 [CHG] Device 00:12:34:56:78:90 Connected: yes [CHG] Device 00:12:34:56:78:90 Connected: no [CHG] Device 00:12:34:56:78:90 Connected: yes Request PIN code [agent] Enter PIN code: 1234 [CHG] Device 00:12:34:56:78:90 Paired: yes Pairing successful [CHG] Device 00:12:34:56:78:90 Connected: no [bluetooth]# connect 00:12:34:56:78:90 Attempting to connect to 00:12:34:56:78:90 [CHG] Device 00:12:34:56:78:90 Connected: yes Connection successful
双系统配对
对于双启动 Linux 系统，如#保存配置中所述，只需确保 /var/lib/bluetooth/BT-Adapter-MAC-address 中的所有文件在每个安装中都相同，方法是复制或链接它们。
使用 Windows 或 macOS，要在双启动设置中配对设备，您需要更改 Linux 安装中的配对密钥以使其匹配。
本页仅描述手动方法。要自动化此过程，请参阅 bt-dualboot 项目（不支持蓝牙低功耗）和相关仓库。对于半自动过程，请使用 bluetooth-dualboot 脚本，该脚本不编辑任何文件，但可以帮助您运行正确的命令并剪切粘贴正确的值。
设置
为此，请先在您的 Arch Linux 安装中配对设备。然后重启到另一个操作系统并配对设备。现在您需要提取配对密钥，但首先请关闭蓝牙设备以防止任何连接尝试。
适用于 Windows
您可以在 Linux 或 Windows 上提取蓝牙密钥
在 Windows 上提取
首先，启动到 Windows。
包含链接密钥的注册表项只能由 SYSTEM 帐户访问，而该帐户无法登录。因此，您需要 Microsoft 的 PsExec 工具，从官方 Windows Sysinternals 网站下载，以便以 SYSTEM 身份运行 regedit.exe。
下载 PsTools，然后解压 PsExec64.exe。
在管理员权限的 命令提示符中，从解压出的 EXE 所在的位置，启动注册表编辑器
.\PsExec64.exe -s -i regedit.exe
在注册表编辑器中，导航到以下注册表项
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\BTHPORT\Parameters\Keys
在此注册表项下，每个蓝牙适配器都有一个子项，以 MAC 地址命名。如果存在多个子项，并且您不确定使用哪个，请遵循本指南查找所需蓝牙适配器的 MAC 地址。
在所需的适配器注册表项中，每个配对的设备都有一个名称-值对，名称是其 MAC 地址。此外，您可能会看到一些以 MAC 地址命名的子项，每个子项都包含名称为 LTK 或 IRK 的名称-值对。这些子项（如果存在）是为蓝牙 5.1 设备准备的。如果您要共享的设备有子项，则它是一个蓝牙 5.1 设备。如果没有子项，只有名称-值对，则它不是蓝牙 5.1 设备。
右键单击适配器的注册表项并将其导出为 .reg 文件。这是一个文本文件，您可以从中复制密钥。如前所述，它包含非蓝牙 5.1 设备的配对密钥（以名称-值对的形式），以及蓝牙 5.1 设备的配对密钥（以及一些其他信息）在每个设备的子项中。将此文件提供给您的 Linux 安装并重启进入它。
如果设备不是蓝牙 5.1 设备，请跳转到#保存配置。如果是蓝牙 5.1 设备，您需要对配对密钥和相关信息进行一些修改，然后再完成。有关如何操作，请参阅#准备蓝牙 5.1 密钥。
在 Linux 上提取
启动到 Arch。安装 chntpw。挂载您的 Windows 系统驱动器。切换到注册表蜂巢目录，并在 SYSTEM 蜂巢上启动 chntpw
$ cd /path/to/windows/system/Windows/System32/config $ chntpw -e SYSTEM
在 chntpw 环境中，运行
> cd CurrentControlSet\Services\BTHPORT\Parameters\Keys
您可能会看到 ControlSet00X（使用 ls 检查）而不是 CurrentControlSet；请使用此替代项。
> cd ControlSet00X\Services\BTHPORT\Parameters\Keys
可能只有一个子项，其名称是您的蓝牙适配器的 MAC 地址。使用 ls 显示它，然后 cd 进入它。
> ls > cd your-adapter's-mac-address
该适配器下的子项名称是适配器配对的*设备*的 MAC 地址。使用 ls 显示它们，然后 cd 进入您想要双系统配对的每个设备。
> ls > cd your-device's-mac-address
如果这不是蓝牙 5.1 设备，您将只看到配对密钥。
> ls
Node has 0 subkeys and 1 values size type value name [value if type DWORD] 16 REG_BINARY <ab12cd34ef56>
如果是，请使用 hex 显示您的设备密钥的十六进制转储。
> hex ab12cd34ef56
:00000 XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX (some other chars)
“XX”是配对密钥。记下哪些密钥对应哪些 MAC 地址。
如果这是蓝牙 5.1 设备，那么您将看到多个对应于一个设备的密钥。
Node has 0 subkeys and 8 values
size type value name [value if type DWORD]
16 3 REG_BINARY <LTK>
4 4 REG_DWORD <KeyLength> 16 [0x10]
8 b REG_QWORD <ERand>
4 4 REG_DWORD <EDIV> 37520 [0x9290]
16 3 REG_BINARY <IRK>
8 b REG_QWORD <Address>
4 4 REG_DWORD <AddressType> 1 [0x1]
4 4 REG_DWORD <AuthReq> 45 [0x2d]
请参阅#准备蓝牙 5.1 密钥，了解如何使用这些密钥，使用 hex value_name 获取所需的键值。
最后，要将密钥导入您的 Linux 安装，请继续#保存配置。
适用于 macOS
启动到 macOS
- 适用于 macOS Monterey 或更高版本
- 打开“钥匙串访问”并搜索蓝牙。
- 按日期排序。
- 如果您最近删除了设备并重新连接了它，那么您可以简单地按修改日期排序并选择最新的。它可能名为 MobileBluetooth（对于较旧的蓝牙设备）或只是一个 UUID（对于蓝牙 5.1+）。
- 双击该条目。检查“帐户”字段中的 MAC 地址是否与您的设备的 MAC 地址匹配。
- 点击“显示密码”复选框。您现在需要输入两次您的密码。
- 复制密码字段中的文本，它实际上是一个 XML 文件（
⌘+a⌘+c） - 将文本粘贴到您主目录的
bt_keys.txt中。
- 对于 High Sierra 或更高版本，请在终端中运行以下命令
# defaults read /private/var/root/Library/Preferences/com.apple.bluetoothd.plist LinkKeys > ~/bt_keys.txt
- 对于 Sierra 或更早版本，请在终端中运行以下命令
# defaults read /private/var/root/Library/Preferences/blued.plist LinkKeys > ~/bt_keys.txt
~/.bt_keys.txt 文件现在包含已建立的蓝牙密钥。对于旧版本的 macOS（High Sierra 及更早版本），您必须在继续之前反转密钥。例如，98 54 2f aa bb cc dd ee ff gg hh ii jj kk ll mm 变为 MM LL KK JJ GG FF EE DD CC BB AA 2F 54 98。
>>> key = "98 54 2f aa bb cc dd ee ff gg hh ii jj kk ll mm" >>> " ".join(reversed(key.split()))
如果这是蓝牙 5.1 设备，那么将有多个密钥对应一个设备。请参阅#准备蓝牙 5.1 密钥了解如何使用它们。
最后，要将密钥导入您的 Linux 安装，请重启到 Linux 并继续#保存配置。
准备蓝牙 5.1 密钥
如果您在遵循#适用于 Windows 或#适用于 macOS 时观察到存在蓝牙 5.1 密钥，则必须在将它们导入 Linux 之前对它们的值进行某些转换。创建请求的文件及其适当的内容，以供在#保存配置中安装。此过程将取决于设备，并且某些值需要进行处理；下面提供了用于执行此操作的代码实用程序。
| 设备 | 源密钥和转换（Windows） | 源密钥和转换（macOS） | 目标密钥文件 |
|---|---|---|---|
|
|
? | IdentityResolvingKey.Key
|
|
? | SlaveLongTermKey.Key 和 PeripheralLongTermKey.Key | |
ERand 和 EDIV 应为 0 |
随机数 和 加密的分配器 应为 0。 |
– | |
|
|
? | IdentityResolvingKey.Key
|
|
? | LocalSignatureKey.Key
| |
|
? | LongTermKey.Key
| |
|
? | LongTermKey.EncSize
| |
|
? | LongTermKey.EDiv
| |
|
? | LongTermKey.Rand
| |
|
|
? | IdentityResolvingKey.Key
|
|
? | LongTermKey.Key
| |
|
? | LongTermKey.EncSize
| |
|
? | LongTermKey.EDiv
| |
|
? | LongTermKey.Rand
| |
|
|
? | RemoteSignatureKey.Key
|
|
|
|
IdentityResolvingKey.Key
|
|
|
LongTermKey.Key
| |
|
|
LongTermKey.Rand
| |
|
|
LongTermKey.EDiv
| |
| 其他设备 |
|
|
LongTermKey.Key
|
|
|
LongTermKey.Rand
| |
|
|
LongTermKey.EDiv
| |
| Xbox 无线控制器 |
|
? | SlaveLongTermKey.Key
|
>>> "key_value".replace(" ", "")
- 此 Python 代码仅执行字节反转
>>> ERand=" 63 02 84 B8 5D 40 44 DF " >>> ERand=list(reversed(ERand.strip().split()))
- 此 Python 代码执行一些额外的十进制转换
>>> int("".join(ERand), 16)
16088054540146049635
- 此 Python 代码执行 base64 到十六进制的转换
binascii.hexlify(base64.decodebytes(b'...')).upper()
- 此 Python 代码执行完整的 macOS 加密分配器转换
struct.unpack('<H', base64.decodebytes(b'...'))
- 此 Python 代码执行完整的 macOS 随机数转换
struct.unpack('<Q', base64.decodebytes(b'...'))
通用情况示例
LTK为48 4D AF CD 0F 92 22 88 0A 52 9A F4 76 DA 8B 94的LongTermKey.Key为484DAFCD0F9222880A529AF476DA8B94。ERand为63 02 84 B8 5D 40 44 DF的Rand为16088054540146049635。EDIV为37520的EDiv为37520。
保存配置
现在您已经有了密钥，请切换到 root 用户，然后继续
# cd /var/lib/bluetooth/BT-Adapter-MAC-address
在这里，您将找到每个配对蓝牙设备的文件夹。对于您想要在 Arch 和双系统上配对的每个设备，请执行以下操作
# cd device-MAC-address
如果您有配对密钥（即这不是蓝牙 5.1 设备），则编辑 info 文件并更改 [LinkKey] 下的密钥。例如。
info
[LinkKey] Key=XXXXXXXXXXXXXXX
如果您有多个密钥，如蓝牙 5.1，请编辑 info 文件并用记录的值替换所有适用的密钥。例如，对于 Xbox One S 无线控制器。
info
[IdentityResolvingKey] Key=<IdentityResolvingKey.Key> [PeripheralLongTermKey] Key=<PeripheralLongTermKey.Key> [SlaveLongTermKey] Key=<SlaveLongTermKey.Key>
然后重启 bluetooth.service 和 pulseaudio（使用 pulseaudio -k && pulseaudio --start）。
您现在应该能够连接到您的设备了。
配置
默认传输 3.0 vs 5.x (低功耗蓝牙)
要强制蓝牙控制器使用较旧的蓝牙传输协议（例如，因为与 5.x BLE 设备相比，3.0 设备的双系统配对更容易设置），请在 /etc/bluetooth/main.conf 的 [General] 部分设置 ControllerMode=bredr。
/etc/bluetooth/main.conf
[General] ControllerMode=bredr
默认值为 ControllerMode=dual，即 BR/EDR 和 LE 都已启用。
默认适配器电源状态
截至 bluez 5.65，BlueZ 的默认行为是在启动服务或从挂起状态恢复时打开所有蓝牙适配器。[2]
如果您希望适配器不被自动启用（例如，在希望节省电池的便携式设备上），请在 /etc/bluetooth/main.conf 的 [Policy] 部分设置 AutoEnable=false。
/etc/bluetooth/main.conf
[Policy] AutoEnable=false
适配器仍然可以通过运行 power on 来手动打开，如#配对中所述。
启动时可发现
如果设备应始终可见且可直接连接
/etc/bluetooth/main.conf
[General] DiscoverableTimeout = 0
从挂起唤醒
允许蓝牙键盘、鼠标等唤醒处于挂起状态的系统。首先，检查 BIOS 设置，确保未禁用“USB 唤醒”。在许多情况下，主板上的蓝牙设备是 USB 设备。
为蓝牙适配器添加新的 udev 规则（USB 无线控制器基础类，蓝牙编程接口协议），以启用从挂起状态唤醒。
/etc/udev/rules.d/91-bluetooth-wakeup.rules
ACTION=="add", SUBSYSTEM=="usb", DRIVERS=="usb", \
ATTR{bDeviceClass}=="e0", \
ATTR{bDeviceProtocol}=="01", \
ATTR{bDeviceSubClass}=="01", \
ATTR{power/wakeup}="enabled"
为了在唤醒后自动重新配置您的蓝牙键盘，例如以使用不同的键映射或按键重复速率（有关详细信息，请参阅 Xorg/Keyboard configuration#Adjusting typematic delay and rate 和 xmodmap），请创建一个可执行脚本。
configure_keyboard.sh
#!/bin/sh export DISPLAY=:0 xset r rate 220 30 xmodmap /your/path/to/.Xmodmap
然后创建另一个类似上述的 udev 规则。
/etc/udev/rules.d/92-keyboard-reconfiguration-wakeup.rules
ACTION=="add", SUBSYSTEM=="usb", DRIVERS=="usb", \
ATTR{bDeviceClass}=="e0", \
ATTR{bDeviceProtocol}=="01", \
ATTR{bDeviceSubClass}=="01" \
RUN+="/your/path/to/configure_keyboard.sh"
启用实验性功能
Bluez 堆栈将新的、可能存在 bug 的功能隐藏在 D-Bus 实验性和内核实验性选项后面。这些选项下的功能会随时间变化，因为实验性功能被认为稳定且不再需要该选项（例如：当前启用 D-Bus 实验性接口可以报告旧耳机电量）。要启用这些功能，请取消注释配置文件中的相应行。
/etc/bluetooth/main.conf
... # Enables D-Bus experimental interfaces # Possible values: true or false Experimental = true # Enables kernel experimental features, alternatively a list of UUIDs # can be given. # Possible values: true,false,<UUID List> # Possible UUIDS: ... # Defaults to false. KernelExperimental = true
或者，您可以编辑 `bluetooth.service` 以添加 `--experimental` 或 `--kernel` 标志，如下面的下拉文件所示：
/etc/systemd/system/bluetooth.service.d/override.conf
[Service] ExecStart= ExecStart=/usr/lib/bluetooth/bluetoothd --experimental
无论哪种方式，您都必须重新启动 `bluetooth.service`。
音频
您通常需要采取额外的步骤才能将音频服务器与蓝牙集成。这将在下面的部分中详细介绍。
有关蓝牙音频和蓝牙耳机的更多信息，请参阅蓝牙耳机页面。
PulseAudio
要能够使用蓝牙耳机或扬声器等音频设备，您需要安装额外的 pulseaudio-bluetooth 包。请务必重新启动PulseAudio以使安装生效：`pulseaudio -k`。使用默认的 PulseAudio 安装（特别是使用带有打包的 `default.pa` 的用户实例），您应该能够立即从蓝牙设备流式传输音频到您的扬声器。[3]
如果您有系统范围的 PulseAudio 设置，请确保运行守护进程的用户（通常是 `pulse`）在 `lp` 组中，并在您的 PulseAudio 配置中加载蓝牙模块。
/etc/pulse/system.pa
... load-module module-bluetooth-policy load-module module-bluetooth-discover ...
如果希望自动将所有音频切换到蓝牙设备，可以选择性地添加 `load-module module-switch-on-connect`。
PipeWire
PipeWire 从 v0.3.19 开始默认启用其蓝牙支持。
ALSA
首先，确保您的蓝牙音频设备已正确配对并连接到系统。
然后，安装 bluez-alsa-gitAUR，启动（并启用）`bluealsa` 服务，并将您的用户添加到 `audio` 组。
运行以下命令以检查一切是否按预期工作（请将下面的 `XX:XX:XX:XX:XX:XX` 和 `FILE.wav` 替换为实际值）
$ aplay -D bluealsa:SRV=org.bluealsa,DEV=XX:XX:XX:XX:XX:XX,PROFILE=a2dp FILE.wav
最后，将以下行添加到您的 `~/.asoundrc` 文件中：
~/.asoundrc
defaults.bluealsa {
service "org.bluealsa"
device "XX:XX:XX:XX:XX:XX"
profile "a2dp"
}
现在您可以使用 `bluealsa` 设备来访问您的蓝牙音频设备。音量管理正常通过 `alsamixer` 进行，选项为 `-D bluealsa`。
蓝牙串行
要使蓝牙串行通信在蓝牙-串行模块（HC-05、HC-06）上正常工作，请执行以下步骤：
使用 `bluetoothctl` 如上所述配对您的蓝牙设备。
安装 bluez-deprecated-tools，因为它提供了一些较新工具所缺乏的功能。
将配对设备的 MAC 地址绑定到 tty 终端
# rfcomm bind rfcomm0 MAC_address_of_Bluetooth_device
现在您可以打开 `/dev/rfcomm0` 进行串行通信。
$ picocom /dev/rfcomm0 -b 115200
故障排除
一般故障排除
调试
为了进行调试，首先停止 `bluetooth.service`。
然后使用 `-d` 参数启动它。
# /usr/lib/bluetooth/bluetoothd -n -d
另一个选项是使用 `btmon` 工具。
已弃用的 BlueZ 工具
八个 BlueZ 工具已被弃用并从 bluez-utils 中删除，尽管并非所有这些工具都有较新的替代品。 bluez-deprecated-tools 包现在提供了这些已弃用的工具。
| 已弃用的工具 | 最可能的替代品 |
|---|---|
| gatttool | btgatt-client，D-Bus Gatt API[死链接 2023-10-29—HTTP 404] |
| hciattach | btattach |
| hciconfig | btmgmt（以及 bluetoothctl?） |
| hcidump | btmon（以及 btsnoop） |
| hcitool | 缺失，D-Bus Device API[死链接 2023-10-29—HTTP 404] 可用 |
| rfcomm | 缺失，使用 D-Bus Profile1 API[死链接 2023-10-29—HTTP 404] 实现？ |
| ciptool | |
| sdptool | 缺失，功能似乎分散在不同的 D-Bus 对象中：Profile[死链接 2023-10-29—HTTP 404]、Advertising[死链接 2023-10-29—HTTP 404]，以及 `device`[死链接 2023-10-29—HTTP 404] 和 `adapter`[死链接 2023-10-29—HTTP 404] 中的 UUID 数组。 |
服务问题
systemd：条件检查导致 Bluetooth 服务被跳过
`bluetooth.service` 仅需要 `/sys/class/bluetooth` 目录存在，该目录应由内核模块 `bluetooth` 创建，而 `bluetooth` 模块仅在 `systemd-udev` 实际找到工作的蓝牙硬件设备时才被自动加载。
如果您的 `/sys/class/bluetooth` 不存在，请检查您的内核蓝牙模块是否由 `lsmod` 加载。如果未加载，并且您认为您有蓝牙设备，您可以尝试手动加载它们，方法是加载蓝牙模块并重新启动 `bluetooth.service`。
加载 `bluetooth` 模块时，您还应该加载相应的内核蓝牙驱动程序，最可能是 `btusb`，但也可能是 `btrtl,btintel,btbcm,bnep,btusb` 等。
检查 `bluetooth.service` 的单元状态，以查看它是否已启动。
另请参阅 Debian Bug report logs - #853207。
如果 `bluetooth.service` 成功启动，但您仍然无法正常使用蓝牙（例如，当您 `scan on` 时 `bluetoothctl` 显示类似 `org.Bluez.Error.NotReady` 的内容），则可能存在问题。如果发生这种情况，请尝试重新启动您的计算机，并仔细检查：`/sys/class/bluetooth` 目录是否存在；`lsmod` 是否包含正确的蓝牙模块；日志中的日志消息；等等。`systemd-udev` 应该能够自动识别您的蓝牙硬件，而无需再次进行手动更改。
蓝牙立即唤醒处于“挂起到空闲”状态的设备
在支持挂起到空闲/S2idle/S0ix/Modern Standby的系统上，蓝牙控制器在睡眠期间将保持启用状态。如果连接了任何蓝牙设备，这通常会导致系统在进入睡眠状态后立即唤醒。
为防止这种情况发生，您可以在进入睡眠状态之前完全禁用蓝牙 - 安装 bluez-utils 并创建以下文件：
/etc/systemd/system/bluetooth-disable-before-sleep.service
[Unit] Description=Disable Bluetooth before going to sleep Before=sleep.target Before=suspend.target Before=hybrid-sleep.target Before=suspend-then-hibernate.target StopWhenUnneeded=yes [Service] Type=oneshot RemainAfterExit=yes ExecStart=/usr/bin/bluetoothctl power off ExecStop=/usr/bin/bluetoothctl power on [Install] WantedBy=sleep.target WantedBy=suspend.target WantedBy=hybrid-sleep.target WantedBy=suspend-then-hibernate.target
启用此服务，并检查蓝牙设备在进入睡眠状态时是否断开连接，以及在系统唤醒后蓝牙是否已重新连接。
如果使用了此解决方法，则使用蓝牙鼠标/键盘唤醒系统将不起作用。
在无头/服务器系统上注销后蓝牙关闭
这可能有多种原因。
- 默认情况下，PulseAudio 和 PipeWire 都作为用户服务运行，当最后一个会话结束时，它们将被终止。为用户启用残留以解决此问题。
- 此外，当使用 PipeWire（通常是这样）运行 WirePlumber 时，WirePlumber 会运行一个“logind-monitor”，该监控器会在登录时启用蓝牙，在注销时禁用蓝牙。有关修复方法，请参阅 WirePlumber#Keep Bluetooth running after logout / Headless Bluetooth。
适配器问题
hcitool scan: 未找到设备
- 在某些笔记本电脑（例如 Dell Studio 15、Lenovo Thinkpad X1）上，您必须将蓝牙模式从 HID 切换到 HCI。安装 bluez-hid2hci 包，然后 udev 应该会自动完成此操作。或者，您可以手动运行此命令切换到 HCI：
# /usr/lib/udev/hid2hci
- 如果设备未显示，并且您的机器上装有 Windows 操作系统，请尝试启动 Windows 并从 Windows 中启用蓝牙适配器。
- 有时这个简单的命令也有帮助：
# bluetoothctl power on
bluetoothctl: 未提供默认控制器
首先，请确保设备未被 rfkill 阻止。如果使用 USBGuard，请确保它未阻止该设备（请参阅 USBGuard#Allow Bluetooth controllers）。
否则，请考虑以下可能的原因：
- 某些主板蓝牙控制器存在一个导致此问题的 bug。要查看是否是此问题，请运行 `journalctl | grep hci` 并检查是否包含 `command tx timeout` 或 `Reading Intel version command failed`。如果包含，请关闭计算机电源并拔下电源线几秒钟。这会强制控制器重新加载固件，与标准重启不同（请参阅 bug 报告）。
- 某些 Intel 网卡（如 8260）未被蓝牙服务正确识别。在这种情况下，使用已弃用的 bluez-deprecated-tools 而不是 bluez-utils 可能会解决问题。
- 一些加密狗，例如CSR 克隆，在内核级别存在兼容性问题。
- 省电措施可能导致问题，在这种情况下，添加内核参数 `btusb.enable_autosuspend=n` 是一个潜在的解决方案（请参阅 bug 报告）。
最后，卸载并重新加载 `btusb` 而不带任何选项有时有助于恢复控制器。
# modprobe -r btusb # modprobe btusb
rfkill unblock：不解除阻止
如果您的设备仍然被软阻止并且您正在运行 ConnMan，请尝试此操作：
$ connmanctl enable bluetooth
蓝牙 USB 加密狗
如果您使用的是 USB 加密狗，您应该检查您的蓝牙加密狗是否被识别。您可以通过在插入 USB 加密狗时以 root 身份运行 `journalctl -f` 来完成（或检查 `/var/log/messages.log`）。它应该看起来像这样（注意 hci）：
Feb 20 15:00:24 hostname kernel: [ 2661.349823] usb 4-1: new full-speed USB device number 3 using uhci_hcd Feb 20 15:00:24 hostname bluetoothd[4568]: HCI dev 0 registered Feb 20 15:00:24 hostname bluetoothd[4568]: Listening for HCI events on hci0 Feb 20 15:00:25 hostname bluetoothd[4568]: HCI dev 0 up Feb 20 15:00:25 hostname bluetoothd[4568]: Adapter /org/bluez/4568/hci0 has been enabled
如果您只看到前两行，您可能会发现它找到了设备，但您需要启用它。例如：
# btmgmt
[mgmt]# info Index list with 1 item hci0: Primary controller addr 00:1A:7D:DA:71:10 version 6 manufacturer 10 class 0x000000 supported settings: powered connectable fast-connectable discoverable bondable link-security ssp br/edr hs le advertising secure-conn debug-keys privacy static-addr current settings: connectable discoverable bondable ssp br/edr le secure-conn name Mozart short name [mgmt]# select hci0 Selected index 0 [hci0]# power up hci0 Set Powered complete, settings: powered connectable discoverable bondable ssp br/edr le secure-conn [hci0]# info hci0: Primary controller addr 00:1A:7D:DA:71:10 version 6 manufacturer 10 class 0x1c0104 supported settings: powered connectable fast-connectable discoverable bondable link-security ssp br/edr hs le advertising secure-conn debug-keys privacy static-addr current settings: powered connectable discoverable bondable ssp br/edr le secure-conn
或者：
# bluetoothctl
[bluetooth]# show Controller 00:1A:7D:DA:71:10 (public) Name: Mozart Alias: Mozart Class: 0x0000095c Powered: no Discoverable: yes Pairable: yes [bluetooth]# power on [CHG] Controller 00:1A:7D:DA:71:10 Class: 0x001c0104 Changing power on succeeded [CHG] Controller 00:1A:7D:DA:71:10 Powered: yes [bluetooth]# show Controller 00:1A:7D:DA:71:10 (public) Name: Mozart Alias: Mozart Class: 0x001c0104 Powered: yes Discoverable: yes Pairable: yes
要验证设备是否被检测到，您可以使用 `btmgmt`，它是 `bluez-utils` 的一部分。通过发出以下命令，您可以获取可用设备列表及其标识符和 MAC 地址：
$ btmgmt info
Index list with 1 item hci0: Primary controller addr 00:1A:7D:DA:71:10 version 6 manufacturer 10 class 0x1c0104 supported settings: powered connectable fast-connectable discoverable bondable link-security ssp br/edr hs le advertising secure-conn debug-keys privacy static-addr current settings: powered connectable discoverable bondable ssp br/edr le secure-conn
根据官方规范中的表格，可以检查映射到 HCI 版本的蓝牙版本。例如，在上一个输出中，HCI **版本 6** 是蓝牙版本 4.0。
可以使用已弃用的 `hciconfig` 来检索有关设备的更详细信息。（bluez-deprecated-tools）
$ hciconfig -a hci0
hci0: Type: USB
BD Address: 00:1B:DC:0F:DB:40 ACL MTU: 310:10 SCO MTU: 64:8
UP RUNNING PSCAN ISCAN
RX bytes:1226 acl:0 sco:0 events:27 errors:0
TX bytes:351 acl:0 sco:0 commands:26 errors:0
Features: 0xff 0xff 0x8f 0xfe 0x9b 0xf9 0x00 0x80
Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3
Link policy: RSWITCH HOLD SNIFF PARK
Link mode: SLAVE ACCEPT
Name: 'BlueZ (0)'
Class: 0x000100
Service Classes: Unspecified
Device Class: Computer, Uncategorized
HCI Ver: 2.0 (0x3) HCI Rev: 0xc5c LMP Ver: 2.0 (0x3) LMP Subver: 0xc5c
Manufacturer: Cambridge Silicon Radio (10)
音频设备在离加密狗很近的距离开始跳帧
如果其他设备共享同一 USB 主机，它们可能会中断与音频设备的通信。确保它是其总线上唯一连接的设备。例如：
$ lsusb
Bus 002 Device 002: ID 0a12:0001 Cambridge Silicon Radio, Ltd Bluetooth Dongle (HCI mode) Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub Bus 001 Device 004: ID 048d:1345 Integrated Technology Express, Inc. Multi Cardreader Bus 001 Device 003: ID 0424:a700 Standard Microsystems Corp. 2 Port Hub Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
CSR 加密狗 0a12:0001
设备 `ID 0a12:0001 Cambridge Silicon Radio, Ltd Bluetooth Dongle (HCI mode)` 有一个回归 bug，目前仅在内核版本 5.17 及 < 6.0 时工作。有关更多信息，请参阅 Kernel Bug 60824。
Logitech 蓝牙 USB 加密狗
有些 Logitech 加密狗（例如 Logitech MX5000）可以工作在两种模式下：嵌入式和 HCI。在嵌入式模式下，加密狗会模拟一个 USB 设备，因此您的 PC 会认为您正在使用普通的 USB 鼠标/键盘。
如果您按下 USB BT 迷你接收器上的小红色按钮，它将启用另一种模式。按住 BT 加密狗上的红色按钮并将其插入计算机，然后按住按钮 3-5 秒钟后，系统托盘中将出现蓝牙图标。讨论
或者，您可以安装 bluez-hid2hci 包。当您连接 Logitech 加密狗时，它会自动切换。
Foxconn / Hon Hai / Lite-On Broadcom 设备
其中一些设备需要在启动时将固件刷新到设备中。
在 AUR 上的AUR中搜索 `broadcom` 时，可以找到一些固件，其中一个值得注意的包是 broadcom-bt-firmwareAUR，它提供了多个网卡的文件。
或者，可以使用 hex2hcd（随 bluez-utils 一起安装）将 Microsoft Windows `.hex` 文件转换为 `.hcd` 文件。
为了获得正确的 `.hex` 文件，请尝试使用 `lsusb` 获取的设备供应商：产品代码进行搜索，例如：
Bus 002 Device 004: ID 04ca:2006 Lite-On Technology Corp. Broadcom BCM43142A0 Bluetooth Device
或者
Bus 004 Device 004: Id 0489:e031 Foxconn / Hon Hai
或者，启动到 Windows（虚拟机安装即可）并从设备管理器实用程序中获取固件名称。如果您想知道设备型号但无法在 `lsusb` 中看到它，您可能可以在 `lsusb -v` 中将其作为 `iProduct` 找到。
`.hex` 文件可以从下载的 Windows 驱动程序中提取，而无需运行 Windows。下载正确的驱动程序，例如 Bluetooth Widcomm[死链接 2023-09-16—域名未解析]。根据格式，提取文件可能需要 unrar 或 cabextract。要找出众多 `.hex` 文件中哪一个适合您，请查看文件 `Win32/bcbtums-win7x86-brcm.inf` 并搜索 `[RAMUSBE031.CopyList]`，其中 `E031` 应替换为您设备的（在 `lsusb` 中的第二个十六进制数字）产品代码（大写）。其下方应显示正确的 `.hex` 文件名。
获得 `.hcd` 文件后，将其复制到 `/lib/firmware/brcm/BCM.hcd` - 此文件名由 dmesg 建议，并且在您的情况下可能会更改，因此请检查您的 `dmesg` 输出以进行验证。然后重新加载 `btusb` 模块：
# rmmod btusb # modprobe btusb
现在设备应该可用了。有关使这些更改持久化的信息，请参阅 BBS#162688。
Intel 组合 Wi-Fi 和蓝牙卡
请参阅 Wireless network configuration#Bluetooth coexistence。
Mediatek MT7921 或 MT7961 在与 Windows 双启动时
在双启动系统上，如果 Windows 和 Linux 的蓝牙固件版本不同，在重新启动到 Windows 后蓝牙适配器将无法工作。
防止这种情况的最佳方法是更新每个操作系统的最新版本蓝牙驱动程序（特别是固件）。
如果您找不到 Windows 的最新版本驱动程序（或固件），您可以从 Arch Linux 复制最新的固件文件 `/usr/lib/firmware/mediatek/BT_RAM_CODE_MT7961_1_2_hdr.bin.xz` 并将其提取到 Windows（例如，`C:\WINDOWS\system32\DRIVERS\`，您可以在 Windows 的设备管理器中找到固件文件路径）。
暂停/恢复后适配器消失
首先，找到适配器的供应商 ID 和产品 ID。例如：
$ lsusb -tv
/: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/12p, 480M
ID 1d6b:0002 Linux Foundation 2.0 root hub
...
|__ Port 3: Dev 3, If 0, Class=Wireless, Driver=btusb, 12M
ID 8087:0025 Intel Corp.
|__ Port 3: Dev 3, If 1, Class=Wireless, Driver=btusb, 12M
ID 8087:0025 Intel Corp.
...
在这种情况下，供应商 ID 为 8087，产品 ID 为 0025。
然后，使用 usb_modeswitch 重置适配器：
# usb_modeswitch -R -v vendor_ID -p product_ID
配对和连接问题
计算机不可见
如果您的计算机无法从手机上发现，请启用可发现模式。
# bluetoothctl discoverable on
验证可发现模式是否已开启：
# bluetoothctl show
Powered: yes Discoverable: yes Pairable: yes
如果计算机仍然不显示，请尝试更改 `/etc/bluetooth/main.conf` 中的设备类别，如下所示：
# Default device class. Only the major and minor device class bits are # considered. #Class = 0x000100 # Computer Type (from default config) Class = 0x100100 # (Object-Transfer Service & Computer Type)
一位用户报告说，这是使其计算机对手机可见的唯一解决方案。LG 电视（以及其他一些电视）可以从其音频设备上发现，因此使用 `000414`（soundbar 类别）将使此类设备出现。
请参阅 https://bluetooth-pentest.narod.ru/software/bluetooth_class_of_device-service_generator.html 来生成蓝牙设备/服务类别。
设备连接后，几分钟后断开连接
如果您在日志中看到类似以下消息，并且您的设备连接失败或在连接后不久断开连接：
bluetoothd: Unable to get connect data for Headset Voice gateway: getpeername: Transport endpoint is not connected (107) bluetoothd: connect error: Connection refused (111)
这可能是因为您已将设备与另一个使用同一蓝牙适配器的操作系统配对（例如，双启动）。某些设备无法处理与同一 MAC 地址（即蓝牙适配器）关联的多个配对。请按照 #Dual boot pairing 中的说明解决此问题。
设备未在扫描中显示
一些使用低功耗蓝牙 (BLE) 的设备在 `bluetoothctl` 扫描时不会出现，例如 Logitech MX Master。您可以使用 `transport le` 来扫描它。
# bluetoothctl
[bluetooth]# menu scan [bluetooth]# transport le [bluetooth]# back [bluetooth]# scan on [bluetooth]# devices ... Device XX:XX:XX:XX:XX:XX DA V2 X <---- low energy device here
连接它们的另一种方法是安装 bluez-deprecated-tools，然后启动 `bluetooth.service` 并执行：
# bluetoothctl
[NEW] Controller (MAC) myhostname [default] [bluetooth]# power on [CHG] Controller (MAC) Class: 0x0c010c Changing power on succeeded [CHG] Controller (MAC) Powered: yes [bluetooth]# scan on Discovery started [CHG] Controller (MAC) Discovering: yes
在另一个终端中：
# hcitool lescan
等待您的设备出现，然后按 `Ctrl+c` 退出 `hcitool`。`bluetoothctl` 现在应该可以看到您的设备并正常配对了。
使用 Intel Corp. AX200 蓝牙无法发现任何 BLE 设备
似乎该设备的 BLE 被动扫描存在问题。有关更多详细信息，请参阅上游 bug 报告。
睡眠后无法重新连接
您可能会注意到，在设备进入睡眠状态后，或者在计算机从挂起状态唤醒后，您无法自动重新连接到设备。
您会在日志中看到类似以下的错误：
bluetoothd[487]: Authentication attempt without agent bluetoothd[487]: Access denied: org.bluez.Error.Rejected
这可能是因为设备未被标记为*受信任*。请参阅#Pairing。
设备特定问题
蓝牙鼠标延迟/断开/无响应
请参阅 Bluetooth mouse#Troubleshooting。
音频设备连接失败，出现 br-connection-profile-unavailable
如果正在使用 pipewire（而不是 pulseaudio-bluetooth）但 pipewire 的实例未运行，蓝牙音频设备将无法连接。请启动 `pipewire.service` 用户单元或播放一些音频以启动 pipewire 守护进程，然后重试连接音频设备。
耳机和鼠标之间的干扰
如果您在使用蓝牙鼠标和键盘的同时遇到音频卡顿，您可以尝试以下方法，正如 #23 中提到的 https://bugs.launchpad.net/ubuntu/+source/bluez/+bug/424215：
# hciconfig hci0 lm ACCEPT,MASTER # hciconfig hci0 lp HOLD,SNIFF,PARK
TP-LINK UB400 和 Xbox 控制器持续连接/断开
使用以下设置：
/etc/bluetooth/main.conf
... [General] JustWorksRepairing = always FastConnectable = true Class = 0x000100 ... [GATT] ReconnectIntervals=1,1,2,3,5,8,13,21,34,55 AutoEnable=true ...
然后重新启动 `bluetooth.service`。
您可以在 xpadneo 的相关讨论中看到，但 xpadneo 驱动程序不是必需的。
文件传输问题
gnome-bluetooth
如果您在尝试在 `bluetooth-properties` 中启用接收文件时看到此消息：
Bluetooth OBEX start failed: Invalid path Bluetooth FTP start failed: Invalid path
请确保 XDG 用户目录存在。
由于符号链接而无法接收传输的文件
如果文件传输在其他方面功能正常的蓝牙连接上失败，问题可能在于文件传输路径中的符号链接。日志中会出现类似以下内容：
Jun 18 11:18:13 ember obexd[3338969]: open(/home/me/.cache/obexd/MOC740): Operation not permitted (1)
如果错误消息中显示的路径包含符号链接，那么 `obexd` 默认情况下将不接受它。可以通过 `obex.service` 用户服务的下拉文件在初始化时覆盖此行为：
~/.config/systemd/user/obex.service.d/10-symlink.conf
[Service] ExecStart= ExecStart=/usr/lib/bluetooth/obexd --symlinks
然后重新加载调用用户的 *systemd* 管理器配置，并重新启动 `obex.service` 用户单元。