User Guide¶

This document is the central usage entry for the Quectel Pi M1/L1 Linux system. It summarizes the core usage methods for power supply, connection, network, display, camera, multimedia, storage, and expansion interfaces for quick reference.

Power-On and Power Supply¶

Quectel Pi uses the POWER IN Type-C port as the main power input. A power adapter and matching cable capable of 5 V / 5 A output are recommended. A power supply below 3 A is not recommended, because it may cause boot failure, system freeze, unstable peripherals, or power loss under high load.

Before power-on, check the DIP switches, display, camera, USB peripherals, expansion board, and other connections. MIPI, camera, HDMI, high-power USB peripherals, and 40-pin expansion interfaces should be connected or disconnected only after power is off, to avoid communication errors or hardware damage caused by hot plugging. After connecting the power cable, press and hold the side PWRKEY until the system starts. After the power indicator stays on, wait for the system to finish booting, and then enter the system through ADB, serial port, display, or network.

Do not confuse the USB Type-C debug/flashing port with the POWER IN power port. USB Device mode is mainly used for ADB, flashing, and interaction with the host PC; it is not used for external USB flash drives, keyboards, mice, or other USB peripherals. USB Host mode can connect USB flash drives, keyboards, mice, USB cameras, and other common peripherals, but high-power modules should use external power.

Default Network Port Exposure Description¶

The default port policy follows the least-exposure principle. Only services that need to be accessed by external hosts listen on all addresses or NIC addresses. Services used only by local components should listen on loopback addresses. The default externally exposed port is mainly TCP 22 (SSH) for remote login and maintenance.

Protocol/Port	Default Listening Scope	Purpose	Description
TCP 22	Externally reachable address	SSH remote login	Used for development, debugging, and maintenance. After the device obtains a valid IP and the network is reachable, it can be accessed through SSH.
TCP 5037	`127.0.0.1`	ADB local service	Used only for local ADB-related process communication, not exposed as an external network port.
TCP 9083	`127.0.0.1`	Local port bridge	Used only by internal services on the development board.
TCP/UDP 53	`127.0.0.53` / `127.0.0.54`	Local DNS resolution	Used for local domain name resolution, not provided as an external DNS service.
UDP 323	`127.0.0.1` / `::1`	Local time synchronization	Used only locally and not provided as an external time synchronization service by default.

Common service ports such as 3389 (RDP/xrdp), 5900 (VNC), and 80/443 (HTTP/HTTPS) are not opened as external services by default. They may listen and become externally accessible only after users install, enable, and configure the corresponding services.

Device Connection Methods¶

ADB Terminal¶

ADB is suitable for local debugging during development, entering the shell, transferring files, rebooting the device, and executing one-time commands. After connecting the host and development board with a USB Type-C data cable, prepare platform-tools or the system-provided adb tool on the host side to manage the device through ADB.

adb devices -l
adb shell
adb push ./file.txt /data/
adb pull /data/file.txt ./
adb reboot

The development board usually has adbd.service integrated. To confirm the service status, run the following command from a local terminal or serial console:

systemctl status adbd.service --no-pager -l

Debug UART Serial Port¶

Debug UART does not depend on the network or graphical interface. It is suitable for viewing boot logs and troubleshooting low-level issues such as system boot failure, display abnormality, and network abnormality. Use a USB-to-TTL serial adapter that supports 3.3 V logic level, and connect TX/RX/GND correctly.

On a Linux host, use a serial tool to connect. The common baud rate is 115200, and the actual device node depends on host detection:

ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
picocom -b 115200 /dev/ttyUSB0

If there is no output or garbled output, first check whether TX/RX are crossed correctly, whether GND is common, whether the baud rate is consistent, and whether the serial adapter driver works normally.

SSH Remote Terminal and SCP File Transfer¶

SSH is used for remote command-line login after the network is reachable. SCP is used for file transfer based on SSH. Before use, confirm that the development board has obtained an IP address through Ethernet, Wi-Fi, or cellular network, and that the SSH service is running.

ip -br addr
systemctl status ssh --no-pager
ssh <username>@<device_ip>
scp ./file.txt <username>@<device_ip>:/home/<username>/
scp -r ./project <username>@<device_ip>:/home/<username>/

