170 lines
8.3 KiB
Markdown
170 lines
8.3 KiB
Markdown
# MyParking 停车机器人
|
||
|
||
[简体中文](README.md) | [English](README_en.md)
|
||
|
||
## 重写说明
|
||
|
||
本仓库是停车机器人控制软件的重写版本。当前不以一次性恢复全部旧功能为目标，而是按以下顺序重新建立可验证、可维护的能力：
|
||
|
||
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 路串口配置 |
|
||
| 驱动反馈与安全链路 | 待实现 | 驱动协议、轮速/舵角反馈、电池、急停和报警例程目前没有实际逻辑 |
|
||
| 停车作业功能 | 待实现 | 钻车、轮胎识别、夹抱等旧参数当前被条件编译禁用 |
|
||
| 多车能力 | 暂不实施 | 多车参数当前被条件编译禁用，待单车及跟踪能力稳定后再设计 |
|
||
|
||
## 软件结构
|
||
|
||
```text
|
||
上层 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。
|
||
|
||
## 目录说明
|
||
|
||
```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/ # 下层框架引用程序集
|
||
```
|
||
|
||
## 开发环境与依赖
|
||
|
||
- 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 或独立仿真启动配置。
|
||
|
||
## 编译
|
||
|
||
在仓库根目录执行：
|
||
|
||
```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` 尚未赋值，不影响程序集生成。
|
||
|
||
## 运行与配置
|
||
|
||
本仓库只生成插件类库，不能通过 `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. 分支、代码评审和发布流程待项目团队补充。
|
||
|
||
## 许可证
|
||
|
||
仓库中暂未提供许可证文件。使用和分发范围请遵循公司内部规定。
|