ParkingRobot/README.md

MyParking 停车机器人

简体中文 | English

重写说明

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

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

当前处于第 1 阶段，开发重点是单车基本功能。 PilotConfig.cs 中由 #if false 包围的钻车、夹抱和多车参数仅作为历史代码或设计参考，不参与当前编译，也不表示相关功能已经可用。

项目简介

MyParking 是一个面向多轮停车机器人底盘的 C# 控制工程。仓库包含上层运动控制插件 ClumsyPilot 和下层硬件适配插件 MedullaAdapter，用于建立从单车运动指令到 MCU 串口桥、CAN/串口端口的基础链路。

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

当前范围

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

软件结构

上层 Clumsy 运行环境
        │
        ▼
ClumsyPilot：单车动作、轨迹跟踪、测试入口
        │ 底盘速度指令
        ▼
Medulla 运行环境 / MedullaAdapter
        │ P/Invoke
        ▼
mcu_serial_bridge.dll → MCU → CAN / Serial / Digital IO

两个工程均生成类库，仓库中没有独立的可执行入口：

• ClumsyPilot：上层单车运动控制，目标框架为 .NET Standard 2.0；
• MedullaAdapter：下层 MCU 和底盘适配，目标框架为 .NET 8.0。

目录说明

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/                          # 下层框架引用程序集

开发环境与依赖

• 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 宿主环境；宿主程序和部署配置当前未包含在仓库中。

仓库中未发现 ROS/ROS 2、Docker 或独立仿真启动配置。

编译

在仓库根目录执行：

dotnet restore ParkingRobot.sln
dotnet build ParkingRobot.sln -c Debug

主要输出位置：

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

当前源码已通过解决方案编译。现有警告为 DiverCartDefinition.TransmitterLastTime 尚未赋值，不影响程序集生成。

运行与配置

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

当前能够从代码确认的 MCU 默认初始化参数如下：

参数	默认值
MCU 端口	COM4
MCU 连接波特率	1000000
CAN 通道	1 路，500000 bit/s，重试时间 10 ms
串口通道	3 路，9600 bit/s，接收帧时间 10 ms

实机启动前应在宿主参数界面或对应配置中确认端口和硬件参数。首次调试建议架空驱动轮或使用安全测试区域，并准备可靠的急停手段；当前安全报警与急停反馈逻辑尚未完成，不能将软件停车作为唯一安全措施。

单车功能验证

MovementTests.cs 向 Clumsy 测试界面注册了以下人工测试：

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

这些是宿主环境内的动作测试，并非 dotnet test 自动化测试。实机验证前需要先确认定位数据、底盘速度接口、舵轮方向、速度单位和急停链路。

开发路线

阶段 1：单车基本功能（当前）

• 打通上层动作、底盘控制、Medulla 适配和 MCU 通信链路；
• 完成单车启停、直线前进/后退、原地旋转和停止保护；
• 补齐驱动器命令、轮速与舵角反馈、IO、电池、急停和报警处理；
• 建立可重复的仿真/台架/实车验证方法。

阶段 2：增加停车作业功能

• 在单车基础控制稳定后，逐项接入遥控、感知、钻车、夹抱和退出车辆等功能；
• 每项功能分别完成参数定义、异常处理和实车验证，不直接启用旧的禁用代码。

阶段 3：优化跟踪方法

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

阶段 4：考虑多车场景

• 在单车接口稳定的前提下设计车辆身份、通信、心跳、超时和失联降级；
• 再实现编队、同步动作、车间位姿校正和多车安全策略；
• 多车预研参数需要重新评审，不以当前 #if false 代码作为完成依据。

参与开发

1. 修改前确认所属阶段，当前提交优先服务于单车基本功能；
2. 保持 ClumsyPilot 与 MedullaAdapter 的职责边界，避免在上层动作中直接实现硬件协议；
3. 新增硬件参数时注明单位、默认值、适用车型和安全范围；
4. 提交前至少执行 dotnet build ParkingRobot.sln，并记录宿主测试或实车测试条件；
5. 分支、代码评审和发布流程待项目团队补充。

许可证

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