docs: 完善项目文档，新增系统架构说明

- 新增 docs/architecture.md 系统架构文档 - 完善主仓库 README.md 项目说明 - 更新 chassis/vision/vision-web 子模块至最新（含文档完善）
2026-06-07 21:02:44 +08:00
parent 87b085fe82
commit 78b8b25def
5 changed files with 247 additions and 15 deletions
@@ -1,22 +1,64 @@
 # Auto-Aim Mobile Bot
-> **自动瞄准移动机器人**
+> 自动瞄准移动机器人系统 — 多处理器分布式架构，具备自主识别、追踪与运动控制能力。
 >
 > 依托于 2025 年电赛 E 题。本项目旨在开发一套具备自主识别、追踪目标能力的移动机器人系统。
-## 📂 项目结构
+## 项目概述
-本项目采用 **Git Submodule** 管理各个功能模块，核心代码分散在子仓库中。
+本项目实现了一套完整的自动瞄准移动机器人系统。系统由四个功能模块组成，分别运行在独立的嵌入式处理器上，通过串口和网络进行实时通信。系统支持三种工作模式：全自主追踪巡线 (AUTO)、手动遥控 (MANUAL) 和在线调试 (DEBUG)。
-## 🛠️ 技术栈
+## 系统架构
- **硬件平台**:
+```
- **开发语言**:
+┌─────────────┐     ┌────────────────────┐     ┌──────────────┐
- **核心算法**:
+│  Vision-Web │ ──► │  Vision (ROS2)     │ ──► │  Gimbal MCU  │
 │  (Vue3 前端) │     │  (Jetson, 视觉处理) │     │  (云台控制)    │
 └─────────────┘     └────────┬───────────┘     └──────────────┘
                             │
                             ▼
                      ┌──────────────┐
                      │  Chassis MCU │
                      │  (底盘控制)    │
                      └──────────────┘
 ```
-## 🚀 快速开始
+详细架构说明见 [docs/architecture.md](docs/architecture.md)。
-由于项目使用了子模块，克隆时请务必加上 `--recursive` 参数：
+## 模块
 | 模块 | 路径 | 硬件平台 | 说明 |
 |------|------|----------|------|
 | Vision | `modules/vision/` | NVIDIA Jetson | ROS2 视觉处理、PnP 位姿估计、HTTP API |
 | Gimbal | `modules/gimbal/` | STM32H723ZG | 两轴云台、IMU 姿态解算、DM 电机控制 |
 | Chassis | `modules/chassis/` | MSPM0G3507 | 差速底盘、IMU、巡线、三环 PID |
 | Vision-Web | `modules/vision-web/` | 浏览器 | Vue3 远程控制、MJPEG 视频流、PID 调参 |
 ## 技术栈
 | 层 | 技术 |
 |----|------|
 | 视觉处理 | ROS2 Humble, Python 3, OpenCV, Microdot |
 | 云台控制 | C, FreeRTOS, STM32CubeH7 HAL, CMSIS-DSP |
 | 底盘控制 | C, Keil MDK, TI MSPM0 SDK |
 | 前端 | Vue 3, Vite, roslibjs |
 | 通信 | UART (二进制帧协议), CAN (DM 电机), WebSocket (rosbridge) |
 ## 快速开始
 ```bash
-git clone --recursive <主仓库地址>
+# 克隆主仓库及所有子模块
 git clone --recursive git@git.skyli.cc:AimBot/Auto-Aim-Mobile-Bot.git
 # 更新子模块到最新
 git submodule update --remote --recursive
 ```
 各模块的构建和运行说明见对应子模块的 README 文档。
 ## 子模块仓库
 | 模块 | 仓库地址 |
 |------|----------|
 | Vision | `git@git.skyli.cc:AimBot/Vision.git` |
 | Vision-Web | `git@git.skyli.cc:AimBot/Vision-Web.git` |
 | Gimbal | `git@git.skyli.cc:AimBot/Gimbal.git` |
 | Chassis | `git@git.skyli.cc:AimBot/Chassis.git` |
