velocity_smoother（速度限幅与加减速平滑）

velocity_smoother（速度限幅与加减速平滑）

实车先看：平滑哪一路速度、反馈来自哪里

当前velocity_smoother处理controller_server输出的速度指令，逐轴限目标速度、限速度变化，再处理死区。OPEN_LOOP使用上一轮内部指令作当前速度，不用里程计实测速度；scale_velocities=False仍会限速和限加减速。 本节点处理Twist，不修改规划路径，也不查询代价地图判断碰撞。

普通路径跟踪，两种navigation_launch分支相同：
    controller_server／OmniPID
        → cmd_vel_controller
        → velocity_smoother
            ├─ 最新目标速度先夹到各轴min／max范围
            ├─ OPEN_LOOP：以内部last_cmd作为当前速度
            ├─ 按加／减速参数约束本轮变化
            └─ 内部记录 → 应用死区 → 发布
        → cmd_vel_nav2_result
        → fake_vel_transform：换平移轴，再加cmd_spin
        → cmd_vel → 串口／执行端

恢复行为：
    组件分支behavior_server → cmd_vel_nav2_result，绕过平滑器
    独立分支behavior_server → namespace/cmd_vel，另有接线问题

当前launch把平滑器内部cmd_vel订阅重映射为cmd_vel_controller，把cmd_vel_smoothed发布重映射为cmd_vel_nav2_result；不是直接套用教程中的cmd_vel_nav→cmd_vel名称。恢复与下游自旋的限速条件另见behavior_server和fake_vel_transform。

本次安装的nav2_velocity_smoother和nav2_util均为1.1.20。VelocitySmoother与OdomSmoother安装头文件匹配该版本，平滑器库存在；本页依据对应官方源码及当前工程接线说明，不把后续版本的TwistStamped或其他参数直接套入。平滑器源码、里程计窗口源码

参数

下面原样保留发送的12项参数。源码与安装副本的reality段一致；simulation段只有use_sim_time=True不同。本次只写文档，未改工程配置或运行参数。

velocity_smoother:
  ros__parameters:
    use_sim_time: False
    smoothing_frequency: 20.0
    scale_velocities: False
    feedback: "OPEN_LOOP"
    max_velocity: [2.5, 2.5, 3.0]
    min_velocity: [-2.5, -2.5, -3.0]
    max_accel: [4.5, 4.5, 5.0]
    max_decel: [-4.5, -4.5, -5.0]
    odom_topic: "odometry"
    odom_duration: 0.1
    deadband_velocity: [0.0, 0.0, 0.0]
    velocity_timeout: 1.0

所有三元素数组顺序都是**x，y，theta**，对应Twist的linear.x、linear.y、angular.z。前两项是平移，第三项是绕z轴的旋转；theta这一项不是以rad为单位的目标角度。

ros__parameters（时钟、频率与反馈方式）

参数表

参数详解

smoothing_frequency（定时器、步长与上游控制频率）

Active阶段用wall timer触发smootherTimer。当前1000／20=50 ms；定时器周期转换为整数毫秒，其他频率可能有截断，例如33 Hz会创建30 ms周期，而变化上限仍按配置33计算。因此不能把任何设置值都视为精确实测频率。定时器创建

每轮允许变化按参数除以smoothing_frequency计算，没有根据上次实际回调时间测dt。负载导致周期延迟时，真实每秒的变化过程会受影响；这也是指令平滑约束，不代表实测机械加速度已被限制到同样数值。

当前controller_server也为20 Hz，所以两者名义频率相同；提高平滑频率可在两条控制指令之间继续生成过渡输出，但不会提高规划／路径跟踪本身的计算频率。两定时循环也没有自动锁定相位，不能保证每轮输出都对应刚收到的一条新控制指令。控制器频率

例如提高到100 Hz而保持加速度不变，名义线速度每轮上限从0.225降为0.045 m/s，角速度从0.25降为0.05 rad/s；理想每秒仍对应4.5 m/s²和5 rad/s²。这是参数计算，未改变当前频率或测量输出。

OPEN_LOOP（内部命令反馈，不等于机器人实测速度）

OPEN_LOOP把上一轮last_cmd作为本轮current速度，再向最新目标靠近。当前死区为0时，它等于上一轮发布的三个有效分量；若以后启用非零死区，last_cmd记录在死区置零之前，就不一定等于实际发布值。反馈选择与记录顺序

这种模式默认车辆能跟上此前指令，不能从中知道打滑、卡住、驱动限流或真实速度滞后，也不会因收到odometry自动切成实测闭环。当前启动读取odom_topic和odom_duration，但不创建OdomSmoother，不用它们参与current速度。

CLOSED_LOOP改用窗口内里程计Twist均值；这里的“闭环”是平滑器以实测反馈为限变化的起点，并非额外建立一个车轮速度PID。反馈频率低或一直为0时，每轮可能都从同一个反馈速度重新算，不能像开环那样自然累计已发命令。

scale_velocities（缩放速度变化量，不是关闭限幅）

