限制单车自转角速度并更新底盘配置与项目文档

2026-07-31 15:34:11 +08:00
parent c1fe73caec
commit 5da31a6c40
12 changed files with 453 additions and 196 deletions
@@ -2,167 +2,262 @@

 [简体中文](README.md) | [English](README_en.md)

-## 重写说明
+## 重写路线与当前状态

-本仓库是停车机器人控制软件的重写版本。当前不以一次性恢复全部旧功能为目标，而是按以下顺序重新建立可验证、可维护的能力：
+本仓库是停车机器人控制软件的重写版本，研发顺序保持为：

 1. 先实现单台停车机器人小车的基本功能；
 2. 在单车闭环稳定后逐步增加停车作业功能；
-3. 再优化轨迹跟踪方法及其稳定性；
-4. 最后评估并实现多车通信、编队与协同控制。
+3. 基于仿真、台架和实车数据优化轨迹跟踪方法；
+4. 最后再考虑多车通信、编队和协同控制。

-**当前处于第 1 阶段，开发重点是单车基本功能。** `PilotConfig.cs` 中由 `#if false` 包围的钻车、夹抱和多车参数仅作为历史代码或设计参考，不参与当前编译，也不表示相关功能已经可用。
+当前工作仍以**单车**为主，已经从基础框架搭建进入底盘联调、功能补充和跟踪实验阶段。多车配置仍位于 `PilotConfig.cs` 的 `#if false` 区域，`Shared/FleetKinematics.cs` 仍是占位文件，不能视为多车能力已经实现。
+
+| 阶段 | 当前状态 | 说明 |
+| --- | --- | --- |
+| 1. 单车基本功能 | 联调中 | 已接入运动控制、MCU 通信、轮组反馈、急停 IO、电池、灯光、遥控和诊断代码，仍需持续实车验证 |
+| 2. 增加停车功能 | 部分开展 | 已提供夹臂控制、限位、报警和测试入口；轮胎识别、钻车和完整停车流程尚未实现 |
+| 3. 优化跟踪方法 | 已启动 | 已加入直线、圆弧、S 型、蟹行测试、实验 CSV 记录和 Python 绘图工具 |
+| 4. 多车场景 | 暂不实施 | 多车参数和预研内容未参与当前编译，当前版本不提供多车联动 |

 ## 项目简介

-MyParking 是一个面向多轮停车机器人底盘的 C# 控制工程。仓库包含上层运动控制插件 `ClumsyPilot` 和下层硬件适配插件 `MedullaAdapter`，用于建立从单车运动指令到 MCU 串口桥、CAN/串口端口的基础链路。
+MyParking 是一个面向多轮停车机器人底盘的 C# 工程，覆盖上层运动动作、共享运动学、底层硬件适配、离线 Web 仿真和实验数据分析。

-当前代码已经包含单车终点直线跟踪、前进/后退测试、PID 原地旋转、停止保护，以及 MCU 串口桥的托管封装和初始化流程。完整停车作业所需的驱动器协议、反馈解析、安全报警、夹抱执行和感知流程仍待实现或接入。
+核心代码分为：

-## 当前范围
+- `ClumsyPilot`：Clumsy 上层动作、轨迹跟踪和人工测试；
+- `MedullaAdapter`：Medulla 下层 MCU、CAN、串口、轮组、夹臂、遥控和报警适配；
+- `Shared`：统一的二维坐标、底盘命令、坐标变换和多轮底盘适配；
+- `CommonUsage-MultiVehicleSync/commonusage`：仓库内的 `CommonUsage` 底盘公共库源码；
+- `Simulation`：基于 ASP.NET Core 的单车 Web 仿真器；
+- `data_process`：轨迹实验 CSV 的 Python 分析工具。

-| 范围 | 状态 | 说明 |
-| --- | --- | --- |
-| 单车几何控制器 | 已接入 | 根据公共配置创建 `MultiWheelGeometricController` |
-| 单车终点跟踪 | 已实现基础版本 | 使用直线路径，可测试前进和后退，到达或退出时发送零速度 |
-| 单车原地旋转 | 已实现基础版本 | 读取定位朝向并通过 PID 输出角速度，到位后停车 |
-| MCU 串口桥 | 已封装 | 支持打开、复位、状态/版本查询、端口配置、IO、串口与 CAN 收发/回调 |
-| MCU 初始化 | 已实现基础流程 | 默认使用 `COM4`、1 路 CAN 和 3 路串口配置 |
-| 驱动反馈与安全链路 | 待实现 | 驱动协议、轮速/舵角反馈、电池、急停和报警例程目前没有实际逻辑 |
-| 停车作业功能 | 待实现 | 钻车、轮胎识别、夹抱等旧参数当前被条件编译禁用 |
-| 多车能力 | 暂不实施 | 多车参数当前被条件编译禁用，待单车及跟踪能力稳定后再设计 |
+仓库中没有 ROS/ROS 2 或 Docker 配置。