If the connection fails, first confirm that the IP is correct, the host and development board can reach each other, port 22 is listening, and the username/password are correct.

Graphical Remote Desktop¶

Graphical remote desktop is suitable when the Linux desktop needs to be viewed or operated remotely. M1 can use the integrated graphical remote desktop capability; L1 can use the Weston RDP backend depending on image support. Remote desktop requires network connectivity between the device and controller, and the graphical session or remote desktop service must be started.

If TeamViewer is used, make sure both the device side and the controller side can access the public network, and complete device ID, password, or account binding configuration. TeamViewer is more suitable for cross-network remote maintenance, while RDP is more suitable for access within the same LAN.

Samba and Apache Services¶

Samba can be used for LAN file sharing, and Apache can be used to provide simple web pages or file services. Both services depend on network reachability, service startup, correct shared directory or web root configuration, and may involve accounts, passwords, and directory permissions.

systemctl status smb --no-pager 2>/dev/null || systemctl status smbd --no-pager
systemctl status apache2 --no-pager 2>/dev/null || systemctl status httpd --no-pager
ip -br addr
ss -lntup

If file sharing or web service is not required in the product scenario, keep these services disabled to avoid unnecessary network exposure.

Common qpi-config Configuration¶

qpi-config is used to view and configure common board-side functions, including LED, desktop environment, temperature, system status, and Wi-Fi. This document is organized from the Linux command-line perspective and does not depend on the Debian desktop workflow.

qpi-config dump temperature
qpi-config dump systemusage
qpi-config led get
qpi-config wifi scan

If qpi-config is used to configure Wi-Fi, the actual backend supported by the image still applies. If Wi-Fi must be connected manually, refer first to the wpa_supplicant / wpa_cli workflow in the Wi-Fi section of this document.

Display Function¶

The display section includes two output types: MIPI-DSI and Micro HDMI. Power-off operation is recommended before connecting or switching display interfaces. The display capability, touch path, and audio/video path of MIPI and HDMI depend on the screen, cable, touch USB cable, and system graphical environment configuration.

MIPI Display¶

A MIPI screen is usually connected through a DSI ribbon cable and may be used together with touch functionality. If display abnormalities occur, check the cable orientation, latch, backlight, touch cable, and system display nodes.

ls /sys/class/drm/
cat /sys/class/backlight/*/brightness 2>/dev/null
cat /sys/class/backlight/*/max_brightness 2>/dev/null

HDMI Display¶

HDMI is suitable for external monitors or touch displays. HDMI touch screens usually require a separate USB touch cable. If HDMI has no display, first check the cable, display input source, resolution mode, and DRM status.

cat /sys/class/drm/card0-HDMI-A-1/status 2>/dev/null
cat /sys/class/drm/card0-HDMI-A-1/modes 2>/dev/null

Camera Function¶

The camera document mainly covers MIPI CSI cameras, with IMX219 as the example accessory. Before use, confirm the camera model, FPC cable orientation, connector position, and latch status. If the camera is abnormal, check the hardware connection first, and then check video nodes and capture formats.

ls /dev/video*
v4l2-ctl --list-devices 2>/dev/null
v4l2-ctl --list-formats-ext -d /dev/video0 2>/dev/null

Preview, photo capture, and video recording can be executed with GStreamer, v4l2, or application-layer tools provided by the image. When using dual cameras, confirm that both cameras are recognized by the system, and avoid cable, power, or lane configuration errors.

Wi-Fi and Bluetooth¶

Wi-Fi Connection (Linux / wpa_supplicant)¶

Wi-Fi connection is organized as a Linux command-line workflow. The main workflow uses wpa_supplicant / wpa_cli, not nmcli. Before connecting, confirm the wireless interface name, commonly wlan0.

ip link show wlan0
rfkill list 2>/dev/null
ip link set wlan0 up

Use wpa_passphrase to generate the configuration and start wpa_supplicant:

wpa_passphrase "SSID_NAME" "Wi-Fi_PASSWORD" > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
udhcpc -i wlan0 2>/dev/null || dhclient wlan0
ip addr show wlan0
ip route
ping -c 4 8.8.8.8