先把目标各轴夹到min／max范围，再计算dv=目标−current。False令eta=1，各轴分别夹紧自己的dv；True从受约束轴中找更严格的统一比例eta，先缩放全部dv，再按各轴自己的约束夹紧。eta与逐轴约束

按当前频率、从零起步、目标已在速度范围内且死区为0，举例：

前两项单位m/s，第三项rad/s。False能让小需求轴先达到目标，但首轮平移方向不按原请求的10∶1比例；True在此例协调变化比例，代价是其他轴也更慢接近。这是源码公式示例，不是车辆轨迹测试。

current不为0时，同比的是从current到目标的变化向量，不是直接把整个目标速度乘同一个数。先行的各轴绝对速度夹紧、后续逐轴夹紧和死区也可能改变最终比例，不能把True理解为任何情况下都保证原始速度方向不变。

速度与加减速数组（每轴范围、带符号下界）

参数表

参数详解

max／min_velocity（x、y独立夹紧，不是合速度上限）

当前目标限制为vx、vy各在-2.5,2.5 m/s，wz在-3,3 rad/s。例如目标(vx,vy)=(2.5,2.5)没有超出任何一轴，平移模长却为sqrt(2.5²+2.5²)≈3.54 m/s。仅本平滑器的这组数组不能推出模长≤2.5。目标夹紧

当前OmniPID另有标量平移速度范围和计算过程；普通跟踪实际能达到多少要看上游输出。这里的3.54只是本数组允许的目标组合，不是证明当前PID或实车已经输出该速度。min_velocity中的-2.5允许负向运动，没有把0.1 m/s之类的小速度抬到2.5 m/s。PID速度约束

速度范围在平滑输入的坐标轴上施加。当前平移指令按gimbal_yaw_fake约定，fake_vel_transform后再换到实际gimbal_yaw；平面纯旋转换轴保持平移模长，但不能保证转换后每个分量仍满足同一轴上界。角速度又会加cmd_spin，最终值不由本数组统一夹紧。

源码夹的是目标，没有在加减速计算后再做一次最终速度夹紧。当前开环、固定边界且内部初值在范围内时，会逐步靠近范围内目标；若改闭环且反馈本身超界，或运行中缩小边界，过渡输出仍可能暂时超出新界。例如current.vx=3、目标夹到2.5、20 Hz减速步长0.225时，本轮得2.775 m/s。此例说明实现顺序，未运行闭环或改变限值。

max_accel与max_decel（符号、加速判据与反向）

每轴依据下面条件选择变化区间：

若 abs(v_target) >= abs(v_current)，且 v_current × v_target >= 0：
    使用加速：Δv ∈ [-max_accel/f，+max_accel/f]
否则：
    使用减速：Δv ∈ [max_decel/f，-max_decel/f]

v_next = v_current + clamp(eta × (v_target-v_current)，Δv下界，Δv上界)

f为配置的smoothing_frequency。负方向增速仍使用正max_accel来定义变化幅值；正方向减速则使用负max_decel，不是按“正vx用accel、负vx用decel”区分。跨零反向的这一轮先按减速区间处理，之后是否改用加速由下一轮current和目标重新判断。逐轴公式

当前名义50 ms一轮：线速度最多变0.225 m/s，角速度最多变0.25 rad/s。从零到单轴2.5 m/s至少需要12次名义更新；从零到3 rad/s也需要12次，约0.6 s周期尺度。上游目标持续变化、其他轴统一缩放、定时器相位及实际驱动反馈会改变具体过程；这里不是实测起步时间。

max_decel从-4.5改成-2，虽然数值提高，幅值却减小，减速更慢；改成-6则幅值更大。应按车辆制动能力和任务响应调整，不能随手去掉负号。当前OmniPID还按0.9 m/s²限制标量速度变化，它与本逐轴4.5 m/s²不是同一变量；最终命令受串联过程共同影响，恢复旁路也不自动受到两者的相同约束。

里程计反馈（当前OPEN_LOOP不参与估计）

参数表

参数详解

odom_duration（消息窗口中的样本平均）

CLOSED_LOOP才在配置时创建OdomSmoother，直接累加Odometry.twist.twist，再除以保留的消息数。新消息到来时按“最新消息时间戳−最早消息时间戳>odom_duration”移除旧消息，因此窗口以消息stamp衡量，且边界等于0.1 s时仍保留。不是连续时间积分平均，也不按协方差加权。窗口与均值

例如时间戳严格等间隔20 ms且稳定收包时，0.1 s窗口名义可保留6个样本（含两端）；实际时间戳抖动会改变数量，不是固定五帧。odom_duration=0.1也不表示等待0.1 s收满才允许输出。

窗口只在收到新里程计时更新；getTwist返回缓存，没有按now检查其是否过期。里程计断流不由velocity_timeout检测，后者只检测速度指令断流；因此切换闭环前必须另行核对反馈新鲜度。当前开环不受这条里程计缓存分支影响。缓存读取

当前odometry不能未经核对就直接作为闭环真值

