First_Dev_Dept/ParkingRobot
10
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

限制单车自转角速度并更新底盘配置与项目文档

Browse Source
This commit is contained in:
yuxiang.shen
2026-07-31 15:34:11 +08:00
parent c1fe73caec
commit 5da31a6c40
12 changed files with 453 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README_en.md
+190 -95
View File
@@ -2,167 +2,262 @@
[简体中文](README.md) | [English](README_en.md)
## Rewrite Notice
## Rewrite Roadmap and Current Status
This repository is a rewrite of the parking-robot control software. The goal is not to restore every legacy feature at once. Development follows this sequence:
This repository is a rewrite of the parking-robot control software. Development follows this order:
1. Implement the basic functions of one parking robot first;
2. Add parking-operation features after the single-robot loop is stable;
3. Improve the tracking method and its robustness;
4. Evaluate and implement multi-robot communication, formation, and coordination last.
3. Improve tracking with simulation, bench, and physical-vehicle data;
4. Consider multi-robot communication, formation, and coordination last.
**The project is currently in Stage 1 and focuses on basic single-robot functions.** The vehicle-entry, clamping, and multi-robot parameters enclosed by `#if false` in `PilotConfig.cs` are retained only as legacy or design references. They are excluded from the current build and do not indicate available features.
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.
| Stage | Current status | Notes |
| --- | --- | --- |
| 1. Basic single-robot functions | Integration in progress | Motion control, MCU communication, wheel feedback, emergency-stop I/O, battery, lights, remote control, and diagnostics are connected in code; physical validation is ongoing |
| 2. Add parking functions | Partially started | Clamp control, limits, alarms, and test entries exist; tire recognition, vehicle entry, and the complete parking workflow are not implemented |
| 3. Improve tracking | Started | Straight, arc, S-curve, and crab tests, experiment CSV recording, and Python plotting tools are available |
| 4. Multi-robot scenarios | Deferred | Multi-robot R&D settings are excluded from the build, and the current version provides no fleet coordination |
## Overview
MyParking is a C# control project for a multi-wheel parking-robot chassis. It contains an upper-layer motion-control plugin, `ClumsyPilot`, and a lower-layer hardware adapter, `MedullaAdapter`. Together, they establish the basic path from single-robot motion commands to an MCU serial bridge and its CAN, serial, and digital-I/O ports.
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.
The current code includes basic straight-line destination tracking, forward and reverse tests, PID-based in-place rotation, stop-on-exit handling, a managed wrapper for the MCU bridge, and its initialization sequence. Driver protocols, feedback parsing, safety alarms, clamping actuators, perception, and the complete parking workflow still need to be implemented or integrated.
The main components are:
## Current Scope
- `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;
- `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.
| Area | Status | Notes |
| --- | --- | --- |
| Single-robot geometric controller | Integrated | Creates a `MultiWheelGeometricController` from shared configuration |
| Destination tracking | Basic version implemented | Tracks a straight path forward or backward and sends zero speed when finished or interrupted |
| In-place rotation | Basic version implemented | Reads the localization heading and produces angular speed through a PID controller |
| MCU serial bridge | Wrapped | Supports open/reset, state/version queries, port configuration, I/O, serial, CAN, and callbacks |
| MCU initialization | Basic flow implemented | Defaults to `COM4`, one CAN channel, and three serial channels |
| Driver feedback and safety chain | To be implemented | Driver protocol, wheel/steering feedback, battery, emergency-stop, and alarm routines contain no operational logic yet |
| Parking-operation features | To be implemented | Vehicle entry, tire recognition, and clamping parameters are currently excluded by conditional compilation |
| Multi-robot features | Deferred | Multi-robot parameters are excluded and will be reconsidered after single-robot tracking is stable |
No ROS/ROS 2 or Docker configuration is present.
## Software Structure
## Currently Integrated Capabilities
| Module | Current code capability |
| --- | --- |
| Single-robot motion | Straight, arc, and S-curve paths; forward, crab, and in-place rotation |
| Chassis commands | `SendMotion`, `SendXYThSpeed`, and a virtual-Ackermann test backend |
| Mode switching | Normal, crab, and spin modes; stop, pre-steer, and wait for wheel alignment before motion |
| Tracking | Destination tracking, line tracking, Detour-based line tracking, and crab motion-frame tracking |
| Clamp | Left/right speed commands, position feedback, soft limits, driver alarms, physical/virtual remote control, and target-position actions |
| MCU communication | Bridge open/reset, version/state queries, digital I/O, synchronous serial/CAN access, and asynchronous callbacks |
| 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.
## Software Architecture
```text
Upper-layer Clumsy runtime
│
▼
ClumsyPilot: single-robot actions, tracking, and test entries
│ chassis velocity commands
▼
Medulla runtime / MedullaAdapter
│ P/Invoke
▼
mcu_serial_bridge.dll → MCU → CAN / Serial / Digital IO
Clumsy host
│
▼
ClumsyPilot ───────────────┐
│ │
▼ │ experiment CSV
Shared / CommonUsage ├──────────► data_process
│ │
▼ │
Medulla host │
│ │
▼ │
MedullaAdapter │
│ P/Invoke │
▼ │
mcu_serial_bridge.dll │
│ │
▼ │
MCU ─► CAN / Serial / IO ──┘
Simulation ─► Shared data types ─► browser simulator
```
Both projects build as libraries; this repository contains no standalone executable entry point:
- `ClumsyPilot`: upper-layer single-robot motion control targeting .NET Standard 2.0;
- `MedullaAdapter`: lower-layer MCU and chassis adapter targeting .NET 8.0.
`ClumsyPilot` and `MedullaAdapter` build as plugin libraries that require their respective hosts. `Simulation` is an independently runnable ASP.NET Core Web project.
## Repository Layout
```text
MyParking/
├── ParkingRobot.sln # Visual Studio solution
├── ClumsyPilot/
│ ├── AGV.cs # Upper-layer AGV interface
│ ├── ChassisController.cs # Single-robot geometric-controller setup
│ ├── Movements.cs # Destination tracking, delay, and rotation actions
│ ├── MovementTests.cs # Manual action tests in the Clumsy runtime
│ ├── PilotConfig.cs # Active single-robot and disabled legacy/R&D settings
│ ├── PilotDefinition.cs # Vehicle dimensions and vehicle-number definition
│ └── ref/ # Upper-layer framework assemblies
└── MedullaAdapter/
├── DiverCartDefinition.cs # Vehicle I/O, monitoring fields, and MCU initialization
├── MCUSerialBridgeCLR.cs # C# wrapper for the native MCU serial bridge
├── MCUSerialBridgeError.cs # Error codes and diagnostic descriptions
├── AlarmRoutine.cs # Placeholder for safety and alarm routines
├── MCURoutine.cs # Placeholder for MCU I/O and feedback routines
├── MotorRoutine.cs # Placeholder for motor-control routines
├── Remote.cs # Placeholder for remote-control routines
└── ref/ # Lower-layer framework assemblies
├── 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
├── 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
```
The root `ParkingRobot.sln` currently contains only `ClumsyPilot` and `MedullaAdapter`. Build `CommonUsage` and `Simulation` separately.
## Development Environment and Dependencies
- Windows development/runtime environment; current hardware access uses a COM port and a native DLL;
- Visual Studio 2022, or a .NET SDK capable of building .NET 8.0 and .NET Standard 2.0 projects;
- NuGet packages: `Newtonsoft.Json 13.0.3` and `System.Numerics.Vectors 4.6.1`;
- Internal framework assemblies under `ClumsyPilot/ref` and `MedullaAdapter/ref`;
- `mcu_serial_bridge.dll` for physical-hardware operation; it is not currently included in this repository;
- A compatible Clumsy/Medulla host capable of loading `ClumsyPilot.dll` and `MedullaAdapter.dll`. The host application and deployment configuration are not included.
- 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;
- `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.
No ROS/ROS 2, Docker, or standalone simulation launch configuration was found in the repository.
Primary NuGet/Python 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.
## Build
Run from the repository root:
### 1. Build CommonUsage
After changing the common chassis library, run:
```powershell
dotnet restore CommonUsage-MultiVehicleSync\commonusage\CommonUsage.csproj
dotnet build CommonUsage-MultiVehicleSync\commonusage\CommonUsage.csproj -c Debug
```
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 output locations:
Primary outputs:
```text
ClumsyPilot/build/Clumsy/ClumsyPilot.dll
MedullaAdapter/build/Medulla/plugins/MedullaAdapter.dll
```
The current source builds successfully. The remaining warning reports that `DiverCartDefinition.TransmitterLastTime` is never assigned; it does not prevent assembly generation.
### 3. Build the Web Simulator
## Runtime and Configuration
```powershell
dotnet restore Simulation\MyParking.Simulation.csproj
dotnet build Simulation\MyParking.Simulation.csproj -c Debug
```
This repository produces plugin libraries and cannot be started independently with `dotnet run`. A compatible Clumsy/Medulla host must load the assemblies above. The exact host version, copy locations, configuration-file paths, and startup command have not been provided and remain to be documented.
## Run the Web Simulator
MCU defaults confirmed from the current source are:
```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.
## 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.
MCU defaults confirmed from the current source:
| Setting | Default |
| --- | --- |
| MCU port | `COM4` |
| MCU connection baud rate | `1000000` |
| CAN channels | One at `500000 bit/s`, with a `10 ms` retry time |
| Serial channels | Three at `9600 bit/s`, with a `10 ms` receive-frame time |
| CAN | One channel at `500000 bit/s`, with a `10 ms` retry time |
| Serial | Three channels at `9600 bit/s`, with a `10 ms` receive-frame time |
| Battery port index | `3` |
| Maximum spin rate | `30 deg/s` |
| Wheel-speed diagnostic directory | `logs\wheel-speed` |
Confirm the port and hardware parameters in the host configuration before physical operation. For initial tests, lift the drive wheels or use a controlled safety area and provide a reliable physical emergency stop. The alarm and emergency-stop feedback logic is incomplete, so software stop commands must not be the only safety measure.
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.
## Single-Robot Validation
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.
`MovementTests.cs` registers these manual tests in the Clumsy test interface:
## Single-Robot Test Entries
- `测试终点跟踪动作-前进`: select a source and destination for forward straight-line tracking;
- `测试终点跟踪动作-后退`: track backward with a 180-degree vehicle-direction offset;
- `底盘旋转测试`: enter a target world-frame heading and run PID-based in-place rotation.
`ClumsyPilot/MovementTests.cs` currently registers:
These are host-integrated action tests, not an automated `dotnet test` suite. Before physical testing, verify localization data, the chassis velocity interface, steering direction, speed units, and the emergency-stop chain.
- `准备：四个舵轮与车头方向一致`
- `SendMotion：连续前进4m`
- `SendXYThSpeed：原地自转90°`
- `SendXYThSpeed：原地自转180°`
- `SendMotion：左转90°半径2m圆弧`
- `SendMotion：蟹行直线4m`
- `SendMotion：蟹行左转90°半径2m圆弧`
- `SendMotion：4m S型曲线`
- `夹臂关闭测试`
- `夹臂启动测试`
## Development Roadmap
These are run through the Clumsy host's test interface and are not an automated `dotnet test` suite. Motion tests record the experiment number, reference path, Detour pose, and control commands according to their configuration.
### Stage 1: Basic Single-Robot Functions (Current)
## Experiment Data Analysis
- Connect upper-layer actions, chassis control, the Medulla adapter, and MCU communication;
- Complete single-robot start/stop, straight forward/reverse motion, in-place rotation, and stop protection;
- Implement driver commands, wheel and steering feedback, I/O, battery, emergency-stop, and alarm handling;
- Establish repeatable simulation, bench, and physical-vehicle validation procedures.
The tracking recorder saves CSV files under the host application's:
### Stage 2: Add Parking-Operation Features
```text
TrackingExperiments/
```
- After basic single-robot control is stable, integrate remote control, perception, vehicle entry, clamping, and vehicle-exit functions one at a time;
- Define parameters, exception handling, and physical validation for each feature instead of directly enabling legacy disabled code.
Medulla wheel-speed diagnostics can be controlled with the `StartWheelSpeedDiagnostic` and `StopWheelSpeedDiagnostic` utility buttons. Their default output directory is:
### Stage 3: Improve Tracking
```text
logs/wheel-speed/
```
- Use single-robot test data to improve path tracking, speed planning, steering control, and arrival detection;
- Cover curves, reverse motion, and low-speed near-target conditions, with reproducible regression tests;
- Freeze the single-robot interfaces only after safety, stability, and diagnostics meet project requirements.
Install dependencies in a Python environment managed by your team:
### Stage 4: Consider Multi-Robot Scenarios
```powershell
python -m pip install -r data_process\requirements.txt
```
- Once the single-robot interfaces are stable, design vehicle identity, communication, heartbeats, timeouts, and disconnect fallback behavior;
- Then implement formation control, synchronized actions, relative-pose correction, and multi-robot safety policies;
- Re-review all legacy multi-robot parameters; the current `#if false` block is not evidence of completed functionality.
Generate trajectory comparison, tracking error, speed response, and angular-command plots for one or more CSV files:
```powershell
python data_process\run_all_plots.py "path\trial1.csv" "path\trial2.csv" --output-dir "path\plots"
```
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.
## 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;
- 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.
## Contributing
1. Confirm the applicable roadmap stage before making a change; current contributions should prioritize basic single-robot functions.
2. Preserve the boundary between `ClumsyPilot` and `MedullaAdapter`; hardware protocols should not be implemented directly in upper-layer actions.
3. Document units, defaults, applicable vehicle types, and safe ranges for new hardware parameters.
4. Run at least `dotnet build ParkingRobot.sln` before submitting and record the host or physical-test conditions used.
5. The team still needs to document its branch, code-review, and release processes.
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.
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`.
6. The team still needs to document its branch, review, and release processes.
## License