第一个硬件项目¶
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
本教程将带您使用Quectel Pi H1开发套件完成两个入门级硬件实践：使用IMX219摄像头拍照和读取板载按键事件。
使用IMX219摄像头拍摄第一张照片¶
如果未配备IMX219摄像头，可跳过本章。
安装摄像头¶
安装和拆卸排线前，请务必关闭Quectel Pi H1智能主控板电源。
找到智能主控板上标注为 CAMERA1 或 CAMERA2 的MIPI CSI排线接口（后续示例均以 CAMERA1 为例）。
先轻轻向上拨开黑色锁扣，再将IMX219摄像头的排线金手指朝下（朝向电路板正面）插入接口，插到底后按下锁扣压紧。（注意：严禁反向插接或歪斜插入，否则通电后可能导致供电短路烧板）。
确认排线固定稳固且未发生倾斜后，重新上电并启动智能主控板。
控制摄像头拍照¶
环境配置¶
运行拍照命令前，请先设置插件路径（每次打开新的终端窗口后均需重新设置）：
export GST_PLUGIN_PATH=/usr/lib/gstreamer-1.0:$GST_PLUGIN_PATH
拍照¶
执行以下命令采集图像并保存为JPEG文件：
max-files 同时决定拍摄张数和本地保存的文件数。当前设置为 max-files=1，因此拍摄1张照片，并在 /home/pi 目录中保存1个JPEG文件；设置为 max-files=n 时，拍摄 n 张照片，并在本地保存 n 个文件。
sudo -E gst-launch-1.0 -e \
qtiqmmfsrc name=camsrc ! \
'video/x-raw,format=NV12,width=1280,height=720,framerate=30/1' ! \
queue ! videoconvert ! jpegenc ! \
multifilesink location=/home/pi/shot-%05d.jpg max-files=1
管道状态显示为 PLAYING 时，表示摄像头正在采集图像。按 Ctrl+ C 可停止管道。
停止后请执行以下命令确认照片是否生成成功，也可直接在 GNOME 桌面双击打开照片查看：
ls -lh /home/$USER/shot-*.jpg
预期输出示例：
-rw-r--r-- 1 root root 128K Oct 1 10:30 /home/$USER/shot-00000.jpg
进阶：使用Python与OpenCV拍摄照片¶
安装OpenCV：
sudo apt update
sudo apt install -y python3-opencv
创建文件 ~/capture.py：
import cv2
# MIPI摄像头需通过GStreamer管道访问
gst_pipeline = (
"qtiqmmfsrc name=camsrc ! "
"video/x-raw,format=NV12,width=1280,height=720,framerate=30/1 ! "
"videoconvert ! video/x-raw,format=BGR ! appsink drop=true max-buffers=1"
)
cap = cv2.VideoCapture(gst_pipeline, cv2.CAP_GSTREAMER)
if not cap.isOpened():
print("错误：无法打开摄像头")
sys.exit(1)
# 跳过前几帧（摄像头需要时间完成自动曝光和白平衡）
for i in range(30):
cap.read()
ret, frame = cap.read()
if ret:
cv2.imwrite("/home/pi/opencv_photo.jpg", frame)
print("拍照成功！已保存到 /home/pi/opencv_photo.jpg")
else:
print("错误：无法读取图像帧")
cap.release()
备注
脚本会将照片保存到 /home/pi/opencv_photo.jpg。如需更改位置，请修改脚本中的保存路径。
运行（需要 sudo 权限，运行前确保已设置 export GST_PLUGIN_PATH=/usr/lib/gstreamer-1.0:$GST_PLUGIN_PATH。）：
sudo -E python3 ~/capture.py
备注
IMX219是一款MIPI CSI-2图像传感器，在Quectel Pi H1平台上，摄像头由高通QMMF多媒体服务（qtiqmmfsrc 插件）统一管理，本示例通过GStreamer管道访问摄像头。
探索GPIO¶
查看GPIO引脚状态¶
安装GPIO命令行工具：
sudo apt update && sudo apt install -y gpiod
查看系统中所有GPIO控制器：
sudo gpiodetect
示例输出：
pi@quectelpi:/$ sudo gpiodetect
gpiochip0 [c440000.spmi:pmic@8:pinctrl@c00] (12 lines)
gpiochip1 [c440000.spmi:pmic@1:gpio@8800] (10 lines)
gpiochip2 [c440000.spmi:pmic@2:gpio@8800] (9 lines)
gpiochip3 [c440000.spmi:pmic@0:gpio@b000] (4 lines)
gpiochip4 [f100000.pinctrl] (176 lines)
gpiochip5 [33c0000.pinctrl] (15 lines)
查看指定控制器上所有引脚的状态：
sudo gpioinfo --chip gpiochip4
示例输出：
pi@quectelpi:/$ sudo gpioinfo --chip gpiochip4
gpiochip4 - 176 lines:
line 0: unnamed input
line 1: unnamed input
line 2: unnamed output active-low consumer=perst
line 3: unnamed input
line 4: unnamed input
line 5: unnamed input
line 6: unnamed output consumer=switch
line 7: unnamed output consumer=enable
line 8: unnamed output
line 9: unnamed output consumer=soc@0:pin40_en_vr
...
每一行代表一个GPIO引脚；标有 consumer=xxx 的引脚已被内核驱动占用。
备注
板载 KEY1 和 KEY2 由内核中的 gpio-keys 和 pmic_resin 驱动管理，在用户空间中呈现为标准Linux输入设备。因此，应使用 evtest 或 evdev 读取按键事件，而不是直接操作GPIO引脚。
使用evtest验证按键¶
安装 evtest 工具：
sudo apt install -y evtest
Quectel Pi H1智能主控板提供 KEY1 和 KEY2 两个用户板载按键（按键旁有对应丝印），可通过Linux输入子系统读取。设备节点可能随系统版本变化，请先运行 sudo evtest 确认 gpio-keys 和 pmic_resin 对应的 event 编号；下表为本示例环境的映射：
按键 |
输入设备 |
映射键码 |
|---|---|---|
KEY1 |
/dev/input/event3 |
KEY_VOLUMEDOWN (114) |
KEY2 |
/dev/input/event1 |
KEY_VOLUMEUP (115) |
使用以下命令监听 KEY1：
sudo evtest /dev/input/event3
按下 KEY1，终端将实时输出按键事件：
Event: time ..., type 1 (EV_KEY), code 114 (KEY_VOLUMEDOWN), value 1 ← 按下
Event: time ..., type 1 (EV_KEY), code 114 (KEY_VOLUMEDOWN), value 0 ← 松开
按 Ctrl+ C 退出。同样，可使用 sudo evtest /dev/input/event1 监听 KEY2。
使用Python监听按键事件¶
安装 evdev 库：
sudo apt update && sudo apt install -y python3-evdev
创建文件 ~/button_monitor.py：
from evdev import InputDevice, ecodes
import selectors
# 绑定设备事件节点（请根据evtest查询到的实际节点编号进行核对）
dev_key1 = InputDevice("/dev/input/event3")
dev_key2 = InputDevice("/dev/input/event1")
print(f"监听 KEY1: {dev_key1.name}")
print(f"监听 KEY2: {dev_key2.name}")
print("按 Ctrl+C 退出")
sel = selectors.DefaultSelector()
sel.register(dev_key1, selectors.EVENT_READ)
sel.register(dev_key2, selectors.EVENT_READ)
try:
while True:
for key, _ in sel.select():
device = key.fileobj
for event in device.read():
if event.type == ecodes.EV_KEY and event.value == 1:
if event.code == ecodes.KEY_VOLUMEDOWN:
print("KEY1 被按下！")
elif event.code == ecodes.KEY_VOLUMEUP:
print("KEY2 被按下！")
except KeyboardInterrupt:
print("\n退出监听")
运行：
sudo python3 ~/button_monitor.py
按下 KEY1 或 KEY2，终端将输出相应提示。按 Ctrl+ C 退出。
备注
访问Linux输入设备需要root权限，因此应使用 sudo 运行脚本。
常见问题¶
拍照命令报错“no element qtiqmmfsrc”。
请先设置插件路径：
export GST_PLUGIN_PATH=/usr/lib/gstreamer-1.0:$GST_PLUGIN_PATH
然后执行拍照命令。
拍照命令报错“Failed to connect to bus”。
请确保命令带有 sudo -E 前缀，因为摄像头插件需要root权限。
若仍报错，表明系统后台的相机守护进程异常。可在终端中重启媒体服务：
sudo systemctl restart qmmf-server
evtest 没有显示按键事件。
设备编号可能与文中示例不同。运行 sudo evtest（不带参数）可列出所有输入设备，从中找到 gpio-keys 和 pmic_resin 对应的 event 编号即可。
Python脚本报权限错误。
Linux输入设备和摄像头都需要root权限：
按键脚本：sudo python3 ~/button_monitor.py
拍照脚本：sudo -E python3 ~/capture.py