# 网络摄像头控制台
***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***
---
本项目以 Quectel Pi M2 智能主控板作为边缘计算和桌面应用运行平台，适用于支持 RTSP 的网络摄像头，以及需要云台控制、实时预览、抓拍和录像的智能视觉场景。应用将 ONVIF 和 RTSP 分开管理：RTSP 负责实时预览和录像，ONVIF 负责设备信息、媒体配置、抓拍地址和 PTZ 控制。
## **开发配件清单**
说明：以下为推荐开发配件，实际使用时可根据目标平台、摄像头类型和展示场景灵活调整。
| **配件名称** | **
数量
** | **规格或要求** |
| --- | --- | --- |
| Quectel Pi M2智能主控板
|
1 台
| Quectel Pi M2智能主控板 |
| 网络摄像头
|
1 个
| 支持 RTSP；如需云台和变焦，需支持 ONVIF PTZ |
| 网络连接设备
|
1 套
| 路由器、交换机或可访问摄像头子网的无线网络 |
| 显示器
|
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 为例：
```bash
sudo apt update
sudo apt install -y python3 python3-gi gir1.2-gtk-3.0 python3-opencv ffmpeg
```
检查关键命令是否可用：
```bash
python3 --version
ffmpeg -version
ffprobe -version
```
### **检查网络连通性**
将命令中的摄像头地址和端口替换为实际值：
```bash
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` 检查对应服务端口。
### **创建配置文件**
进入项目目录并复制配置模板：
```bash
cd project/camera-control
cp .env.example .env
```
编辑 `.env`，将示例地址、账号和密码替换为实际摄像头配置：
```plaintext
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 接入同一局域网，或为主控板配置能够访问摄像头子网的路由。
推荐使用项目提供的启动脚本：
```bash
./run_desktop.sh
```
启动脚本会进入项目目录，自动加载 `.env`（如果存在），补充缺省环境变量，然后执行：
```bash
python3 desktop_app.py
```
## **应用界面说明**
### **主界面布局**
```{image} images/image_Ng9vb6HuooC6XDxlCP8cgoKJn7e.webp
:width: 1211px
:height: 907px
:align: center
```
主界面主要包含以下区域：
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 预览画面中使用当前帧作为抓拍来源。
```{image} images/image_KfM1b5iyyo61GhxdKpGcleRYnce.webp
:width: 1272px
:height: 960px
:align: center
```
### **连接 RTSP 并查看预览**
1. 在 `RTSP Stream URL` 中填写完整的 RTSP 地址。
2. 确认账号密码正确；应用会对 RTSP URL 中的认证信息进行编码处理。
3. 点击 `Connect RTSP`。
4. 等待顶部状态显示 `RTSP Live`，实时视频会显示在 `Live Preview` 区域。
如果 RTSP 预览已经运行，再次连接新的地址会先停止旧预览，再打开新地址。
```{image} images/image_R8tibL944oNcp7xmhdaciSjfn3V.webp
:width: 1272px
:height: 960px
:align: center
```
### **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 当前帧抓拍时，必须先等待预览画面成功显示。
输出文件名格式为：
```plaintext
snapshots/snapshot-YYYYMMDD-HHMMSS.jpg
```
```{image} images/image_RcpKbheyBotmBdxnTkicIZeknCd.webp
:width: 1228px
:height: 914px
:align: center
```
### **录像**
1. 先点击 `Connect RTSP`，确认状态为 `RTSP Live`。
2. 点击 `Start Recording` 开始录像。
3. 按钮会切换为停止状态，状态区域显示正在写入的文件名。
4. 再次点击录像按钮停止录像。
5. 等待 MP4 封装完成，并在 `recordings/` 目录查看文件。
录像使用 FFmpeg 通过 RTSP over TCP 读取视频：
- 第一条视频流使用直接复制方式保存，不重新编码 H.264/HEVC。
- 可选的第一条音频流转换为 MP4 兼容的 AAC。
- 停止录像时发送中断信号，使 FFmpeg 有机会正常完成 MP4 封装。
输出文件名格式为：
```plaintext
recordings/recording-YYYYMMDD-HHMMSS.mp4
```
录屏 2026-10-12 05-57-36
## **输出文件与数据安全**
项目运行时会自动创建以下目录：
```plaintext
recordings/ # MP4 录像
snapshots/ # JPG 抓拍
```
建议注意以下事项：
- 不要提交包含真实密码的 `.env` 文件。
- 不要将私人地址、真实账号、敏感视频或抓拍图片提交到公开仓库。
- 建议为摄像头创建权限受限的专用账户。
- 录像会持续占用磁盘空间，长期运行时应定期清理或增加磁盘配额管理。
- HEVC 预览可能消耗较多 CPU，若画面卡顿，可降低码率、分辨率或改用 H.264 流。
## **常见问题排查**
### **应用无法启动，提示 GTK 或 PyGObject 缺失**
确认系统依赖已安装：
```bash
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 地址差异、界面问题和功能建议。如在使用过程中遇到问题，欢迎在 [移远官方论坛]() 提交技术咨询，我们的技术支持团队将及时为您解答。