@@ -0,0 +1,190 @@
 # Auto-Aim Mobile Bot — 系统架构
 ## 概述
 Auto-Aim Mobile Bot 是一个基于多处理器分布式架构的自动瞄准移动机器人系统。系统由四个功能模块组成，分别运行在独立的硬件平台上，通过串口和网络进行实时通信。
 ## 硬件拓扑
 ```
 ┌──────────────────────────────────────────────────────────────────┐
 │                         Jetson (aarch64)                          │
 │  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────────┐  │
 │  │ 工业相机      │  │ vision (ROS2)│  │ Nginx :80               │  │
 │  │ (Hikrobot)   │  │ - 目标检测    │  │ - 前端静态文件            │  │
 │  │              │  │ - PnP 位姿   │  │ - /stream → web_video    │  │
 │  │              │  │ - HTTP API   │  │ - /api → web_node        │  │
 │  └──────────────┘  └──────┬───────┘  └─────────────────────────┘  │
 │                           │ UART                                  │
 │          ┌────────────────┼────────────────┐                      │
 │          ▼                ▼                ▼                      │
 │  ┌─────────────┐  ┌────────────┐  ┌──────────────┐               │
 │  │ Gimbal MCU  │  │Chassis MCU │  │ 激光模组       │               │
 │  │ (STM32H723) │  │(MSPM0G3507)│  │ (GPIO 控制)   │               │
 │  └──────┬──────┘  └──────┬─────┘  └──────────────┘               │
 │         │                │                                        │
 │    ┌────┴────┐      ┌────┴────┐                                   │
 │    │DM-G6220 │      │ 左轮电机  │                                   │
 │    │DM-J4310 │      │ 右轮电机  │                                   │
 │    │BMI088   │      │ICM-42688│                                   │
 │    └─────────┘      │灰度传感器 │                                   │
 │                     └─────────┘                                   │
 └──────────────────────────────────────────────────────────────────┘
 ```
 ## 模块架构
 ### 1. Vision (ROS2 视觉处理) — `modules/vision/`
 运行在 NVIDIA Jetson 上，是整个系统的"眼睛"和"大脑"。
 - **技术栈**: ROS2 Humble, Python 3, OpenCV, Microdot
 - **核心功能**:
  - Hikrobot 工业相机图像采集
  - Otsu 二值化 + 轮廓层级矩形检测
  - PnP 位姿估计 (SOLVEPNP_IPPE)
  - 激光光斑世界坐标计算
  - HTTP REST API (模式切换、PID 配置、激光控制)
 - **串口通信**: 与云台 (921600bps) 和底盘 (115200bps) 通过定制二进制帧协议通信
 - **Web 服务**: rosbridge WebSocket (9090), web_video_server (8081), Nginx (80)
 ### 2. Gimbal (云台控制) — `modules/gimbal/`
 运行在 STM32H723ZG (Cortex-M7, 480MHz) 上，控制两轴云台实现视觉追踪。
 - **技术栈**: C, FreeRTOS, STM32CubeH7 HAL, CMSIS-DSP
 - **核心功能**:
  - BMI088 IMU 姿态解算 (四元数 EKF)
  - DM 电机双环 PID 控制 (外环视觉PID + 内环角度PID)
  - 上位机串口协议解析 (0xA5/A6/A7/A8 帧)
  - Pub-Sub 消息总线解耦模块
  - 三种工作模式: AUTO/MANUAL/DEBUG
 - **控制频率**: INS 1kHz, Motor 1kHz, Robot 500Hz, Daemon 100Hz
 ### 3. Chassis (底盘控制) — `modules/chassis/`
 运行在 TI MSPM0G3507 (Cortex-M0+, 80MHz) 上，控制两轮差速底盘运动。
 - **技术栈**: C, Keil MDK, TI MSPM0 SDK
 - **核心功能**:
  - 双电机 PWM 驱动 + QEI 编码器测速
  - ICM-42688-P IMU 姿态解算 (Mahony AHRS)
  - 8 通道灰度传感器巡线
  - 三环 PID 控制 (速度环 / 角度环 / 位置环)
  - UART 串口命令解析 (0xA6/A7/A8/A9 帧)
  - 三种工作模式: AUTO/MANUAL/DEBUG
 ### 4. Vision-Web (前端) — `modules/vision-web/`
 基于 Vue 3 的 Web 前端，提供远程监控和遥控。
 - **技术栈**: Vue 3, Vite, Vue Router 4, roslibjs
 - **页面**:
  - **AutoMode**: MJPEG 视频流实时预览
  - **ManualMode**: WASD + 方向键键盘遥控底盘和云台
  - **DebugMode**: 在线 PID 参数调节
 - **通信**: rosbridge WebSocket (实时控制), HTTP REST (模式切换), MJPEG (视频流)
 ## 数据流
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │  camera_node ──/camera/image_raw──► vision_node                  │
 │                                       │                          │
 │                    ┌──────────────────┼──────────────┐           │
 │                    ▼                  ▼              ▼           │
 │              /vision/target    /vision/result   /vision/debug    │
 │                    │                  │              │           │
 │                    ▼                  ▼              ▼           │
 │             gimbal_node        web_video_server (MJPEG)          │
 │                    │                  │                           │
 │                    ▼                  ▼                           │
 │            UART 0xA5 帧       浏览器 <img> 标签                    │
 │                    │                                              │
 │                    ▼                                              │
 │            Gimbal MCU (USART10)                                   │
 │                    │                                              │
 │                    ▼                                              │
 │            robot_cmd ──gimbal_cmd──► gimbal ──► DM Motor         │
 │                                                                   │
 │  ┌─────────────────────────────────────────────────────┐         │
 │  │ 浏览器 (Vue3)                                        │         │
 │  │                                                      │         │
 │  │ ManualMode: WASD → roslibjs → /cmd_chassis          │         │
 │  │                                                      │         │
 │  │             方向键 → roslibjs → /cmd_gimbal           │         │
 │  │                                                      │         │
 │  │ J 键 → fetch POST /api/laser                        │         │
 │  └─────────────────────────────────────────────────────┘         │
 │                                                                   │
 │  ┌─────────────────────────────────────────┐                     │
 │  │ web_node (:8080)                         │                     │
 │  │                                           │                     │
 │  │ POST /api/gimbal/mode/switch → /gimbal/mode                    │
 │  │ POST /api/chassis/mode/switch → /chassis/mode                  │
 │  │ POST /api/laser → /laser/command                               │
 │  │ GET/POST /api/gimbal/pidconfig → /web/gimbal_pid_config       │
 │  │ GET/POST /api/chassis/pidconfig → /web/chassis_pid_config     │
 │  └─────────────────────────────────────────┘                     │
 └─────────────────────────────────────────────────────────────────┘
 ```
 ## 通信协议
 系统内部使用统一的二进制帧协议，帧头区分帧类型，校验和为字节累加。
 ### 云台协议 (USART10, 921600bps)
 | 帧头 | 长度 | 方向 | 用途 |
 |------|------|------|------|
 | 0xA5 | 18B | PC→MCU | 自动追踪 (measure_x, ref_x, measure_y, ref_y) |
 | 0xA6 | 10B | PC→MCU | 手动控制 (yaw_vel, pitch_vel) |
 | 0xA7 | 3B | PC→MCU | 命令帧 (模式切换, 激光控制) |
 | 0xA8 | 50B | PC→MCU | PID 调参 (12 个 float) |
 | 0xA9 | 6B | PC→MCU | 前馈角速度 |
 ### 底盘协议 (UART, 115200bps)
 | 帧头 | 长度 | 方向 | 用途 |
 |------|------|------|------|
 | 0xA6 | 8B | PC→MCU | 手动控制 (motor_speed_base, angle_velocity) |
 | 0xA7 | 3B | PC→MCU | 命令帧 (模式切换) |
 | 0xA8 | 38B | PC→MCU | PID 调参 (9 个 float) |
 | 0xA9 | 6B | MCU→PC | 前馈角速度 |
 ### PID 控制层级
 ```
 底盘:
  位置环 (50Hz) ──► 角度环 (50Hz) ──► 速度环 (100Hz)
  灰度传感器          IMU Yaw           编码器
 云台:
  视觉环 (500Hz) ──► 角度环 (1kHz)
  图像测量             IMU 姿态
 ```
 ## 工作模式
 | 模式 | 云台 | 底盘 | 说明 |
 |------|------|------|------|
 | AUTO | 视觉追踪目标 | 灰度巡线 | 全自主运行 |
 | MANUAL | 接收角速度指令 | 接收速度指令 | 手动遥控 |
 | DEBUG | 电机失能，可调参 | 电机失能，可调参 | PID 在线调试 |
 ## 网络端口分配
 | 端口 | 服务 | 协议 |
 |------|------|------|
 | 80 | Nginx (前端 + 反代) | HTTP |
 | 8080 | web_node (API) | HTTP |
 | 8081 | web_video_server | HTTP (MJPEG) |
 | 9090 | rosbridge | WebSocket |
 ## 硬件规格
 | 模块 | MCU | 主频 | Flash | RAM | 传感器 |
 |------|-----|------|-------|-----|--------|
 | Gimbal | STM32H723ZG (Cortex-M7) | 480MHz | 1MB | 128KB DTCM | BMI088 6轴 IMU |
 | Chassis | MSPM0G3507 (Cortex-M0+) | 80MHz | 128KB | 32KB | ICM-42688-P, 8ch 灰度 |
 | Vision | NVIDIA Jetson (aarch64) | — | — | — | Hikrobot 工业相机 |