Graduation_Project/README.md

# 全向智能跟随垃圾桶的开发与实现

本项目是一个基于树莓派 4B 的智能垃圾桶控制系统，包含 Web 远程控制、四轮全向运动控制、路径录制与回放、摄像头目标跟踪以及自然语言控制等功能。系统后端使用 Flask 提供控制接口，前端通过浏览器完成设备操作，底层通过 PCA9685 PWM 驱动板控制四个电机运动。

## 功能特性

- Web 控制界面：支持前进、后退、左右平移、原地旋转和斜向移动。
- 路径录制与回放：记录用户操作动作和时间戳，并保存为 JSON 轨迹文件。
- 视觉目标跟踪：基于 OpenCV 实现运动目标检测、相机运动补偿和目标中心跟随。
- 智能助手控制：通过自然语言指令调用智能垃圾桶运动、路径播放和路径管理功能。
- 多输入方式：支持鼠标、触摸、语音输入和游戏手柄控制。

## 项目结构

```text
.
├── server.py              # Flask Web 服务与控制接口
├── motor.py               # PCA9685 与四电机底层驱动
├── camera.py              # 摄像头目标跟踪与自动运动控制
├── agent.py               # 智能助手指令解析与动作执行
├── index.html             # Web 控制界面入口
├── CSS/                   # 页面样式文件
├── Javascript/            # 前端交互、轨迹回放、语音和手柄控制脚本
├── Path/                  # 保存的轨迹 JSON 文件
├── agent/skills.md        # 智能助手可调用技能说明
├── motor_test.py          # 电机测试程序
└── camera_test.py         # 摄像头测试程序
```

## 硬件环境

本项目主要面向以下硬件环境：

- Raspberry Pi 4B
- PCA9685 PWM 驱动板
- 四个MG310减速电机
- 四轮全向轮或福来轮
- USB 摄像头或树莓派摄像头
- 电机供电模块

使用前需要在树莓派中开启 I2C 接口，并确认 PCA9685 的默认地址为 `0x60`。

## 软件环境

建议环境：

- Python 3.8+
- Flask
- OpenCV
- NumPy
- smbus2
- requests
- urllib3

可以使用以下命令安装主要依赖：

```bash
pip install flask opencv-python numpy smbus2 requests urllib3
```

如果在树莓派上安装 OpenCV 速度较慢，可以优先使用系统软件源安装：

```bash
sudo apt update
sudo apt install python3-opencv
```

## 运行方式

### 1. 启动 Web 控制服务

```bash
python server.py
```

默认启动地址为：

```text
https://localhost:5443
```

在局域网中访问时，可以使用树莓派的 IP 地址：

```text
https://<树莓派IP>:5443
```

服务默认使用 Flask 的临时 HTTPS 证书，浏览器首次访问时可能会提示证书不受信任，继续访问即可。

### 2. 修改服务端口

可以通过环境变量修改监听端口：

```bash
HTTPS_PORT=5443 python server.py
```

Windows PowerShell 中可使用：

```powershell
$env:HTTPS_PORT="5443"
python server.py
```

### 3. 运行摄像头跟踪程序

```bash
python camera.py
```

程序会打开摄像头画面，并根据目标中心与画面中心的偏差调用 `motor.py` 中的电机控制函数，实现目标跟随。

### 4. 测试电机

```bash
python motor_test.py
```

该脚本会依次测试前进、后退、平移、斜向移动和旋转动作。测试前请确保智能垃圾桶周围有足够空间，避免碰撞。

## Web 接口说明

### 控制接口

```http
POST /control
Content-Type: application/json
```

请求示例：

```json
{
  "direction": "forward"
}
```

支持的方向包括：

- `forward`
- `backward`
- `left`
- `right`
- `rotate_left`
- `rotate_right`
- `forward_left`
- `forward_right`
- `backward_left`
- `backward_right`
- `stop`

### 路径管理接口

保存路径：

```http
POST /save_path
```

列出路径：

```http
GET /list_paths
```

加载路径：

```http
GET /load_path?name=test1
```

删除路径：

```http
DELETE /delete_path
```

路径文件保存在 `Path/` 目录下，格式示例：

