Wi-Fi/BT

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

The Quectel Pi Debian development board supports Wi-Fi and Bluetooth (BT) connections. This document is based on the current board-side environment: the system is Debian GNU/Linux 13 (trixie), the wireless network interface is wlan0, the NetworkManager service is active, and commands such as nmcli, wpa_cli, wpa_supplicant, and bluetoothctl are available on the board.

💡 It is recommended to connect to Wi-Fi through the Debian desktop or nmcli first. Use wpa_cli / wpa_supplicant only when NetworkManager is unavailable, low-level debugging is required, or wpa_supplicant behavior needs to be verified.

Wi-Fi Usage

Method 1: Connect to Wi-Fi from the Debian Desktop

If a MIPI/HDMI display is connected and the board has entered the Debian GNOME desktop, you can connect to a wireless network directly from the desktop network menu. This method is suitable for basic functional verification and does not require manual command input.

  1. Connect the display, mouse, and keyboard. Power on the development board and enter the Debian desktop.

  2. Click the system status area in the upper-right corner of the desktop to expand the network menu.

  3. Make sure the Wi-Fi switch is turned on. If it is off, enable Wi-Fi first.

  4. Select the target SSID from the wireless network list.

  5. Enter the Wi-Fi password and confirm the connection.

  6. After the connection succeeds, verify network connectivity by opening a webpage in the browser, or by running ip addr show wlan0 and ping -c 4 8.8.8.8 in the terminal.

Method 3: Connect to Wi-Fi with wpa_cli / wpa_supplicant (Low-Level Debugging Method)

wpa_supplicant is the low-level Linux component responsible for Wi-Fi authentication and connection, and wpa_cli is its interactive control tool. This method is suitable when NetworkManager is not managing the interface, or when driver, firmware, or authentication behavior needs to be verified. If wlan0 is currently managed by NetworkManager, disconnect it or stop NetworkManager first to avoid two processes controlling the same wireless interface at the same time.

💡 Before using the wpa_supplicant method, make sure it will not interrupt the current remote connection. If the development board depends on Wi-Fi for remote login, stopping NetworkManager may disconnect the network.

1. Stop NetworkManager from managing wlan0 (run only when needed)

nmcli device disconnect wlan0
# Or temporarily stop NetworkManager during debugging
systemctl stop NetworkManager

2. Create the wpa_supplicant configuration file

wpa_passphrase "SSID_NAME" "Wi-Fi_PASSWORD" > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf

3. Start wpa_supplicant

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

4. Obtain an IP address through DHCP

dhclient wlan0
# If dhclient is not installed, use udhcpc or NetworkManager to obtain an address according to the actual system environment

5. Check connection status with wpa_cli

wpa_cli -i wlan0 status
wpa_cli -i wlan0 scan
wpa_cli -i wlan0 scan_results

When wpa_state=COMPLETED and ip_address contains a valid address, Wi-Fi authentication and IP acquisition are basically working.

6. Connect interactively with wpa_cli (optional)

wpa_cli -i wlan0
> scan
> scan_results
> add_network
> set_network 0 ssid "\"SSID_NAME\""
> set_network 0 psk "\"Wi-Fi_PASSWORD\""
> enable_network 0
> save_config
> status

Bluetooth Usage

The Quectel Pi Debian development board has built-in Bluetooth support. In the current board environment, the bluetooth service is active and bluetoothctl show can identify the controller, which indicates that the basic Bluetooth service has started.

Method 1: Connect to a Bluetooth Device from the Debian Desktop

  1. After entering the Debian desktop, open Settings.

  2. Go to the Bluetooth page.

  3. Turn on Bluetooth and set the target Bluetooth device to pairing/discoverable mode.

  4. Select the target device from the device list, such as a Bluetooth headset, keyboard, or mouse.

  5. Follow the on-screen prompts to complete Pair and Connect.

Method 2: Connect to a Bluetooth Device with bluetoothctl

If no graphical interface is available, or if debugging is required through ADB or serial console, use bluetoothctl.

systemctl status bluetooth
bluetoothctl

After entering bluetoothctl, run:

power on
agent on
default-agent
scan on

Wait until the target device is found, record the device MAC address, and then run:

pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
scan off
quit

After the device is connected, use the following commands to check the controller and device status:

bluetoothctl show
bluetoothctl devices
bluetoothctl info XX:XX:XX:XX:XX:XX

Common Troubleshooting

Symptom

Troubleshooting Method

Wi-Fi networks cannot be scanned

Check whether the antenna is connected. Run rfkill list to check whether Wi-Fi is blocked by software or hardware. Run nmcli radio wifi on and scan again.

wlan0 does not exist

Run ip link and dmesg | grep -i wlan to check whether the driver and firmware are loaded.

nmcli connection fails

Check whether the SSID and password are correct. Use journalctl -u NetworkManager -b to view NetworkManager logs.

wpa_cli shows that it cannot connect

Make sure wpa_supplicant has started, and that the control interface matches the interface used by wpa_cli -i wlan0.

Bluetooth cannot scan devices

Make sure systemctl status bluetooth is normal, run bluetoothctl power on, and confirm that the peripheral device is in discoverable mode.

Board-Side Confirmation Commands

When maintaining or locating issues, collect the following information first to confirm the system, interface, and service status:

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