# 智能视觉小车

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

---

# 概述

智能视觉小车面向教育科研、机器人创新和嵌入式智能应用验证场景，搭载 **Quectel Pi H1** 智能主控板、ROS 2软件栈与多传感器硬件，可通过手机App、Docker/ROS环境以及WonderPi套件实现快速上手。本文档梳理了开发资源、组装步骤、环境部署和玩法示例，帮助你在最短时间内完成软硬件调测并投入教学或项目演示。

# 应用产品特性

- 一体化智能视觉解决方案：集成高清云台摄像头、超声波、巡线传感器与多自由度底盘。

- 软硬件双栈开发：提供Docker镜像、ROS 2工作空间及移动端控制，便于二次开发。

- 多玩法示例：内置遥控、目标追踪、取色巡线、二维码识别、智能避障等可扩展示例。

- 快速复制部署：配套环境脚本与系统服务。

# 支持列表

| **类别** | **支持内容** |
| --- | --- |
| 硬件平台 | Quectel Pi H1智能主控板 + 扩展板、云台摄像头、超声波、巡线传感器、TT马达、18650电池盒 |
| 系统/软件 | Debian 13、Docker、ROS 2 Humble、App（Android/iOS） |
| 接口能力 | I2C9、UART12、GPIO、PWM舵机接口、四路巡线传感器接口 |
| 控制方式 | 手机App直连/局域网、ADB/SSH、Docker容器 |

# 开发资源汇总

## 开发配件清单

### 购买链接以及配件清单

