# 底盘标定 CSV 字段协议

本协议是现场底盘标定数据落盘的固定格式。`capture_chassis_session.py` 和 `replay_chassis_smoke.py` 会在写入 `dataset_index.yaml` 前校验这些列。

## 通用约定

- 文件编码：UTF-8。
- 分隔符：英文逗号。
- 表头：必须包含本协议列名；允许增加额外列，但算法模板只承诺读取本协议列。
- 时间基：`hardware_timestamp_us` 和 `command_timestamp_us` 均为 Unix 微秒时间戳，必须来自同一套车间时钟或已完成时间同步换算。
- 坐标系：`truth_trajectory.csv` 中的位姿表示 `base_link` 在 `workshop` 坐标系下的位姿。
- 角度单位：字段名带 `_rad` 的单位为弧度，字段名带 `_deg` 的单位为角度。
- 布尔值：使用 `0/1`，也允许 `true/false`。
- 空值：数值字段不允许为空；没有对应实测值时写 `0`，并在诊断文件中说明。

## chassis_motion.csv

路径约定：`chassis/chassis_motion.csv`

| 字段 | 类型 | 单位 | 说明 |
| --- | --- | --- | --- |
| `hardware_timestamp_us` | int64 | us | 底盘遥测硬件时间戳。 |
| `chassis_type` | string | 无 | `ackermann`、`differential`、`single_steer_wheel`、`multi_steer_wheel`。 |
| `odom_x_m` | float64 | m | 车端里程计 X。 |
| `odom_y_m` | float64 | m | 车端里程计 Y。 |
| `odom_yaw_rad` | float64 | rad | 车端里程计偏航角。 |
| `linear_velocity_ms` | float64 | m/s | 实际线速度。 |
| `angular_velocity_rads` | float64 | rad/s | 实际角速度。 |
| `estop_engaged` | bool | 无 | 急停是否触发。 |
| `driver_error_code` | uint32 | 无 | 底盘驱动错误码。 |
| `active_job_id` | string | 无 | 当前底盘动作任务 ID。 |
| `lateral_slip_estimate` | float64 | 无 | 估计横向滑移。 |
| `curvature_estimate` | float64 | 1/m | 估计曲率。 |
| `module_states_json` | JSON array | 无 | 轮/舵模块数组，每个元素包含 `module_id`、`encoder_ticks`、`wheel_speed_rpm`、`steer_angle_deg`、`motor_current_amp`。 |

## actuator_commands.csv

路径约定：`chassis/actuator_commands.csv`

| 字段 | 类型 | 单位 | 说明 |
| --- | --- | --- | --- |
| `command_timestamp_us` | int64 | us | 命令下发时间戳。 |
| `command_id` | string | 无 | 命令 ID。 |
| `source` | string | 无 | 命令来源，例如 `vehicle_agent`、`planned_command`。 |
| `target_speed_ms` | float64 | m/s | 目标速度。 |
| `target_distance_m` | float64 | m | 目标距离；实时底层命令没有该值时写本次动作原语计划距离或 `0`。 |
| `target_accel_ms2` | float64 | m/s^2 | 目标加速度；没有该值时写 `0`。 |
| `target_steering_angle_rad` | float64 | rad | 阿克曼或舵轮目标转角；差速轮无转角时写 `0`。 |
| `target_steering_rate_rads` | float64 | rad/s | 目标转角速度；没有该值时写 `0`。 |
| `brake_command` | float64 | 无 | 制动命令，范围建议为 `[0, 1]`。 |
| `throttle_command` | float64 | 无 | 驱动命令，范围建议为 `[0, 1]`。 |
| `command_timeout_sec` | float64 | s | 命令超时时间；没有该值时写 `0`。 |

## truth_trajectory.csv

路径约定：`external/truth_trajectory.csv`

| 字段 | 类型 | 单位 | 说明 |
| --- | --- | --- | --- |
| `hardware_timestamp_us` | int64 | us | 外部真值观测时间戳。 |
| `pose_valid` | bool | 无 | 位姿是否有效。 |
| `x_m` | float64 | m | `base_link` 在 `workshop` 下的 X。 |
| `y_m` | float64 | m | `base_link` 在 `workshop` 下的 Y。 |
| `z_m` | float64 | m | `base_link` 在 `workshop` 下的 Z。 |
| `roll_rad` | float64 | rad | 横滚角。 |
| `pitch_rad` | float64 | rad | 俯仰角。 |
| `yaw_rad` | float64 | rad | 偏航角。 |
| `position_stddev_m` | float64 | m | 位置标准差。 |
| `yaw_stddev_rad` | float64 | rad | 航向标准差。 |
| `tracking_loss_ratio` | float64 | 无 | 跟踪丢失比例。 |
| `time_sync_offset_ms` | float64 | ms | 外部真值与车端时钟偏差。 |
| `quality_score` | float64 | 无 | 外部真值质量分。 |
| `observed_target_count` | uint32 | 个 | 当前观测到的标定目标数量。 |
| `reference_source_name` | string | 无 | 外部真值来源名称。 |
| `active_job_id` | string | 无 | 当前底盘动作任务 ID。 |
