# Wi-Fi/BT

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

**Quectel Pi** Debian 开发板支持 **Wi-Fi** 和 **蓝牙（BT）** 连接。本文以当前板端环境为准：系统为 Debian GNU/Linux 13（trixie），无线网卡接口为 `wlan0`，NetworkManager 服务处于 active 状态，同时板端已提供 `nmcli`、`wpa_cli`、`wpa_supplicant` 和 `bluetoothctl` 等命令。

> 💡 推荐优先使用 Debian 桌面或 `nmcli` 连接 Wi-Fi；只有在 NetworkManager 不可用、需要底层调试或验证 wpa_supplicant 行为时，再使用 `wpa_cli` / `wpa_supplicant` 方式。

# Wi-Fi 功能使用

## 方式一：Debian 桌面连接 Wi-Fi

如果已连接 MIPI/HDMI 显示器并进入 Debian GNOME 桌面，可以直接通过桌面网络菜单连接无线网络。该方式适合普通功能验证，不需要手动输入命令。

1. 连接显示器、鼠标和键盘，上电启动开发板，进入 Debian 桌面。

2. 点击桌面右上角系统状态区域，展开网络菜单。

3. 确认 Wi-Fi 开关已打开；如果未打开，先启用 Wi-Fi。

4. 在无线网络列表中选择目标 SSID。

5. 输入 Wi-Fi 密码并确认连接。

6. 连接成功后，可通过浏览器访问网页，或在终端执行 `ip addr show wlan0`、`ping -c 4 8.8.8.8` 验证网络连通性。

## 方式二：使用 nmcli 连接 Wi-Fi（推荐命令行方式）

`nmcli` 是 NetworkManager 的命令行工具。当前 Debian 板端 NetworkManager 已运行，`wlan0` 被识别为 Wi-Fi 设备，因此推荐用该方式完成命令行连接。

**1. 查看无线设备状态**

```bash
nmcli general status
nmcli radio wifi
nmcli device status
```

正常情况下应能看到 `wlan0` 类型为 `wifi`。如果 Wi-Fi 显示 disabled，可执行：

```bash
nmcli radio wifi on
```

**2. 扫描附近 Wi-Fi**

```bash
nmcli device wifi rescan ifname wlan0
nmcli device wifi list ifname wlan0
```

**3. 连接目标 Wi-Fi**

```bash
nmcli device wifi connect "SSID名称" password "Wi-Fi密码" ifname wlan0
```

如果 SSID 或密码中包含空格、特殊字符，建议保留英文双引号。连接成功后，NetworkManager 会自动保存连接配置，后续开机或网络恢复时通常会自动重连。

**4. 查看连接结果**

```bash
nmcli connection show --active
ip addr show wlan0
ip route
ping -c 4 8.8.8.8
```

**5. 常用维护命令**

```bash
# 断开 wlan0 当前连接
nmcli device disconnect wlan0

# 重新拉起已保存连接
nmcli connection up "SSID名称"

# 删除已保存连接
nmcli connection delete "SSID名称"
```

## 方式三：使用 wpa_cli / wpa_supplicant 连接 Wi-Fi（底层调试方式）

`wpa_supplicant` 是 Linux 下负责 Wi-Fi 认证和连接的底层组件，`wpa_cli` 是它的交互控制工具。该方式适合 NetworkManager 不参与管理、需要验证驱动/固件/认证流程时使用。若当前 `wlan0` 正由 NetworkManager 管理，建议先断开或停止 NetworkManager，避免两个进程同时控制同一无线网卡。

> 💡 执行 wpa_supplicant 方式前，请确认不会影响当前远程连接。如果开发板依赖 Wi-Fi 远程登录，停止 NetworkManager 可能导致网络中断。

**1. 停止 NetworkManager 管理 wlan0（按需执行）**

```bash
nmcli device disconnect wlan0
# 或者调试时临时停止 NetworkManager
systemctl stop NetworkManager
```

**2. 创建 wpa_supplicant 配置文件**

```bash
wpa_passphrase "SSID名称" "Wi-Fi密码" > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
```

**3. 启动 wpa_supplicant**

```bash
ip link set wlan0 up
wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
```

**4. 通过 DHCP 获取 IP 地址**

```bash
dhclient wlan0
# 如果系统未安装 dhclient，可根据系统实际情况使用 udhcpc 或 NetworkManager 方式获取地址
```

**5. 使用 wpa_cli 查看连接状态**

```bash
wpa_cli -i wlan0 status
wpa_cli -i wlan0 scan
wpa_cli -i wlan0 scan_results
```

当 `wpa_state=COMPLETED` 且 `ip_address` 有有效地址时，表示 Wi-Fi 认证和 IP 获取基本正常。

**6. 使用 wpa_cli 交互式连接（可选）**

```bash
wpa_cli -i wlan0
> scan
> scan_results
> add_network
> set_network 0 ssid "\"SSID名称\""
> set_network 0 psk "\"Wi-Fi密码\""
> enable_network 0
> save_config
> status
```

# 蓝牙功能使用

**Quectel Pi** Debian 开发板内置蓝牙功能。当前板端 `bluetooth` 服务处于 active 状态，`bluetoothctl show` 可识别到控制器，说明蓝牙基础服务已启动。

## 方式一：Debian 桌面连接蓝牙设备

1. 进入 Debian 桌面后，打开 Settings（设置）。

2. 进入 Bluetooth（蓝牙）页面。

3. 打开蓝牙开关，并将目标蓝牙设备设置为可配对/可发现状态。

4. 在设备列表中选择目标设备，例如蓝牙耳机、键盘或鼠标。

5. 根据界面提示完成 Pair（配对）和 Connect（连接）。

## 方式二：使用 bluetoothctl 连接蓝牙设备

如果没有图形界面，或需要通过 ADB/串口进行调试，可以使用 `bluetoothctl`。

```bash
systemctl status bluetooth
bluetoothctl
```

进入 `bluetoothctl` 后执行：

```
power on
agent on
default-agent
scan on
```

等待扫描到目标设备后，记录设备 MAC 地址，然后执行：

```
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
scan off
quit
```

连接后可使用以下命令查看控制器和设备状态：

```bash
bluetoothctl show
bluetoothctl devices
bluetoothctl info XX:XX:XX:XX:XX:XX
```

# 常见问题排查

| **现象** | **排查方法** |
| --- | --- |
| 扫描不到 Wi-Fi | 确认天线连接、执行 `rfkill list` 检查是否被软/硬件禁用，执行 `nmcli radio wifi on` 后重新扫描。 |
| wlan0 不存在 | 执行 `ip link`、`dmesg \| grep -i wlan` 检查驱动和固件是否加载。 |
| nmcli 连接失败 | 检查 SSID/密码是否正确，使用 `journalctl -u NetworkManager -b` 查看 NetworkManager 日志。 |
| wpa_cli 显示无法连接 | 确认 wpa_supplicant 已启动，并且控制接口与 `wpa_cli -i wlan0` 使用的接口一致。 |
| 蓝牙无法扫描设备 | 确认 `systemctl status bluetooth` 正常，执行 `bluetoothctl power on`，并确认外设处于可发现模式。 |

# 板端确认命令

维护或定位问题时，可先收集以下信息，确认系统、接口和服务状态：

```bash
cat /etc/os-release
uname -a
ip link show wlan0
nmcli general status
nmcli device status
systemctl is-active NetworkManager
systemctl is-active bluetooth
bluetoothctl show
```