# YRobot Motor Control Panel

Rust/egui desktop tool for YRobot motor debugging. It supports direct BLE and USB Dongle transport, motor control commands, realtime debug plots, CSV recording, and session statistics.

## Build

Windows executable:

```bash
cargo build --release --target x86_64-pc-windows-gnu
```

Output:

```text
target/x86_64-pc-windows-gnu/release/yrobot-motor-control-panel.exe
```

Run tests for the Windows target:

```bash
cargo test --target x86_64-pc-windows-gnu
```

Run the full local verification gate:

```bash
./scripts/verify.sh
```

## Minimal Project Files

To hand the project to another developer, keep these tracked files:

- `Cargo.toml`
- `Cargo.lock`
- `docs/`
- `README.md`
- `scripts/`
- `src/`

Do not include local/generated directories such as `target/`, `.agents/`, `.claude/`, or `.codegraph/`.

## Use

1. Select `BLE` or `USB Dongle`.
2. Select `Left`, `Right`, or `Neutral` before connecting.
3. BLE: click `Scan / Refresh`, select a device, then `Connect BLE`. Use `Stop Scan` to stop discovery.
4. USB Dongle: refresh/select a serial port, then `Open USB`. The serial session uses `115200 8N1`.
5. After connection, use motor controls, realtime debug, CSV recording, and status/statistics panels.

Heartbeat starts only after BLE notify subscription or USB serial open succeeds, and stops when the session is disconnected.
CSV recording is flushed and closed when recording is stopped or the session ends.
The status panel shows live metrics and the latest error summary for the current session.
Closing the app cancels scans, disconnects the active session, and closes any active CSV recorder.

## Protocol Notes

- BLE uses Nordic UART characteristics:
  - TX: `6e400002-b5a3-f393-e0a9-e50e24dcca9e`
  - RX notify: `6e400003-b5a3-f393-e0a9-e50e24dcca9e`
- USB Dongle downlink wraps motor payload as `5A A5 + DEV(0x31) + LEN + PAYLOAD + CRC8/MAXIM`.
- USB Dongle uplink extracts `seq_id(2B LE)` and `dt_ms(2B LE)` before motor protocol parsing.

## Verification

Current automated checks cover data model defaults/serde, protocol encode/decode, heartbeat cancel/error behavior, parameter validation, tuning packet reassembly, debug-field error marking, communication-event logging, CSV writing/no-op/error paths, session-end/app-close recorder cleanup, host interval statistics, USB `seq_id`/`dt_ms` statistics, and simulated BLE/USB receive paths into chart/statistics.

Hardware validation still requires a real YRobot motor and USB Dongle:

- BLE scan/connect/notify/write.
- 2s heartbeat under real connection.
- Motor parameter set/query.
- Realtime debug stream at device rate.
- USB Dongle serial open, wrapping/unwrapping, `seq_id`/`dt_ms` diagnostics.
- Long-run stability on the target machine.

Use [docs/hardware-validation.md](docs/hardware-validation.md) to record final hardware acceptance.