WIFI/BT
The Quectel Pi H1 single-board computer supports QCA1023 SDIO Wifi. This document describes how to connect to a Wi-Fi hotspot using Network Manager.
nmcli is a user-space program and a command-line tool provided by NetworkManager in Linux systems. It is used to manage network connections, especially in environments where a graphical interface is unavailable or for automated scripting. It can configure connections such as Ethernet, Wi-Fi, VLAN, bridging, proxy, and VPN. The following tutorial demonstrates how to connect to a Wi-Fi hotspot using nmcli.
WIFI function usage
Enable Wireless Functionality
Use the following command to enable wireless functionality, which is equivalent to "turning on the Wi-Fi switch" in the desktop version:
nmcli radio wifi on
View Available WiFi List
Execute the command to scan and list the Wi-Fi networks detected by the current wireless network card. This command will display nearby WiFi networks along with their names (SSID), signal strength, channels, encryption methods, and other information:
nmcli dev wifi list ifname wlan0
The return result is as follows, showing information about surrounding hotspots:
root@QuecPi:~# 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 WiFi Network
Select the WiFi network you want to connect to and execute the command nmcli dev wifi connect "your WiFi name" password "your password" to connect to the network. For example, nmcli dev wifi connect "MyHomeWiFi" password "12345678". If the network has no password, the password parameter is not required.
Connect to an encrypted hotspot:
root@QuecPi:~# nmcli dev wifi connect "SSID" password "12345678" ifname wlan0
Device 'wlan0' successfully activated with 'd0ef4183-ac40-41d5-8822-2cc174107c77'.
Connect to an open hotspot:
root@QuecPi:~# nmcli dev wifi connect "SSID" ifname wlan0
Device 'wlan0' successfully activated with 'd0ef4183-ac40-41d5-8822-2cc174107c77'.
Use the ifconfig command to view the network interface address:
root@qcm6490-idp:~# 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)
Network Testing
Execute the ping command to verify the network connection:
ping 192.168.1.1→ If the IP address can be pinged successfully, it indicates a successful network connection (replace the gateway IP with actual values).ping 114.114.114.114→ If the address can be pinged successfully, it indicates a successful external network connection.ping baidu.com→ If the address can be pinged successfully, it indicates a successful DNS resolution and external network connection.
Bluetooth function use
The Quectel Pi H1 single-board computer supports the QCA1023 HCI UART Bluetooth module for connecting Bluetooth peripherals. This document describes how to test Bluetooth keyboard and mouse connectivity.
Initialize Bluetooth Module
The Bluetooth module connects to the CPU via HCI UART using the HCI H4 protocol.
Power on the Bluetooth peripheral by writing to the device node with the following command. Power off the Bluetooth peripheral by writing to the device node with echo 0.
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
Verify HCI device status with hciconfig. When the status is UP RUNNING, it indicates that the HCI Bluetooth device is enabled:
root@qcm6490-idp:~# 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 Bluetooth configuration tool. When the command prompt changes to [bluetooth]# , it indicates that the device enters Bluetooth control mode.
root@qcm6490-idp:~# bluetoothctl
[bluetooth]#
Execute scan on to start device discovery to 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 the pair command to pair the device with your peripherals' address.
[bluetooth]# pair C3:3E:68:5E:E7:1F
When pairing succeeds, a passkey dialog may appear. Confirm the pairing request by clicking “Pair” in the UI or typing yes in the terminal so the connection can proceed.
If the pairing is successful, the CHG logs will be printed out. Then the mouse is registered to the input device such as input5 (Please refer to the actual registered address).
[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
Add the device to trust and connect. (Optional 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
At this point, you can use the evtest tool to verify if the peripheral is functional. Enter evtest to view the list of available event devices. Then, select the device corresponding to your mouse (e.g., event 5).
root@qcm6490-idp:~# 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 information appears, the connection is completed. Mouse movements will generate real-time event reports.
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 BLE Peripheral Advertising
The Quectel Pi H1 can operate as a Bluetooth Low Energy (BLE) peripheral that proactively advertises so that phones, tablets, and other BLE central devices can discover and connect.
Procedure Overview
Start advertising
bluetoothctl> advertise onEnables advertising, creates an advertising instance, and makes the device discoverable.
Configure advertising parameters
- Set IO capability to
KeyboardDisplay - Configure extended advertising (connectable mode, 1280 ms interval)
- Populate advertising data flags (LE General Discoverable Mode, BR/EDR not supported)
- Enable the advertising instance through HCI commands
- Set IO capability to
Inspect controller status
bluetoothctl> showConfirms controller name, MAC address, supported roles, GATT services, and advertising capacity.
Technical Highlights
- Roles: Supports acting as both BLE peripheral and central
- Connectivity: Discoverable and connectable so centrals can initiate links
- GATT services: Includes GATT, Device Information, audio roles (Source/Sink/Headset), Message Notification, Phone Book Access, and vendor-specific services
System Capabilities
- BLE GATT via BlueZ 5.x
- Automatic advertising enablement
- Automatic pairing workflow
Example Use Cases
- BLE sensor gateway
- Smart-home controller
- Bluetooth audio endpoint
- Message notification hub
- Remote control accessory