把 Robostral Navigate 接进仿真环境时，报错通常长成两种样子：模型侧收不到话题，或者 tf 查不到某对 frame。真正要动的地方其实只有三类——坐标系（frame 名和父子关系）、话题名与消息字段映射、时间戳与单位约定。建议的动手顺序是：先只读盘点仿真侧已经提供了什么，再建立坐标与单位约定，然后写映射配置，最后跑一条最小通路并看日志。跳过盘点直接改模型侧参数，往往会在两套命名之间来回返工。

适用场景：仿真环境本身能跑起来，但模型侧收不到数据或算出来的结果对不上。操作动作：先用命令导出话题列表、frame 树和控制指令格式，标出与预期不符的字段，再把差异集中写进一份可回退的映射配置。验证方式：跑通“传感器输入 → 模型输出 → 控制指令”的最小链路，用频率、日志确认无丢帧、无 NaN、时间戳单调。风险边界：如果仿真侧压根不发布某条变换或不支持某类控制指令，只能在适配层补齐，调模型参数解决不了。

列出仿真环境已有的话题、坐标系和控制接口

这一步只读不改，目的是拿到一份“外部系统实际长什么样”的清单，而不是先按模型文档去猜。下面的命令是通用骨架，假设仿真器提供 ROS 2 风格的 CLI；如果用的是别的中间件，用等价的列表导出方式代替，结论口径一样。

# 1) 话题清单与消息类型
ros2 topic list -t
ros2 topic info /<topic_name> -v        # 看发布者、订阅者、QoS
ros2 interface show <msg_type>          # 看字段名与字段类型

# 2) 帧树与变换连通性
ros2 run tf2_tools view_frames          # 生成帧树快照
ros2 run tf2_ros tf2_echo map base_link # 确认某条链是否连通

# 3) 控制指令格式
ros2 topic info /<cmd_topic> -v
ros2 topic echo /<cmd_topic> `--once`

盘点时需要重点标出三类不一致：frame 命名（base_link 与 base_footprint、odom 与 world 常被混用）、话题命名（扁平名 /scan 与分层名 /lidar/scan 不通用）、控制接口形态（速度指令、关节指令还是自定义结构）。把这些差异写成一张对照表，后面写映射配置时直接照着填，不靠记忆。

建立坐标变换和单位约定

坐标错位最常见的原因不是算法，而是米与厘米、弧度与角度、四元数分量顺序这三件事没有提前约定。建议在接入开始就固定一条主链，其余传感器都挂到它下面：

map  →  odom  →  base_link  →  <sensor_frame>
         ^          ^
   全局定位/重定位   底盘本体

约定上建议统一用国际单位制：长度用米，角度用弧度，四元数按 x y z w 顺序，欧拉角旋转顺序写清楚是 ZYX 还是 XYZ。静态变换放进静态变换源（如 /tf_static），动态变换由仿真侧的里程计或定位模块发布；每条变换的时间戳优先取仿真时钟，避免用系统墙钟，否则回放或加速仿真时整条链会漂。

验证方式很直接：对主链上每一对相邻 frame 都跑一次 tf2_echo，确认能连续输出而不是只打印一次警告；再看帧树快照里是不是只有一棵连通树，出现多棵独立子树基本就是父子关系写错了。这一步没过，不要往下写映射。

写话题名与消息字段映射配置

映射配置的作用是把仿真接口和模型预期的名称解耦，让差异集中在一个文件里，而不是散落在代码各处。下面是通用骨架，所有取值都是占位符，需要按仿真侧实际暴露的话题和字段替换：

# mapping.yaml（占位符示例，按实际替换）
inputs:
  - model_topic: <model_input_topic>
    sim_topic:   <sim_sensor_topic>
    msg_type:    <sensor_msg_type>
    fields:                      # 模型字段名 : 仿真消息字段名
      <model_field_a>: <sim_field_a>
      <model_field_b>: <sim_field_b>
    frame_override: <target_frame>   # 需要时把 header.frame_id 改写到主链下

outputs:
  - model_topic: <model_output_topic>
    sim_topic:   <sim_cmd_topic>
    msg_type:    <cmd_msg_type>
    fields:
      <model_cmd_field>: <sim_cmd_field>

哪些字段需要替换不能靠猜：话题名来自第一步的列表，字段名来自 ros2 interface show 或等价的消息定义，frame_override 只在仿真侧 frame 名与主链不一致时才填。单位换算如果无法在仿真侧改，就放在这一层做显式换算，并在配置里写明换算系数和方向，避免同一份数据在两个地方各换算一次。

跑通最小数据通路并记录日志

先不要跑完整任务，只验证一条链路：一路传感器进、模型出一路控制指令、指令回到仿真。启动脚本骨架如下，具体节点名按实际替换：

# 终端 A：仿真环境
<sim_launch_command>

# 终端 B：适配层（加载上一步的 mapping.yaml）
<adapter_launch_command> `--config` mapping.yaml `--log-level` debug

# 终端 C：观察通路
ros2 topic hz /<model_input_topic>    # 输入频率是否符合仿真步长
ros2 topic hz /<sim_cmd_topic>        # 输出频率是否稳定
ros2 topic echo /<sim_cmd_topic> `--once`

日志里建议固定几个可搜索的关键字，方便快速定位：输入话题首次收到数据的记录、变换查询超时、数值异常（NaN / inf）、队列丢弃。如果仿真器或适配层没有现成关键字，在适配层自己打，例如收到一帧就打一条带话题名和序号的行。

除了频率，还要看三件事：输入输出序列号是否连续（判断有无丢帧）、指令字段里是否出现 NaN 或极大值、同一话题连续两帧的 header.stamp 是否非递减。短时间录一段数据包再离线检查，比盯着终端刷屏更容易发现问题。

整理接入失败时的回退顺序

报错时不要从头翻代码，按下面四层自下而上回退，每层都有明确的通过标准：

1. 配置层：话题名、消息类型、字段名是否与仿真侧一致。通过标准：ros2 topic info -v 能看到适配层作为发布者或订阅者挂在正确话题上，且类型完全匹配，没有“类型不兼容”或静默丢弃。
2. 坐标层：frame 名与父子关系是否正确、单位是否需要换算。通过标准：帧树是一棵连通树，主链上每对相邻 frame 都能用 tf2_echo 连续查到变换。
3. 时间戳层：header.stamp 用的是仿真时钟还是墙钟，容忍窗口设多大。通过标准：连续帧时间戳非递减，变换查询不持续报超时；回放或加速仿真时链路保持稳定。
4. 控制指令层：指令结构、取值范围、坐标系约定是否与仿真接口一致。通过标准：仿真侧实际按指令动起来，且 ros2 topic echo 看到的数值在合理范围内，没有 NaN 或突变。

每一层不通过就先修这一层，不要跳到上一层调参数。如果某一层依赖仿真侧修改而暂时改不了，就在适配层做显式补偿，并在配置里留注释说明补偿的原因和范围，方便后续仿真侧对齐后删掉。