```json
{
  "name": "test1",
  "actions": [
    {
      "direction": "forward",
      "timestamp": 1734
    },
    {
      "direction": "stop",
      "timestamp": 2074
    }
  ]
}
```

## 视觉跟踪逻辑

`camera.py` 采用轻量化 OpenCV 视觉处理方案，适合树莓派 4B 这类算力有限的平台。程序主要流程如下：

1. 从摄像头读取图像，并设置分辨率为 `320x240`。
2. 将图像转换为灰度图并进行高斯滤波。
3. 使用特征点与光流法估计相机运动。
4. 对上一帧进行运动补偿后与当前帧做差分。
5. 通过阈值分割和形态学处理提取运动区域。
6. 根据面积、长宽比、填充率和边缘位置筛选候选目标。
7. 维护目标状态，记录目标中心、面积、边界框和速度信息。
8. 根据目标中心与画面中心的偏差调用电机控制函数。

该方法没有使用 YOLO，主要原因是树莓派 4B 直接运行深度学习目标检测模型时响应速度较慢，并且 CPU、内存和发热压力较大。对于本系统而言，实时控制响应比单帧识别精度更重要，因此采用了计算量更低的传统视觉跟踪方案。

## 电机控制逻辑

`motor.py` 通过 I2C 控制 PCA9685，向不同通道输出 PWM 信号。每个电机占用两个通道，通过两个通道的 PWM 输出关系控制电机正反转和停止。

四个电机组合后可以实现：

- 前进与后退
- 左右平移
- 左右旋转
- 四个方向的斜向移动
- 停止

如果实际运动方向与预期相反，可以根据电机接线和轮子安装方向，调整 `motor.py` 中各运动函数的正负号，或在 `server.py`、`camera.py` 中调整方向映射。

## AI Agent功能实现

`agent.py` 提供自然语言指令解析与执行功能。前端将用户输入发送到 `/agent_chat`，后端根据 `agent/skills.md` 中定义的技能规则调用对应动作。

支持示例：

- 前进 3 秒
- 后退 2 秒
- 左转 1 秒
- 停止
- 执行路径 test1
- 列出路径
- 删除路径 test1

使用Agent功能前，需要在 Web 页面中配置可用的 LLM API 地址、API Key 和模型名称。

## 常见问题

### 1. 浏览器无法打开摄像头或语音输入

语音输入和摄像头权限通常要求 HTTPS 或 localhost 环境。本项目默认使用 HTTPS 启动，如果浏览器提示证书不可信，需要手动选择继续访问。

### 2. 智能垃圾桶前后方向反了

这通常与电机接线、轮子安装方向或程序中的方向映射有关。可以优先检查：

- `motor.py` 中 `forward()` 和 `backward()` 的电机正负号。
- `server.py` 中 `/control` 对 `forward`、`backward` 的映射。
- `camera.py` 中 `drive_to_target()` 对目标偏移方向的控制逻辑。

### 3. 摄像头跟踪不稳定

当前方法基于运动区域检测，复杂背景、光照变化、遮挡和其他运动物体都会影响识别效果。可以尝试：

- 降低背景干扰。
- 保持光照稳定。
- 调整 `MIN_CONTOUR_AREA`、`MAX_CONTOUR_AREA` 和 `CONTROL_DEADZONE`。
- 后续接入轻量化 YOLO 或硬件 AI 加速模块。

### 4. 路径回放存在偏移

当前路径回放基于时间戳记录动作，属于开环控制。电池电压、地面摩擦、电机响应差异和轮胎打滑都会造成误差。后续可以通过编码器、IMU 或视觉定位实现闭环修正。

## 注意事项

- 电机测试前请架空智能垃圾桶移动底盘或确保周围空间安全。
- 树莓派和电机建议分开供电，避免电机启动瞬间导致树莓派掉电。
- 如果长时间运行摄像头跟踪，建议注意树莓派温度。
- 轨迹文件保存在 `Path/` 目录中，删除前请确认文件名称。

## License

本项目用于课程设计、毕业设计或个人学习研究。若用于其他用途，请根据实际情况补充许可证说明。