# MyParking 停车机器人 [简体中文](README.md) | [English](README_en.md) ## 重写路线与当前状态 本仓库是停车机器人控制软件的重写版本，研发顺序保持为： 1. 先实现单台停车机器人小车的基本功能； 2. 在单车闭环稳定后逐步增加停车作业功能； 3. 基于仿真、台架和实车数据优化轨迹跟踪方法； 4. 最后再考虑多车通信、编队和协同控制。 当前工作仍以**单车**为主，已经从基础框架搭建进入底盘联调、功能补充和跟踪实验阶段。多车配置仍位于 `PilotConfig.cs` 的 `#if false` 区域，`Shared/FleetKinematics.cs` 仍是占位文件，不能视为多车能力已经实现。 | 阶段 | 当前状态 | 说明 | | --- | --- | --- | | 1. 单车基本功能 | 联调中 | 已接入运动控制、MCU 通信、轮组反馈、急停 IO、电池、灯光、遥控和诊断代码，仍需持续实车验证 | | 2. 增加停车功能 | 部分开展 | 已提供夹臂控制、限位、报警和测试入口；轮胎识别、钻车和完整停车流程尚未实现 | | 3. 优化跟踪方法 | 已启动 | 已加入直线、圆弧、S 型、蟹行测试、实验 CSV 记录和 Python 绘图工具 | | 4. 多车场景 | 暂不实施 | 多车参数和预研内容未参与当前编译，当前版本不提供多车联动 | ## 项目简介 MyParking 是一个面向多轮停车机器人底盘的 C# 工程，覆盖上层运动动作、共享运动学、底层硬件适配、离线 Web 仿真和实验数据分析。 核心代码分为： - `ClumsyPilot`：Clumsy 上层动作、轨迹跟踪和人工测试； - `MedullaAdapter`：Medulla 下层 MCU、CAN、串口、轮组、夹臂、遥控和报警适配； - `Shared`：统一的二维坐标、底盘命令、坐标变换和多轮底盘适配； - `CommonUsage-MultiVehicleSync/commonusage`：仓库内的 `CommonUsage` 底盘公共库源码； - `Simulation`：基于 ASP.NET Core 的单车 Web 仿真器； - `data_process`：轨迹实验 CSV 的 Python 分析工具。 仓库中没有 ROS/ROS 2 或 Docker 配置。 ## 当前已接入能力 | 模块 | 当前代码能力 | | --- | --- | | 单车运动 | 直线、圆弧、S 型轨迹，前进、蟹行和原地旋转 | | 底盘命令 | `SendMotion`、`SendXYThSpeed` 和虚拟阿克曼测试后端 | | 模式切换 | 正常、蟹行、自转模式；切换时先停车、预转舵轮并等待到位 | | 跟踪控制 | 终点跟踪、直线跟踪、基于 Detour 的直线跟踪和蟹行运动坐标系跟踪 | | 夹臂 | 左右夹臂速度命令、位置反馈、软限位、驱动报警、实体/虚拟遥控和目标位置动作 | | MCU 通信 | 串口桥打开、复位、版本/状态查询、数字 IO、CAN/串口同步收发和异步回调 | | 驱动与反馈 | 8 个驱动电机和 4 个舵轮的命令、速度/位置/舵角反馈及远程帧状态 | | 车辆状态 | 急停、启停、抱闸、灯光、电池 SOC/SOH 和驱动使能状态 | | 诊断 | CAN 轮速事件与周期快照 CSV、轨迹实验 CSV、控制命令和 Detour 位姿记录 | | 仿真 | 浏览器二维车辆显示、模式按钮、手动控制、车辆配置、复位和 REST API | 以上表示代码和测试入口已经存在，不等同于所有工况均已完成实车验收。 ## 软件架构 ```text Clumsy 宿主 │ ▼ ClumsyPilot ───────────────┐ │ │ ▼ │ 实验 CSV Shared / CommonUsage ├──────────► data_process │ │ ▼ │ Medulla 宿主 │ │ │ ▼ │ MedullaAdapter │ │ P/Invoke │ ▼ │ mcu_serial_bridge.dll │ │ │ ▼ │ MCU ─► CAN / Serial / IO ──┘ Simulation ─► Shared 数据类型 ─► 浏览器仿真界面 ``` `ClumsyPilot` 和 `MedullaAdapter` 生成插件类库，需要由对应宿主加载；`Simulation` 是可以独立启动的 ASP.NET Core Web 项目。 ## 目录说明 ```text MyParking/ ├── 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 开发/实机运行环境； - Visual Studio 2022，或支持 .NET 8.0 和 .NET Standard 2.0 的 .NET SDK； - Python 环境，用于可选的实验数据绘图； - Clumsy/Medulla 内部框架程序集，位于各项目的 `ref` 目录； - 实机所需的 `mcu_serial_bridge.dll`，当前仓库中未包含该文件； - 能够加载 `ClumsyPilot.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。 ## 编译 ### 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 ``` ### 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` 特性后，调度器会自动发现并在网页生成对应动作。 ## 实车运行与 MCU 配置 实车插件不能通过 `dotnet run` 独立启动。需要由匹配版本的 Clumsy/Medulla 宿主加载两个 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` | 当前工作区存在 `chassis.json` 底盘参数样例，但源码中尚未发现自动加载该文件的入口；实车参数仍应以宿主实际配置为准。 实机测试前必须确认端口、车号、舵轮零位与限位、速度单位、驱动方向、夹臂限位和急停链路。建议先架空驱动轮或在隔离区域低速测试，并保留独立可靠的物理急停，不能只依赖软件停车。 ## 单车测试入口 `ClumsyPilot/MovementTests.cs` 当前注册： - `准备：四个舵轮与车头方向一致` - `SendMotion：连续前进4m` - `SendXYThSpeed：原地自转90°` - `SendXYThSpeed：原地自转180°` - `SendMotion：左转90°半径2m圆弧` - `SendMotion：蟹行直线4m` - `SendMotion：蟹行左转90°半径2m圆弧` - `SendMotion：4m S型曲线` - `夹臂关闭测试` - `夹臂启动测试` 这些测试由 Clumsy 宿主的测试界面执行，并不是 `dotnet test` 自动化测试。运动测试会按配置记录实验编号、参考轨迹、Detour 位姿和控制命令。 ## 实验数据分析 轨迹记录器默认把 CSV 保存到宿主程序目录下的： ```text TrackingExperiments/ ``` Medulla 的轮速诊断可通过 `StartWheelSpeedDiagnostic` / `StopWheelSpeedDiagnostic` 操作按钮控制，默认输出到： ```text logs/wheel-speed/ ``` 在自行管理的 Python 环境中安装依赖： ```powershell python -m pip install -r data_process\requirements.txt ``` 对一份或多份轨迹 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. 保持上层动作、共享运动学、底层硬件协议和仿真模块的边界； 3. 新增参数时注明坐标系、单位、默认值、车型和安全范围； 4. 提交前构建受影响的项目，并记录仿真、台架或实车验证条件； 5. 修改 `CommonUsage` 后同步更新根目录 `ref/CommonUsage.dll`； 6. 分支、评审和发布流程待团队补充。 ## 许可证 仓库中暂未提供许可证文件。使用和分发范围请遵循公司内部规定。