-## 软件结构
+## 当前已接入能力
+
+| 模块 | 当前代码能力 |
+| --- | --- |
+| 单车运动 | 直线、圆弧、S 型轨迹，前进、蟹行和原地旋转 |
+| 底盘命令 | `SendMotion`、`SendXYThSpeed` 和虚拟阿克曼测试后端 |
+| 模式切换 | 正常、蟹行、自转模式；切换时先停车、预转舵轮并等待到位 |
+| 跟踪控制 | 终点跟踪、直线跟踪、基于 Detour 的直线跟踪和蟹行运动坐标系跟踪 |
+| 夹臂 | 左右夹臂速度命令、位置反馈、软限位、驱动报警、实体/虚拟遥控和目标位置动作 |
+| MCU 通信 | 串口桥打开、复位、版本/状态查询、数字 IO、CAN/串口同步收发和异步回调 |
+| 驱动与反馈 | 8 个驱动电机和 4 个舵轮的命令、速度/位置/舵角反馈及远程帧状态 |
+| 车辆状态 | 急停、启停、抱闸、灯光、电池 SOC/SOH 和驱动使能状态 |
+| 诊断 | CAN 轮速事件与周期快照 CSV、轨迹实验 CSV、控制命令和 Detour 位姿记录 |
+| 仿真 | 浏览器二维车辆显示、模式按钮、手动控制、车辆配置、复位和 REST API |
+
+以上表示代码和测试入口已经存在，不等同于所有工况均已完成实车验收。
+
+## 软件架构

 ```text
-上层 Clumsy 运行环境
-        │
-        ▼
-ClumsyPilot：单车动作、轨迹跟踪、测试入口
-        │ 底盘速度指令
-        ▼
-Medulla 运行环境 / MedullaAdapter
-        │ P/Invoke
-        ▼
-mcu_serial_bridge.dll → MCU → CAN / Serial / Digital IO
+Clumsy 宿主
+    │
+    ▼
+ClumsyPilot ───────────────┐
+    │                      │
+    ▼                      │ 实验 CSV
+Shared / CommonUsage       ├──────────► data_process
+    │                      │
+    ▼                      │
+Medulla 宿主               │
+    │                      │
+    ▼                      │
+MedullaAdapter             │
+    │ P/Invoke             │
+    ▼                      │
+mcu_serial_bridge.dll      │
+    │                      │
+    ▼                      │
+MCU ─► CAN / Serial / IO ──┘
+
+Simulation ─► Shared 数据类型 ─► 浏览器仿真界面
 ```

-两个工程均生成类库，仓库中没有独立的可执行入口：
-
- `ClumsyPilot`：上层单车运动控制，目标框架为 .NET Standard 2.0；
- `MedullaAdapter`：下层 MCU 和底盘适配，目标框架为 .NET 8.0。
+`ClumsyPilot` 和 `MedullaAdapter` 生成插件类库，需要由对应宿主加载；`Simulation` 是可以独立启动的 ASP.NET Core Web 项目。

 ## 目录说明

 ```text
 MyParking/
-├── ParkingRobot.sln                 # Visual Studio 解决方案
-├── ClumsyPilot/
-│   ├── AGV.cs                       # 上层 AGV 接口
-│   ├── ChassisController.cs         # 单车几何控制器配置
-│   ├── Movements.cs                 # 终点跟踪、等待、原地旋转动作
-│   ├── MovementTests.cs             # Clumsy 环境中的人工动作测试
-│   ├── PilotConfig.cs               # 当前单车配置及禁用的历史/预研配置
-│   ├── PilotDefinition.cs           # 车型尺寸和车号定义
-│   └── ref/                          # 上层框架引用程序集
-└── MedullaAdapter/
-    ├── DiverCartDefinition.cs       # 车型 IO、监控字段及 MCU 初始化
-    ├── MCUSerialBridgeCLR.cs        # 原生 MCU 串口桥的 C# 封装
-    ├── MCUSerialBridgeError.cs      # 错误码与诊断说明
-    ├── AlarmRoutine.cs              # 安全报警例程占位
-    ├── MCURoutine.cs                # MCU IO/反馈例程占位
-    ├── MotorRoutine.cs              # 电机控制例程占位
-    ├── Remote.cs                    # 遥控例程占位
-    └── ref/                          # 下层框架引用程序集
+├── ParkingRobot.sln
+├── ClumsyPilot/                     # 上层动作、跟踪、测试和实验记录
+├── MedullaAdapter/                  # 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                     # 电机调试记录
 ```

+根目录的 `ParkingRobot.sln` 当前只包含 `ClumsyPilot` 和 `MedullaAdapter`；`CommonUsage` 与 `Simulation` 需要分别构建。
+
 ## 开发环境与依赖

