280 lines
13 KiB
Markdown
280 lines
13 KiB
Markdown
# MyParking 停车机器人
|
||
|
||
[简体中文](README.md) | [English](README_en.md)
|
||
|
||
## 重写路线与当前状态
|
||
|
||
本仓库是停车机器人控制软件的重写版本，研发顺序保持为：
|
||
|
||
1. 先实现单台停车机器人小车的基本功能；
|
||
2. 在单车闭环稳定后逐步增加停车作业功能；
|
||
3. 基于台架和实车数据优化轨迹跟踪方法；
|
||
4. 最后再考虑多车通信、编队和协同控制。
|
||
|
||
当前工作仍以**单车**为主，处于底盘联调、功能补充和跟踪实验阶段。多车配置位于 `MultiWheelC/PilotConfig.cs` 的 `#if false` 区域，`Shared/Fleet/FleetKinematics.cs` 仍是占位文件，不能视为多车能力已经实现。
|
||
|
||
| 阶段 | 当前状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| 1. 单车基本功能 | 联调中 | 已接入运动控制、MCU 通信、轮组反馈、急停 IO、电池、灯光、遥控和诊断代码，仍需持续实车验证 |
|
||
| 2. 增加停车功能 | 部分开展 | 已接入夹臂控制、限位和报警；夹臂动作测试当前已注释，轮胎识别、钻车和完整停车流程尚未实现 |
|
||
| 3. 优化跟踪方法 | 已启动 | 保留旧版 `SendMotion` 测试，并新增 Stanley 横向 + PID 纵向控制、组合运动计划、实验 CSV 和新版绘图工具 |
|
||
| 4. 多车场景 | 暂不实施 | 多车参数和预研内容未参与当前编译，当前版本不提供多车联动 |
|
||
|
||
## 项目简介
|
||
|
||
MyParking 是一个面向多轮停车机器人底盘的 C# 工程，覆盖上层运动动作、共享运动学、底层硬件适配和实验数据分析。
|
||
|
||
核心模块：
|
||
|
||
- `MultiWheelC`：Clumsy 上层（C 层）动作、轨迹跟踪、人工测试和实验记录；
|
||
- `MedullaAdapter`：Medulla 下层（M 层）MCU、CAN、串口、轮组、夹臂、遥控和报警适配；
|
||
- `Shared`：M/C 共享的二维坐标、底盘命令、坐标变换和多轮底盘适配（无独立 `.csproj`，由两端编译引入）；
|
||
- `CommonUsage-MultiVehicleSync/commonusage`：仓库内的 `CommonUsage` 底盘公共库源码；
|
||
- `data_process`：轨迹实验与舵轮响应的 Python 分析工具。
|
||
|
||
仓库中没有 ROS/ROS 2、Docker 或 Web 仿真项目。插件由 Clumsy / Medulla 宿主加载，不能通过 `dotnet run` 独立启动。
|
||
|
||
## 当前已接入能力
|
||
|
||
| 模块 | 当前代码能力 |
|
||
| --- | --- |
|
||
| 单车运动 | 直线、圆弧、S 型轨迹，前进、蟹行和原地旋转 |
|
||
| 底盘命令 | `SendMotion`、`SendXYThSpeed` 和虚拟阿克曼测试后端 |
|
||
| 模式切换 | 正常、蟹行、自转模式；切换时先停车、预转舵轮并等待到位 |
|
||
| 跟踪控制 | 旧版终点/直线/蟹行跟踪；新版 Stanley 横向控制、PID 纵向控制、前后 GCP 分配、轨迹偏离保护和终点状态判定 |
|
||
| 状态估计 | Detour 位姿与差分速度；新版实验可保留 Detour 位姿并用舵轮反馈解算、低通滤波后的车体纵向速度替代其差分纵向速度 |
|
||
| 夹臂 | 左右夹臂速度命令、位置反馈、软限位、驱动报警、实体/虚拟遥控和目标位置动作 |
|
||
| MCU 通信 | 串口桥打开、复位、版本/状态查询、数字 IO、CAN/串口同步收发和异步回调 |
|
||
| 驱动与反馈 | 8 个驱动电机和 4 个舵轮的命令、速度/位置/舵角反馈及远程帧状态 |
|
||
| 车辆状态 | 急停、启停、抱闸、灯光、电池 SOC/SOH 和驱动使能状态 |
|
||
| 诊断 | CAN 轮速事件与周期快照 CSV、轨迹实验 CSV、控制命令和 Detour 位姿记录 |
|
||
|
||
以上表示代码和测试入口已经存在，不等同于所有工况均已完成实车验收。
|
||
|
||
## 软件架构
|
||
|
||
```text
|
||
Clumsy 宿主
|
||
│
|
||
▼
|
||
MultiWheelC ───────────────┐
|
||
│ │
|
||
▼ │ 实验 CSV
|
||
Shared / CommonUsage ├──────────► data_process
|
||
│ │
|
||
▼ │
|
||
Medulla 宿主 │
|
||
│ │
|
||
▼ │
|
||
MedullaAdapter │
|
||
│ P/Invoke │
|
||
▼ │
|
||
mcu_serial_bridge.dll │
|
||
│ │
|
||
▼ │
|
||
MCU ─► CAN / Serial / IO ──┘
|
||
```
|
||
|
||
`MultiWheelC` 与 `MedullaAdapter` 生成插件类库，需由对应宿主加载。`CommonUsage` 是独立底盘库，不反向依赖 `Shared`、M 层或 C 层。
|
||
|
||
## 坐标系与单位
|
||
|
||
- `Shared` 统一使用 SI 单位：m、m/s、rad、rad/s。
|
||
- 车体坐标系：X 向前、Y 向左、逆时针为正。
|
||
- 旧接口单位只在边界处转换。
|
||
- 角度归一化、最短角差和度弧度转换统一使用 `Shared/Mathematics/AngleMath.cs`。
|
||
- 弧度归一化范围为 `[-π, π)`，度归一化范围为 `[-180°, 180°)`。
|
||
- 车辆航向可用圆周最短角差；受 `[-120°, 120°]` 限制的机械舵角误差必须直接使用目标值减实际值。
|
||
|
||
## 目录说明
|
||
|
||
```text
|
||
MyParking/
|
||
├── ParkingRobot.sln # 根解决方案（CommonUsage / M / C）
|
||
├── build-and-package.ps1 # 官方构建与 M/C 打包脚本
|
||
├── AGENTS.md # 协作与代码规范
|
||
├── MultiWheelC/ # C 层动作、跟踪、测试和实验记录
|
||
├── MedullaAdapter/ # M 层 MCU、CAN、轮组、夹臂、遥控和报警
|
||
├── Shared/ # 共享模型、数学方法和底盘适配
|
||
├── CommonUsage-MultiVehicleSync/
|
||
│ └── commonusage/ # CommonUsage 公共底盘库源码
|
||
├── ref/ # 构建生成的 CommonUsage.dll（勿手工覆盖）
|
||
├── data_process/
|
||
│ ├── plot_new_controller_experiment.py # 新版控制器实验六子图工具
|
||
│ ├── 新版控制器轨迹测试处理/ # 新版绘图工具的 Python 依赖
|
||
│ ├── 旧版控制器轨迹测试处理/ # 旧版轨迹对比、误差和响应绘图
|
||
│ └── 电机响应处理/ # 舵轮响应快照分析
|
||
├── docs/
|
||
│ ├── SteeringConstraintDesign.md # 舵轮限位设计讨论
|
||
│ ├── chassis参考.json # 底盘参数样例
|
||
│ ├── 测试方案.txt # 单车轨迹实验方案
|
||
│ └── 记录.txt # 项目调试记录
|
||
└── output/ # 打包输出（gitignore）
|
||
├── M/ # MedullaAdapter.dll + CommonUsage.dll
|
||
└── C/ # MultiWheelC.dll + CommonUsage.dll
|
||
```
|
||
|
||
根目录 `ParkingRobot.sln` 包含 `CommonUsage`、`MedullaAdapter` 和 `MultiWheelC`，便于在 Visual Studio 中打开整仓。`Shared` 无独立项目，由 M/C 编译引入。部署打包仍以 `build-and-package.ps1` 为准。
|
||
|
||
## 开发环境与依赖
|
||
|
||
- Windows 开发 / 实机运行环境；
|
||
- Visual Studio 2022，或支持 .NET 8.0 和 .NET Standard 2.0 的 .NET SDK；
|
||
- Python 环境，用于可选的实验数据绘图；
|
||
- Clumsy / Medulla 内部框架程序集，位于各项目的 `ref` 目录；
|
||
- 实机所需的 `mcu_serial_bridge.dll`，当前仓库中未包含该文件；
|
||
- 能够加载 `MultiWheelC.dll` 和 `MedullaAdapter.dll` 的匹配版本宿主程序，当前仓库中未包含宿主。
|
||
|
||
主要依赖：
|
||
|
||
- `MultiWheelC`（`netstandard2.0`）：`Newtonsoft.Json 13.0.3`、`System.Numerics.Vectors 4.6.1`；
|
||
- `MedullaAdapter`（`net8.0`）：无 NuGet PackageReference，依赖本地 `ref` 程序集；
|
||
- `CommonUsage`（`netstandard2.0`）：`MQTTnet 4.3.7.1207`、`Newtonsoft.Json 13.0.3` 等；
|
||
- `data_process`：见各子目录 `requirements.txt`。
|
||
|
||
## 编译与打包
|
||
|
||
在 `MyParking` 目录执行官方脚本（默认 Debug）：
|
||
|
||
```powershell
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-and-package.ps1
|
||
```
|
||
|
||
Release 构建：
|
||
|
||
```powershell
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-and-package.ps1 -Configuration Release
|
||
```
|
||
|
||
脚本流程：
|
||
|
||
1. 构建 `CommonUsage`，并将 `CommonUsage.dll` 复制到根目录 `ref/`；
|
||
2. 构建 `MedullaAdapter` 和 `MultiWheelC`；
|
||
3. 将 M/C 产物分别打包到 `output/M` 和 `output/C`，两边使用同一份 `CommonUsage.dll`。
|
||
|
||
首次克隆或依赖变更后，如遇 `--no-restore` 失败，可先恢复依赖再打包：
|
||
|
||
```powershell
|
||
dotnet restore CommonUsage-MultiVehicleSync\commonusage\CommonUsage.csproj
|
||
dotnet restore MedullaAdapter\MedullaAdapter.csproj
|
||
dotnet restore MultiWheelC\MultiWheelC.csproj
|
||
```
|
||
|
||
主要中间输出：
|
||
|
||
```text
|
||
MedullaAdapter/build/Medulla/plugins/MedullaAdapter.dll
|
||
MultiWheelC/build/Clumsy/MultiWheelC.dll
|
||
```
|
||
|
||
不要直接编辑 `bin`、`obj`、`build`、`output` 中的产物，也不要手工覆盖 `ref/CommonUsage.dll`。
|
||
|
||
## 实车运行与 MCU 配置
|
||
|
||
实车插件不能通过 `dotnet run` 独立启动，需要由匹配版本的 Clumsy / Medulla 宿主分别加载：
|
||
|
||
```text
|
||
output/C/MultiWheelC.dll
|
||
output/M/MedullaAdapter.dll
|
||
```
|
||
|
||
宿主版本、部署目录和完整启动步骤尚未随仓库提供，待补充。
|
||
|
||
当前源码中的 MCU 默认参数：
|
||
|
||
| 参数 | 默认值 |
|
||
| --- | --- |
|
||
| MCU 端口 | `COM4` |
|
||
| MCU 连接波特率 | `1000000` |
|
||
| CAN | 1 路，`500000 bit/s`，重试时间 `10 ms` |
|
||
| 串口 | 3 路，`9600 bit/s`，接收帧时间 `10 ms` |
|
||
| 电池通信端口索引 | `3` |
|
||
| 遥控自转最大角速度 | `30 deg/s` |
|
||
| 轮速诊断目录 | `logs\wheel-speed` |
|
||
|
||
`docs/chassis参考.json` 是底盘参数样例；源码中尚未发现自动加载该文件的入口，实车参数仍应以宿主实际配置为准。
|
||
|
||
实机测试前必须确认端口、车号、舵轮零位与限位、速度单位、驱动方向、夹臂限位和急停链路。建议先架空驱动轮或在隔离区域低速、短距离测试，并保留独立可靠的物理急停，不能只依赖软件停车。
|
||
|
||
## 单车测试入口
|
||
|
||
`MultiWheelC/Experiments` 当前启用以下宿主测试入口：
|
||
|
||
- `准备：四个舵轮与车头方向一致`
|
||
- `SendMotion：连续前进4m`
|
||
- `SendXYThSpeed：输入角度原地自转`
|
||
- `SendMotion：左转90°半径2m圆弧`
|
||
- `SendMotion：蟹行直线4m`
|
||
- `SendMotion：蟹行左转90°半径2m圆弧`
|
||
- `SendMotion：4m S型曲线`
|
||
- `新版控制器：4m直线轨迹跟踪`
|
||
- `新版控制器：直线-左半圆-直线轨迹跟踪`
|
||
- `新版控制器：直线-圆弧-折线组合测试`
|
||
|
||
这些测试由 Clumsy 宿主的测试界面执行，并不是 `dotnet test` 自动化测试。运动测试会按配置记录实验编号、参考轨迹、Detour 位姿、轮速解算速度和控制命令。`MultiWheelC/Experiments/ClampTests.cs` 中的夹臂测试目前整段注释，不会注册到宿主。
|
||
|
||
## 实验数据分析
|
||
|
||
轨迹记录器默认把 CSV 保存到宿主程序目录下的：
|
||
|
||
```text
|
||
TrackingExperiments/
|
||
```
|
||
|
||
Medulla 的轮速诊断可通过 `StartWheelSpeedDiagnostic` / `StopWheelSpeedDiagnostic` 操作按钮控制，默认输出到：
|
||
|
||
```text
|
||
logs/wheel-speed/
|
||
```
|
||
|
||
### 新版控制器轨迹处理
|
||
|
||
```powershell
|
||
python -m pip install -r data_process\新版控制器轨迹测试处理\requirements.txt
|
||
python data_process\plot_new_controller_experiment.py "路径\实验1.csv" "路径\实验2.csv" --output-dir "路径\plots"
|
||
```
|
||
|
||
该工具为每份新版控制器 CSV 生成一张六子图总图，包含轨迹、横向/航向误差、速度和前后 GCP/四舵轮转角。省略 CSV 参数时，它只扫描 `data_process` 根目录及其 `data` 子目录。
|
||
|
||
### 旧版控制器轨迹处理
|
||
|
||
```powershell
|
||
python -m pip install -r data_process\旧版控制器轨迹测试处理\requirements.txt
|
||
python data_process\旧版控制器轨迹测试处理\run_all_plots.py "路径\实验1.csv" "路径\实验2.csv" --output-dir "路径\plots"
|
||
```
|
||
|
||
旧版工具默认重采样频率为 `20 Hz`，滤波窗口为 `0.55 s`，可通过 `--frequency` 和 `--window` 调整。
|
||
|
||
### 电机响应处理
|
||
|
||
```powershell
|
||
python -m pip install -r data_process\电机响应处理\requirements.txt
|
||
python data_process\电机响应处理\plot_steering_response.py
|
||
```
|
||
|
||
默认读取 `logs\wheel-speed` 中最新的 `*_snapshot.csv`。详见 [`data_process/电机响应处理/README.md`](data_process/电机响应处理/README.md)。
|
||
|
||
## 尚未完成或需要继续验证
|
||
|
||
- 雷达点云、轮胎识别、自动钻车、车辆释放和完整停车作业状态机；
|
||
- 当前运动和夹臂功能的完整实车验收、故障注入及长期稳定性测试；
|
||
- 舵轮软限位预测和自动车身重定向；当前仅有设计文档 [`docs/SteeringConstraintDesign.md`](docs/SteeringConstraintDesign.md)；
|
||
- 自动化单元测试和持续集成；
|
||
- 多车通信、编队、同步和安全降级；`FleetKinematics.cs` 当前仅为占位；
|
||
- 宿主版本、插件部署目录、配置文件位置和发布流程。
|
||
|
||
## 参与开发
|
||
|
||
1. 当前改动优先服务于单车闭环、停车功能和跟踪质量，不提前启用多车代码；
|
||
2. 保持 `CommonUsage`、`Shared`、`MedullaAdapter`、`MultiWheelC` 的模块边界；
|
||
3. 新增参数时注明坐标系、单位、默认值、车型和安全范围；
|
||
4. 修改相关项目后运行 `build-and-package.ps1`，并确认 M/C 部署包使用同一份 `CommonUsage.dll`；
|
||
5. 未经明确要求，不改变速度或舵角符号、CAN ID、遥控器映射、机械限位和模式切换策略；
|
||
6. 分支、评审和发布流程待团队补充。
|
||
|
||
更细的协作约定见 [`AGENTS.md`](AGENTS.md)。
|
||
|
||
## 许可证
|
||
|
||
仓库中暂未提供许可证文件。使用和分发范围请遵循公司内部规定。
|