同步中英文README与当前工程结构，并整理文档目录与构建忽略规则
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Cursor
+95
-93
@@ -8,10 +8,10 @@ This repository is a rewrite of the parking-robot control software. Development
|
||||
|
||||
1. Implement the basic functions of one parking robot first;
|
||||
2. Add parking-operation features after the single-robot loop is stable;
|
||||
3. Improve tracking with simulation, bench, and physical-vehicle data;
|
||||
3. Improve tracking with bench and physical-vehicle data;
|
||||
4. Consider multi-robot communication, formation, and coordination last.
|
||||
|
||||
The current work remains focused on the **single robot** and has progressed from framework construction to chassis integration, feature development, and tracking experiments. Multi-robot settings remain inside the `#if false` section of `PilotConfig.cs`, while `Shared/FleetKinematics.cs` is still a placeholder. These files do not represent an implemented multi-robot system.
|
||||
The current work remains focused on the **single robot** and is in chassis integration, feature development, and tracking experiments. Multi-robot settings remain inside the `#if false` section of `MultiWheelC/PilotConfig.cs`, while `Shared/Fleet/FleetKinematics.cs` is still a placeholder. These files do not represent an implemented multi-robot system.
|
||||
|
||||
| Stage | Current status | Notes |
|
||||
| --- | --- | --- |
|
||||
@@ -22,18 +22,17 @@ The current work remains focused on the **single robot** and has progressed from
|
||||
|
||||
## Overview
|
||||
|
||||
MyParking is a C# project for a multi-wheel parking-robot chassis. It covers upper-layer actions, shared kinematics, lower-layer hardware adaptation, an offline Web simulator, and experiment-data analysis.
|
||||
MyParking is a C# project for a multi-wheel parking-robot chassis. It covers upper-layer actions, shared kinematics, lower-layer hardware adaptation, and experiment-data analysis.
|
||||
|
||||
The main components are:
|
||||
Main modules:
|
||||
|
||||
- `ClumsyPilot`: Clumsy actions, tracking, and manual tests;
|
||||
- `MedullaAdapter`: Medulla MCU, CAN, serial, wheel, clamp, remote-control, and alarm adaptation;
|
||||
- `Shared`: common 2D coordinates, chassis commands, frame transforms, and multi-wheel adaptation;
|
||||
- `MultiWheelC`: Clumsy upper layer (C layer) for actions, tracking, manual tests, and experiment recording;
|
||||
- `MedullaAdapter`: Medulla lower layer (M layer) for MCU, CAN, serial, wheel, clamp, remote-control, and alarm adaptation;
|
||||
- `Shared`: M/C-shared 2D coordinates, chassis commands, frame transforms, and multi-wheel adaptation (no standalone `.csproj`; compiled into both ends);
|
||||
- `CommonUsage-MultiVehicleSync/commonusage`: in-repository source for the `CommonUsage` chassis library;
|
||||
- `Simulation`: an ASP.NET Core single-robot Web simulator;
|
||||
- `data_process`: Python tools for tracking-experiment CSV files.
|
||||
- `data_process`: Python tools for tracking experiments and steering-response analysis.
|
||||
|
||||
No ROS/ROS 2 or Docker configuration is present.
|
||||
No ROS/ROS 2, Docker, or Web simulator project is present. The plugins are loaded by Clumsy / Medulla hosts and cannot be started independently with `dotnet run`.
|
||||
|
||||
## Currently Integrated Capabilities
|
||||
|
||||
@@ -48,7 +47,6 @@ No ROS/ROS 2 or Docker configuration is present.
|
||||
| Drive and feedback | Commands and speed/position/steering feedback for eight drive motors and four steer modules, plus remote-frame state |
|
||||
| Vehicle state | Emergency stop, start/stop, brake, lights, battery SOC/SOH, and drive-enable state |
|
||||
| Diagnostics | CAN wheel-speed events, periodic snapshot CSVs, tracking CSVs, command recording, and Detour pose recording |
|
||||
| Simulation | Browser-based 2D display, mode actions, manual control, vehicle configuration, reset, and REST APIs |
|
||||
|
||||
The presence of code and test entries does not mean every operating condition has passed physical acceptance testing.
|
||||
|
||||
@@ -58,7 +56,7 @@ The presence of code and test entries does not mean every operating condition ha
|
||||
Clumsy host
|
||||
│
|
||||
▼
|
||||
ClumsyPilot ───────────────┐
|
||||
MultiWheelC ───────────────┐
|
||||
│ │
|
||||
▼ │ experiment CSV
|
||||
Shared / CommonUsage ├──────────► data_process
|
||||
@@ -74,111 +72,109 @@ mcu_serial_bridge.dll │
|
||||
│ │
|
||||
▼ │
|
||||
MCU ─► CAN / Serial / IO ──┘
|
||||
|
||||
Simulation ─► Shared data types ─► browser simulator
|
||||
```
|
||||
|
||||
`ClumsyPilot` and `MedullaAdapter` build as plugin libraries that require their respective hosts. `Simulation` is an independently runnable ASP.NET Core Web project.
|
||||
`MultiWheelC` and `MedullaAdapter` build as plugin libraries that require their respective hosts. `CommonUsage` is an independent chassis library and must not depend back on `Shared`, the M layer, or the C layer.
|
||||
|
||||
## Coordinates and Units
|
||||
|
||||
- `Shared` uses SI units: m, m/s, rad, rad/s.
|
||||
- Body frame: X forward, Y left, counterclockwise positive.
|
||||
- Legacy API units are converted only at boundaries.
|
||||
- Angle normalization, shortest angular difference, and degree/radian conversion use `Shared/Mathematics/AngleMath.cs`.
|
||||
- Radian normalization range is `[-π, π)`; degree normalization range is `[-180°, 180°)`.
|
||||
- Vehicle heading may use the shortest circular difference; mechanical steering error under the `[-120°, 120°]` limit must use target minus actual directly.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
```text
|
||||
MyParking/
|
||||
├── ParkingRobot.sln
|
||||
├── ClumsyPilot/ # Upper-layer actions, tracking, tests, and recording
|
||||
├── MedullaAdapter/ # MCU, CAN, wheel, clamp, remote, and alarms
|
||||
├── Shared/ # Shared commands, frame transforms, and chassis adapter
|
||||
├── build-and-package.ps1 # Official build and M/C packaging script
|
||||
├── AGENTS.md # Collaboration and coding rules
|
||||
├── MultiWheelC/ # C-layer actions, tracking, tests, and recording
|
||||
├── MedullaAdapter/ # M-layer MCU, CAN, wheel, clamp, remote, and alarms
|
||||
├── Shared/ # Shared models, math, and chassis adapter
|
||||
├── CommonUsage-MultiVehicleSync/
|
||||
│ └── commonusage/ # CommonUsage chassis-library source
|
||||
├── Simulation/ # .NET 8 Web simulator
|
||||
│ ├── Commands/ # Attribute-discovered simulation actions
|
||||
│ ├── Core/ # Vehicles, steer wheels, clock, and world
|
||||
│ ├── Models/ # Web API DTOs
|
||||
│ └── wwwroot/ # Browser UI
|
||||
├── data_process/ # Python experiment-plotting scripts
|
||||
├── ref/ # CommonUsage.dll shared by both plugins
|
||||
├── 测试方案.txt # Single-robot tracking experiment plan
|
||||
├── 记录.txt # Project debugging notes
|
||||
└── 电机记录.txt # Motor debugging notes
|
||||
├── ref/ # Generated CommonUsage.dll (do not overwrite by hand)
|
||||
├── data_process/
|
||||
│ ├── 轨迹测试处理/ # Trajectory comparison, error, speed, and yaw plots
|
||||
│ └── 电机响应处理/ # Steering-response snapshot analysis
|
||||
├── docs/
|
||||
│ ├── SteeringConstraintDesign.md # Steering-limit design notes
|
||||
│ ├── chassis参考.json # Sample chassis parameters
|
||||
│ ├── 测试方案.txt # Single-robot tracking experiment plan
|
||||
│ └── 记录.txt # Project debugging notes
|
||||
└── output/ # Packaging output (gitignored)
|
||||
├── M/ # MedullaAdapter.dll + CommonUsage.dll
|
||||
└── C/ # MultiWheelC.dll + CommonUsage.dll
|
||||
```
|
||||
|
||||
The root `ParkingRobot.sln` currently contains only `ClumsyPilot` and `MedullaAdapter`. Build `CommonUsage` and `Simulation` separately.
|
||||
There is no root-level `ParkingRobot.sln`. The only solution file is `CommonUsage-MultiVehicleSync/commonusage/CommonUsageSln.sln`.
|
||||
|
||||
## Development Environment and Dependencies
|
||||
|
||||
- Windows development and physical-runtime environment;
|
||||
- Visual Studio 2022, or a .NET SDK supporting .NET 8.0 and .NET Standard 2.0;
|
||||
- A Python environment for optional experiment plotting;
|
||||
- Internal Clumsy/Medulla framework assemblies under each project's `ref` directory;
|
||||
- Internal Clumsy / Medulla framework assemblies under each project's `ref` directory;
|
||||
- `mcu_serial_bridge.dll` for physical operation; this file is not currently in the repository;
|
||||
- Compatible hosts capable of loading `ClumsyPilot.dll` and `MedullaAdapter.dll`; the hosts are not included.
|
||||
- Compatible hosts capable of loading `MultiWheelC.dll` and `MedullaAdapter.dll`; the hosts are not included.
|
||||
|
||||
Primary NuGet/Python dependencies:
|
||||
Primary dependencies:
|
||||
|
||||
- `ClumsyPilot`: `Newtonsoft.Json 13.0.3` and `System.Numerics.Vectors 4.6.1`;
|
||||
- `CommonUsage`: `MQTTnet 4.3.7.1207`, `Newtonsoft.Json 13.0.3`, and related packages;
|
||||
- `data_process`: NumPy, pandas, Matplotlib, and SciPy.
|
||||
- `MultiWheelC` (`netstandard2.0`): `Newtonsoft.Json 13.0.3` and `System.Numerics.Vectors 4.6.1`;
|
||||
- `MedullaAdapter` (`net8.0`): no NuGet PackageReferences; depends on local `ref` assemblies;
|
||||
- `CommonUsage` (`netstandard2.0`): `MQTTnet 4.3.7.1207`, `Newtonsoft.Json 13.0.3`, and related packages;
|
||||
- `data_process`: see each subdirectory's `requirements.txt`.
|
||||
|
||||
## Build
|
||||
## Build and Packaging
|
||||
|
||||
### 1. Build CommonUsage
|
||||
From the `MyParking` directory, run the official script (Debug by default):
|
||||
|
||||
After changing the common chassis library, run:
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-and-package.ps1
|
||||
```
|
||||
|
||||
Release build:
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-and-package.ps1 -Configuration Release
|
||||
```
|
||||
|
||||
Script flow:
|
||||
|
||||
1. Build `CommonUsage` and copy `CommonUsage.dll` to the root `ref/` directory;
|
||||
2. Build `MedullaAdapter` and `MultiWheelC`;
|
||||
3. Package M/C outputs into `output/M` and `output/C`, both using the same `CommonUsage.dll`.
|
||||
|
||||
After a fresh clone or dependency change, if `--no-restore` fails, restore first and then package:
|
||||
|
||||
```powershell
|
||||
dotnet restore CommonUsage-MultiVehicleSync\commonusage\CommonUsage.csproj
|
||||
dotnet build CommonUsage-MultiVehicleSync\commonusage\CommonUsage.csproj -c Debug
|
||||
dotnet restore MedullaAdapter\MedullaAdapter.csproj
|
||||
dotnet restore MultiWheelC\MultiWheelC.csproj
|
||||
```
|
||||
|
||||
The project includes a build target that copies the generated `CommonUsage.dll` to the root `ref` directory.
|
||||
|
||||
### 2. Build Physical-Robot Plugins
|
||||
|
||||
```powershell
|
||||
dotnet restore ParkingRobot.sln
|
||||
dotnet build ParkingRobot.sln -c Debug
|
||||
```
|
||||
|
||||
Primary outputs:
|
||||
Primary intermediate outputs:
|
||||
|
||||
```text
|
||||
ClumsyPilot/build/Clumsy/ClumsyPilot.dll
|
||||
MedullaAdapter/build/Medulla/plugins/MedullaAdapter.dll
|
||||
MultiWheelC/build/Clumsy/MultiWheelC.dll
|
||||
```
|
||||
|
||||
### 3. Build the Web Simulator
|
||||
|
||||
```powershell
|
||||
dotnet restore Simulation\MyParking.Simulation.csproj
|
||||
dotnet build Simulation\MyParking.Simulation.csproj -c Debug
|
||||
```
|
||||
|
||||
## Run the Web Simulator
|
||||
|
||||
```powershell
|
||||
dotnet run --project Simulation\MyParking.Simulation.csproj --launch-profile http
|
||||
```
|
||||
|
||||
Open:
|
||||
|
||||
```text
|
||||
http://localhost:5203
|
||||
```
|
||||
|
||||
The UI provides normal, left-crab, right-crab, spin, forward, backward, left-turn, right-turn, stop, and reset actions. It also supports vehicle-layout configuration and manual-control input. Main APIs include:
|
||||
|
||||
- `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` contains an example custom action. Add the `SimulationAction` attribute to a static method to have it discovered by the dispatcher and exposed in the Web UI.
|
||||
Do not edit artifacts under `bin`, `obj`, `build`, or `output`, and do not manually overwrite `ref/CommonUsage.dll`.
|
||||
|
||||
## Physical Runtime and MCU Configuration
|
||||
|
||||
The physical-robot plugins cannot be started independently with `dotnet run`. Compatible Clumsy/Medulla hosts must load both DLLs. The required host versions, deployment directories, and complete startup procedure have not yet been provided.
|
||||
The physical-robot plugins cannot be started independently with `dotnet run`. Compatible Clumsy / Medulla hosts must load:
|
||||
|
||||
```text
|
||||
output/C/MultiWheelC.dll
|
||||
output/M/MedullaAdapter.dll
|
||||
```
|
||||
|
||||
The required host versions, deployment directories, and complete startup procedure have not yet been provided.
|
||||
|
||||
MCU defaults confirmed from the current source:
|
||||
|
||||
@@ -192,13 +188,13 @@ MCU defaults confirmed from the current source:
|
||||
| Maximum spin rate | `30 deg/s` |
|
||||
| Wheel-speed diagnostic directory | `logs\wheel-speed` |
|
||||
|
||||
A `chassis.json` chassis-parameter example is present in the current workspace, but no automatic loader for it was found in the source. Treat the actual host configuration as authoritative.
|
||||
`docs/chassis参考.json` is a chassis-parameter example. No automatic loader for it was found in the source. Treat the actual host configuration as authoritative.
|
||||
|
||||
Before physical testing, verify the port, vehicle ID, steering zero and limits, speed units, motor direction, clamp limits, and emergency-stop chain. Begin with lifted drive wheels or a segregated low-speed test area and retain an independent physical emergency stop; never rely on software stopping alone.
|
||||
Before physical testing, verify the port, vehicle ID, steering zero and limits, speed units, motor direction, clamp limits, and emergency-stop chain. Begin with lifted drive wheels or a segregated low-speed, short-distance test area and retain an independent physical emergency stop; never rely on software stopping alone.
|
||||
|
||||
## Single-Robot Test Entries
|
||||
|
||||
`ClumsyPilot/MovementTests.cs` currently registers:
|
||||
`MultiWheelC/MovementTests.cs` currently registers:
|
||||
|
||||
- `准备：四个舵轮与车头方向一致`
|
||||
- `SendMotion：连续前进4m`
|
||||
@@ -227,25 +223,29 @@ Medulla wheel-speed diagnostics can be controlled with the `StartWheelSpeedDiagn
|
||||
logs/wheel-speed/
|
||||
```
|
||||
|
||||
Install dependencies in a Python environment managed by your team:
|
||||
### Trajectory processing
|
||||
|
||||
```powershell
|
||||
python -m pip install -r data_process\requirements.txt
|
||||
python -m pip install -r data_process\轨迹测试处理\requirements.txt
|
||||
python data_process\轨迹测试处理\run_all_plots.py "path\trial1.csv" "path\trial2.csv" --output-dir "path\plots"
|
||||
```
|
||||
|
||||
Generate trajectory comparison, tracking error, speed response, and angular-command plots for one or more CSV files:
|
||||
The default resampling frequency is `20 Hz`, and the default filter window is `0.55 s`; use `--frequency` and `--window` to change them.
|
||||
|
||||
### Steering-response processing
|
||||
|
||||
```powershell
|
||||
python data_process\run_all_plots.py "path\trial1.csv" "path\trial2.csv" --output-dir "path\plots"
|
||||
python -m pip install -r data_process\电机响应处理\requirements.txt
|
||||
python data_process\电机响应处理\plot_steering_response.py
|
||||
```
|
||||
|
||||
When no CSV path is supplied, the scripts search the `data_process` directory. The default resampling frequency is `20 Hz`, and the default filter window is `0.55 s`; use `--frequency` and `--window` to change them.
|
||||
By default this reads the latest `*_snapshot.csv` under `logs\wheel-speed`. See [`data_process/电机响应处理/README.md`](data_process/电机响应处理/README.md).
|
||||
|
||||
## Incomplete or Pending Validation
|
||||
|
||||
- Lidar point clouds, tire recognition, automatic vehicle entry, vehicle release, and the complete parking-operation state machine;
|
||||
- Full physical acceptance, fault injection, and long-duration testing for current motion and clamp functions;
|
||||
- Steering soft-limit prediction and automatic body reorientation; `SteeringConstraintManager.cs` currently contains mainly design notes;
|
||||
- Steering soft-limit prediction and automatic body reorientation; only the design document [`docs/SteeringConstraintDesign.md`](docs/SteeringConstraintDesign.md) exists today;
|
||||
- Automated unit tests and continuous integration;
|
||||
- Multi-robot communication, formation, synchronization, and safety fallback; `FleetKinematics.cs` is currently only a placeholder;
|
||||
- Host versions, plugin deployment directories, configuration-file locations, and the release process.
|
||||
@@ -253,12 +253,14 @@ When no CSV path is supplied, the scripts search the `data_process` directory. T
|
||||
## Contributing
|
||||
|
||||
1. Prioritize single-robot closed-loop behavior, parking functions, and tracking quality; do not enable multi-robot code prematurely.
|
||||
2. Preserve the boundaries between upper-layer actions, shared kinematics, hardware protocols, and simulation.
|
||||
2. Preserve the boundaries among `CommonUsage`, `Shared`, `MedullaAdapter`, and `MultiWheelC`.
|
||||
3. Document coordinate frames, units, defaults, applicable vehicle types, and safe ranges for new parameters.
|
||||
4. Build every affected project before submission and record the simulation, bench, or physical-test conditions.
|
||||
5. After changing `CommonUsage`, update the root `ref/CommonUsage.dll`.
|
||||
4. After changing the related projects, run `build-and-package.ps1` and confirm that the M/C packages use the same `CommonUsage.dll`.
|
||||
5. Do not change velocity or steering signs, CAN IDs, remote-control mappings, mechanical limits, or mode-switch policy unless explicitly requested.
|
||||
6. The team still needs to document its branch, review, and release processes.
|
||||
|
||||
See [`AGENTS.md`](AGENTS.md) for more detailed collaboration rules.
|
||||
|
||||
## License
|
||||
|
||||
No license file is currently included. Use and distribution must follow internal company policy.
|
||||
|
||||
Reference in New Issue
Block a user