第6章 系统架构总览¶

逐行解读

• string number：数字识别结果，如 "3" 表示 3 号步兵，"outpost" 表示前哨站。与旧版不同，2027版使用字符串而非 uint8，可以表示更复杂的标识符（如哨兵、前哨站等特殊单位）。
• string type：装甲板类型，"small" 或 "large"。小装甲是普通步兵，大装甲是英雄机器人。这个信息影响弹道参数选择。
• float32 distance_to_image_center：装甲板中心到图像中心的归一化距离（0.0 ~ 1.0）。当画面中有多个装甲板时，优先选择离画面中心最近的目标，因为那通常是主目标。
• geometry_msgs/Pose pose：装甲板的完整位姿——包含 3D 位置 position (x, y, z) 和四元数朝向 orientation (x, y, z, w)。注意这里使用了 Pose 而非简单的 Point，意味着不仅知道装甲板在哪，还知道它朝哪个方向。这是 PnP 解算的输出结果，坐标系为 camera_optical_frame。

逐行解读

• std_msgs/Header header：标准消息头，包含时间戳 stamp（图像采集时间）和坐标系 ID frame_id（通常是 "camera_optical_frame"）。时间戳至关重要——跟踪器需要用它来计算帧间时间差，用于 EKF 的状态预测。
• Armor[] armors：检测到的所有装甲板的数组。一帧图像中可能检测到 0 到多个装甲板。当机器人背对相机时，可能检测到 2 块装甲板（前后各一）。当阵亡时，可能检测到 0 块。

逐行解读

• std_msgs/Header header：消息头，时间戳为跟踪器预测的目标时刻。
• bool tracking：是否正在跟踪目标。false 表示目标丢失，电控端应保持上一帧的瞄准状态或搜索目标。这是最关键的状态标志。
• string id：目标机器人 ID，与 Armor.msg 的 number 对应。如 "3" 表示正在跟踪 3 号步兵。电控端根据 ID 选择不同的弹道参数表。
• int32 armors_num：目标装甲板总数。4 块 = 普通步兵，3 块 = 前哨站，2 块 = 小陀螺状态。电控端据此建立目标的旋转几何模型。
• geometry_msgs/Point position：目标中心在 odom 坐标系下的 3D 位置 (x, y, z)，单位米。这是 EKF 状态向量中的位置分量。
• geometry_msgs/Vector3 velocity：目标中心的速度 (vx, vy, vz)，单位 m/s。这是 EKF 的速度估计值，用于预测弹丸飞行期间目标的位移。
• float64 yaw：目标朝向角（弧度）。想象从上方俯视，目标车头指向的角度。结合 radius_1 和 radius_2 可以算出每块装甲板的具体位置。
• float64 v_yaw：目标角速度（弧度/秒）。正数表示逆时针旋转，负数表示顺时针。用于预测目标旋转到哪个面。
• float64 radius_1：目标中心到前/后装甲板的水平距离（米）。这是目标几何模型的关键参数。
• float64 radius_2：目标中心到左/右装甲板的水平距离（米）。通常 r1 != r2，因为机器人底盘不是正方形。
• float64 dz：上下两层装甲板的高度差（米）。英雄机器人（大装甲）有上下两层装甲板，dz > 0；普通步兵 dz = 0。

逐行解读

导入部分（第1-6行）： - yaml：用于解析 YAML 配置文件 - get_package_share_directory：获取 ROS2 包的 share 目录路径（安装后配置文件的位置） - Command：Launch 框架的字符串拼接工具，用于动态生成 xacro 命令 - Node：Launch 中定义 ROS2 节点的 Action

launch_params 加载（第8-9行）： - 从 rm_vision_bringup 包的 config/launch_params.yaml 读取所有启动参数 - 这些参数控制相机类型、日志级别、串口路径等运行时选项