You can also connect interactively with wpa_cli:

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

When wpa_state=COMPLETED and the interface obtains a valid IP, authentication and address acquisition are basically normal. If no AP can be scanned, check the antenna, rfkill, driver firmware, and signal environment.

Bluetooth Connection¶

Bluetooth can be operated through bluetoothctl. Before connection, confirm that the Bluetooth service is running and that the target device is discoverable or pairable.

systemctl status bluetooth --no-pager
bluetoothctl

power on
agent on
default-agent
scan on
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
scan off
quit

Cellular Network¶

Cellular network connects to the operator LTE network through a USIM card. After the system starts, modem initialization, SIM recognition, operator registration, and data dialing are completed automatically. Normally, users do not need to run dialing commands manually. After a valid USIM card is inserted and the cellular antenna is connected, a cellular data interface such as rmnet_data0 is generated and obtains an IP address after network registration succeeds.

ifconfig rmnet_data0 2>/dev/null || ip addr show rmnet_data0
ip route
ping -c 4 8.8.8.8
ping -c 4 www.baidu.com

If rmnet_data0 does not exist or has no IP address, first check SIM card orientation, plan status, antenna connection, signal coverage, modem initialization status, and APN configuration. If ModemManager is integrated in the system, use mmcli -L and mmcli -m 0 to view modem/SIM status.

GNSS Positioning¶

Before testing GNSS positioning, connect the GNSS antenna and place it outdoors, near a window, or in an unobstructed location as much as possible. Indoor environments, shielded environments, disconnected antenna, or incorrect antenna orientation may cause long satellite search time or positioning failure.

For positioning acceptance, use garden_app first. qlril-api-test is mainly used for QLRIL / cellular communication API testing and is only an auxiliary verification method.

command -v garden_app
command -v qlril-api-test
garden_app -h
garden_app -n -y -t 120 -o 120
garden_app -n -y -t 120 -A 4 -B 28

-n outputs NMEA, -y outputs visible satellite information, -t sets the test duration, and -o can be used for TTFF threshold checking. If -A 4 -B 28 passes, it only means satellites meeting the threshold are visible; it does not mean that a latitude/longitude fix has been obtained. The real positioning result should be based on the location callback, latitude/longitude, and TTFF.

Ethernet¶

The development board provides an RJ45 Ethernet port and supports 10/100/1000 Mbps communication rates. Ethernet obtains network configuration through DHCP by default. After connecting the network cable, check the interface IP, default route, and DNS configuration.

ifconfig eth0 2>/dev/null || ip addr show eth0
ip route
cat /etc/resolv.conf
ping -c 4 8.8.8.8
ping -c 4 www.example.com

If the interface has no IP address, check the network cable, switch/router, DHCP service, and interface status. If the IP is normal but domain names cannot be accessed, further check DNS configuration.

Audio Function¶

The audio system consists of ALSA and upper-layer audio services. The hardware includes input and output channels, which can be used for onboard microphone, headset microphone, speaker, or headphone playback. Before operation, confirm the hardware connection and audio configuration file status.

cat /proc/asound/cards
cat /proc/asound/pcm

Recording and playback can use tinymix, agmcap, aplay, or other audio tools provided by the image. Before recording, confirm the capture path, mixer configuration, sampling rate, channel count, and device name. Before playback, confirm the output path and volume. If the sound card or PCM stream does not exist, ALSA and upper-layer audio services cannot work normally.

USB Function¶

The development board provides multiple USB Type-A ports and USB Type-C ports. The onboard USB mode can be switched between Device and Host scenarios through DIP switches.

USB Device mode: The device acts as a USB peripheral and is recognized and controlled by the host PC. This mode applies to ADB, firmware flashing, and host-PC interaction. USB flash drives, keyboards, mice, and other USB peripherals cannot be connected in this mode.

USB Host mode: The device acts as a USB host, actively recognizing and driving USB flash drives, keyboards, mice, USB cameras, and other peripherals, and powering common USB peripherals.

dmesg | grep -i usb
lsusb
ls /dev/video* 2>/dev/null
fdisk -l
df -h