- Windows 开发/运行环境；当前硬件接入使用 COM 端口和原生 DLL；
- Visual Studio 2022，或能够构建 .NET 8.0 与 .NET Standard 2.0 项目的 .NET SDK；
- NuGet 包：`Newtonsoft.Json 13.0.3`、`System.Numerics.Vectors 4.6.1`；
- `ClumsyPilot/ref` 和 `MedullaAdapter/ref` 中的内部框架程序集；
- 实机运行所需的 `mcu_serial_bridge.dll`；该文件当前未包含在仓库中；
- 能够加载 `ClumsyPilot.dll` 与 `MedullaAdapter.dll` 的 Clumsy/Medulla 宿主环境；宿主程序和部署配置当前未包含在仓库中。
+- Windows 开发/实机运行环境；
+- Visual Studio 2022，或支持 .NET 8.0 和 .NET Standard 2.0 的 .NET SDK；
+- Python 环境，用于可选的实验数据绘图；
+- Clumsy/Medulla 内部框架程序集，位于各项目的 `ref` 目录；
+- 实机所需的 `mcu_serial_bridge.dll`，当前仓库中未包含该文件；
+- 能够加载 `ClumsyPilot.dll` 和 `MedullaAdapter.dll` 的匹配版本宿主程序，当前仓库中未包含宿主。

-仓库中未发现 ROS/ROS 2、Docker 或独立仿真启动配置。
+主要 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。

 ## 编译

-在仓库根目录执行：
+### 1. 构建 CommonUsage
+
+修改公共底盘库后，先执行：
+
+```powershell
+dotnet restore CommonUsage-MultiVehicleSync\commonusage\CommonUsage.csproj
+dotnet build CommonUsage-MultiVehicleSync\commonusage\CommonUsage.csproj -c Debug
+```
+
+该项目的构建目标会把生成的 `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
 ```

-当前源码已通过解决方案编译。现有警告为 `DiverCartDefinition.TransmitterLastTime` 尚未赋值，不影响程序集生成。
+### 3. 构建 Web 仿真器

-## 运行与配置
+```powershell
+dotnet restore Simulation\MyParking.Simulation.csproj
+dotnet build Simulation\MyParking.Simulation.csproj -c Debug
+```

-本仓库只生成插件类库，不能通过 `dotnet run` 独立启动。需要由匹配版本的 Clumsy/Medulla 宿主加载上述程序集。具体宿主版本、目录复制方式、配置文件位置和启动命令尚未随仓库提供，待补充。
+## 启动 Web 仿真

-当前能够从代码确认的 MCU 默认初始化参数如下：
+```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` 特性后，调度器会自动发现并在网页生成对应动作。
+
+## 实车运行与 MCU 配置
+
+实车插件不能通过 `dotnet run` 独立启动。需要由匹配版本的 Clumsy/Medulla 宿主加载两个 DLL。宿主版本、部署目录和完整启动步骤尚未随仓库提供，待补充。
+
+当前源码中的 MCU 默认参数：

 | 参数 | 默认值 |
 | --- | --- |
 | MCU 端口 | `COM4` |
 | MCU 连接波特率 | `1000000` |
-| CAN 通道 | 1 路，`500000 bit/s`，重试时间 `10 ms` |
-| 串口通道 | 3 路，`9600 bit/s`，接收帧时间 `10 ms` |
+| CAN | 1 路，`500000 bit/s`，重试时间 `10 ms` |
+| 串口 | 3 路，`9600 bit/s`，接收帧时间 `10 ms` |
+| 电池通信端口索引 | `3` |
+| 自转最大角速度 | `30 deg/s` |
+| 轮速诊断目录 | `logs\wheel-speed` |

-实机启动前应在宿主参数界面或对应配置中确认端口和硬件参数。首次调试建议架空驱动轮或使用安全测试区域，并准备可靠的急停手段；当前安全报警与急停反馈逻辑尚未完成，不能将软件停车作为唯一安全措施。
+当前工作区存在 `chassis.json` 底盘参数样例，但源码中尚未发现自动加载该文件的入口；实车参数仍应以宿主实际配置为准。

-## 单车功能验证
+实机测试前必须确认端口、车号、舵轮零位与限位、速度单位、驱动方向、夹臂限位和急停链路。建议先架空驱动轮或在隔离区域低速测试，并保留独立可靠的物理急停，不能只依赖软件停车。

-`MovementTests.cs` 向 Clumsy 测试界面注册了以下人工测试：
+## 单车测试入口

- `测试终点跟踪动作-前进`：选取起点和终点后执行前向直线跟踪；
- `测试终点跟踪动作-后退`：以 180° 车身方向偏置执行后退跟踪；
- `底盘旋转测试`：输入世界坐标系目标角度后执行 PID 原地旋转。
+`ClumsyPilot/MovementTests.cs` 当前注册：

