ParkingRobot/README_en.md

# MyParking Parking Robot

[简体中文](README.md) | [English](README_en.md)

## Rewrite Notice

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:

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.

**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.

## 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.

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.

## Current Scope

| 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 |

## Software Structure

```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
```

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.

## 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
```

## 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.

No ROS/ROS 2, Docker, or standalone simulation launch configuration was found in the repository.

## Build

Run from the repository root:

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

Primary output locations:

```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.

## Runtime and Configuration

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.

MCU defaults confirmed from the current source are:

| 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 |

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.

## Single-Robot Validation

`MovementTests.cs` registers these manual tests in the Clumsy test interface:

- `测试终点跟踪动作-前进`: 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.

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.

## Development Roadmap

### Stage 1: Basic Single-Robot Functions (Current)

- 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.

### Stage 2: Add Parking-Operation Features

- 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.

### Stage 3: Improve Tracking

- 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.

### Stage 4: Consider Multi-Robot Scenarios

- 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.

## 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.

## License

No license file is currently included. Use and distribution must follow internal company policy.