2、基础知识：机器人传感器类型及其数据格式，模型输出与动作日志的构成
机器人现场调试的核心任务，是让开发者能够准确回答三个问题：“机器人现在感知到了什么？”、“决策模型认为应该怎么做？”、“执行器实际做了什么？”。这三个问题分别对应传感器数据、模型输出和动作日志。如果这三者无法对齐，调试就会陷入“盲人摸象”的困境——传感器说前方有障碍，规划模型却输出直行指令，而执行器日志显示电机根本没有转动。因此，理解每一类数据的产生机制、格式规范和语义含义，是进行高效现场调试的前提。
上图展示了机器人调试中数据流动的完整链路。从左侧的传感器层开始，原始数据经过总线或话题传递到模型层，模型输出决策结果，再转化为控制指令下发到执行器层，最终由动作日志记录执行情况。现场调试的核心工作，就是确保这条链路上每一个环节的数据都可解析、可对比、可追溯。下面我们将逐一拆解每一层的具体内容。
2.1 核心原理：传感器类型与数据格式
机器人感知外部环境和自身状态，依赖多种异构传感器。每种传感器都有其独特的物理原理、数据格式和采样特性。现场调试时，工程师必须能够快速识别传感器类型，并理解其输出数据的组织方式。
| 传感器类型 | 物理原理 | 典型数据格式 | 关键参数 | 调试关注点 |
|---|---|---|---|---|
| 激光雷达 (LiDAR) | 激光测距（TOF/相位法） | 点云：sensor_msgs/PointCloud2，每个点包含 (x, y, z, intensity) |
扫描频率 (10-20Hz)、角分辨率、测量范围 | 点云畸变、遮挡、反射率异常 |
| 相机 (Camera) | 光电转换（CMOS/CCD） | 图像：sensor_msgs/Image（RGB/灰度），深度图 Image (32FC1) |
分辨率、帧率 (30-60fps)、曝光时间 | 过曝/欠曝、运动模糊、畸变 |
| 惯性测量单元 (IMU) | MEMS加速度计+陀螺仪 | sensor_msgs/Imu：orientation, angular_velocity, linear_acceleration |
采样率 (100-1000Hz)、零偏、噪声密度 | 零偏漂移、温漂、振动噪声 |
| 编码器 (Encoder) | 光电/磁电脉冲计数 | 增量式：脉冲计数；式：二进制位置值 | 分辨率 (PPR)、最大转速、计数方向 | 丢步、方向反、零位丢失 |
以激光雷达为例，其输出的点云数据在ROS中通常以PointCloud2消息发布。调试时，我们不仅需要查看点云的坐标值，还要关注header.stamp时间戳和header.frame_id坐标系。如果点云的坐标系与机器人基座坐标系（base_link）未正确变换，后续所有感知结果都会出现系统性偏移。
2.2 模型输出：从感知到规划的含义解读
模型输出是机器人“大脑”的决策结果，通常分为三个层级：感知输出、预测输出和规划输出。每一层输出的数据结构和语义都不同，调试时需要分别验证其正确性。
2.2.1 感知输出
感知模型将传感器原始数据转化为语义信息。例如，目标检测模型输出障碍物列表，每个障碍物包含类别、置信度、边界框坐标（在相机坐标系或激光雷达坐标系下）。语义分割模型则输出每个像素的类别标签。调试感知输出时，需要将模型输出与原始传感器数据叠加显示，人工判断检测结果是否与真实场景一致。
# 感知输出示例（ROS自定义消息）
Header header
Object[] objects
uint8 id
string class_name
float32 confidence
geometry_msgs/PoseWithCovariance pose # 位置和姿态
float32[8] bbox_corners # 3D边界框8个角点2.2.2 预测输出
预测模块根据历史轨迹和感知结果，推测其他运动物体的未来状态。常见输出包括：预测轨迹（一系列未来时间戳对应的位置点）、概率分布（如高斯分布的均值和协方差）。调试预测输出时，重点检查预测轨迹是否平滑、是否与物理运动规律（如最大加速度约束）相符。
2.2.3 规划输出
规划模块生成机器人的运动指令，包括全局路径（一系列路点）和局部速度指令（线速度+角速度）。在ROS的导航栈中，cmd_vel话题是典型的规划输出，其数据类型为geometry_msgs/Twist。调试规划输出时，需要关注速度指令的平滑性、是否超出机器人运动学约束（如最大线速度、最大角速度）。
rosbag record录制传感器数据和模型输出，然后使用rqt_bag或PlotJuggler进行离线回放。将感知输出（如障碍物框）与原始点云/图像叠加显示，可以快速发现感知漏检或误检问题。对于规划输出，绘制速度曲线随时间的变化图，可以直观发现速度跳变或振荡。
2.3 动作日志：控制指令与执行器反馈的构成
动作日志记录了机器人执行层面的所有信息，是判断“机器人是否按指令执行”的唯一依据。动作日志通常包含两部分：控制指令（下发给执行器的目标值）和执行器反馈（执行器实际状态）。
2.3.1 控制指令的构成
控制指令是模型输出经过运动学/动力学转换后，下发给电机驱动器或舵机的具体命令。常见的控制指令格式包括：
- 速度指令：目标线速度 (m/s) 和目标角速度 (rad/s)，常用于轮式机器人底盘。
- 位置指令：目标关节角度 (rad) 或目标末端位姿，常用于机械臂。
- 力矩/电流指令：目标力矩 (Nm) 或目标电流 (A)，用于力控场景。
在CANopen协议中，控制指令通常通过PDO（过程数据对象）传输。例如，一个典型的电机速度控制指令包含：控制字（使能/停止）、目标速度（RPM）、加减速时间等参数。
2.3.2 执行器反馈的构成
执行器反馈是电机驱动器或舵机返回的实际状态数据，用于闭环控制和状态监控。典型的反馈数据包括：
- 实际速度：电机当前转速 (RPM) 或机器人实际线速度。
- 实际位置：电机当前角度 (rad) 或编码器累计脉冲数。
- 电流/力矩：电机当前相电流或输出力矩。
- 状态字：包含使能状态、报警标志、限位触发等二进制信息。
# 动作日志典型记录（CSV格式）
timestamp, cmd_linear_vel, cmd_angular_vel, actual_linear_vel, actual_angular_vel, motor_current, status_word
1699000001.234, 0.500, 0.000, 0.487, 0.002, 1.234, 0x0231
1699000001.254, 0.500, 0.000, 0.491, 0.001, 1.245, 0x0231
1699000001.274, 0.500, 0.000, 0.495, 0.001, 1.256, 0x02312.4 案例拆解：AGV小车速度跟踪异常排查
下面通过一个实际案例，演示如何利用传感器数据、模型输出和动作日志进行对齐调试。
背景与约束：某工厂AGV（自动导引车）在直线行驶时出现速度波动，表现为周期性加速和减速，影响运输效率。AGV配备激光雷达、IMU、轮式编码器，使用ROS导航栈进行路径规划，底层电机驱动器通过CANopen通信。
初始现象：AGV在平坦地面直线行驶时，实际速度在0.4~0.6 m/s之间波动（目标速度为0.5 m/s），波动周期约为2秒。
关键数据采集：
- 使用
rostopic echo /cmd_vel查看规划输出，发现目标速度稳定在0.5 m/s，无波动。 - 使用
rostopic echo /odom查看里程计数据，发现实际速度在0.4~0.6 m/s波动。 - 查看电机驱动器反馈日志，发现电机实际转速波动与里程计一致。
- 查看IMU数据，发现AGV在行驶过程中存在轻微俯仰角变化（±1°）。
分析判断过程：规划输出正常，说明模型层无问题。执行器反馈与里程计一致，说明执行层确实存在速度波动。IMU数据显示俯仰角变化，提示AGV可能存在机械振动或路面不平。进一步检查发现，AGV的驱动轮存在轻微磨损，导致轮子与地面接触半径周期性变化，从而引起速度波动。
实际操作步骤：
- 将AGV架起，使驱动轮悬空，运行速度指令，发现电机转速稳定，排除电机和驱动器问题。
- 将AGV放回地面，在驱动轮下方垫一块平整钢板，再次运行，速度波动消失，确认是路面或轮胎问题。
- 更换磨损的驱动轮，重新测试，速度波动消除。
结果对比：更换轮胎后，实际速度稳定在0.49~0.51 m/s范围内，波动幅度从±0.1 m/s降低到±0.01 m/s。
风险与代价：若未及时排查，速度波动可能导致AGV定位偏差累积，最终造成导航偏移或碰撞风险。本次排查耗时约2小时，主要时间花费在数据采集和对比分析上。
复盘经验：当出现执行层异常时，应首先确认指令-反馈是否一致，然后逐层向上排查。将执行器悬空测试是区分“执行器自身问题”与“外部负载问题”的有效手段。
2.5 常见误区与总结复盘
在传感器数据、模型输出和动作日志的对齐调试中，工程师常犯以下错误：
message_filters）将数据对齐到同一时刻。
laser_link坐标系下，而规划输出在map坐标系下。如果未正确使用TF变换，直接对比会导致位置偏差。调试时应始终通过tf2工具确认坐标变换是否正确。
总结复盘：传感器、模型、执行器构成了机器人系统的“感知-决策-执行”闭环。现场调试的核心方法论可以概括为：先看时间戳是否对齐，再看坐标系是否统一，最后对比数值是否在合理范围。建议在调试初期就建立标准的数据记录模板，包含时间戳、坐标系、单位、数据范围等元信息，这样可以大幅减少后续排查的时间成本。