bluetoothctl使用说明

夜星辰2025

已于 2025-04-01 14:30:17 修改

阅读量1.3k

点赞数 22

文章标签： bt bluetoothctl

于 2025-03-18 14:40:15 首次发布

本文链接：https://blog.csdn.net/weixin_37787043/article/details/146341132

版权

bluetoothctl 是 Linux 系统中一个强大的命令行工具，用于管理和配置 Bluetooth 设备。通过 bluetoothctl，用户可以扫描、配对、连接、取消配对设备，甚至进行更高级的配置操作。以下是 bluetoothctl 的详细使用说明，涵盖从基础操作到高级功能的各个方面。
在这里插入图片描述

前言

bluetoothctl 是 BlueZ 套件的一部分，BlueZ 是 Linux 上的官方 Bluetooth 协议栈。通过 bluetoothctl，用户可以以交互式的方式管理 Bluetooth 设备，适用于桌面和嵌入式系统。

安装 `bluetoothctl`

大多数现代 Linux 发行版默认已安装 BlueZ 和 bluetoothctl。如果未安装，可以通过以下命令安装：

Debian/Ubuntu 系列

sudo apt update
sudo apt install bluez

Fedora

sudo dnf install bluez bluez-tools

Arch Linux

sudo pacman -S bluez bluez-utils

安装完成后，可以通过 bluetoothctl 命令使用该工具。

启动 `bluetoothctl`

在终端中输入以下命令启动 bluetoothctl：

bluetoothctl

进入 bluetoothctl 交互模式后，提示符会变为 [bluetooth]#，表示可以输入命令进行管理。

基本命令和操作

以下是一些 bluetoothctl 的基本命令和常见操作。

查看帮助

在 bluetoothctl 提示符下输入 help 或 ? 可以查看所有可用的命令。

[bluetooth]# help

查看当前状态

查看 Bluetooth 控制器的状态。

[bluetooth]# show

输出示例：

Controller XX:XX:XX:XX:XX:XX (public)
        Name: your-device-name
        Alias: your-device-name
        Powered: yes
        Discoverable: no
        Pairable: yes
        UUID: ...

打开/关闭 Bluetooth

打开 Bluetooth

[bluetooth]# power on

关闭 Bluetooth

[bluetooth]# power off

扫描设备

开始扫描

[bluetooth]# scan on

系统会开始扫描周围的 Bluetooth 设备，并在终端中实时显示发现的设备信息。

停止扫描

[bluetooth]# scan off

配对设备

开始配对
首先需要确保 Bluetooth 已开启并且设备处于可发现状态。
```
[bluetooth]# pair XX:XX:XX:XX:XX:XX
```
替换 XX:XX:XX:XX:XX:XX 为目标设备的 MAC 地址。
输入 PIN （如果需要）
某些设备可能会要求输入 PIN 进行配对，具体操作取决于设备类型和安全设置。

信任设备

信任设备后，系统会自动接受来自该设备的连接请求。

[bluetooth]# trust XX:XX:XX:XX:XX:XX

连接设备

[bluetooth]# connect XX:XX:XX:XX:XX:XX

断开设备

[bluetooth]# disconnect XX:XX:XX:XX:XX:XX

取消配对设备

[bluetooth]# remove XX:XX:XX:XX:XX:XX

列出已配对设备

[bluetooth]# devices

输出示例：

Device XX:XX:XX:XX:XX:XX Device_Name

高级操作

除了基本的连接和配对功能，bluetoothctl 还支持一些更高级的操作。

管理代理

代理用于处理配对请求和密钥管理。

启动代理

[bluetooth]# agent on

设置默认代理

[bluetooth]# default-agent

设置设备为不可见

默认情况下，设备在配对模式下是可见的。可以通过以下命令控制设备是否可见。

设置设备为可见

[bluetooth]# discoverable on

设置设备为不可见

[bluetooth]# discoverable off

配置音频配置文件

对于音频设备，可以管理并切换不同的音频配置文件（如 A2DP、Headset）。

列出音频配置文件

[bluetooth]# list

切换音频配置文件（需要具体工具如 `pavucontrol` 或 `blueman` 支持）

bluetoothctl 本身不直接管理音频配置文件，但配对和连接后，可以结合 PulseAudio 或 PipeWire 进行音频配置。

示例场景

配对并连接蓝牙耳机

启动 bluetoothctl
```
bluetoothctl
```
打开 Bluetooth
```
[bluetooth]# power on
```

设置代理

[bluetooth]# agent on
[bluetooth]# default-agent

扫描设备
```
[bluetooth]# scan on
```
找到耳机的 MAC 地址
例如，发现耳机的 MAC 地址为 AA:BB:CC:DD:EE:FF。
开始配对
```
[bluetooth]# pair AA:BB:CC:DD:EE:FF
```
信任设备
```
[bluetooth]# trust AA:BB:CC:DD:EE:FF
```
连接设备
```
[bluetooth]# connect AA:BB:CC:DD:EE:FF
```
完成后，可退出 bluetoothctl
```
[bluetooth]# exit
```

连接蓝牙音箱

流程与连接蓝牙耳机类似，具体步骤参照上述配对步骤，只需替换设备的 MAC 地址和名称。

提示与故障排除

确保 Bluetooth 服务已启动
在使用 bluetoothctl 前，确保 BlueZ 服务正在运行。
```
sudo systemctl status bluetooth
```
如果未启动，可以通过以下命令启动：
```
sudo systemctl start bluetooth
```
查看支持的命令和状态
使用 help 命令查看可用命令，确保输入正确。
驱动和固件
某些 Bluetooth 硬件可能需要特定的驱动或固件支持，确保系统中已正确安装。
日志检查
如果遇到问题，可以查看系统日志以获取更多信息。
```
sudo journalctl -u bluetooth
```
重置 Bluetooth 适配器
有时重置适配器可能有助于解决连接问题。
```
[bluetooth]# power off
[bluetooth]# power on
```
设备兼容性
确保目标设备处于配对模式，并且支持与 Linux 系统的兼容性。