robot_description 生成（第11-13行）： - 用 xacro 命令解析 URDF 模型文件 rm_gimbal.urdf.xacro - xyz 和 rpy 参数表示相机相对于云台的安装偏移——这会在 common.py 中被 Command 拼接成完整的 xacro 命令 - 生成的 URDF 描述了 gimbal_link → camera_link → camera_optical_frame 的静态 TF 变换

robot_state_publisher（第15-20行）： - 启动 robot_state_publisher 节点，它会根据 URDF 广播静态 TF - publish_frequency: 1000.0 表示以 1000Hz 发布 TF——远高于一般的 50Hz，是为了保证 tracker 查询 TF 时延迟极低

tracker_node（第25-32行）： - 定义 armor_tracker 节点，加载 node_params.yaml 中的参数 - emulate_tty=True：模拟终端，确保日志颜色输出正常 - ros_arguments：通过命令行覆盖日志级别，方便调试时动态调整

逐行解读

• 第1-2行：导入标准库 os（路径操作）和 sys（修改 Python 模块搜索路径）
• 第3行：获取 rm_vision_bringup 包的 share 目录
• 第4行：将 launch/ 目录加入 Python 路径，这样后续 from common import ... 才能找到 common.py 模块。这是一个常见的 Launch 文件技巧。

逐行解读

• generate_launch_description()：ROS2 Launch 系统的入口函数，必须返回一个 LaunchDescription 对象
• from common import ...：在函数内部导入 common.py 中预定义的变量。在函数内而非文件顶部导入，是因为 Launch 系统会在导入阶段就执行模块级代码，放在函数内可以延迟执行
• ComposableNode：可组合节点描述——定义一个可以和其他 Component 共享进程的节点
• ComposableNodeContainer：组件容器——一个进程，多个 Component 在其中共享内存
• TimerAction：定时触发动作，用于延迟启动某些节点
• Shutdown：当节点退出时触发整个 Launch 系统关闭

逐行解读

• 第1行：工厂函数，根据包名和插件名创建相机组件节点。支持海康(hik_camera)和迈德威视(mindvision_camera)两种相机
• package：相机驱动所在的 ROS2 包名
• plugin：插件类的全限定名，如 hik_camera::HikCameraNode，这是 Component 注册时用的名字
• name='camera_node'：节点在 ROS2 图中的名称
• parameters=[node_params]：加载 node_params.yaml 中的参数（曝光时间、增益等）
• use_intra_process_comms: True：关键优化！ 开启进程内通信，使该节点与同容器内的其他节点共享内存，避免图像数据的序列化/拷贝

逐行解读

• name='camera_detector_container'：容器进程名称，便于 ros2 node list 时识别
• namespace=''：使用全局命名空间（无前缀）
• executable='component_container'：使用单线程组件容器（component_container_mt 为多线程版）
• composable_node_descriptions：要在容器中加载的组件列表
  • camera_node：上面创建的相机组件——在进程内直接传递图像指针
  • ArmorDetectorNode：检测器组件，与相机共享进程
  • 两个节点都开启了 use_intra_process_comms，形成 零拷贝通信链路
• output='both'：同时输出到终端和日志文件
• emulate_tty=True：模拟终端，保留彩色日志输出
• ros_arguments：通过 --log-level 设置检测器的日志级别，值来自 launch_params.yaml
• on_exit=Shutdown()：如果容器进程意外退出，关闭整个 Launch 系统——因为没有检测器，整个自瞄链路就断了，不如直接重启

逐行解读

• 第1-2行：分别创建海康和迈德威视两种相机的组件节点描述
• 第4-7行：根据 launch_params.yaml 中的 camera 字段选择使用哪种相机。'hik' = 海康，'mv' = 迈德威视。选好后，将相机节点和检测器节点打包进同一个组件容器
• 这种工厂模式使得切换相机只需改配置文件，无需修改代码

逐行解读

