Initial commit from MyParking project
This commit is contained in:
+264
@@ -0,0 +1,264 @@
|
||||
# MyParking Parking Robot
|
||||
|
||||
[简体中文](README.md) | [English](README_en.md)
|
||||
|
||||
## Rewrite Roadmap and Current Status
|
||||
|
||||
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 tracking with simulation, 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.
|
||||
|
||||
| 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# 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 main components are:
|
||||
|
||||
- `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.
|
||||
|
||||
No ROS/ROS 2 or Docker configuration is present.
|
||||
|
||||
## 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
|
||||
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
|
||||
```
|
||||
|
||||
`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
|
||||
├── 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 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.
|
||||
|
||||
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
|
||||
|
||||
### 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 outputs:
|
||||
|
||||
```text
|
||||
ClumsyPilot/build/Clumsy/ClumsyPilot.dll
|
||||
MedullaAdapter/build/Medulla/plugins/MedullaAdapter.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.
|
||||
|
||||
## 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 | 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` |
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Single-Robot Test Entries
|
||||
|
||||
`ClumsyPilot/MovementTests.cs` currently registers:
|
||||
|
||||
- `准备：四个舵轮与车头方向一致`
|
||||
- `SendMotion：连续前进4m`
|
||||
- `SendXYThSpeed：原地自转90°`
|
||||
- `SendXYThSpeed：原地自转180°`
|
||||
- `SendMotion：左转90°半径2m圆弧`
|
||||
- `SendMotion：蟹行直线4m`
|
||||
- `SendMotion：蟹行左转90°半径2m圆弧`
|
||||
- `SendMotion：4m S型曲线`
|
||||
- `夹臂关闭测试`
|
||||
- `夹臂启动测试`
|
||||
|
||||
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.
|
||||
|
||||
## Experiment Data Analysis
|
||||
|
||||
The tracking recorder saves CSV files under the host application's:
|
||||
|
||||
```text
|
||||
TrackingExperiments/
|
||||
```
|
||||
|
||||
Medulla wheel-speed diagnostics can be controlled with the `StartWheelSpeedDiagnostic` and `StopWheelSpeedDiagnostic` utility buttons. Their default output directory is:
|
||||
|
||||
```text
|
||||
logs/wheel-speed/
|
||||
```
|
||||
|
||||
Install dependencies in a Python environment managed by your team:
|
||||
|
||||
```powershell
|
||||
python -m pip install -r data_process\requirements.txt
|
||||
```
|
||||
|
||||
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. 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
|
||||
|
||||
No license file is currently included. Use and distribution must follow internal company policy.
|
||||
Reference in New Issue
Block a user