- [购买智能视觉小车套件](<https://item.taobao.com/item.htm?app=weixin&bc_fl_src=share-1041258748959517-2-1&bxsign=scdF_GVQ_7pxdVe3rh7GCxVCdIBBFARWi3--cvCUfFORsfZ8QTLl9HkTu7mQKCd7F48G3lqWr3boZuoclfS5IwawTXnf9NwUkQYwAB4TGRFRPMkXMUxlxlETNa-z0547Lsk&cpp=1&id=698668065022&price=589&shareUniqueId=33212744657&share_crt_v=1&shareurl=true&short_name=h.SdzuSaEZVEJxn4F&skuId=5762142577354&sourceType=item&sp_tk=cEUyMTR2c055OHk%3D&spm=a2159r.13376460.0.0&suid=1B37D527-EC28-4D87-BC40-E428CD28D415&tbSocialPopKey=shareItem&tk=pE214vsNy8y&un=c23113814a7deafa0f8768acc41474bb&un_site=0&ut_sk=1.YXLBjF4rNYkDALVXmYw0Vq0S_21380790_1758519195228.Copy.1&wxsign=tbw9WKBXgsnYhCh4ldmJDElxeSEwQKS2wpcS-QJJG-Zu7n7_PJagtxBFh-40Izb6SgXc4Piubu_0ky8kvWnSBacTgoejiiqeQD4-PNV25ObWwOPAOOJRRXSnLFGlM9KNBdI>)。

- 套件包含型材/电子/螺丝等结构件、18650电池盒、主控与扩展板、云台摄像头、工具配件等，详见下方实物参考。

## 配件实物参考

以下图片提供器材、电子元器件、螺丝与工具的实物参考，便于到货后快速核对与入料管理。

### 型材配件

```{image} images/image_T6zJbnRSWowlVExTjoocM1x5ndb.webp
:width: 579px
:height: 369px
```

```{image} images/image_IDwwb9UWDoZrUKxvl0YcySDLnKg.webp
:width: 676px
:height: 491px
```

### 螺丝配件

```{image} images/image_Jdx5bv4u0oXk2qxCJGWcAypPn3e.webp
:width: 528px
:height: 736px
```

### 电子配件

```{image} images/image_FerYbLS1Ro9JnnxBLULcosrsnlf.webp
:width: 576px
:height: 821px
```

```{image} images/image_JtB6bV996oeUrdxGA4ec7QBLnnf.webp
:width: 485px
:height: 762px
```

### 工具

```{image} images/image_NkexbJ5huoouTUxHPNscaTxFnHd.webp
:width: 498px
:height: 311px
```

# 使用前组装说明

## 组装步骤

- 用4颗M2*5圆头自攻螺丝，将发光超声波传感器装至超声波支架上。

```{image} images/image_TZuvbiodMoph7Mx6RoMcMf8vnQe.webp
:width: 515px
:height: 488px
```

- 用2颗M2*4圆头机械螺丝，将PWM舵机装在底座支架上；用2颗黑色M3*6圆头机械螺丝，将组装好的超声波支架装在底座支架上（组装前先把4pin线装上）。

```{image} images/image_HsBabOfCsovYfPxzQPrcTxQhnTg.webp
:width: 526px
:height: 297px
```

- 用8颗M3*25机械螺丝和8颗M3螺母，将四个TT马达固定在底盘上。

```{image} images/image_XvKbbREA1oZyqzxc3ezcwxibnQe.webp
:width: 442px
:height: 270px
```

- 用2颗M4*8圆头机械螺丝和2根M4*28双通铜柱，固定在底盘上。再用2颗M4*8圆头机械螺丝将四路巡线传感器固定在底盘上。安装好四路巡线传感器之后，将4pin线一端插入传感器接口。

```{image} images/image_Nf4Eb1Js9oQPVdx3iascpx5gncG.webp
:width: 694px
:height: 507px
```

- 用4颗黑色M3*6圆头机械螺丝把组装好的底座支架安装在底盘上。

```{image} images/image_WB2GbbvKfoWtSkxO7pVcxT1tnYg.webp
:width: 478px
:height: 380px
```

- 用3颗M2.5*5单通尼龙柱和3颗M2.5*10双通尼龙柱把主板固定好。并将扩展板的排母，对准主板的排针（一一对齐）插入主板中。然后用2颗M2.5*6圆头机械螺丝将扩展板和主板固定住。

```{image} images/image_Jo0AbzTEGoY2zJxZsPycjhA5nSc.webp
:width: 1152px
:height: 896px
```

- 用4颗M2.5*6圆头机械螺丝把组装好的主板固定在底盘上，并将四路巡线传感器和发光超声波传感器接到扩展板对应接口上。

```{image} images/image_EDaib5tvhorsnjx1kkgclUAvnGI.webp
:width: 1072px
:height: 776px
```

- 用4颗M3*4平头机械螺丝把电池盒固定在底盘下。

```{image} images/image_QB9cbhkzZoVcxUxXWjBcAiX3npe.webp
:width: 1200px
:height: 721px
```

- 联轴器安装在TT马达的轮轴上，并用4颗盘头半机牙自攻/M2.3*25螺丝把麦轮与TT马达的轮轴固定住。

```{image} images/image_DCNQbh4t2oe6ZLxLJUQc9SA4n7f.webp
:width: 1328px
:height: 615px
```

- 用2颗M2*4圆头自攻螺丝把塑料轴固定在云台U型支架上，接着用1颗M2*4圆头自攻螺丝把组装好的云台U型支架安装在小车上。

```{image} images/image_PdSwbyensoYXOtxDvwVcXQY7nVb.webp
:width: 1266px
:height: 802px
```

- 用2颗M2*12圆头机械螺丝和2颗M2螺母把PWM舵机固定云台摄像头支架上。

```{image} images/image_Og41bQ7u7oPuqRxBOwEctZszndl.webp
:width: 658px
:height: 341px
```

- 用4颗M2*4圆头机械螺丝和4根M2*8滚花铜柱固定在云台摄像头支架上。然后用2颗M2*4圆头机械螺丝将摄像头固定在云台摄像头支架上。

```{image} images/image_HLqSbOrsWovrvGxrPTjcky7lnhh.webp
:width: 677px
:height: 302px
```

```{image} images/image_NgYmbIBzioKrFtx0fVwc5ifdnzf.webp
:width: 650px
:height: 472px
```

- 用1颗M2*6圆头自攻螺丝把组装好的云台摄像头支架固定在小车上。

```{image} images/image_SvoSbK95toPKSSxKPzLcRujJn4d.webp
:width: 1169px
:height: 478px
```

- 将4个TT马达接口和2个云台舵机的接口（橙色接S（信号线）、红色接+、棕色接-）与扩展板进行连接。

```{image} images/image_VYAvbj9v0oB1XQx4EExcbmHMnMg.webp
:width: 673px
:height: 550px
```

- 安装好后，车体如下。

```{image} images/image_L4tJbBr5Jo1NKgx1DzZcsDFKnXf.webp
:width: 680px
:height: 490px
```

# 使用前环境部署

## 下载环境

使用前需要下载相关环境，下载链接如下：  
[部署环境](<https://developer.quectel.com/doc/files/smartcar/qpi_smartcar.zip>)

下载好部署环境后，将部署环境通过adb push到设备中，再进行解压。

```bash
#推送到设备
adb push ./qpi_smartcar.zip /mnt
adb shell

#解压压缩包：unzip /mnt/qpi_smartcar.zip -d /mnt/

#为 run/ 目录下的所有文件和 deploy_container.sh 添加可执行权限：chmod +x /mnt/qpi_smartcar/service_config/run/*
chmod +x /mnt/qpi_smartcar/deploy_container.sh
```

解压后得到以下的目录结构：

```plaintext
qpi_smartcar/
├── docker_images/
│   └── docker_qpi_smart_car.tar    # Docker 镜像文件
├── ros2_ws/
│   ├── src/                           # ROS 2 源代码
│   └── software/                      # 软件工具
├── service_config/
│   ├── rules.d/                       # udev 规则文件
│   ├── service/                       # systemd 服务文件
│   └── run/                           # 开机快速启动脚本              
└── deploy_container.sh                # 完整部署脚本
```

## 确保通信

为保证Quectel Pi智能主控板和扩展板能够通信，需要使能40pin上的i2c9和uart12，使能方法如下：

- 在Quectel Pi智能主控板上，修改 **qpi-config.ini** 配置文件。请先执行以下命令打开文件：**vi /etc/qpi-config/qpi-config.ini**，然后将其内容修改为：

```toml
i2c9=enablespi10=disableuart12_2w=enablei2c13=disablespi14=disableheartbeat_color=greenled_red_brightness=0led_blue_brightness=0led_green_brightness=0heartbeat_switch=on
```

- 输入 **qpi-config 40pin set**，之后 **重启** Quectel Pi智能主控板生效。

## 完整部署流程

在以上重启之后，需要插上网线或者连接Wi-Fi，确保处于可联网环境，然后执行部署脚本 *deploy_container.sh*。

```bash
# 运行完整部署
/mnt/qpi_smartcar/deploy_container.sh
```

部署脚本执行后，如果部署成功，会弹出以下提示：

```bash
[SUCCESS] Deployment completed successfully!
ROS2 application has been automatically started!
```

## 使用前设备准备

### 电池充电

由于运输途中电池不能充满，所以在初次开机前，建议先给电池充满电，以下是具体充电方法：

1. 拿出电池充电器，将两节18650电池（选配）按照正负极对应（正对正，负对负）装到电池充电器中，注意！电池正负极切勿装反！再通过数据线将电池充电器（选配）和充电头（5V 3A，需自备）进行连接，最后连接电源。

```{image} images/image_ZiK1bKbQ4o0nZuxIk9wcJowDnyf.webp
:width: 405px
:height: 445px
```

2. 等待充电完成（适配器接通电源后指示灯默认为绿色，正确装入亏电电池后指示灯应变为红色（代表充电中，时长约5小时）；当指示灯由红色重新变为绿色时，代表充电完成）。充电完成后，请尽快拔掉充电器，切勿一直充电。

3. 充电完成后，安装电池前请确保电池盒的开关拨到“OFF”档（OFF档位置见开机准备章节）。

### 手机App安装

安卓：扫描以下二维码进行安装。

```{image} images/image_AmdNbWWTSosq82xtseVcpZKtnBg.webp
:width: 506px
:height: 507px
```

iOS：可前往App Store搜索“WonderPi”并进行下载安装。

```{image} images/image_H3Q1bD3qKokgLCxDszycHFs5nHj.webp
:width: 429px
:height: 350px
```

### 开机准备

1. 将两节有电的18650电池按照正负极对应装到小车底部的电池盒中，之后将底部的开关拨至“ON”。

```{image} images/image_XaUsb5qmUoPRofxl2xycd9CLnYc.webp
:width: 603px
:height: 484px
```

2. 再将扩展板的开关由“OFF”推动到“ON”，此时扩展板的LED1、LED2常亮，稍等片刻后LED1由常亮变为每隔1秒闪亮一次、云台回到初始姿态、蜂鸣器发出“嘀”的一声，即设备成功开机（大概需要等待30s后会听见“嘀”的一声）。

```{image} images/image_EJa7bpNuyoN8msxIoX3c0kVdnzd.webp
:width: 509px
:height: 441px
```

```{note}
LED2为电源指示灯，通电时点亮，设备运行过程中是常亮的状态，若灯光变暗则表示电源没电了，需要充电；  
LED1为通信指示灯，设备出厂默认的网络连接模式为直连模式，设备开机成功后，LED1每隔1秒闪烁一次；若将其设置为局域网模式，LED1则会常亮；  
设备运行过程中，若LED1与LED2灯光变暗，并保持常亮的状态，则表示电源没电了，需要充电。
```

# 设备试玩

## 使用前连接

1. 设备开机成功后，会进入AP直连模式，并生成一个以“HW”开头的热点。在手机上打开手机App“WonderPi”，依次点击“初级套件”、“TurboPi”。

```{image} images/image_HM54bOufloqRb2xuuexcerAAntf.webp
:width: 603px
:height: 285px
```

2. 点击界面右下角的“+”按钮，选择“直连模式”。

```{image} images/image_PSR1bSz8SoK4S1xGhoIcvIFknBA.webp
:width: 620px
:height: 288px
```

3. 点击“去连接设备热点”按键，前往设置界面，连接以“HW”开头的热点，连接时需输入密码“hiwonder”。

```{image} images/image_J3SxbtP2poLZmxxuu9Icx8h5nzc.webp
:width: 607px
:height: 288px
```

```{image} images/image_GUGsbw2mZoTFi9x8lypca1SGnrb.webp
:width: 309px
:height: 309px
```

4. 连接成功后返回手机App，稍等片刻，当搜索到下图所示图标时，即为连接成功（若设备列表下方未显示，可点击右上方的刷新，刷新设备）。

```{image} images/image_CXiMbCep4oTkQCxl6NWcWoJ0n0f.webp
:width: 600px
:height: 279px
```

```{note}
若出现“网络不可用，是否继续连接”的提示弹窗，单击“保持连接”按键即可。
```

5. 点击上图的TurboPi图标即可进入玩法模式选择界面，如下所示：

```{image} images/image_CZYNbTWoEoccZTxrAP2c9Q7Gnib.webp
:width: 1752px
:height: 807px
```

## 机体遥控

介绍：该玩法可以实时控制小车运动及超声波的RGB灯；界面分为四个部分，各部分的描述以及功能图标如下所示：

```{image} images/image_OFO5bbXP5o2swkxScc2cGB33nJf.webp
:width: 637px
:height: 294px
```

① 状态栏：可以控制玩法的退出、回传画面的截图以及状态栏的隐藏；

② 控制栏：可以控制小车运动；

③ 回传画面：显示摄像头的回传画面，并显示设备的电压值；

④ 超声波RGB灯的调节功能：可以控制超声波模块的RGB灯开启、关闭以及亮起不同颜色的灯。

操作如下描述：

<table>
  <tr>
    <th>界面分布</th>
    <th>图标</th>
    <th>对应功能</th>
  </tr>
  <tr>
    <td rowspan="3">控制栏</td>
    <td><div style="text-align: center"><img src="images/image_BFD5b0jTloQ2pixvqhBcP97Qnwk.webp" alt="image" width="85" height="86"></div></td>
    <td>拖动中间的按钮，可控制TurboPi车体朝各个方向运动。</td>
  </tr>
  <tr>
    <td><div style="text-align: center"><img src="images/image_UH2ub154MoREVnxzzwVcsUdYnmf.webp" alt="image" width="123" height="87"></div></td>
    <td>点击或长按此图标，可控制TurboPi车体原地逆时针转动。</td>
  </tr>
  <tr>
    <td><div style="text-align: center"><img src="images/image_PNNVbHHJAoVgIyxBrYMcxxPvnJc.webp" alt="image" width="119" height="89"></div></td>
    <td>点击或长按此图标，可控制TurboPi车体原地顺时针转动。</td>
  </tr>
</table>

如需返回到玩法选择界面，点击左上方的返回箭头即可。

## 目标追踪

介绍：点击“目标追踪”，进入玩法界面。该玩法开启后可以实现小车随着目标颜色的移动而移动的功能。

```{image} images/image_XHYrb3XYjoXfxOxCCCjcZg4inPb.webp
:width: 695px
:height: 313px
```

操作步骤如下：

1. 在以上画面中，点击①处按钮会从“取色”变为“确定取色”，在右边摄像头捕捉的画面中，挪动红色小圆点选中目标颜色，再点击“确定取色”确认颜色；

2. 点击②处“云台追踪”按钮，可启动追踪玩法，此时设备的摄像头将跟随选定的颜色目标运动，车体不动；

3. 若要实现车身跟随的玩法，需要同时选中②处“云台追踪”和③处“车身跟随”这两个按钮，此时设备的车体和云台会跟随选定的颜色目标运动。

```{note}
请在光线充足的室内环境下进行，但尽量避免在强光直射下进行。  
识别时，摄像头画面内请勿出现和目标颜色相同或相近的杂物，避免干扰识别。
```

## 取色巡线

介绍：点击“取色巡线”，进入玩法界面。启动该玩法后，可以让小车沿着黑线或红线前进。

```{image} images/image_PratbovahoD8bBxx7xVco4Qgn3c.webp
:width: 815px
:height: 371px
```

操作步骤如下：

1. 在以上画面中，点击①处按钮会从“取色”变为“确定取色”，在右边摄像头捕捉的画面中，挪动红色小圆点选中目标颜色，再点击“确定取色”确认颜色；

2. 点击②处“开始”按钮，将沿着目标颜色的线条前进。

```{note}
请在光线充足的室内环境下进行，但尽量避免在强光直射下进行。  
识别时，摄像头画面内请勿出现和目标颜色相同或相近的杂物，避免干扰识别。
```

## 二维码识别

介绍：点击“二维码”识别，进入玩法界面。该玩法启动后可以让小车的摄像头识别不同的二维码，执行对应的动作。

```{image} images/image_XfYIb9TkBoK3S9xiI58cWY4XnLL.webp
:width: 648px
:height: 309px
```

① 界面左侧是二维码开关及选择区域；

② 界面右侧是二维码画面。

操作步骤如下：

点击“开始识别”按钮，并选择不同的二维码，将二维码放在设备的摄像头前方进行识别，设备将在识别到不同的二维码之后执行不同的动作。

| **按钮图标** | **功能说明** |
| --- | --- |
| <div style="text-align: center"><img src="images/image_AjjNbGVabozrQlx0bObc5k70nab.webp" alt="image" width="132" height="58"></div> | 小车执行前进动作的二维码 |
| <div style="text-align: center"><img src="images/image_BdUnbohUJoj14BxbQuIcbKiBnHb.webp" alt="image" width="129" height="55"></div> | 小车执行后退动作的二维码 |
| <div style="text-align: center"><img src="images/image_FtQKbaAtrorInAx1fDncy2zlnCX.webp" alt="image" width="126" height="59"></div> | 小车执行左移动作的二维码 |
| <div style="text-align: center"><img src="images/image_VKLjbOkMBomlGdx4Jcjc5FpvnTe.webp" alt="image" width="128" height="58"></div> | 小车执行右移动作的二维码 |
| <div style="text-align: center"><img src="images/image_Df2nbaOQBo9JWVxvxUpcB7unnqh.webp" alt="image" width="142" height="100"></div> | 显示选中的二维码信息 |

```{note}
识别二维码时距离不宜太近或太远，一般二维码图片与摄像头相距为35 cm为最佳。  
请在光线充足的室内环境下进行，但尽量避免在强光直射下进行。
```

## 智能避障

点击“智能避障”，进入玩法界面。该玩法启动后可让小车通过超声波识别前方是否有障碍物并避开。

```{image} images/image_FpiObEjJdorg2CxKRnKcxDjznUc.webp
:width: 787px
:height: 361px
```

① 界面左侧是避障玩法开关及障碍物阈值设置区域；

② 界面中间是摄像头回传画面区域；

③ 界面右侧是RGB彩灯和电机速度设置区域。

操作步骤如下：

点击“开始避障”按钮，设备将一直前进，检测到障碍物会左转，直到没有障碍物，然后继续前进。

| **按钮图标** | **功能说明** |
| --- | --- |
| <div style="text-align: center"><img src="images/image_ISZhbaeD7oCjSlxFBXTcSmxknhc.webp" alt="image" width="202" height="35"></div> | 开启/关闭玩法。 |
| <div style="text-align: center"><img src="images/image_Az0XbuPm6oeNn2xJ0xHcFnWZnse.webp" alt="image" width="103" height="151"></div> | 调节障碍物阈值，单位：cm。 |
| <div style="text-align: center"><img src="images/image_NLehb3Pnvo0fM1xzCGncJucrnfq.webp" alt="image" width="221" height="35"></div> | 超声波RGB彩灯开启/关闭。 |
| <div style="text-align: center"><img src="images/image_IuafbFBTvosVXpxQWfkc61tMnRd.webp" alt="image" width="121" height="115"></div> | 超声波RGB灯光颜色调节。 |
| <div style="text-align: center"><img src="images/image_XTOMbZbq3ovHgwxJqIecBqknnBf.webp" alt="image" width="197" height="78"></div> | 电机速度调节，数值越大，电机速度越快。 |

```{note}
请勿长时间近距离检测物体。
```

# 技术支持与贡献

如在使用过程中遇到问题，欢迎在 [移远官方论坛](<https://forumschinese.quectel.com/c/quectel-pi/58>) 提交技术咨询，我们的技术支持团队将及时为您解答。