USB cameras can be checked with v4l2-ctl for nodes, formats, and resolutions. USB flash drives can be confirmed through block device, mount point, and filesystem status.

SD Card¶

The development board is equipped with a micro SD + Nano SIM two-in-one card slot. The upper slot is for micro SD, and the lower slot is for Nano SIM. After inserting an SD card, confirm system recognition through block device, mount information, and mount directory.

fdisk -l
df -h
ls /mnt/sdcard

To mount manually, create a mount directory and mount the corresponding partition. After use, unmount before removing the card to avoid data corruption.

mkdir -p /media/sdcard
mount /dev/mmcblk1p1 /media/sdcard
ls /media/sdcard
umount /media/sdcard

If a normal user encounters insufficient permission when accessing the SD card, adjust directory ownership or permissions according to the actual user and mount policy.

ADC Function¶

The ADC subsystem converts external analog voltage into digital values. During testing, use an adjustable DC power supply as the input signal source. Connect the positive terminal of the power supply to ADC0 or ADC1, and connect the GND pin to the development board GND. Common channel nodes are as follows:

Channel	Node	Description
ADC0	`in_voltage_adc_gpio4_input`	Corresponds to GPIO4 ADC input.
ADC1	`in_voltage_adc_gpio7_input`	Corresponds to GPIO7 ADC input. Whether L1 supports it depends on the specific hardware.

cd /sys/bus/iio/devices/iio:device0
cat in_voltage_adc_gpio4_input
cat in_voltage_adc_gpio7_input

Read values are usually in microvolts (μV). Before testing, confirm the input voltage range to avoid exceeding the allowed hardware range.

40-Pin Expansion Interface¶

The 40-pin expansion interface supports GPIO, I2C, SPI, UART, PWM, and other functions. Before use, always check pin definitions, power pins, GND, and signal level to avoid incorrect wiring that may damage peripherals or the development board.

GPIO¶

GPIO can be exported through sysfs nodes, configured for direction, and read/written for level. The actual GPIO number is subject to the corresponding hardware table and system node.

echo 481 > /sys/class/gpio/export
echo out > /sys/class/gpio/gpio481/direction
echo 1 > /sys/class/gpio/gpio481/value

I2C¶

Before using I2C, confirm that the bus is enabled and /dev/i2c* nodes are generated. Use i2cdetect to view device addresses, and use i2cget / i2cset to read and write registers.

40Pin-ctrl common_i2c enable
ls -al /dev/i2c*
i2cdetect -y 1
i2cget -y 1 0x53 0x05 b
i2cset -y 1 0x53 0x05 0x03 b

SPI / UART / PWM¶

SPI can be confirmed through /dev/spidev* nodes and is commonly used for OLEDs, sensors, and other peripherals. UART can be used for serial loopback or external serial modules. PWM can be used for buzzers, backlight, or other pulse-control scenarios. Before testing, confirm pinmux status, device tree configuration, peripheral power supply, and signal level.

ls /dev/spidev* 2>/dev/null
ls /dev/ttyHS* /dev/ttyMSM* 2>/dev/null
ls /sys/class/pwm/ 2>/dev/null

Recommended Usage Order¶

Confirm the power input, adapter capability, DIP switches, and peripheral connection status first.
For first-time debugging, use ADB or Debug UART first to ensure that the Linux shell can be accessed.
For remote maintenance, configure Ethernet, Wi-Fi, or cellular network first, then use SSH / SCP.
If a graphical interface is required, configure RDP, TeamViewer, or local MIPI / HDMI display.
Verify peripherals one by one in the order of display, camera, audio, USB, SD card, ADC, and 40-pin expansion.
When an exception occurs, confirm the hardware connection first, then check nodes, service status, logs, and network routes.

Notes¶

Insufficient power supply causes many nondeterministic issues, including boot failure, peripheral disconnection, filesystem abnormality, and unstable network.
Before testing MIPI, camera, 40-pin, ADC, and other interfaces, always confirm wiring and voltage range.
Network services such as Remote Desktop, Samba, Apache, and TeamViewer should be enabled according to actual product security requirements. They are not recommended to be opened by default when not needed.