📚 课程目录第4章 EyeQ软件架构与量产交付包解析

4. EyeQ软件架构与量产交付包解析

EyeQ 平台上的量产软件并不是一个“大程序”，而是由多个可独立编译、独立标定、独立升级的功能模块，通过一套稳定的接口契约组合而成。理解这套架构，是读懂交付包、定位配置项、判断标定数据归属的前提。本节从模块划分入手，再落到交付包的目录组织、配置文件与标定数据的实际组织方式。

一、感知、规划、控制三层模块划分

EyeQ 软件在逻辑上通常划分为三层：感知层（Perception）、规划层（Planning）与控制层（Control）。三层之间通过明确定义的数据结构通信，而不是直接函数调用，这样每一层都可以独立替换或升级。

感知层负责把摄像头、雷达等原始输入转换为环境模型。在 EyeQ 上，感知层通常包含图像预处理、目标检测（车辆、行人、车道线、交通标志）、目标跟踪与融合、以及自车状态估计。感知层的输出不是图像，而是结构化的目标列表与车道模型，例如每个目标包含 ID、类别、位置、速度、置信度、跟踪状态等字段。

规划层接收感知层的环境模型，结合导航信息与自车状态，生成行驶决策与轨迹。规划层内部一般再分为行为决策（是否变道、跟车、避让）与轨迹规划（生成带时间戳的路径点序列）。规划层的输出是轨迹点、目标加速度/曲率等控制期望值。

控制层把规划层的期望值转换为执行器可接受的指令，例如转向角、驱动扭矩、制动压力。控制层需要处理执行器特性、延迟补偿与安全限幅，其输出直接作用于车辆总线。

三层之间的接口通常以“接口版本号 + 数据结构定义”的方式固化。量产项目中，任何一层的数据结构变更都必须同步更新接口版本，否则会出现“感知输出字段与规划输入字段不匹配”的典型集成故障。

二、交付包目录结构

量产交付包通常以“模块目录 + 公共目录 + 标定目录 + 启动脚本”的方式组织。一个典型的 EyeQ 交付包根目录如下：

eyeq_release_v2.1.0/
├── perception/
│   ├── libperception.so
│   ├── perception_cfg.json
│   └── calib_camera.bin
├── planning/
│   ├── libplanning.so
│   ├── planning_cfg.json
│   └── behavior_param.yaml
├── control/
│   ├── libcontrol.so
│   ├── control_cfg.json
│   └── actuator_calib.bin
├── common/
│   ├── interface_v2.1.h
│   ├── vehicle_param.json
│   └── diagnostic_cfg.xml
├── calibration/
│   ├── camera_intrinsic.bin
│   ├── camera_extrinsic.bin
│   └── radar_extrinsic.bin
├── scripts/
│   ├── start.sh
│   └── health_check.sh
└── manifest.json

这个结构的关键在于：每个模块的库文件、配置文件和标定文件放在同一目录下，便于按模块独立升级。公共接口头文件放在 common/ 下，确保三层引用同一版本。calibration/ 目录集中存放跨模块共用的标定数据，避免同一份相机外参在多个模块中重复维护。manifest.json 记录整个交付包的版本、各模块版本、校验和与依赖关系，是集成时首先检查的文件。

三、配置文件组织方式

配置文件按“模块级 + 参数级”两层组织。模块级配置（如 perception_cfg.json）定义该模块启用的功能、输入输出话题、运行频率等；参数级配置（如 behavior_param.yaml）定义具体算法参数。以感知模块为例：

{
  "module": "perception",
  "version": "2.1.0",
  "inputs": ["camera_front", "radar_front"],
  "outputs": ["object_list", "lane_model"],
  "frequency_hz": 30,
  "features": {
    "pedestrian_detection": true,
    "traffic_sign": true,
    "lane_detection": true
  },
  "confidence_threshold": 0.65
}

配置文件的读取顺序通常是：默认配置 → 车型配置 → 项目配置 → 现场标定覆盖。后加载的配置覆盖先加载的同名参数。这种分层覆盖机制使得同一套软件可以适配不同车型，只需替换车型配置层，而不必修改代码。

配置覆盖顺序必须在集成前确认。若现场标定覆盖了 confidence_threshold，而集成人员仍按默认值排查问题，会得到错误结论。建议在 manifest.json 中记录每层配置的实际来源路径。

四、标定数据组织方式

标定数据分为两类：传感器标定与执行器标定。传感器标定包括相机内参（焦距、主点、畸变系数）、相机外参（相对车辆坐标系的旋转与平移）、雷达外参。执行器标定包括转向角零位、转向比、制动踏板与减速度的对应关系、驱动扭矩与加速度的对应关系。

标定数据通常以二进制文件（.bin）存储，原因是数据量大且需要精确的浮点表示。文件内部按固定结构排列，例如相机内参文件包含 3×3 内参矩阵、5 个畸变系数、图像宽高。集成时必须确认标定文件的版本与软件版本匹配，否则会出现“标定文件解析失败”或“标定值被错误解释”的问题。

标定数据的加载时机一般在模块初始化阶段。感知模块加载相机标定，控制模块加载执行器标定。若标定文件缺失或校验失败，模块应进入安全降级状态，而不是使用默认值继续运行。这一点在量产交付中必须通过 health_check.sh 显式检查。

标定文件与配置文件不同：配置文件可以分层覆盖，标定文件通常整体替换。不要试图只修改标定文件中的某一个系数，而应重新生成完整标定文件并更新校验和。

五、集成时的检查要点

拿到交付包后，建议按以下顺序检查：先读 manifest.json 确认版本与校验和；再检查 common/interface_v2.1.h 与各模块库文件是否匹配；然后确认 calibration/ 下三类标定文件齐全且版本正确；最后运行 health_check.sh，观察各模块是否正常加载配置与标定。若某一层报“接口版本不匹配”，优先检查 common/ 下的头文件版本，而不是修改模块代码。

理解这套“三层模块 + 目录映射 + 分层配置 + 整体标定”的组织方式，就能在集成现场快速判断一个问题属于配置层、标定层还是接口层，从而把排查范围从整个交付包缩小到具体文件。