ParkingRobot/README.md

MyParking 停车机器人

简体中文 | English

重写路线与当前状态

本仓库是停车机器人控制软件的重写版本，研发顺序保持为：

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

当前工作仍以单车为主，处于底盘联调、功能补充和跟踪实验阶段。多车配置位于 MultiWheelC/PilotConfig.cs 的 #if false 区域，Shared/Fleet/FleetKinematics.cs 仍是占位文件，不能视为多车能力已经实现。

阶段	当前状态	说明
1. 单车基本功能	联调中	已接入运动控制、MCU 通信、轮组反馈、急停 IO、电池、灯光、遥控和诊断代码，仍需持续实车验证
2. 增加停车功能	部分开展	已提供夹臂控制、限位、报警和测试入口；轮胎识别、钻车和完整停车流程尚未实现
3. 优化跟踪方法	已启动	已加入直线、圆弧、S 型、蟹行测试、实验 CSV 记录和 Python 绘图工具
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 和虚拟阿克曼测试后端
模式切换	正常、蟹行、自转模式；切换时先停车、预转舵轮并等待到位
跟踪控制	终点跟踪、直线跟踪、基于 Detour 的直线跟踪和蟹行运动坐标系跟踪
夹臂	左右夹臂速度命令、位置反馈、软限位、驱动报警、实体/虚拟遥控和目标位置动作
MCU 通信	串口桥打开、复位、版本/状态查询、数字 IO、CAN/串口同步收发和异步回调
驱动与反馈	8 个驱动电机和 4 个舵轮的命令、速度/位置/舵角反馈及远程帧状态
车辆状态	急停、启停、抱闸、灯光、电池 SOC/SOH 和驱动使能状态
诊断	CAN 轮速事件与周期快照 CSV、轨迹实验 CSV、控制命令和 Detour 位姿记录

以上表示代码和测试入口已经存在，不等同于所有工况均已完成实车验收。

软件架构

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°] 限制的机械舵角误差必须直接使用目标值减实际值。

目录说明

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/
│   ├── 轨迹测试处理/                # 轨迹对比、误差、速度与角速度绘图
│   └── 电机响应处理/                # 舵轮响应快照分析
├── 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 -NoProfile -ExecutionPolicy Bypass -File .\build-and-package.ps1

Release 构建：

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 失败，可先恢复依赖再打包：

dotnet restore CommonUsage-MultiVehicleSync\commonusage\CommonUsage.csproj
dotnet restore MedullaAdapter\MedullaAdapter.csproj
dotnet restore MultiWheelC\MultiWheelC.csproj

主要中间输出：

MedullaAdapter/build/Medulla/plugins/MedullaAdapter.dll
MultiWheelC/build/Clumsy/MultiWheelC.dll

不要直接编辑 bin、obj、build、output 中的产物，也不要手工覆盖 ref/CommonUsage.dll。

实车运行与 MCU 配置

实车插件不能通过 dotnet run 独立启动，需要由匹配版本的 Clumsy / Medulla 宿主分别加载：

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/MovementTests.cs 当前注册：

• 准备：四个舵轮与车头方向一致
• SendMotion：连续前进4m
• SendXYThSpeed：原地自转90°
• SendXYThSpeed：原地自转180°
• SendMotion：左转90°半径2m圆弧
• SendMotion：蟹行直线4m
• SendMotion：蟹行左转90°半径2m圆弧
• SendMotion：4m S型曲线
• 夹臂关闭测试
• 夹臂启动测试

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

实验数据分析

轨迹记录器默认把 CSV 保存到宿主程序目录下的：

TrackingExperiments/

Medulla 的轮速诊断可通过 StartWheelSpeedDiagnostic / StopWheelSpeedDiagnostic 操作按钮控制，默认输出到：

logs/wheel-speed/

轨迹测试处理

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 调整。

电机响应处理

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。

尚未完成或需要继续验证

• 雷达点云、轮胎识别、自动钻车、车辆释放和完整停车作业状态机；
• 当前运动和夹臂功能的完整实车验收、故障注入及长期稳定性测试；
• 舵轮软限位预测和自动车身重定向；当前仅有设计文档 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。

许可证

仓库中暂未提供许可证文件。使用和分发范围请遵循公司内部规定。