# 手势遥控器
***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***
---
本项目是一个基于Quectel Pi M2智能主控板实现的手势识别远程视频控制示例。
系统通过摄像头采集手部图像，结合AI手势识别算法，实现隔空控制视频播放、进度与音量的自然交互体验。
```{image} images/image_Xjdqbr1dNouTbaxtSLwcOJwpnJg.webp
:width: 1280px
:height: 800px
:align: center
```
# 开发资源汇总
## 开发配件清单
```{note}
```
|
配件名称
|
数量
|
规格参数
|
| --- | --- | --- |
| Quectel Pi M2智能主控板 |
1块
|
-
|
| USB-C电源线充电器 |
1个
| |
| HDMI A 型对公线 |
1根
| HDMI 2.0；线长1 m；接口：HDMI-A（公头）-HDMI-A（公头） |
| 网线 |
1根
|
线长：1m；传输速率：千兆；
|
| USB摄像头模块 |
1个
| |
| 显示屏 |
1个
|
24英寸HDMI显示器
|
## 配件实物参考
```{image} images/image_NIJtbQJrHoFX75xIUeEcGfF0n1e.webp
:width: 980px
:height: 624px
:align: center
```
# 快速上手
## 开发准备
**Quectel Pi M2** 智能主控板出厂默认搭载 **Debian 13** 系统镜像，因此无需再次烧录镜像，仅需按照如下步骤操作即可。
## 硬件连接
完成以下所有硬件连接操作，序号与接口示意图保持一致：
```{image} images/image_QFCMbkUORoxKQDx97j7c8hxqnHg.webp
:width: 627px
:height: 463px
:align: center
```
1. **显示连接:** 需根据显示器的接口选择连接方案，这里采用方案二；将Micro HDMI 线一端接主控板 Micro HDMI 接口，另一端接显示器 HDMI 接口；
- 方案1（高清）：将 **FPC** 排线一端接入 **Quectel Pi M2** 的 **MIPI** 接口，另一端接入显示器的 **MIPI** 接口, 具体细节参考 [MIPI](<../../../使用指南/显示/MIPI/MIPI.md>)。
- 方案2（兼容）：将 **HDMI** 线一端接入 **Quectel Pi M2** 的 **HDMI** 接口，另一端接入显示器的 **HDMI** 接口。
2. **网络连接**: 用网线连接 **Quectel Pi M2** 网口和路由器的 **LAN** 口即可。
3. **外设连接**: 将USB键盘、鼠标、USB摄像头接入 **Quectel Pi M2** 的 **USB-A** 接口上；若用无线键鼠，将接收器插入 **USB** 口即可。
4. **供电连接**：最后将 **USB-A** 电源线的 **USB-A** 端接入电源适配器，**USB-C** 端接入 **Quectel Pi M2** 的电源口。
```{note}
```
## 项目实现
1. 在智能主控板上打开终端，使用git克隆项目代码。
```bash
sudo apt update
sudo apt install -y git
git clone https://github.com/Quectel-Pi/demo-gesture-remote-control.git
```
执行完成后，当前目录下应生成 *demo-gesture-remote-control* 文件夹。
2. 在智能主控板的终端下依次执行下面命令，终端显示 *Deployment complete* 则说明部署完成。
```bash
cd demo-gesture-remote-control
sudo chmod 755 install.sh
./install.sh
```
如果执行 *./install.sh* 过程中报错，或终端未显示"Deployment complete"，请先不要继续执行后续步骤。建议先确认网络连接正常，再返回项目根目录重新执行一次 *install.sh*。
3. 重新打开终端，验证Python版本，输出 *Python 3.10.15* 则表示安装成功。
```bash
python3 --version
```
### 运行程序
在 *src* 路径下执行 *main.py* 启动脚本；若程序正常启动，会打开摄像头画面窗口。
```bash
cd demo-gesture-remote-control/src/
python3 main.py
```
## 手势映射
> 请确保摄像头正对用户操作区域，并具备稳定光照条件。
| **手势动作** | **控制功能** |
| --- | --- |
| 张开手掌（5指） | 播放 |
| 握拳 | 暂停 |
| 手指向右滑动 | 快进5秒 |
| 手指向左滑动 | 快退5秒 |
| 手指向上滑动 | 音量 +5% |
| 手指向下滑动 | 音量-5% |
# 常见问题及解决方案
## 摄像头无法识别
**现象：**
```plaintext
No available camera device found
```
**解决方案：**
- 检查摄像头是否正确连接到USB接口。
- 使用命令检查摄像头是否被识别：
```shell
ls -la /dev/video*
```
- 尝试使用其他USB接口。
- 如果还是不行，使用USB集线器并连接电源。
- 重新插拔USB摄像头。
## 运行main.py提示No module named cv2
**现象：**
```plaintext
ModuleNotFoundError: No module named 'cv2'
```
**解决方案：**
该问题通常表示 *install.sh* 未安装成功，请先返回项目根目录重新执行安装脚本：
```bash
cd demo-gesture-remote-control
./install.sh
```
# 应用演示
gesture-remote-control
# 技术支持与贡献
如在使用过程中遇到问题，欢迎在 [移远官方论坛]() 提交技术咨询，我们的技术支持团队将及时为您解答。
项目开源地址：[https://github.com/Quectel-Pi/demo-gesture-remote-control]()
欢迎提交Issue反馈问题或Pull Request贡献代码改进！