当前发布者sensor_scan_generation给出的是gimbal_yaw位姿及其差分Twist，平移差分在odom轴上计算，时间分母使用回调steady_clock，还存在首帧处理问题；它不等于已经验证的底盘速度测量。平面条件下odom轴可能与gimbal_yaw_fake输入轴近似一致，也不能因此跳过时间、原点和速度对象核对。上游速度实现与问题

尤其angular.z可能包含实际云台独立yaw运动，而平滑器的导航旋转分量与下游附加底盘自旋又是不同来源。OdomSmoother不会根据child_frame_id自动换系或分离这些角运动；切成CLOSED_LOOP前，应明确反馈的是哪个实体、哪个参考点及哪一套轴下的速度。当前保持开环不意味着这些上游问题已经被修复。

死区与输入超时（低速置零、超时后减速）

参数表

参数详解

deadband_velocity（比较速度绝对值，不是相邻消息差）

源码先计算受加减速约束的结果并写入last_cmd，再对发布结果做abs(v)<deadband置零。当前全0时，不会因为“速度变化很小”而忽略消息，也不改变任意非零小速度；等于阈值的分量不被置零。死区处理顺序

若以后把x死区设0.3 m/s，按当前开环步长、从零朝1 m/s起步：第一轮内部0.225而发布0，第二轮内部0.45而发布0.45。这会使发布值从0直接跳到0.45，不能据内部0.225步长宣称死区后的每轮输出仍严格遵守同一变化上限。此为顺序计算例，未改当前全0死区。

所以死区适合在确认驱动最低可执行速度、微动现象和到点需求后再设置；它不会增加定位精度，也不是控制器的min_x／min_y_velocity_threshold。控制器那些门槛处理输入里程计，当前这个门槛处理平滑后的发布速度。

velocity_timeout（先等待门槛，再把零当目标平滑）

收到有效Twist时保存目标并把last_command_time更新为接收时的now；NaN或Inf消息被拒绝，不刷新这个计时。Twist本身没有时间戳，因此这里测的是接收间隔，不是原始指令生成时刻或网络总延迟。输入回调

没有收到过任何指令时，定时回调直接返回，不持续发布零。收到指令后，即使暂时没有新消息，也继续按最新目标平滑；当ROS时间差严格>1 s，在某次回调把command改为零，再按当前减速参数生成输出。显式收到零指令则立即把它作为新目标，不先等待这1秒。超时分支

例如超时触发时内部单轴速度为2.5 m/s，当前开环、死区0、20 Hz和减速幅值4.5下，需要12次名义减速更新才能归零，约0.6 s周期尺度。加上前面的1 s门槛与定时相位，不能写成“失去输入1秒内必定停住”；物理停车还受执行端影响。本例是离散公式换算，不是断流实测。

超时后内部last_cmd已精确为零或stopped=True时，函数直接返回，不再持续发布零。当前开环能逐步到达精确零，随后停止发布；闭环或非零死区情形仍应结合内部状态与真实反馈判断，不能把停止发布当作车已静止的测量。

本超时使用ROS时钟，平滑定时器却使用墙钟。use_sim_time=True且/clock暂停时，回调可能仍运行、按最新目标继续生成指令，而1 s超时差不再增长。恢复旁路也不受这条输入超时统一管理；平滑器发零后，fake_vel_transform仍可能加上保留的cmd_spin。

动态参数、配置边界与验证范围

当前1.1.20哪些值会动态进入成员

本节点在activate安装回调，deactivate移除；本版不能把“ROS参数设置成功”一律理解成所有内部设置已联动更新。动态参数实现

此外，max_accel／max_decel动态回调检查符号后，即使判为失败也仍有赋值成员的代码，批量设置还可能先更新前面的成员再遇到后项失败。不能依赖“设置失败”证明内部完全未变；本次没有运行这种非法设置实验。符号检查与赋值

启动配置要保持三元素数组、加速非负、减速非正、各轴min≤max及有效频率／时间；当前这些数值符合源码的基本符号和数组要求，但是否匹配实际驱动能力仍需实物数据。平滑器没有jerk约束，没有统一的车体合速度限幅，也没有代价地图碰撞检查；机械能力与碰撞处理不能只靠这组参数证明。

本次核对与实物观察

• 已核对： nav2_velocity_smoother／nav2_util版本、两份安装头文件与库；reality／simulation参数及安装副本；两种navigation_launch的控制器和平滑器重映射、恢复旁路；上游odometry生成和下游速度换系／自旋。
• 源码能确认： 十二项参数的使用条件、三轴顺序与单位；目标夹紧→变化约束→内部记录→死区发布的顺序；开环和闭环窗口区别；超时零目标降速、ROS与墙钟差异；动态参数覆盖及未覆盖分支。
• 实物观察时重点： 同时对照cmd_vel_controller、cmd_vel_nav2_result及最终cmd_vel，观察起步、减速、横移／方向切换和驱动实际响应；确认附加自旋、恢复旁路和控制指令断流各自的处理结果。若保持开环，先不以odom_duration作为调试输出平滑的入口。
• 本次范围： 仅更新文档和目录，未改变运行参数或工程代码，未发布速度、未启动导航／恢复、未进行运动或断流测试；所有数值例子均为源码公式计算。