# 汽车数字孪生系统

主控程序和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 | 夜间 |