第一个硬件项目¶
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
本教程将带您使用Quectel Pi H1开发套件完成两个入门级硬件实践：使用IMX219摄像头拍照和读取板载按键事件。
用IMX219摄像头拍第一张照片¶
如果未配备IMX219摄像头，可跳过本章。
安装摄像头¶
关闭Quectel Pi H1智能主控板电源。
找到板上标注为 CAMERA1 或 CAMERA2 的MIPI CSI排线接口。
将IMX219摄像头的排线金手指朝下，插入接口并扣紧卡扣。
重新上电并启动Quectel Pi H1智能主控板。
备注
请勿反向插入排线，金手指应朝向电路板（向下）。安装和拆卸排线时务必先断电。
控制摄像头拍照¶
环境配置¶
运行拍照命令前，请先设置插件路径（每次打开新的终端窗口后均需重新设置）：
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' ! \
tee name=t ! \
queue ! videoconvert ! jpegenc ! \
multifilesink location=/home/pi/shot-%05d.jpg max-files=1
管道状态显示为 PLAYING 时，表示摄像头正在采集图像。按“Ctrl+C”可停止管道。
备注
如需拍摄 n 张照片并在本地保存 n 个文件，请将参数设置为 max-files=n。
进阶：用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"
)
cap = cv2.VideoCapture(gst_pipeline, cv2.CAP_GSTREAMER)
if not cap.isOpened():
print("错误：无法打开摄像头")
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 权限）：
sudo -E python3 ~/capture.py
备注
IMX219是MIPI CSI摄像头，不支持标准V4L2接口，因此OpenCV需要借助GStreamer管道来访问。运行前确保已设置 export GST_PLUGIN_PATH=/usr/lib/gstreamer-1.0:$GST_PLUGIN_PATH。
探索GPIO¶
查看GPIO引脚状态¶
安装GPIO命令行工具：
sudo apt install -y gpiod
查看系统中所有GPIO控制器：
sudo gpiodetect
查看指定控制器上所有引脚的状态：
sudo gpioinfo --chip gpiochip4
输出中的每一行代表一个GPIO引脚；标有 consumer=xxx 的引脚已被内核驱动占用。
备注
板载 KEY1 和 KEY2 由内核中的 gpio-keys 和 pmic_resin 驱动管理，在用户空间中呈现为标准Linux输入设备。因此，应使用 evtest 或 evdev 读取按键事件，而不是直接操作GPIO引脚。
使用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) |
安装 evtest 工具：
sudo apt install -y evtest
使用以下命令监听 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 库：
pip install evdev
创建文件 ~/button_monitor.py：
from evdev import InputDevice, ecodes
import selectors
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 -E python3 ~/button_monitor.py
按下KEY1或KEY2，终端将输出相应提示。按“Ctrl+C”退出。
备注
访问Linux输入设备需要 root 权限，因此应使用 sudo 运行脚本。
常见问题¶
Q：拍照命令报错“no element qtiqmmfsrc”
请先设置插件路径：
export GST_PLUGIN_PATH=/usr/lib/gstreamer-1.0:$GST_PLUGIN_PATH
然后执行拍照命令。
Q：拍照命令报错“Failed to connect to bus”
请确保命令带有 sudo -E 前缀，因为摄像头插件需要 root 权限。
Q：*evtest*没有显示按键事件
设备编号可能与文中示例不同。运行 sudo evtest（不带参数）可列出所有输入设备，从中找到 gpio-keys 和 pmic_resin 对应的 event 编号即可。
Q：Python脚本报权限错误
Linux输入设备和摄像头都需要 root 权限：
按键脚本：sudo -E python3 ~/button_monitor.py
拍照脚本：sudo -E python3 ~/capture.py