serial_driver_node（第1-10行）： - 这是一个 普通节点（不是 Component），因为串口驱动需要独立进程——它有专用的 IO 线程和阻塞式读取 - on_exit=Shutdown()：串口断开意味着与电控失联，必须触发系统重启 - 日志级别由 launch_params 控制

delay_serial_node（第12-15行）： - TimerAction(period=1.5, ...)：延迟 1.5 秒 后再启动串口驱动 - 原因：STM32 上电初始化需要时间，过早打开串口会连接失败

delay_tracker_node（第16-19行）： - 延迟 2.0 秒 后启动跟踪器 - 原因：tracker 需要等待串口驱动广播 odom → gimbal_link 的 TF 变换后才能正常工作

逐行解读

decision_node（第1-15行）： - rm_decision 是一个独立的决策节点，负责根据比赛状态做出自主决策 - hp_threshold: 200.0：血量阈值——当己方血量低于 200 时触发特定行为（如撤退） - hp_recovery_ratio: 0.90：血量恢复比例——血量恢复到 90% 才重新进攻 - nav_action_name：导航 Action 的名称，用于发送导航目标 - remappings：话题重映射——将 game_status 重映射到 /serial/game_status，从串口驱动接收裁判系统数据

delay_decision_node（第17-20行）： - 延迟 2.5 秒 启动，是所有节点中最晚的 - 原因：决策节点依赖裁判系统数据，需要等串口驱动先启动并开始接收数据

逐行解读

• robot_state_publisher：第一个启动，立即广播静态 TF（gimbal_link → camera_link → camera_optical_frame）
• cam_detector：第二个启动（无延迟），相机 + 检测器是整条链路的源头
• delay_serial_node：1.5 秒后启动串口驱动
• delay_tracker_node：2.0 秒后启动跟踪器
• delay_decision_node：2.5 秒后启动决策节点
• 启动顺序遵循 依赖链：先源头 → 再通信 → 再消费数据 → 最后决策

逐行解读

• uint8_t header = 0xA5：帧头标志，固定为 0xA5。接收方通过扫描连续字节流找到 0xA5 来同步帧边界
• uint16_t data_length = 15：后续数据的长度（不包含 Header 本身）。默认 15 字节
• uint8_t seq = 0：序列号，每发一包递增。接收方可以检测是否丢包（序号不连续就说明丢了）
• uint8_t crc8 = 0：Header 自身的 CRC8 校验。先校验 Header，如果 Header 就错了，整个包直接丢弃，省去解析数据区的开销
• uint16_t cmd_id：命令 ID，标识这个包是什么类型的数据（IMU、裁判系统、底盘数据等）
• __attribute__((packed))：GCC 编译器指令，禁止结构体内存对齐。没有它，编译器会在字段间插入 padding 字节，导致结构体大小与线上协议不匹配，数据解析出错

逐行解读

• Header header：通用帧头，包含 0xA5 标志和命令 ID
• float pitch：云台俯仰角（度），正值向上看。这是瞄准计算的核心输入之一
• float roll：云台横滚角（度），正常情况下接近 0（车身水平时）
• float yaw：云台偏航角（度），相对于 odom 系的旋转角度。serial_driver 用它来广播 odom → gimbal_link 的 TF 变换
• uint8_t roboid：机器人 ID，标识当前是哪台车
• uint8_t id：装甲板 ID 或模式标识
• uint8_t timeseries：测试时间戳，用于调试延迟测量
• uint16_t crc16：对整个包（除 CRC 字段本身）计算的 CRC16 校验

逐行解读

• uint8_t game_info：比赛信息的打包字段。低 4 位存储比赛类型（1v1/3v3/5v5 等），高 4 位存储比赛阶段（未开始/准备/倒计时/进行中/结算）
• uint16_t stage_remain_time：当前阶段剩余时间（秒）。决策节点用它来判断是否需要紧急动作
• uint64_t sync_timestamp：裁判系统同步时间戳，用于对齐多个数据源的时间

