上传Markdown文档及素材照片

README.md

@@ -1,3 +1,277 @@
-# Graduation_Project
+# 智能垃圾桶控制系统
 
-毕业设计
+本项目是一个基于树莓派 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 驱动板
+- 四个直流电机
+- 四轮全向轮或福来轮移动底盘
+- 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` 中调整方向映射。
+
+## 智能助手控制
+
+`agent.py` 提供自然语言指令解析与执行功能。前端将用户输入发送到 `/agent_chat`，后端根据 `agent/skills.md` 中定义的技能规则调用对应动作。
+
+支持示例：
+
+- 前进 3 秒
+- 后退 2 秒
+- 左转 1 秒
+- 停止
+- 执行路径 test1
+- 列出路径
+- 删除路径 test1
+
+使用智能助手前，需要在 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
+
+本项目用于课程设计、毕业设计或个人学习研究。若用于其他用途，请根据实际情况补充许可证说明。