网络摄像头控制台

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

本项目以 Quectel Pi M2 智能主控板作为边缘计算和桌面应用运行平台，适用于支持 RTSP 的网络摄像头，以及需要云台控制、实时预览、抓拍和录像的智能视觉场景。应用将 ONVIF 和 RTSP 分开管理：RTSP 负责实时预览和录像，ONVIF 负责设备信息、媒体配置、抓拍地址和 PTZ 控制。

开发配件清单

说明：以下为推荐开发配件，实际使用时可根据目标平台、摄像头类型和展示场景灵活调整。

配件名称


数量

规格或要求

Quectel Pi M2智能主控板

image


1 台

Quectel Pi M2智能主控板

网络摄像头

image


1 个

支持 RTSP；如需云台和变焦，需支持 ONVIF PTZ

网络连接设备

image


1 套

路由器、交换机或可访问摄像头子网的无线网络

显示器

image


1 台

最低建议 960 × 680，推荐 1280 × 800 或更高

快速上手

运行要求

本项目以 Quectel Pi M2 智能主控板为主要验证平台。Quectel Pi M2 运行 Linux 桌面环境后，可直接承载本项目的 GTK3 图形界面、OpenCV 视频预览和 FFmpeg 录像任务。除 Quectel Pi M2 外，具备相同软件条件的 64 位 ARM 或 x86 Linux 主机也可以用于开发和兼容性验证。

硬件要求

  • Quectel Pi M2 智能主控板；兼容验证时也可使用其他 64 位 ARM 或 x86 Linux 主机/开发板。

  • 最低双核 CPU、1 GB 内存；推荐四核 CPU、2 GB 或更多内存。

  • X11 或 Wayland 桌面会话。

  • 最低显示分辨率 960 × 680，推荐 1280 × 800 或更高。

  • 主机可以访问摄像头的 ONVIF 服务端口和 RTSP 端口。

  • 摄像头支持 RTSP；需要移动和变焦时还需要 ONVIF PTZ。

软件要求

  • Python 3.9 或更高版本。

  • GTK3 和 PyGObject。

  • OpenCV Python 绑定。

  • FFmpeg 和 ffprobe。

  • Bash。

安装系统依赖

以下命令以 Debian/Ubuntu 为例：

sudo apt update
sudo apt install -y python3 python3-gi gir1.2-gtk-3.0 python3-opencv ffmpeg

检查关键命令是否可用：

python3 --version
ffmpeg -version
ffprobe -version

检查网络连通性

将命令中的摄像头地址和端口替换为实际值：

ip route get 192.168.1.100
nc -vz 192.168.1.100 80
nc -vz 192.168.1.100 554

部分摄像头会禁用 ICMP，因此 ping 失败不一定表示 ONVIF 或 RTSP 不可用。应优先使用 nc 检查对应服务端口。

创建配置文件

进入项目目录并复制配置模板：

cd project/camera-control
cp .env.example .env

编辑 .env，将示例地址、账号和密码替换为实际摄像头配置：

CAMERA_IP=192.168.1.100
CAMERA_USER=admin
CAMERA_PASSWORD=摄像头密码

ONVIF_USER=admin
ONVIF_PASSWORD=摄像头密码
ONVIF_PORT=80
ONVIF_URL=http://192.168.1.100:80/onvif/device_service
RTSP_URL=rtsp://192.168.1.100:554/Streaming/Channels/101

不同厂商和型号的 ONVIF 路径、RTSP 路径、端口以及账号权限可能不同。应用界面也支持直接编辑完整的 ONVIF 服务 URL 和 RTSP 流 URL。

启动应用

完成 Quectel Pi M2 的系统启动、显示器连接、网络连接和摄像头连接后，在主控板的终端中进入项目目录。建议将摄像头和 Quectel Pi M2 接入同一局域网，或为主控板配置能够访问摄像头子网的路由。

推荐使用项目提供的启动脚本：

./run_desktop.sh

启动脚本会进入项目目录，自动加载 .env（如果存在），补充缺省环境变量，然后执行：

python3 desktop_app.py

应用界面说明

主界面布局

../../../_images/image_Ng9vb6HuooC6XDxlCP8cgoKJn7e.webp

