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. 查看无线设备状态

nmcli general status
nmcli radio wifi
nmcli device status

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

nmcli radio wifi on

2. 扫描附近 Wi-Fi

nmcli device wifi rescan ifname wlan0
nmcli device wifi list ifname wlan0

3. 连接目标 Wi-Fi

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

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

4. 查看连接结果

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

5. 常用维护命令

# 断开 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（按需执行）

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

2. 创建 wpa_supplicant 配置文件

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

3. 启动 wpa_supplicant

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

4. 通过 DHCP 获取 IP 地址

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

5. 使用 wpa_cli 查看连接状态

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 交互式连接（可选）

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。

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

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

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，并确认外设处于可发现模式。

板端确认命令

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

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