11 KiB
汽车数字孪生系统
主控程序和Unity数据交互协议文档
一、系统交互
系统由两台独立主机组成：
• 主控程序（负责传感器数据采集、系统控制、数据记录存储等）
• Unity数字孪生（负责三维场景渲染、运动计算、视频录制）
数据流向：
| 数据类型 | 方向 | 频率 | 说明 |
| InitConfig | 主控 → Unity | 1次/任务 | 初始化车辆、驾驶员、场景配置 |
| Command | 主控 → Unity | 低频 | 开始/停止/暂停等控制指令 |
| DriveData | 主控 → Unity | 50Hz | 传感器数据驱动虚拟车运动 |
| FrameRecord | Unity → 主控 | 50Hz | 车辆位置记录用于回放 |
| Status | Unity → 主控 | 按需 | Unity运行状态反馈 |
二、InitConfig - 初始化配置
方向：主控 → Unity
频率：任务开始时发送 1 次
用途：配置车辆信息、驾驶员信息、场景参数、录制设置
{
"msgType": "init", // 消息类型：初始化配置
"timestamp": 1737388800000, // 发送时间戳
"session": { // ===== 会话信息 =====
"sessionId": "sess_20250120_143000_001", // 会话唯一ID
"taskId": "task_brake_001", // 任务ID
"taskName": "紧急制动测试", // 任务名称（显示用）
"createTime": "2025-01-20 14:30:00", // 创建时间（可读格式）
"syncTimestamp": 1737388800000 // 同步基准时间戳（数据/视频对齐用）
},
"driver": { // ===== 驾驶员信息 =====
"driverId": "D20250001", // 驾驶员编号
"name": "张三", // 驾驶员姓名
"department": "培训一部", // 所属部门
"level": "初级学员", // 学员等级/身份
"avatar": "" // 头像URL（或预制）
},
"vehicle": { // ===== 车辆配置 =====
"vehicleId": "V003", // 车辆编号
"model": "改装教学车A型", // 车型名称
"plateNo": "沪A·12345", // 车牌号
"color": "#FFFFFF", // 车身颜色（十六进制）
"colorName": "珍珠白" // 颜色名称（显示用）
},
"scene": { // ===== 场景配置 =====
"sceneId": "scene_03", // 场景ID
"sceneName": "城市道路", // 场景名称
"sceneFile": "CityRoad", // Unity场景文件名
"weather": "sunny", // 天气：sunny/rain/fog/night
"spawnPoint": "SpawnPoint_A", // 出生点预制体名称
"hasGpsMapping": true // 该场景是否有GPS坐标映射
},
"recording": { // ===== 录制设置 =====
"enabled": true, // 是否启用录制
"recordId": "rec_20250120_143000_001", // 录制ID（与视频文件关联）
"frameRate": 50, // 数据录制帧率
"videoFrameRate": 30, // 视频录制帧率
"videoResolution": "1280x720" // 视频分辨率
},
"vehicleParams": { // ===== 车辆物理参数 =====
"wheelRadius": 0.32, // 轮胎半径（米）
"steeringRatio": 15.5, // 方向盘转向比
"wheelbase": 2.68 // 轴距（米）
}
}
三、Command - 控制指令
方向：主控 → Unity
频率：低频，人工触发时发送
用途：系统控制、模式切换、回放控制、相机和UI控制
{
"msgType": "command", // 消息类型：控制指令
"timestamp": 1737388800000, // 发送时间戳
"seqId": 1, // 指令序列号（递增）
"action": "start", // ===== 主动作 =====
// start - 开始任务
// stop - 停止任务
// pause - 暂停
// resume - 恢复
// reset - 重置到起点
// emergency_stop - 紧急制动
"mode": { // ===== 模式设置（可选）=====
"type": "realtime", // realtime - 实时驱动模式
// playback - 回放模式
// standby - 待机模式
"playbackId": null // 回放模式时指定录制ID
},
"playback": { // ===== 回放控制（回放模式有效）=====
"action": "play", // play/pause/seek/setSpeed
"seekFrame": 0, // 跳转到指定帧号
"seekTime": 0.0, // 跳转到指定时间（秒）
"playSpeed": 1.0 // 播放速度倍率
},
"camera": { // ===== 相机控制（可选）=====
"viewMode": "chase", // driver - 驾驶员视角
// chase - 追尾视角
"fov": 60 // 视野角度
},
"ui": { // ===== UI控制（暂定，根据UI调整）=====
"showDashboard": true, // 显示仪表盘
"showTelemetry": true, // 显示遥测数据面板
"showTrajectory": false, // 显示行驶轨迹线
"showMinimap": true // 显示小地图
}
}
四、DriveData - 实时驱动数据
方向：主控 → Unity
频率：50Hz（每 20ms 一帧）
用途：传感器数据驱动Unity虚拟车辆运动
{
"msgType": "drive", // 消息类型：驱动数据
"ts": 1737388800123, // 时间戳（毫秒）
"seq": 50001, // 帧序列号（递增，丢帧检测用）
// ==================== 运动控制核心 ====================
"speed": 45.6, // 车速（km/h）
"steer": 12.5, // 方向盘角度（度）左负右正
"wheelRpm": { // 各轮转速（rpm）
"fl": 650.0, // 左前轮 Front-Left
"fr": 652.0, // 右前轮 Front-Right
"rl": 648.0, // 左后轮 Rear-Left
"rr": 649.0 // 右后轮 Rear-Right
},
// ==================== 踏板状态 ====================
"throttle": 0.35, // 油门/电门开度 0.0~1.0
"brake": 0.0, // 刹车开度 0.0~1.0
"handbrake": 0.0, // 手刹开度 0.0~1.0
// ==================== 传动系统 ====================
"gear": 3, // 挡位：-1倒挡/0空挡/1~N前进挡
"engine": { // 发动机/电机数据（可选）
"rpm": 2800, // 转速（rpm）（可选）
"torque": 180.5 // 输出扭矩（N·m）（可选）
},
// ==================== IMU数据（可选）====================
"imu": { // 惯性测量单元
"ax": 0.15, // X轴加速度（m/s²）纵向
"ay": -0.02, // Y轴加速度（m/s²）垂直
"az": 0.05, // Z轴加速度（m/s²）横向
"gx": 0.01, // X轴角速度（rad/s）俯仰
"gy": 0.005, // Y轴角速度（rad/s）横滚
"gz": 0.12 // Z轴角速度（rad/s）偏航
},
// ==================== 车灯状态 ====================
"lights": { // 车灯
"head": 1, // 大灯：0关/1近光/2远光
"turn": 0, // 转向灯：0关/1左/2右/3双闪
"brake": false, // 刹车灯
"reverse": false, // 倒车灯
"fog": false // 雾灯
},
// ==================== 其他状态 ====================
"misc": { // 其他
"horn": false, // 喇叭
"wiper": 0, // 雨刷：0关/1低速/2高速
"seatbelt": true // 安全带是否系好
}
}
五、FrameRecord - 帧记录数据
方向：Unity → 主控
频率：50Hz（每 20ms 一帧）
用途：记录Unity计算的车辆绝对位置，用于精确回放
{
"msgType": "frame", // 消息类型：帧记录
"ts": 1737388800123, // 时间戳（毫秒）
"seq": 50001, // 帧序列号（与DriveData对应）
"elapsed": 100.02, // 相对任务开始的时间（秒）
// ==================== 车辆位置（Unity世界坐标）====================
"pos": { // 位置
"x": 1250.35, // X坐标（米）
"y": 0.42, // Y坐标/高度（米）
"z": 3560.78 // Z坐标（米）
},
// ==================== 车辆旋转 ====================
"rot": { // 旋转（四元数）程序用
"x": 0.0,
"y": 0.383,
"z": 0.0,
"w": 0.924
},
"euler": { // 旋转（欧拉角，度）便于查看
"pitch": 0.5, // 俯仰角（抬头为正）
"yaw": 45.2, // 偏航角/航向（顺时针为正）
"roll": -0.1 // 横滚角（右倾为正）
},
// ==================== 速度向量 ====================
"vel": { // 速度
"x": 32.1, // X方向速度（m/s）
"y": 0.0, // Y方向速度（m/s）
"z": 31.8, // Z方向速度（m/s）
"speed": 45.2 // 合速度（km/h）
},
// ==================== 车轮状态（视觉还原用）====================
"wheels": { // 车轮
"steerAngle": 12.5, // 前轮实际转向角（度）
"fl": { // 左前轮
"rot": 1250.6, // 累计旋转角度（度）
"susp": 0.05 // 悬挂压缩量（米）
},
"fr": { // 右前轮
"rot": 1252.1,
"susp": 0.04
},
"rl": { // 左后轮
"rot": 1248.3,
"susp": 0.03
},
"rr": { // 右后轮
"rot": 1249.0,
"susp": 0.03
}
},
// ==================== 视觉状态 ====================
"visual": { // 视觉状态
"gear": 3, // 挡位显示
"steerWheel": 45.0, // 方向盘角度（内饰视角用）
"speedometer": 45.6, // 速度表读数
"tachometer": 2800, // 转速表读数
"lights": { // 车灯状态
"head": 1,
"turn": 0,
"brake": false,
"reverse": false
}
},
// ==================== GPS显示数据（学校场景用） ====================
"gps": { // GPS坐标（从Unity坐标换算）
"valid": true, // 该场景是否有GPS映射
"lat": 31.230416, // 纬度
"lng": 121.473701, // 经度
"alt": 4.5, // 海拔（米）
"heading": 45.2 // GPS航向（度）
}
}
六、Status - Unity状态反馈
方向：Unity → 主控
频率：状态变化时发送，或主控查询时响应
用途：反馈Unity运行状态、性能指标、错误信息
{
"msgType": "status", // 消息类型：状态反馈
"ts": 1737388800000, // 时间戳
"state": "running", // ===== Unity当前状态 =====
// loading - 加载场景中
// ready - 就绪，等待开始
// running - 任务运行中
// paused - 已暂停
// stopped - 已停止
// playback - 回放中
// error - 出错
"scene": { // ===== 场景状态 =====
"loaded": true, // 场景是否加载完成
"sceneId": "scene_03", // 当前场景ID
"spawnPointFound": true // 出生点预制体是否找到
},
"recording": { // ===== 录制状态 =====
"isRecording": true, // 是否正在录制
"recordId": "rec_20250120_143000_001", // 当前录制ID
"frameCount": 15000, // 已录制帧数
"duration": 300.0 // 已录制时长（秒）
},
"performance": { // ===== 性能指标 =====
"fps": 58, // 当前帧率
"renderTime": 12.5, // 渲染耗时（ms）
"physicsTime": 2.3, // 物理计算耗时（ms）
"encodeTime": 8.2 // 视频编码耗时（ms）
},
"connection": { // ===== 连接状态 =====
"lastDriveDataSeq": 50001, // 最后收到的DriveData序列号
"lastDriveDataTime": 1737388800123, // 最后收到DriveData的时间
"dataLossCount": 0 // 累计丢帧数
},
"error": { // ===== 错误信息 =====
"code": 0, // 错误码：0表示无错误
"message": "" // 错误描述
}
}
状态汇总：
车灯状态
| 字段 | 值 | 说明 |
| head | 0 / 1 / 2 | 大灯：关 / 近光 / 远光 |
| turn | 0 / 1 / 2 / 3 | 转向灯：关 / 左 / 右 / 双闪 |
| wiper | 0 / 1 / 2 | 雨刷：关 / 低速 / 高速 |
| gear | -1 / 0 / 1~N | 挡位：倒挡 / 空挡(N/P) / 前进挡 |
Unity状态
| state值 | 说明 |
| loading | 加载场景中 |
| ready | 就绪，等待开始指令 |
| running | 任务运行中（实时模式） |
| paused | 已暂停 |
| stopped | 已停止 |
| playback | 回放模式运行中 |
| error | 发生错误 |
天气
| weather值 | 说明 |
| sunny | 晴天 |
| rain | 雨天 |
| fog | 雾天 |
| night | 夜间 |