主界面主要包含以下区域：

  1. 顶部标题与连接状态：显示应用名称，以及 ONVIF、RTSP 当前状态。

  2. Connection Settings：填写 ONVIF 服务 URL、RTSP 流 URL、用户名和密码。

  3. Live Preview：显示 RTSP 实时视频画面。

  4. 操作按钮：提供 Connect ONVIF、Connect RTSP、Snapshot 和 Start Recording。

  5. PTZ Control：提供八方向移动、停止、变焦和移动速度调节。

  6. 状态区域：显示连接、预览、抓拍、录像和错误信息。

连接状态含义

状态

含义

ONVIF Offline

尚未连接或 ONVIF 连接失败

ONVIF Connecting…

正在探测端口并初始化 ONVIF 服务

ONVIF Online

ONVIF 初始化成功，可使用 PTZ；如设备支持，也可使用 ONVIF 抓拍

RTSP Offline

尚未启动 RTSP 预览

RTSP Connecting…

正在打开 RTSP 流

RTSP Live

RTSP 预览已正常运行

RTSP Failed / RTSP Unreachable

RTSP 地址、账号、端口或网络不可用

ONVIF 和 RTSP 可以按任意顺序连接。实时预览和录像不依赖 ONVIF；PTZ 控制需要 ONVIF 连接成功。

基本操作

连接 ONVIF

  1. 在 ONVIF Service URL 中填写完整的 ONVIF 设备服务地址。

  2. 填写 Username 和 Password。

  3. 点击 Connect ONVIF。

  4. 等待顶部状态切换为 ONVIF Online。

  5. 应用会尝试读取设备信息、能力、媒体配置、视频流地址和抓拍地址。

如果摄像头支持 GetStreamUri，应用可能会将摄像头返回的视频流地址同步到 RTSP 设置中。如果设备不支持 GetSnapshotUri，应用会在 RTSP 预览画面中使用当前帧作为抓拍来源。

../../../_images/image_KfM1b5iyyo61GhxdKpGcleRYnce.webp

连接 RTSP 并查看预览

  1. 在 RTSP Stream URL 中填写完整的 RTSP 地址。

  2. 确认账号密码正确；应用会对 RTSP URL 中的认证信息进行编码处理。

  3. 点击 Connect RTSP。

  4. 等待顶部状态显示 RTSP Live，实时视频会显示在 Live Preview 区域。

如果 RTSP 预览已经运行，再次连接新的地址会先停止旧预览，再打开新地址。

../../../_images/image_R8tibL944oNcp7xmhdaciSjfn3V.webp

PTZ 云台控制

PTZ 控制需要摄像头支持 ONVIF PTZ，并且已经成功连接 ONVIF。

  1. 在 Movement Speed 滑块中选择移动速度，范围为 10%–100%。

  2. 按住方向按钮移动云台，松开按钮后停止移动。

  3. 点击中间的 STOP 按钮立即发送停止命令。

  4. 使用 Zoom Out 和 Zoom In 调整变焦；同样需要按住并在完成后松开。

支持八个方向：上、下、左、右、左上、右上、左下、右下。

也可以使用键盘快捷键：

按键

操作

方向键 / WASD

云台移动

Q

缩小

E

放大

空格键

停止

当光标正在编辑 URL、用户名或密码输入框时，键盘快捷键不会触发 PTZ 操作。

录屏 2026-10-12 05-50-13

抓拍

  1. 先连接 ONVIF，或先启动 RTSP 预览。

  2. 点击 Snapshot。

  3. 等待状态区域显示 Snapshot saved。

  4. 在项目的 snapshots/ 目录查看 JPG 文件。

抓拍来源按以下顺序选择：

  • 如果 ONVIF 提供抓拍地址，优先使用 ONVIF 抓拍。

  • 如果 ONVIF 不支持抓拍地址，则保存当前 RTSP 预览帧。

  • 使用 RTSP 当前帧抓拍时，必须先等待预览画面成功显示。

输出文件名格式为：

snapshots/snapshot-YYYYMMDD-HHMMSS.jpg
../../../_images/image_RcpKbheyBotmBdxnTkicIZeknCd.webp

录像

  1. 先点击 Connect RTSP，确认状态为 RTSP Live。

  2. 点击 Start Recording 开始录像。

  3. 按钮会切换为停止状态，状态区域显示正在写入的文件名。

  4. 再次点击录像按钮停止录像。

  5. 等待 MP4 封装完成，并在 recordings/ 目录查看文件。

