Wi-Fi/Bluetooth
The Quectel Pi H1 smart single-board computer supports the QCA1023 SDIO Wi-Fi and HCI UART Bluetooth modules. Wi-Fi can be enabled, scanned, connected and network verified through the nmcli command. Bluetooth can be initiated, peripheral pairing and connection achieved through commands such as hciattach, hciconfig, and bluetoothctl. It can also be configured as a BLE peripheral for broadcasting, meeting various wireless connection requirements.
Wi-Fi usage
The Quectel Pi H1 smart single‑board computer supports the QCA1023 SDIO Wi‑Fi module. This section introduces how to configure Wi‑Fi connections using the nmcli command-line tool.
nmcliis a user‑space command-line utility provided by NetworkManager on Linux systems. It is used for managing network connections, especially in environments without a graphical interface or in automation scripts. It supports configuration and management of Ethernet, Wi‑Fi, VLAN, bridge, proxy, VPN, and other types of network connections.
Enable Wi-Fi
Use the following command to turn on Wi‑Fi functionality. It is equivalent to enabling the Wi‑Fi switch in a desktop environment:
nmcli radio wifi on
View available Wi-Fi networks
Execute the following command to scan and list all Wi‑Fi networks detected by the wireless interface.
The command displays nearby Wi‑Fi networks and information such as SSID, signal strength, channel, and security type:
nmcli dev wifi list ifname wlan0
This command instructs interface
wlan0to perform the scan. You may modify the interface name based on the actual hardware.
Key parameter description:
| Parameters | description |
|---|---|
| IN-USE | * indicates that the network is currently connected |
| BSSID | MAC address of the access point |
| SSID | Wi‑Fi network name |
| MODE | Operation mode, Infra indicates infrastructure mode (common) |
| CHAN | Channel number |
| RATE | Maximum data rate |
| SIGNAL | Signal strength |
| BARS | Bar graphical signal indicator |
| SECURITY | Security protocol (such as WPA2, WPA3, and 802.1X) |
Example output:
root@QuectelPi:~# 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
Connect to a Wi-Fi network
Select the Wi-Fi network you want to connect to and execute the command nmcli dev wifi connect "Wi-Fi name" password "Wi-Fi password" to connect to it.
Example:
$ nmcli dev wifi connect "SSID" password "12345678" ifname wlan0
Device 'wlan0' successfully activated with 'd0ef4183-ac40-41d5-8822-2cc174107c77'.
If you are connecting to an open network (no password required), the parameter "Wi-Fi password" is not needed.
Example:
root@QuectelPi:~# nmcli dev wifi connect "SSID" ifname wlan0
Device 'wlan0' successfully activated with 'd0ef4183-ac40-41d5-8822-2cc174107c77'.
Verify network status
Use ifconfig command to view the network interface address.
Example:
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)
From the output, you can see that the wlan0 interface has successfully obtained an IP address.
Test network
Execute the ping command to test network connection (replace the IP with your actual gateway IP):
ping 192.168.1.1→ Tests LAN gateway connection.ping 114.114.114.114→ Tests external network connection.ping baidu.com→ Tests external connectivity and DNS resolution.
Bluetooth usage
The Quectel Pi H1 smart single-board computer supports the QCA1023 HCI UART Bluetooth module for Bluetooth peripheral connections. This section introduces how to connect Bluetooth devices such as keyboards and mice.
Start the Bluetooth module
The Bluetooth module connects to the host controller via HCI UART using the HCI H4 protocol.
Power on the Bluetooth peripheral via the device node with the following command. (echo 0 powers it off).
echo 1 > /sys/devices/platform/rfkill/bt_en
Initialize the Bluetooth module via UART with the hciattach command.
hciattach /dev/ttyHS1 qca 3000000 flow
Query and enable the HCI Bluetooth device with the hciconfig command:
hciconfig hci0 up
Query HCI device status with hciconfig. If the device shows UP RUNNING, Bluetooth has been successfully enabled:
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
Connect Bluetooth peripherals
Execute bluetoothctl to enter the Bluetooth configuration tool. When the command prompt changes to [bluetooth]#, the device enters Bluetooth control mode.
root@QuectelPi:~# bluetoothctl
[bluetooth]#
Execute scan on to start device discovery, which will display nearby Bluetooth devices. Please enable pairing mode on the target device.
[bluetooth]# scan on
After scanning for a while, execute scan off to stop scanning.
[bluetooth]# scan off
Execute devices to list discovered devices and find your Bluetooth device. Here is an example of a Bluetooth mouse.
[bluetooth]# devices
Device C3:3E:68:5E:E7:1F MX Master 2S
Execute pair to pair the device with your peripheral's address.
[bluetooth]# pair C3:3E:68:5E:E7:1F
A pairing code prompt may appear during the pairing. Confirm it by clicking "Pair" in the UI or typing yes in the terminal so the connection can proceed.
If pairing succeeds, CHG logs will appear and the device will be registered to the input device. For example, input5 below (refer to actual registered addresses).
[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
Mark the device as trusted and connect (skip if your device supports autoconnection):
[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
Verify peripheral
After connection, use the evtest tool to verify the peripheral functionality. Enter evtest to view the list of available event devices. Then, select the number corresponding to your device (e.g., event 5 for your mouse).
root@QuectelPi:~# evtest
No device specified, scanning all /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]:
When the following output information appears, the connection is completed. You can test whether events are reported by moving the mouse or pressing its buttons.
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 ------------
Configure the Bluetooth device as a BLE peripheral
The Quectel Pi H1 supports configuring the Bluetooth device as a Bluetooth Low Energy (BLE) peripheral for broadcasting, allowing other BLE devices (such as smartphones and tablets) to discover and connect.
Operation steps
Start Bluetooth advertising
bluetoothctl> advertise onThis command enables the Bluetooth advertising function, creates a Bluetooth advertising instance, and sets the device to be discoverable by nearby Bluetooth devices, preparing for subsequent device pairing and connection.
Configure advertising parameters, configure via the underlying Bluetooth management protocol:
- Set IO capability to
KeyboardDisplay - Configure extended advertising parameters (connectable mode, broadcast interval 1280ms)
- Set advertising data flags (LE General Discoverable Mode, BLE only)
- Enable advertising
- Set IO capability to
View device status
bluetoothctl> showView Bluetooth controller details such as device name, MAC address, supported roles, and GATT services.