# 运控标定现场 CSV 协议

本协议是现场运控参数标定数据落盘的固定格式。`replay_control_smoke.py` 会在写入 `dataset_index.yaml` 前校验这些列，真实采集程序也应输出相同格式。

## control/control_eval.csv

用途：记录控制器执行评估任务时的目标、实测、控制输出和误差。

`chassis_type` 取值：`ackermann`、`differential`、`single_steer_wheel`、`multi_steer_wheel`。

`task_type` 取值：`trajectory_tracking`、`velocity_step`、`acceleration_deceleration`、`stop_accuracy`。

`control_axis` 取值：`lateral_control`、`longitudinal_control`、`combined`。

`controller_algorithm` 取值：`pid`、`mpc`、`lqr`、`pure_pursuit`。

`control_role` 取值：`path_tracking_outer_loop`、`speed_loop`、`acceleration_loop`、`heading_loop`、`yaw_rate_loop`、`steering_angle_inner_loop`、`module_steering_inner_loop`、`wheel_speed_inner_loop`、`multi_loop_pid`。

约束：`pid` 可以配合 `lateral_control` 或 `longitudinal_control`，但参数输出中必须通过 `control_role` 和 `loop_name` 明确具体回路，例如 `speed_loop/speed`、`heading_loop/heading`、`yaw_rate_loop/yaw_rate` 或 `steering_angle_inner_loop/steering_angle`。

必需列：

- `hardware_timestamp_us`
- `chassis_type`
- `task_type`
- `control_axis`
- `controller_algorithm`
- `control_role`
- `target_x_m`
- `target_y_m`
- `target_yaw_rad`
- `target_velocity_ms`
- `measured_x_m`
- `measured_y_m`
- `measured_yaw_rad`
- `measured_velocity_ms`
- `lateral_error_m`
- `heading_error_rad`
- `speed_error_ms`
- `control_output_steer_rad`
- `control_output_accel_ms2`
- `control_output_brake`
- `saturation_flag`
- `active_job_id`
- `diagnostics_json`

## control/reference_signal.csv

用途：记录本次评估任务的参考轨迹、参考速度、参考加速度和停车要求。

必需列：

- `reference_timestamp_us`
- `task_type`
- `sequence_index`
- `target_x_m`
- `target_y_m`
- `target_yaw_rad`
- `target_velocity_ms`
- `target_accel_ms2`
- `curvature_1pm`
- `stop_required`
- `active_job_id`

## control/chassis_response.csv

用途：记录执行运控评估时的底盘实际响应，算法用它区分控制器问题和底盘执行问题。

必需列：

- `hardware_timestamp_us`
- `odom_x_m`
- `odom_y_m`
- `odom_yaw_rad`
- `linear_velocity_ms`
- `angular_velocity_rads`
- `steering_angle_rad`
- `accel_ms2`
- `brake_state`
- `driver_error_code`
- `active_job_id`

## external/truth_trajectory.csv

用途：记录车间外部真值定位输出的车辆轨迹，用于控制误差验收和时序对齐。

必需列：

- `hardware_timestamp_us`
- `pose_valid`
- `x_m`
- `y_m`
- `z_m`
- `roll_rad`
- `pitch_rad`
- `yaw_rad`
- `position_stddev_m`
- `yaw_stddev_rad`
- `tracking_loss_ratio`
- `time_sync_offset_ms`
- `quality_score`
- `observed_target_count`
- `reference_source_name`
- `active_job_id`

## dataset_index.yaml 写入字段

运控数据应写入：

```yaml
data_inputs:
  control:
    control_evaluation_data_files:
      - control/control_eval.csv
    reference_signal_files:
      - control/reference_signal.csv
    chassis_response_files:
      - control/chassis_response.csv
    truth_trajectory_files:
      - external/truth_trajectory.csv
```

会话收尾工具会把这些字段转换成 `control_calibration_service` 的 `data_input.*` ROS 参数。
