Wi-Fi/蓝牙¶
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
Quectel Pi H1智能主控板 支持QCA1023 SDIO Wi-Fi和HCI UART蓝牙模块，Wi-Fi可通过nmcli命令完成开启、扫描、连接及网络验证操作，蓝牙则能通过hciattach、hciconfig、bluetoothctl等命令实现模块启动、外设配对连接，还可配置为BLE外设进行广播，满足不同的无线连接需求。
Wi-Fi功能使用¶
Quectel Pi H1 智能主控板支持QCA1023 SDIO Wi-Fi。接下来将介绍通过 nmcli 配置Wi-Fi连接的操作流程。
nmcli 是一个用户空间的程序，是Linux系统中NetworkManager提供的命令行工具，专用于网络连接管理，尤其适用于无图形界面环境或自动化脚本场景。它支持以太网、Wi-Fi、VLAN、网桥、代理、VPN多种网络连接的配置与管理。
打开Wi-Fi功能¶
使用下列命令打开Wi-Fi功能，相当于桌面版的“打开Wi-Fi开关”。
nmcli radio wifi on
查看可用Wi-Fi列表¶
执行下列命令，扫描并列出当前无线网卡探测到的Wi-Fi网络。该命令会显示附近的Wi-Fi网络以及它们的名称（SSID）、信号强度、频道和加密方式等信息。
nmcli dev wifi list ifname wlan0
上述命令指定 wlan0 接口扫描Wi-Fi。可根据实际网卡名称修改。
输出关键参数说明：
参数 |
含义 |
|---|---|
IN-USE |
标注*表示当前已连接的Wi-Fi |
BSSID |
无线接入点的MAC地址 |
SSID |
Wi‑Fi网络名称 |
MODE |
网络工作模式，Infra为基础架构模式（常用） |
CHAN |
工作信道 |
RATE |
最大传输速率 |
SIGNAL |
信号强度 |
BARS |
信号强度图形化展示 |
SECURITY |
加密认证方式（WPA2/WPA3/802.1X等） |
输出示例：
$ nmcli dev wifi list ifname wlan0
IN-USE BSSID SSID MODE CHAN RATE SIGNAL BARS SECURITY
64:09:80:76:42:BE Xiaomi_42BD Infra 11 130 Mbit/s 100 ▂▄▆█ WPA1 WPA2
* F8:5E:3C:01:F8:18 xiupax Infra 11 130 Mbit/s 100 ▂▄▆█ --
9C:9D:7E:F7:30:5E tdz Infra 2 130 Mbit/s 97 ▂▄▆█ WPA1 WPA2
E2:F1:E1:57:D5:C6 gms-wifi Infra 1 0 Mbit/s 95 ▂▄▆█ WPA1 WPA2
E2:F1:E1:57:D5:C8 cit-test-5g Infra 1 0 Mbit/s 94 ▂▄▆█ WPA2
48:5F:08:BB:BA:41 TP-LINK_BA41 Infra 11 270 Mbit/s 87 ▂▄▆█ --
64:09:80:76:42:BF Xiaomi_42BD_5G Infra 157 270 Mbit/s 82 ▂▄▆█ WPA1 WPA2
B4:2F:03:DA:23:B5 5G_RRO_A23B5 Infra 157 135 Mbit/s 79 ▂▄▆_ WPA1 WPA2
A2:A7:90:A7:5B:A0 LSMate30 Infra 149 270 Mbit/s 77 ▂▄▆_ WPA2
A4:00:E2:EF:F7:83 Quectel-HF Infra 1 260 Mbit/s 74 ▂▄▆_ WPA1 WPA2 802.1X
F0:2F:74:2A:41:78 odmtest Infra 1 260 Mbit/s 74 ▂▄▆_ WPA3
2C:CF:67:6B:4A:86 HW-676B4A85 Infra 36 117 Mbit/s 74 ▂▄▆_ WPA1
A4:00:E2:EF:F7:82 Quectel-HF-2.4G Infra 1 260 Mbit/s 72 ▂▄▆_ WPA1 WPA2 802.1X
A4:00:E2:EF:F7:80 Quectel-Customer-2.4G Infra 1 260 Mbit/s 72 ▂▄▆_ WPA1 WPA2
66:D6:9A:C6:6D:21 PAXWIFIAP_2.4G Infra 1 130 Mbit/s 72 ▂▄▆_ WPA2
A4:00:E2:EF:F7:90 Quectel-Customer Infra 44 540 Mbit/s 72 ▂▄▆_ WPA1 WPA2
A4:00:E2:EF:F7:92 Quectel-HF Infra 44 540 Mbit/s 72 ▂▄▆_ WPA1 WPA2 802.1X
9C:9D:7E:F7:30:5F tdz Infra 149 270 Mbit/s 70 ▂▄▆_ WPA1 WPA2
34:CE:00:09:E5:A8 SW_test Infra 6 130 Mbit/s 69 ▂▄▆_ WPA1 WPA2
E2:F1:E1:57:D5:CA gms-wifi_5G Infra 149 270 Mbit/s 69 ▂▄▆_ WPA1 WPA2
E2:F1:E1:57:D5:CE cit-test-5g Infra 149 270 Mbit/s 69 ▂▄▆_ WPA2
F0:2F:74:2A:41:7C odmtest-5G Infra 161 540 Mbit/s 65 ▂▄▆_ WPA2
A4:00:E2:EF:F8:52 Quectel-HF Infra 36 540 Mbit/s 57 ▂▄▆_ WPA1 WPA2 802.1X
A4:00:E2:EF:F8:50 Quectel-Customer Infra 36 540 Mbit/s 57 ▂▄▆_ WPA1 WPA2
3C:7C:3F:0B:94:FC HWTEST Infra 161 540 Mbit/s 52 ▂▄__ WPA2
A4:00:E2:EF:F4:50 Quectel-Customer Infra 149 540 Mbit/s 49 ▂▄__ WPA1 WPA2
A4:00:E2:EF:F4:52 Quectel-HF Infra 149 540 Mbit/s 47 ▂▄__ WPA1 WPA2 802.1X
连接Wi-Fi网络¶
选择要连接的Wi-Fi网络，执行命令 nmcli dev wifi connect “Wi-Fi网络名称” password “Wi-Fi密码” 来连接到该网络。
示例：
$ nmcli dev wifi connect "SSID" password "12345678" ifname wlan0
Device 'wlan0' successfully activated with 'd0ef4183-ac40-41d5-8822-2cc174107c77'.
连接开放网络时（网络没有密码），则不需要提供“Wi-Fi密码”参数。
示例：
$ nmcli dev wifi connect "SSID" ifname wlan0
Device 'wlan0' successfully activated with 'd0ef4183-ac40-41d5-8822-2cc174107c77'.
验证网络状态¶
使用 ifconfig 命令查看网络接口地址，示例如下：
root@QuectelPi:~# ifconfig
eth0 Link encap:Ethernet HWaddr 32:C0:A2:09:FE:40
UP BROADCAST MULTICAST MTU:1500 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
Interrupt:167 Base address:0x1000
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:65536 Metric:1
RX packets:75 errors:0 dropped:0 overruns:0 frame:0
TX packets:75 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:6301 (6.1 KiB) TX bytes:6301 (6.1 KiB)
p2p0 Link encap:Ethernet HWaddr 02:03:7F:D6:00:01
UP BROADCAST MULTICAST MTU:1500 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:3000
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
wlan0 Link encap:Ethernet HWaddr 00:03:7F:50:00:01
inet addr:192.168.253.211 Bcast:192.168.253.255 Mask:255.255.255.0
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:3421 errors:0 dropped:0 overruns:0 frame:0
TX packets:61 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:3000
RX bytes:151273 (147.7 KiB) TX bytes:7300 (7.1 KiB)
上述输出中，可以发现wlan0口已经获取IP。
测试网络¶
执行 ping 命令测试网络连接：
执行 ping 192.168.1.1 命令，如果 ping 通则表示局域网网络连接正常【这里的目的 ip 需要修改为实际网络的网关地址】。
执行 ping 114.114.114.114 命令，如果 ping 通则表示外网网络连接正常。
执行 ping baidu.com 命令，如果 ping 通则表示外网网络连接正常且 DNS 解析功能正常。
蓝牙功能使用¶
Quectel Pi H1 智能主控板支持QCA1023 HCI UART蓝牙模块，支持蓝牙外设连接。接下来将介绍如何使用蓝牙模块连接键鼠进行测试。
蓝牙模块启动¶
蓝牙模块通过HCI UART接口连接主控，采用HCI H4协议通信。
首先通过设备节点给外设供电，当往节点echo 0时，则给蓝牙外设下电。
echo 1 > /sys/devices/platform/rfkill/bt_en
使用 hciattach 命令，通过串口初始化蓝牙模块。
hciattach /dev/ttyHS1 qca 3000000 flow
使用 hciconfig 命令，查询并且启用HCI蓝牙设备。
hciconfig hci0 up
使用 hciconfig 查询HCI设备状态。当状态显示为UP RUNNING时，说明HCI蓝牙设备已成功启用。
root@QuectelPi:~# hciconfig
hci0: Type: Primary Bus: UART
BD Address: 00:00:00:00:5A:AD ACL MTU: 1024:7 SCO MTU: 60:8
UP RUNNING
RX bytes:783665 acl:1106 sco:0 events:18678 errors:0
TX bytes:4072 acl:57 sco:0 commands:305 errors:0
连接蓝牙外设¶
执行 bluetoothctl 命令，进入蓝牙配置工具，命令提示符变成 [bluetooth]#，表示已经进入蓝牙控制模式。
root@QuectelPi:~# bluetoothctl [bluetooth]#
执行 scan on 命令，此时会执行蓝牙扫描命令，会显示周边蓝牙设备信息，此时需要打开蓝牙设备的配对模式，放在旁边。
[bluetooth]# scan on
扫描到一定时间后，执行 scan off，停止扫描。
[bluetooth]# scan off
执行 devices 命令，列出扫描到的设备，找到你的蓝牙外设，此处以蓝牙鼠标为例。
[bluetooth]# devices
Device C3:3E:68:5E:E7:1F MX Master 2S
使用 pair 命令，进行连接，地址为你的外设地址。
[bluetooth]# pair C3:3E:68:5E:E7:1F
若配对成功，终端可能弹出配对码提示。此时按照界面提示点击“配对”或在命令行输入 yes 确认，确保连接过程继续进行。
当输出CHG的日志时，说明配对成功。此时可以发现，我们的鼠标被注册到了输入设备下，例如input5（根据实际注册地址为准）。
[CHG] Device C3:3E:68:5E:E7:1F Modalias: usb:v046DpB019d0006
[MX Master 2S]# [ 1157.381232][ T1737] input: MX Master 2S Keyboard as /devices/virtual/misc/uhid/0005:046D:B019.0001/input/input4[ 1157.392409][ T1737] input: MX Master 2S Mouse as /devices/virtual/misc/uhid/0005:046D:B019.0001/input/input5
将设备添加为信任设备并且连接（可选：如果设备自动连接则可跳过）。
[MX Master 2S]# trust C3:3E:68:5E:E7:1F
Changing C3:3E:68:5E:E7:1F trust succeeded
[MX Master 2S]# connect C3:3E:68:5E:E7:1F
Attempting to connect to C3:3E:68:5E:E7:1F
Connection successful
验证外设¶
连接后，可以用evtest工具来验证外设是否可用，输入 evtest 命令，会显示可使用的event设备，这时我们选择鼠标编号5。
root@QuectelPi:~# evtest
No device specified, trying to scan all of /dev/input/event*
Available devices:
/dev/input/event0: pm8xxx_vib_ffmemless
/dev/input/event1: gpio-keys
/dev/input/event2: pmic_pwrkey
/dev/input/event3: pmic_resin
/dev/input/event4: MX Master 2S Keyboard
/dev/input/event5: MX Master 2S Mouse
Select the device event number [0-5]:
当出现如下打印信息则代表验证成功，可以通过移动鼠标按键来测试是否有事件上报。
Input driver version is 1.0.1
Input device ID: bus 0x5 vendor 0x46d product 0xb019 version 0x6
Input device name: "MX Master 2S Mouse"
Supported events:
Event type 0 (EV_SYN)
Event type 1 (EV_KEY)
Event code 272 (BTN_LEFT)
Event code 273 (BTN_RIGHT)
Event code 274 (BTN_MIDDLE)
Event code 275 (BTN_SIDE)
Event code 276 (BTN_EXTRA)
Event code 277 (BTN_FORWARD)
Event code 278 (BTN_BACK)
Event code 279 (BTN_TASK)
Event code 280 (?)
Event code 281 (?)
Event code 282 (?)
Event code 283 (?)
Event code 284 (?)
Event code 285 (?)
Event code 286 (?)
Event code 287 (?)
Event type 2 (EV_REL)
Event code 0 (REL_X)
Event code 1 (REL_Y)
Event code 6 (REL_HWHEEL)
Event code 8 (REL_WHEEL)
Event code 11 (REL_WHEEL_HI_RES)
Event code 12 (REL_HWHEEL_HI_RES)
Event type 4 (EV_MSC)
Event code 4 (MSC_SCAN)
Properties:
Testing ... (interrupt to exit)
Event: time 2618.445029, type 4 (EV_MSC), code 4 (MSC_SCAN), value 90001
Event: time 2618.445029, type 1 (EV_KEY), code 272 (BTN_LEFT), value 1
Event: time 2618.445029, -------------- SYN_REPORT ------------
Event: time 2618.610162, type 4 (EV_MSC), code 4 (MSC_SCAN), value 90001
Event: time 2618.610162, type 1 (EV_KEY), code 272 (BTN_LEFT), value 0
Event: time 2618.610162, -------------- SYN_REPORT ------------
配置蓝牙设备作为BLE外设¶
Quectel Pi H1 支持将蓝牙设备配置为低功耗（BLE）外设进行广播，允许其他BLE设备（如手机、平板）发现和连接。
操作步骤¶
启动蓝牙广告广播
bluetoothctl> advertise on
该命令用于开启蓝牙广告广播功能，创建蓝牙广告实例，同时将设备设置为可被周边蓝牙设备发现的状态，为后续设备配对和连接做准备。
配置广告参数，通过底层蓝牙管理协议配置：
设置IO能力为 KeyboardDisplay。
配置扩展广告参数（可连接模式，广播间隔1280ms）。
设置广告数据Flags（LE General Discoverable Mode，仅支持BLE）。
启用广告广播。
查看设备状态
bluetoothctl> show
查看蓝牙控制器信息，包括设备名称、MAC地址、支持的角色和GATT服务等。