First_Dev_Dept/ParkingRobot
10
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

同步中英文README与当前工程结构，并整理文档目录与构建忽略规则

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
yuxiang.shen
2026-08-04 11:31:14 +08:00
co-authored by Cursor
parent 097853234f
commit 31ec941b07
9 changed files with 276 additions and 338 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+96 -94
View File
@@ -8,10 +8,10 @@
1. 先实现单台停车机器人小车的基本功能；
2. 在单车闭环稳定后逐步增加停车作业功能；
3. 基于仿真、台架和实车数据优化轨迹跟踪方法；
3. 基于台架和实车数据优化轨迹跟踪方法；
4. 最后再考虑多车通信、编队和协同控制。
当前工作仍以**单车**为主，已经从基础框架搭建进入底盘联调、功能补充和跟踪实验阶段。多车配置仍位于 `PilotConfig.cs` 的 `#if false` 区域，`Shared/FleetKinematics.cs` 仍是占位文件，不能视为多车能力已经实现。
当前工作仍以**单车**为主，处于底盘联调、功能补充和跟踪实验阶段。多车配置位于 `MultiWheelC/PilotConfig.cs` 的 `#if false` 区域，`Shared/Fleet/FleetKinematics.cs` 仍是占位文件，不能视为多车能力已经实现。
| 阶段 | 当前状态 | 说明 |
| --- | --- | --- |
@@ -22,18 +22,17 @@
## 项目简介
MyParking 是一个面向多轮停车机器人底盘的 C# 工程，覆盖上层运动动作、共享运动学、底层硬件适配、离线 Web 仿真和实验数据分析。
MyParking 是一个面向多轮停车机器人底盘的 C# 工程，覆盖上层运动动作、共享运动学、底层硬件适配和实验数据分析。
核心代码分为：
核心模块：
- `ClumsyPilot`：Clumsy 上层动作、轨迹跟踪和人工测试；
- `MedullaAdapter`：Medulla 下层 MCU、CAN、串口、轮组、夹臂、遥控和报警适配；
- `Shared`：统一的二维坐标、底盘命令、坐标变换和多轮底盘适配；
- `MultiWheelC`：Clumsy 上层（C 层）动作、轨迹跟踪、人工测试和实验记录；
- `MedullaAdapter`：Medulla 下层（M 层）MCU、CAN、串口、轮组、夹臂、遥控和报警适配；
- `Shared`：M/C 共享的二维坐标、底盘命令、坐标变换和多轮底盘适配（无独立 `.csproj`，由两端编译引入）；
- `CommonUsage-MultiVehicleSync/commonusage`：仓库内的 `CommonUsage` 底盘公共库源码；
- `Simulation`：基于 ASP.NET Core 的单车 Web 仿真器；
- `data_process`：轨迹实验 CSV 的 Python 分析工具。
- `data_process`：轨迹实验与舵轮响应的 Python 分析工具。
仓库中没有 ROS/ROS 2 或 Docker 配置。
仓库中没有 ROS/ROS 2、Docker 或 Web 仿真项目。插件由 Clumsy / Medulla 宿主加载，不能通过 `dotnet run` 独立启动。
## 当前已接入能力
@@ -48,7 +47,6 @@ MyParking 是一个面向多轮停车机器人底盘的 C# 工程，覆盖上层
| 驱动与反馈 | 8 个驱动电机和 4 个舵轮的命令、速度/位置/舵角反馈及远程帧状态 |
| 车辆状态 | 急停、启停、抱闸、灯光、电池 SOC/SOH 和驱动使能状态 |
| 诊断 | CAN 轮速事件与周期快照 CSV、轨迹实验 CSV、控制命令和 Detour 位姿记录 |
| 仿真 | 浏览器二维车辆显示、模式按钮、手动控制、车辆配置、复位和 REST API |
以上表示代码和测试入口已经存在，不等同于所有工况均已完成实车验收。
@@ -58,7 +56,7 @@ MyParking 是一个面向多轮停车机器人底盘的 C# 工程，覆盖上层
Clumsy 宿主
│
▼
ClumsyPilot ───────────────┐
MultiWheelC ───────────────┐
│ │
▼ │ 实验 CSV
Shared / CommonUsage ├──────────► data_process
@@ -74,111 +72,109 @@ mcu_serial_bridge.dll │
│ │
▼ │
MCU ─► CAN / Serial / IO ──┘
Simulation ─► Shared 数据类型 ─► 浏览器仿真界面
```
`ClumsyPilot` 和 `MedullaAdapter` 生成插件类库，需要由对应宿主加载；`Simulation` 是可以独立启动的 ASP.NET Core Web 项目。
`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
├── ClumsyPilot/ # 上层动作、跟踪、测试和实验记录
├── MedullaAdapter/ # MCU、CAN、轮组、夹臂、遥控和报警
├── Shared/ # 共享命令、坐标变换和底盘适配
├── build-and-package.ps1 # 官方构建与 M/C 打包脚本
├── AGENTS.md # 协作与代码规范
├── MultiWheelC/ # C 层动作、跟踪、测试和实验记录
├── MedullaAdapter/ # M 层 MCU、CAN、轮组、夹臂、遥控和报警
├── Shared/ # 共享模型、数学方法和底盘适配
├── CommonUsage-MultiVehicleSync/
│ └── commonusage/ # CommonUsage 公共底盘库源码
├── Simulation/ # .NET 8 Web 仿真器
│ ├── Commands/ # 可由特性自动发现的仿真动作
│ ├── Core/ # 仿真车辆、舵轮、时钟和世界
│ ├── Models/ # Web API DTO
│ └── wwwroot/ # 浏览器界面
├── data_process/ # Python 实验绘图脚本
├── ref/ # 两个插件共同使用的 CommonUsage.dll
├── 测试方案.txt # 单车轨迹实验方案
├── 记录.txt # 项目调试记录
└── 电机记录.txt # 电机调试记录
├── ref/ # 构建生成的 CommonUsage.dll（勿手工覆盖）
├── data_process/
│ ├── 轨迹测试处理/ # 轨迹对比、误差、速度与角速度绘图
│ └── 电机响应处理/ # 舵轮响应快照分析
├── docs/
│ ├── SteeringConstraintDesign.md # 舵轮限位设计讨论
│ ├── chassis参考.json # 底盘参数样例
│ ├── 测试方案.txt # 单车轨迹实验方案
│ └── 记录.txt # 项目调试记录
└── output/ # 打包输出（gitignore）
├── M/ # MedullaAdapter.dll + CommonUsage.dll
└── C/ # MultiWheelC.dll + CommonUsage.dll
```
根目录的 `ParkingRobot.sln` 当前只包含 `ClumsyPilot` 和 `MedullaAdapter`；`CommonUsage` 与 `Simulation` 需要分别构建。
仓库内没有根级 `ParkingRobot.sln`。唯一 solution 文件位于 `CommonUsage-MultiVehicleSync/commonusage/CommonUsageSln.sln`。
## 开发环境与依赖
- Windows 开发/实机运行环境；
- Windows 开发 / 实机运行环境；
- Visual Studio 2022，或支持 .NET 8.0 和 .NET Standard 2.0 的 .NET SDK；
- Python 环境，用于可选的实验数据绘图；
- Clumsy/Medulla 内部框架程序集，位于各项目的 `ref` 目录；
- Clumsy / Medulla 内部框架程序集，位于各项目的 `ref` 目录；
- 实机所需的 `mcu_serial_bridge.dll`，当前仓库中未包含该文件；
- 能够加载 `ClumsyPilot.dll` 和 `MedullaAdapter.dll` 的匹配版本宿主程序，当前仓库中未包含宿主。
- 能够加载 `MultiWheelC.dll` 和 `MedullaAdapter.dll` 的匹配版本宿主程序，当前仓库中未包含宿主。
主要 NuGet/Python 依赖：
主要依赖：
- `ClumsyPilot`：`Newtonsoft.Json 13.0.3`、`System.Numerics.Vectors 4.6.1`；
- `CommonUsage`：`MQTTnet 4.3.7.1207`、`Newtonsoft.Json 13.0.3` 等；
- `data_process`：NumPy、pandas、Matplotlib、SciPy。
- `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`。
## 编译
## 编译与打包
### 1. 构建 CommonUsage
在 `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 build CommonUsage-MultiVehicleSync\commonusage\CommonUsage.csproj -c Debug
dotnet restore MedullaAdapter\MedullaAdapter.csproj
dotnet restore MultiWheelC\MultiWheelC.csproj
```
该项目的构建目标会把生成的 `CommonUsage.dll` 复制到根目录 `ref`。
### 2. 构建实车插件
```powershell
dotnet restore ParkingRobot.sln
dotnet build ParkingRobot.sln -c Debug
```
主要输出：
主要中间输出：
```text
ClumsyPilot/build/Clumsy/ClumsyPilot.dll
MedullaAdapter/build/Medulla/plugins/MedullaAdapter.dll
MultiWheelC/build/Clumsy/MultiWheelC.dll
```
### 3. 构建 Web 仿真器
```powershell
dotnet restore Simulation\MyParking.Simulation.csproj
dotnet build Simulation\MyParking.Simulation.csproj -c Debug
```
## 启动 Web 仿真
```powershell
dotnet run --project Simulation\MyParking.Simulation.csproj --launch-profile http
```
浏览器访问：
```text
http://localhost:5203
```
仿真界面提供正常、左蟹行、右蟹行、自转、前进、后退、左转、右转、停止和复位动作，并可修改车辆布局及手动控制输入。主要 API 包括：
- `GET /api/vehicles`
- `GET /api/actions`
- `GET/POST /api/configuration`
- `POST /api/vehicles/{vehicleId}/commands/{command}`
- `POST /api/vehicles/{vehicleId}/manual-control`
- `POST /api/reset`
`Simulation/Commands/MySimulationTests.cs` 给出了自定义仿真动作示例；为静态方法添加 `SimulationAction` 特性后，调度器会自动发现并在网页生成对应动作。
不要直接编辑 `bin`、`obj`、`build`、`output` 中的产物，也不要手工覆盖 `ref/CommonUsage.dll`。
## 实车运行与 MCU 配置
实车插件不能通过 `dotnet run` 独立启动。需要由匹配版本的 Clumsy/Medulla 宿主加载两个 DLL。宿主版本、部署目录和完整启动步骤尚未随仓库提供，待补充。
实车插件不能通过 `dotnet run` 独立启动，需要由匹配版本的 Clumsy / Medulla 宿主分别加载：
```text
output/C/MultiWheelC.dll
output/M/MedullaAdapter.dll
```
宿主版本、部署目录和完整启动步骤尚未随仓库提供，待补充。
当前源码中的 MCU 默认参数：
@@ -192,13 +188,13 @@ http://localhost:5203
| 自转最大角速度 | `30 deg/s` |
| 轮速诊断目录 | `logs\wheel-speed` |
当前工作区存在 `chassis.json` 底盘参数样例，但源码中尚未发现自动加载该文件的入口；实车参数仍应以宿主实际配置为准。
`docs/chassis参考.json` 是底盘参数样例；源码中尚未发现自动加载该文件的入口，实车参数仍应以宿主实际配置为准。
实机测试前必须确认端口、车号、舵轮零位与限位、速度单位、驱动方向、夹臂限位和急停链路。建议先架空驱动轮或在隔离区域低速测试，并保留独立可靠的物理急停，不能只依赖软件停车。
实机测试前必须确认端口、车号、舵轮零位与限位、速度单位、驱动方向、夹臂限位和急停链路。建议先架空驱动轮或在隔离区域低速、短距离测试，并保留独立可靠的物理急停，不能只依赖软件停车。
## 单车测试入口
`ClumsyPilot/MovementTests.cs` 当前注册：
`MultiWheelC/MovementTests.cs` 当前注册：
- `准备：四个舵轮与车头方向一致`
- `SendMotion：连续前进4m`
@@ -227,25 +223,29 @@ Medulla 的轮速诊断可通过 `StartWheelSpeedDiagnostic` / `StopWheelSpeedDi
logs/wheel-speed/
```
在自行管理的 Python 环境中安装依赖：
### 轨迹测试处理
```powershell
python -m pip install -r data_process\requirements.txt
python -m pip install -r data_process\轨迹测试处理\requirements.txt
python data_process\轨迹测试处理\run_all_plots.py "路径\实验1.csv" "路径\实验2.csv" --output-dir "路径\plots"
```
对一份或多份轨迹 CSV 同时生成轨迹对比、跟踪误差、速度响应和角速度命令图：
默认重采样频率为 `20 Hz`，滤波窗口为 `0.55 s`，可通过 `--frequency` 和 `--window` 调整。
### 电机响应处理
```powershell
python data_process\run_all_plots.py "路径\实验1.csv" "路径\实验2.csv" --output-dir "路径\plots"
python -m pip install -r data_process\电机响应处理\requirements.txt
python data_process\电机响应处理\plot_steering_response.py
```
不传 CSV 路径时，脚本会查找 `data_process` 目录中的 CSV。默认重采样频率为 `20 Hz`，滤波窗口为 `0.55 s`，可通过 `--frequency` 和 `--window` 调整。
默认读取 `logs\wheel-speed` 中最新的 `*_snapshot.csv`。详见 [`data_process/电机响应处理/README.md`](data_process/电机响应处理/README.md)。
## 尚未完成或需要继续验证
- 雷达点云、轮胎识别、自动钻车、车辆释放和完整停车作业状态机；
- 当前运动和夹臂功能的完整实车验收、故障注入及长期稳定性测试；
- 舵轮软限位预测和自动车身重定向；`SteeringConstraintManager.cs` 当前主要是设计记录；
- 舵轮软限位预测和自动车身重定向；当前仅有设计文档 [`docs/SteeringConstraintDesign.md`](docs/SteeringConstraintDesign.md)；
- 自动化单元测试和持续集成；
- 多车通信、编队、同步和安全降级；`FleetKinematics.cs` 当前仅为占位；
- 宿主版本、插件部署目录、配置文件位置和发布流程。
@@ -253,12 +253,14 @@ python data_process\run_all_plots.py "路径\实验1.csv" "路径\实验2.csv" -
## 参与开发
1. 当前改动优先服务于单车闭环、停车功能和跟踪质量，不提前启用多车代码；
2. 保持上层动作、共享运动学、底层硬件协议和仿真模块的边界；
2. 保持 `CommonUsage`、`Shared`、`MedullaAdapter`、`MultiWheelC` 的模块边界；
3. 新增参数时注明坐标系、单位、默认值、车型和安全范围；
4. 提交前构建受影响的项目，并记录仿真、台架或实车验证条件；
5. 修改 `CommonUsage` 后同步更新根目录 `ref/CommonUsage.dll`；
4. 修改相关项目后运行 `build-and-package.ps1`，并确认 M/C 部署包使用同一份 `CommonUsage.dll`；
5. 未经明确要求，不改变速度或舵角符号、CAN ID、遥控器映射、机械限位和模式切换策略；
6. 分支、评审和发布流程待团队补充。
更细的协作约定见 [`AGENTS.md`](AGENTS.md)。
## 许可证
仓库中暂未提供许可证文件。使用和分发范围请遵循公司内部规定。