录像使用 FFmpeg 通过 RTSP over TCP 读取视频：

  • 第一条视频流使用直接复制方式保存，不重新编码 H.264/HEVC。

  • 可选的第一条音频流转换为 MP4 兼容的 AAC。

  • 停止录像时发送中断信号，使 FFmpeg 有机会正常完成 MP4 封装。

输出文件名格式为：

recordings/recording-YYYYMMDD-HHMMSS.mp4
录屏 2026-10-12 05-57-36

输出文件与数据安全

项目运行时会自动创建以下目录：

recordings/   # MP4 录像
snapshots/    # JPG 抓拍

建议注意以下事项：

  • 不要提交包含真实密码的 .env 文件。

  • 不要将私人地址、真实账号、敏感视频或抓拍图片提交到公开仓库。

  • 建议为摄像头创建权限受限的专用账户。

  • 录像会持续占用磁盘空间，长期运行时应定期清理或增加磁盘配额管理。

  • HEVC 预览可能消耗较多 CPU，若画面卡顿，可降低码率、分辨率或改用 H.264 流。

常见问题排查

应用无法启动，提示 GTK 或 PyGObject 缺失

确认系统依赖已安装：

sudo apt update
sudo apt install -y python3-gi gir1.2-gtk-3.0 python3-opencv ffmpeg

确认当前会话正在运行桌面环境，并且存在可用的显示环境（X11 或 Wayland）。

ONVIF 连接失败

  1. 检查 ONVIF Service URL 是否为完整地址，路径和端口是否匹配摄像头型号。

  2. 检查 ONVIF_USER、ONVIF_PASSWORD 或界面账号密码是否正确。

  3. 使用 nc -vz 摄像头IP ONVIF端口 检查端口连通性。

  4. 确认摄像头已启用 ONVIF，并且当前账号具备 ONVIF/PTZ 权限。

  5. 查看终端输出的详细诊断信息；界面显示简短状态，终端会输出更具体的错误。

RTSP 无法打开或状态为RTSP Unreachable

  1. 检查 RTSP URL 的协议、IP、端口和路径。

  2. 确认默认 RTSP 端口通常为 554，但具体值以摄像头配置为准。

  3. 检查 RTSP 账号密码和流权限。

  4. 使用 nc -vz 摄像头IP 554 检查端口。

  5. 确认摄像头没有限制客户端 IP，且主机路由指向正确的摄像头网络。

RTSP 已连接但没有画面

  1. 确认摄像头输出的是有效的视频流。

  2. 优先测试摄像头的主码流或子码流地址。

  3. 检查系统是否安装 OpenCV 的 FFmpeg 支持。

  4. 如果使用 HEVC，检查主机 CPU 是否能够承担软件解码；必要时改用 H.264 流。

  5. 关闭并重新连接 RTSP，观察终端输出是否出现帧读取错误。

PTZ 按钮无效

  1. 确认顶部状态为 ONVIF Online。

  2. 确认摄像头型号支持 ONVIF PTZ，而不仅仅是 ONVIF 设备发现。

  3. 检查 ONVIF 账号是否具备云台控制权限。

  4. 尝试降低 Movement Speed，部分设备不接受较高速度值。

  5. 查看终端中的 PTZ SOAP 错误信息。

抓拍失败

  1. 如果使用 ONVIF 抓拍，确认摄像头实现了 GetSnapshotUri。

  2. 如果设备不支持 ONVIF 抓拍，先连接 RTSP 并等待画面显示，再点击 Snapshot。

  3. 检查 snapshots/ 目录的写入权限和磁盘空间。

录像启动失败或 MP4 文件无法播放

  1. 确认 RTSP 预览已经成功连接。

  2. 确认 ffmpeg 和 ffprobe 已安装并可执行。

  3. 检查终端输出中的 FFmpeg 错误，重点关注 RTSP 地址、音视频编码和权限。

  4. 确认 recordings/ 目录可写且磁盘空间充足。

  5. 停止录像后等待状态显示 Recording saved，不要在封装完成前强制关闭应用。

应用演示

IPCcontrol

技术支持与贡献

欢迎提交 Issue 或 Pull Request，反馈设备兼容性、ONVIF/RTSP 地址差异、界面问题和功能建议。如在使用过程中遇到问题，欢迎在 移远官方论坛 提交技术咨询，我们的技术支持团队将及时为您解答。