逐行解读

• uint8_t robot_id：机器人 ID（1-8），用于区分不同机器人
• uint8_t robot_level：机器人等级，影响血量和功率上限
• uint16_t remain_hp：当前剩余血量。决策节点根据血量判断是否撤退（hp_threshold 参数）
• uint16_t max_hp：最大血量，与等级相关
• uint16_t shooter_cooling_rate：枪口冷却速率（热量/秒），影响射击频率限制
• uint16_t shooter_heat_limit：枪口热量上限，超过此值无法射击
• uint16_t chassis_power_limit：底盘功率上限（瓦），影响移动速度
• uint8_t mains_power_state：电源状态位——bit0/1/2 分别表示云台/底盘/发射机构是否供电

逐行解读

• uint8_t header = 0xA5：帧头 0xA5，与 Header 结构中的相同
• uint16_t size：数据区大小
• uint8_t id：包 ID
• uint8_t crc8：Header 部分的 CRC8 校验
• uint16_t cmd_id：命令 ID，标识这个包的业务类型
• float pitch/roll/yaw：云台姿态三轴角度（度）。serial_driver 收到后转换为四元数，广播 odom → gimbal_link 的 TF 变换
• uint16_t checksum：整个包的 CRC16 校验，接收方验证通过后才使用数据

逐行解读

• Header header：通用帧头（0xA5 + cmd_id 等）
• uint8_t id = 0：目标装甲板 ID，0 表示无目标
• uint8_t robo_id = 0：目标机器人 ID
• float pitch：解算后的目标俯仰角（弧度），即"云台应该转到的 Pitch 角度"。注意 2027 版发送的是 角度 而非原始位置——弹道解算在视觉端完成
• float yaw：解算后的目标偏航角（弧度），即"云台应该转到的 Yaw 角度"
• uint8_t accuracy = 50：命中概率估计值（0-100），默认 50。电控端可以据此决定是否开火
• uint8_t shoot：射击指令，0=不射击，1=射击。视觉端根据命中概率和目标状态决定是否开火
• uint16_t checksum：CRC16 校验

逐行解读

• float vx, vy, vz：底盘速度指令（米/秒），用于导航模块控制底盘移动
• uint8_t enable：底盘运动使能标志，0=锁死，1=允许运动。安全开关

逐行解读

• float vx, vy：平面线速度指令
• float wz：绕 Z 轴的角速度（弧度/秒），用于转向控制
• aligned(1)：与 packed 配合，确保 1 字节对齐，消除所有 padding

逐行解读

fromVector（反序列化：字节流 → 结构体）： - template <typename T>：模板函数，可以将字节流转换为任意包类型（IMUPacket、ReceivePacket 等） - T packet：在栈上创建目标类型的实例（字段有默认值） - reinterpret_cast<uint8_t *>(&packet)：将结构体指针强制转换为字节指针——因为 __attribute__((packed)) 保证了内存布局与线上协议完全一致，所以直接拷贝字节就是正确的解析 - std::copy：将 vector 中的字节逐一拷贝到结构体的内存空间

toVector（序列化：结构体 → 字节流）： - sizeof(SendPacket)：获取结构体的字节大小（packed 后没有 padding，大小精确） - 创建一个正好那么大的 vector<uint8_t> - 将结构体的原始字节拷贝到 vector 中，可以直接通过串口发送

逐行解读

• crc8 命名空间：用于 Header 校验。Verify 函数返回校验结果（True/False），Append 函数在发送前自动计算并填充 crc8 字段
• crc16 命名空间：用于整个数据包的校验。流程同上
• 为什么用两层校验：先校验 Header 的 CRC8，如果 Header 就错了，直接丢弃整个包，不用解析数据区。只有 Header 正确了，才继续校验数据区的 CRC16。这是短路优化——在高速串口通信中，每一微秒都很重要