-这些是宿主环境内的动作测试，并非 `dotnet test` 自动化测试。实机验证前需要先确认定位数据、底盘速度接口、舵轮方向、速度单位和急停链路。
+- `准备：四个舵轮与车头方向一致`
+- `SendMotion：连续前进4m`
+- `SendXYThSpeed：原地自转90°`
+- `SendXYThSpeed：原地自转180°`
+- `SendMotion：左转90°半径2m圆弧`
+- `SendMotion：蟹行直线4m`
+- `SendMotion：蟹行左转90°半径2m圆弧`
+- `SendMotion：4m S型曲线`
+- `夹臂关闭测试`
+- `夹臂启动测试`

-## 开发路线
+这些测试由 Clumsy 宿主的测试界面执行，并不是 `dotnet test` 自动化测试。运动测试会按配置记录实验编号、参考轨迹、Detour 位姿和控制命令。

-### 阶段 1：单车基本功能（当前）
+## 实验数据分析

- 打通上层动作、底盘控制、Medulla 适配和 MCU 通信链路；
- 完成单车启停、直线前进/后退、原地旋转和停止保护；
- 补齐驱动器命令、轮速与舵角反馈、IO、电池、急停和报警处理；
- 建立可重复的仿真/台架/实车验证方法。
+轨迹记录器默认把 CSV 保存到宿主程序目录下的：

-### 阶段 2：增加停车作业功能
+```text
+TrackingExperiments/
+```

- 在单车基础控制稳定后，逐项接入遥控、感知、钻车、夹抱和退出车辆等功能；
- 每项功能分别完成参数定义、异常处理和实车验证，不直接启用旧的禁用代码。
+Medulla 的轮速诊断可通过 `StartWheelSpeedDiagnostic` / `StopWheelSpeedDiagnostic` 操作按钮控制，默认输出到：

-### 阶段 3：优化跟踪方法
+```text
+logs/wheel-speed/
+```

- 根据单车测试数据改进路径跟踪、速度规划、转向控制和到位判定；
- 完善曲线、倒车、低速近目标等工况，并补充可复现的回归测试；
- 在安全性、稳定性和可诊断性达到要求后冻结单车接口。
+在自行管理的 Python 环境中安装依赖：

-### 阶段 4：考虑多车场景
+```powershell
+python -m pip install -r data_process\requirements.txt
+```

- 在单车接口稳定的前提下设计车辆身份、通信、心跳、超时和失联降级；
- 再实现编队、同步动作、车间位姿校正和多车安全策略；
- 多车预研参数需要重新评审，不以当前 `#if false` 代码作为完成依据。
+对一份或多份轨迹 CSV 同时生成轨迹对比、跟踪误差、速度响应和角速度命令图：
+
+```powershell
+python data_process\run_all_plots.py "路径\实验1.csv" "路径\实验2.csv" --output-dir "路径\plots"
+```
+
+不传 CSV 路径时，脚本会查找 `data_process` 目录中的 CSV。默认重采样频率为 `20 Hz`，滤波窗口为 `0.55 s`，可通过 `--frequency` 和 `--window` 调整。
+
+## 尚未完成或需要继续验证
+
+- 雷达点云、轮胎识别、自动钻车、车辆释放和完整停车作业状态机；
+- 当前运动和夹臂功能的完整实车验收、故障注入及长期稳定性测试；
+- 舵轮软限位预测和自动车身重定向；`SteeringConstraintManager.cs` 当前主要是设计记录；
+- 自动化单元测试和持续集成；
+- 多车通信、编队、同步和安全降级；`FleetKinematics.cs` 当前仅为占位；
+- 宿主版本、插件部署目录、配置文件位置和发布流程。

 ## 参与开发

-1. 修改前确认所属阶段，当前提交优先服务于单车基本功能；
-2. 保持 `ClumsyPilot` 与 `MedullaAdapter` 的职责边界，避免在上层动作中直接实现硬件协议；
-3. 新增硬件参数时注明单位、默认值、适用车型和安全范围；
-4. 提交前至少执行 `dotnet build ParkingRobot.sln`，并记录宿主测试或实车测试条件；
-5. 分支、代码评审和发布流程待项目团队补充。
+1. 当前改动优先服务于单车闭环、停车功能和跟踪质量，不提前启用多车代码；
+2. 保持上层动作、共享运动学、底层硬件协议和仿真模块的边界；
+3. 新增参数时注明坐标系、单位、默认值、车型和安全范围；
+4. 提交前构建受影响的项目，并记录仿真、台架或实车验证条件；
+5. 修改 `CommonUsage` 后同步更新根目录 `ref/CommonUsage.dll`；
+6. 分支、评审和发布流程待团队补充。

 ## 许可证