Wi-Fi/蓝牙

2026-02-28

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设备（如手机、平板）发现和连接。

操作步骤

  1. 启动蓝牙广告广播

    bluetoothctl> advertise on

    该命令用于开启蓝牙广告广播功能，创建蓝牙广告实例，同时将设备设置为可被周边蓝牙设备发现的状态，为后续设备配对和连接做准备。

  2. 配置广告参数，通过底层蓝牙管理协议配置：

    • 设置IO能力为KeyboardDisplay。
    • 配置扩展广告参数（可连接模式，广播间隔1280ms）。
    • 设置广告数据Flags（LE General Discoverable Mode，仅支持BLE）。
    • 启用广告广播。

  3. 查看设备状态

    bluetoothctl> show

    查看蓝牙控制器信息，包括设备名称、MAC地址、支持的角色和GATT服务等。