1. 从“插件没找到”说起:功能库为什么值得单独建一个包
导航栈跑起来之后,开发者首先想改的地方通常是横向控制器:默认那套在窄通道里贴边太紧,换算法就得 fork 整个导航栈、重编 controller_server,一次十几分钟,升级还得 merge。把控制器做成独立的功能库就能绕开这个循环:这就是一个编译成 .so 的插件包,对外暴露继承自 nav2_core::Controller 的类,再配一份描述“这个类归谁加载”的 XML,最后用 CMake 把导出声明写进 ament 索引。运行时 controller_server 按参数挑插件,核心包一行不改。
它适合的人群很明确:要在 Nav2 里新增或替换控制算法、又不想维护一份导航栈分支的人。整个过程没有多少神秘技巧,但对“导出链”的完整性要求极高:XML、导出声明、install 目标、注册宏,缺任何一环,加载时通常只剩一句插件找不到,而且报错位置和真正的原因往往隔着好几层。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 功能库的骨架:目录层级、依赖分类与导出语句
功能库能不能被 pluginlib 认出来,八成取决于包建得对不对,代码反而是后面的事。这一章把包的骨架固定下来:目录层级、package.xml 的依赖分法、CMakeLists.txt 里的导出语句,三样都到位,后面的类注册才有地方落。
2.1 先定 include 层级,再敲 pkg create
动手之前先看目标结构,别急着建包:
bash复制nav2_pure_pursuit_controller
├── CMakeLists.txt
├── doc
│ └── lookahead_algorithm.png
├── include
│ └── nav2_pure_pursuit_controller
│ └── pure_pursuit_controller.hpp
├── nav2_pure_pursuit_controller.xml
├── package.xml
├── README.md
└── src
└── pure_pursuit_controller.cpp
注意 include 下面多套了一层与包同名的目录。这层并不多余:下游写 #include "nav2_pure_pursuit_controller/pure_pursuit_controller.hpp" 时,靠的就是它;而 install(DIRECTORY include/ DESTINATION include/) 会把这一层原样搬进安装空间。如果图省事把头文件直接放在 include 根下,本地编译也许能过,装完之后下游的 include 路径就得跟着改,插件描述文件里的类名再对也没用。
包用命令行生成,依赖一次列全,省得后面反复补:
bash复制ros2 pkg create nav2_pure_pursuit_controller \
--build-type ament_cmake \
--dependencies rclcpp geometry_msgs nav2_costmap_2d pluginlib nav_msgs nav2_util nav2_core tf2
逐个说清楚它们为什么在:rclcpp 提供节点、日志和时钟,configure 里拿 logger 和 clock 全靠它;geometry_msgs 是输出 TwistStamped 的类型来源;nav_msgs 承载 Path;nav2_costmap_2d 提供 Costmap2DROS 的共享指针,代价地图的坐标系和边界都从它来;nav2_core 是 Controller 基类和异常类型所在;nav2_util 提供 declare_parameter_if_not_declared 和 geometry_utils 里的距离函数;pluginlib 负责注册与加载;tf2 用来做位姿变换。少一个,编译期就会在某个头文件里断掉,而不是等到运行。
生成之后还要手动补两处:nav2_common 不是编译期强依赖,但 find_package(nav2_common REQUIRED) 和 nav2_package() 宏要用到它;nav2_msgs 在头文件里未必直接引用,但实现里处理路径和参数消息时会碰,先留着比后面补省事。
2.2 package.xml:depend 和 exec_depend 别混着写
依赖分三类写,不要一股脑全塞 depend:
xml复制<?xml version="1.0"?>
<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
<package format="3">
<name>nav2_pure_pursuit_controller</name>
<version>1.0.0</version>
<description>Pure pursuit controller</description>
<maintainer email="dev@example.com">某开发者</maintainer>
<license>BSD-3-Clause</license>
<buildtool_depend>ament_cmake</buildtool_depend>
<depend>nav2_common</depend>
<depend>nav2_core</depend>
<depend>nav2_util</depend>
<depend>nav2_costmap_2d</depend>
<depend>rclcpp</depend>
<depend>geometry_msgs</depend>
<depend>nav2_msgs</depend>
<depend>pluginlib</depend>
<depend>tf2</depend>
<exec_depend>nav2_bringup</exec_depend>
<test_depend>ament_cmake_gtest</test_depend>
<export>
<build_type>ament_cmake</build_type>
</export>
</package>
<depend> 等价于 build、export、exec 三者的合并,凡是头文件里 #include 到的、链接时要找符号的,都写这一档。<exec_depend>nav2_bringup</exec_depend> 只在运行时需要:真正拉起 controller_server 的是 bringup,本包编译时根本用不到它;把它写成 depend,会把一堆不相关的运行时包拖进编译环境,构建时间白白变长。<test_depend> 留给 gtest,测试代码才用。<export> 里的 build_type 决定下游怎么找这个包,写错的话 find_package 直接失败。
还有一条容易忽略的:maintainer 那一行必须填一个能收信的地址,格式校验不过 package.xml 会整份被判无效,报错信息还只指向 schema 校验,跟插件加载毫无关系,查起来很绕。
2.3 CMakeLists:共享库、导出语句与 install 目标
CMake 这一段是功能库能被加载的核心环节,逐段看:
bash复制cmake_minimum_required(VERSION 3.5)
project(nav2_pure_pursuit_controller)
find_package(ament_cmake REQUIRED)
find_package(nav2_common REQUIRED)
find_package(nav2_core REQUIRED)
find_package(nav2_costmap_2d REQUIRED)
find_package(nav2_util REQUIRED)
find_package(rclcpp REQUIRED)
find_package(geometry_msgs REQUIRED)
find_package(nav_msgs REQUIRED)
find_package(pluginlib REQUIRED)
find_package(tf2 REQUIRED)
nav2_package()
include_directories(
include
)
set(dependencies
rclcpp
geometry_msgs
nav2_costmap_2d
pluginlib
nav_msgs
nav2_util
nav2_core
tf2
)
add_library(nav2_pure_pursuit_controller SHARED
src/pure_pursuit_controller.cpp)
# prevent pluginlib from using boost
target_compile_definitions(nav2_pure_pursuit_controller PUBLIC "PLUGINLIB__DISABLE_BOOST_FUNCTIONS")
ament_target_dependencies(nav2_pure_pursuit_controller
${dependencies}
)
install(TARGETS nav2_pure_pursuit_controller
ARCHIVE DESTINATION lib
LIBRARY DESTINATION lib
RUNTIME DESTINATION bin
)
install(DIRECTORY include/
DESTINATION include/
)
if(BUILD_TESTING)
find_package(ament_lint_auto REQUIRED)
# the following line skips the linter which checks for copyrights
set(ament_cmake_copyright_FOUND TRUE)
ament_lint_auto_find_test_dependencies()
endif()
ament_export_include_directories(include)
ament_export_libraries(nav2_pure_pursuit_controller)
ament_export_dependencies(${dependencies})
pluginlib_export_plugin_description_file(nav2_core nav2_pure_pursuit_controller.xml)
ament_package()
nav2_package() 是 nav2_common 提供的宏,统一了 C++ 标准、编译选项和安装布局;不用它就得手写一大段,而且很容易和导航栈其余部分的标准对不齐。add_library 的 SHARED 不能省:pluginlib 是从磁盘加载动态库,静态库根本没有可加载的入口。
target_compile_definitions(... PLUGINLIB__DISABLE_BOOST_FUNCTIONS) 这一行关闭 pluginlib 的 boost 回退路径。它的作用是让 pluginlib 走纯 C++ 标准库那套实现,避免链接阶段引入 boost 相关符号;漏掉它,有些环境里会在加载阶段报符号找不到,编译却完全正常。
install(TARGETS ...) 里的三个目标目录要看清:LIBRARY DESTINATION lib 才是共享库真正该去的地方,RUNTIME DESTINATION bin 是给可执行文件预留的。把 .so 装到 bin 下,pluginlib 按 lib 目录找,自然找不到。install(DIRECTORY include/ DESTINATION include/) 把那一层同名目录带上,下游才能正常 include。
ament_export_include_directories、ament_export_libraries、ament_export_dependencies 三句是给下游 find_package 用的,少了它们,别的包依赖你这个功能库时会链接失败。
最后一句 pluginlib_export_plugin_description_file(nav2_core nav2_pure_pursuit_controller.xml) 最关键:第一个参数是基类所在的包名,不是自己的包名;第二个参数才是本包的描述文件。写反了,插件描述文件不会被挂到正确的位置,plugin 在运行时扫不到,日志只留一句找不到类。
3. 把类注册成插件:XML 描述、接口继承与编译开关
骨架搭好之后,得让 pluginlib 知道“这个 .so 里有一个类,它实现的是哪个基类”。三处必须完全对齐:XML 里的类名、头文件里的继承关系、cpp 里的注册宏。任何一处写法不一致,编译器都不会提醒你,只有运行时那句找不到类。
3.1 插件描述 XML:type 与 base_class_type 必须逐字符一致
描述文件长这样,字段不多但每个都不能马虎:
xml复制<class_libraries>
<library path="nav2_pure_pursuit_controller">
<class type="nav2_pure_pursuit_controller::PurePursuitController" base_class_type="nav2_core::Controller">
<description>
nav2_pure_pursuit_controller
</description>
</class>
</library>
</class_libraries>
library path 填库名,不带 lib 前缀、不带 .so 后缀,pluginlib 自己会按平台的命名规则拼出来。type 是 C++ 里的完整限定类名,必须和命名空间加类名逐字符对上,多一个空格、少一个下划线都不行。base_class_type 是基类的完整限定名,这里必须写 nav2_core::Controller:controller_server 是拿着这个基类去 pluginlib 里查询的,你写成自己的包名,等于登记在一个没人查的目录下。description 只是给人看的,随便写,不参与匹配。
3.2 头文件:把 nav2_core::Controller 的纯虚函数补齐
接口继承在头文件里定死,需要实现哪些函数,一眼能看全:
cpp复制#ifndef NAV2_PURE_PURSUIT_CONTROLLER__PURE_PURSUIT_CONTROLLER_HPP_
#define NAV2_PURE_PURSUIT_CONTROLLER__PURE_PURSUIT_CONTROLLER_HPP_
#include <string>
#include <vector>
#include <memory>
#include "nav2_core/controller.hpp"
#include "rclcpp/rclcpp.hpp"
#include "pluginlib/class_loader.hpp"
#include "pluginlib/class_list_macros.hpp"
namespace nav2_pure_pursuit_controller
{
class PurePursuitController : public nav2_core::Controller
{
public:
PurePursuitController() = default;
~PurePursuitController() override = default;
void configure(
const rclcpp_lifecycle::LifecycleNode::WeakPtr & parent,
std::string name, const std::shared_ptr<tf2_ros::Buffer> & tf,
const std::shared_ptr<nav2_costmap_2d::Costmap2DROS> & costmap_ros) override;
void cleanup() override;
void activate() override;
void deactivate() override;
void setSpeedLimit(const double & speed_limit, const bool & percentage) override;
geometry_msgs::msg::TwistStamped computeVelocityCommands(
const geometry_msgs::msg::PoseStamped & pose,
const geometry_msgs::msg::Twist & velocity,
nav2_core::GoalChecker * goal_checker) override;
void setPlan(const nav_msgs::msg::Path & path) override;
protected:
nav_msgs::msg::Path transformGlobalPlan(const geometry_msgs::msg::PoseStamped & pose);
bool transformPose(
const std::shared_ptr<tf2_ros::Buffer> tf,
const std::string frame,
const geometry_msgs::msg::PoseStamped & in_pose,
geometry_msgs::msg::PoseStamped & out_pose,
const rclcpp::Duration & transform_tolerance
) const;
rclcpp_lifecycle::LifecycleNode::WeakPtr node_;
std::shared_ptr<tf2_ros::Buffer> tf_;
std::string plugin_name_;
std::shared_ptr<nav2_costmap_2d::Costmap2DROS> costmap_ros_;
rclcpp::Logger logger_ {rclcpp::get_logger("PurePursuitController")};
rclcpp::Clock::SharedPtr clock_;
double desired_linear_vel_;
double lookahead_dist_;
double max_angular_vel_;
rclcpp::Duration transform_tolerance_ {0, 0};
nav_msgs::msg::Path global_plan_;
std::shared_ptr<rclcpp_lifecycle::LifecyclePublisher<nav_msgs::msg::Path>> global_pub_;
};
} // namespace nav2_pure_pursuit_controller
#endif // NAV2_PURE_PURSUIT_CONTROLLER__PURE_PURSUIT_CONTROLLER_HPP_
configure、cleanup、activate、deactivate、setSpeedLimit、computeVelocityCommands、setPlan 这七个是基类要求的入口,签名一个字都不能改。setSpeedLimit 常见做法是存一个上限值并在 computeVelocityCommands 里取最小值,percentage 为真时按当前速度的百分比折算,为假时直接当作绝对值上限,这个约定在导航栈其余部分是一致的,照着来即可。
transformGlobalPlan 和 transformPose 放在 protected 里,是内部辅助,不是给 pluginlib 看的;node_ 用 WeakPtr 是为了不延长生命周期节点的存活时间,logger_ 和 clock_ 在 configure 里换成真实节点的,日志才能跟着节点一起输出。
3.3 注册宏与锁文件:让 .so 真的导出符号
cpp 里除了实现,末尾少不了这一句:
cpp复制PLUGINLIB_EXPORT_CLASS(nav2_pure_pursuit_controller::PurePursuitController, nav2_core::Controller)
两个参数分别对应 XML 里的 type 和 base_class_type。这个宏干的事是在动态库里生成供 pluginlib 查询的符号;宏不写,.so 里就没有导出记录,XML 写得再规范也匹配不上。头文件中之所以会带 pluginlib/class_list_macros.hpp,主要就是为了让这行宏可用。
对应的实现骨架分四块,先把生命周期和参数这两块写对:
cpp复制#include <algorithm>
#include <string>
#include <memory>
#include "nav2_core/exceptions.hpp"
#include "nav2_util/node_utils.hpp"
#include "nav2_pure_pursuit_controller/pure_pursuit_controller.hpp"
#include "nav2_util/geometry_utils.hpp"
using std::hypot;
using std::min;
using std::max;
using std::abs;
using nav2_util::declare_parameter_if_not_declared;
using nav2_util::geometry_utils::euclidean_distance;
namespace nav2_pure_pursuit_controller
{
/**
* Find element in iterator with the minimum calculated value
*/
template<typename Iter, typename Getter>
Iter min_by(Iter begin, Iter end, Getter getCompareVal)
{
if (begin == end) {
return end;
}
auto lowest = getCompareVal(*begin);
Iter lowest_it = begin;
for (Iter it = ++begin; it != end; ++it) {
auto comp = getCompareVal(*it);
if (comp < lowest) {
lowest = comp;
lowest_it = it;
}
}
return lowest_it;
}
void PurePursuitController::configure(
const rclcpp_lifecycle::LifecycleNode::WeakPtr & parent,
std::string name, const std::shared_ptr<tf2_ros::Buffer> tf,
const std::shared_ptr<nav2_costmap_2d::Costmap2DROS> costmap_ros)
{
node_ = parent;
auto node = node_.lock();
costmap_ros_ = costmap_ros;
tf_ = tf;
plugin_name_ = name;
logger_ = node->get_logger();
clock_ = node->get_clock();
declare_parameter_if_not_declared(
node, plugin_name_ + ".desired_linear_vel", rclcpp::ParameterValue(
0.2));
declare_parameter_if_not_declared(
node, plugin_name_ + ".lookahead_dist",
rclcpp::ParameterValue(0.4));
declare_parameter_if_not_declared(
node, plugin_name_ + ".max_angular_vel", rclcpp::ParameterValue(
1.0));
declare_parameter_if_not_declared(
node, plugin_name_ + ".transform_tolerance", rclcpp::ParameterValue(
0.1));
node->get_parameter(plugin_name_ + ".desired_linear_vel", desired_linear_vel_);
node->get_parameter(plugin_name_ + ".lookahead_dist", lookahead_dist_);
node->get_parameter(plugin_name_ + ".max_angular_vel", max_angular_vel_);
double transform_tolerance;
node->get_parameter(plugin_name_ + ".transform_tolerance", transform_tolerance);
transform_tolerance_ = rclcpp::Duration::from_seconds(transform_tolerance);
global_pub_ = node->create_publisher<nav_msgs::msg::Path>("received_global_plan", 1);
}
void PurePursuitController::cleanup()
{
RCLCPP_INFO(
logger_,
"Cleaning up controller: %s of type pure_pursuit_controller::PurePursuitController",
plugin_name_.c_str());
global_pub_.reset();
}
void PurePursuitController::activate()
{
RCLCPP_INFO(
logger_,
"Activating controller: %s of type pure_pursuit_controller::PurePursuitController",
plugin_name_.c_str());
// 重新创建 publisher,否则 deactivate 之后再次 activate 发不出去
auto node = node_.lock();
global_pub_ = node->create_publisher<nav_msgs::msg::Path>("received_global_plan", 1);
}
} // namespace nav2_pure_pursuit_controller
configure 里逐行看:node_.lock() 把弱指针升成共享指针,节点已被销毁时这里会拿到空值,是后面所有操作的前提;plugin_name_ = name 保存 controller_server 传进来的插件名,决定参数键的前缀;logger_ 和 clock_ 换成真实节点的,否则日志级别和仿真时间都跟着默认值走。
四个 declare_parameter_if_not_declared 的语义是“没声明过才补默认值”:用户已经在配置里写了的,原样保留。这既是它好用的地方,也是后面参数不生效的坑源,留到第五章细说。最后创建 received_global_plan 的 publisher,队列深度 1,用来把接收到的全局路径对外发布出去,调试时能直接看到插件收到的路径。
4. 参数与生命周期:让功能库从“能加载”走到“真能用”
加载成功只是第一步,接下来要确认三件事:参数能读到、生命周期函数成对出现、computeVelocityCommands 能返回合理的速度。这一章的每一步都直接作用于机器人实际运动。
4.1 参数键的拼法:插件名加点加参数名
插件里的参数不是平铺在节点上的,键名由 plugin_name_ + "." + 参数名 拼出来。plugin_name_ 就是 configure 收到的 name,也就是 controller_server 配置这个插件时给它的名字。四个参数的默认值和调整方向整理如下:
| 参数键后缀 | 默认值 | 含义 | 调大 / 调小的影响 |
|---|---|---|---|
desired_linear_vel |
0.2 | 期望线速度,单位 m/s | 调大提速,但角速度上限要同步跟上,否则转向饱和 |
lookahead_dist |
0.4 | 前视距离,单位 m | 调小转弯跟得紧但容易画龙,调大直线稳但切弯、贴边差 |
max_angular_vel |
1.0 | 角速度上限,单位 rad/s | 调小转向保守、容易跟不上弯,调大容易过冲 |
transform_tolerance |
0.1 | 坐标变换允许的时间容差,单位 s | 调小对 TF 抖动敏感,调大换来的稳定要以位姿滞后为代价 |
这四个默认值是偏保守的一组:0.2 m/s 配 0.4 m 前视、1.0 rad/s 角速度上限,适合先在空场地跑通闭环。真正调到生产速度时,前视距离和线速度要成比例往上走,只提单速度不提前视,最典型的表现就是直线段左右摆。
提示:参数键里的插件名必须和 controller_server 里配置的插件名完全一致,包括大小写与下划线。这个前缀对不上时不会报“未知参数”,只会安静地用默认值。
4.2 从 configure 到 activate:publisher 的生命周期
生命周期节点的调用顺序是 configure → activate → deactivate → cleanup,重激活时走的是 deactivate → activate,configure 不会重新执行。这一点决定了哪些资源该在哪里创建。
configure 负责一次性初始化:拿节点、存 tf 和代价地图、声明并读取参数、创建 publisher。cleanup 负责释放,global_pub_.reset() 把 publisher 放掉。activate 负责让功能真正对外生效,deactivate 是它的逆操作。
问题就出在“重激活不重跑 configure”这个前提上。如果 cleanup 里 reset 了 publisher,而 activate 只打一行日志,那么第二次 activate 之后 publisher 是空的,调用发布就会失败——不是崩溃,是安静地什么都不发,调试时极难定位。上面 3.3 节的 activate 里补了重建 publisher 的两行,就是为了避开这个错位。
setSpeedLimit 也要在生命周期里想清楚:限速值存成员变量,deactivate 时不清零,activate 时不重置,让它跟插件实例同寿命;每次都在 computeVelocityCommands 里取 min(desired_linear_vel_, speed_limit_),这样上层动态限速能立刻生效。
4.3 让接口真正跑起来:setPlan 与最小速度闭环
setPlan 通常只做一件事,把全局路径存下来:
cpp复制void PurePursuitController::setPlan(const nav_msgs::msg::Path & path)
{
global_plan_ = path;
}
真正出速度的是 computeVelocityCommands。下面这版是最小闭环,把接口跑通、参数用上,算法细节留给后续替换:
cpp复制geometry_msgs::msg::TwistStamped PurePursuitController::computeVelocityCommands(
const geometry_msgs::msg::PoseStamped & pose,
const geometry_msgs::msg::Twist &,
nav2_core::GoalChecker *)
{
auto cmd = geometry_msgs::msg::TwistStamped();
cmd.header.stamp = clock_->now();
cmd.header.frame_id = pose.header.frame_id;
// 先按 transform_tolerance_ 把全局路径裁到机器人前方一段
auto plan = transformGlobalPlan(pose);
if (plan.poses.empty()) {
return cmd; // 空路径返回零速,交给上层判失败,别抛异常
}
// 在前视距离上取第一个点作为追踪目标
geometry_msgs::msg::PoseStamped target = plan.poses.front();
for (const auto & p : plan.poses) {
if (euclidean_distance(pose, p) >= lookahead_dist_) {
target = p;
break;
}
}
const double dx = target.pose.position.x - pose.pose.position.x;
const double dy = target.pose.position.y - pose.pose.position.y;
const double alpha = std::atan2(dy, dx);
// 纯追踪的几何关系:曲率 = 2 sin(alpha) / 前视距离
const double curvature = 2.0 * std::sin(alpha) / lookahead_dist_;
cmd.twist.linear.x = desired_linear_vel_;
cmd.twist.angular.z = std::clamp(
curvature * desired_linear_vel_, -max_angular_vel_, max_angular_vel_);
return cmd;
}
几个参数落点要说清:lookahead_dist_ 决定在前方多远切点,取点用 euclidean_distance 算平面距离,路径点太密时这个循环会多走几次,但逻辑是对的;curvature 用的是前视点相对车头方向的夹角,前视距离放在分母上,所以前视越小曲率越大、转向越急;max_angular_vel_ 用 std::clamp 限幅,这一步不做,曲率在急弯处会算出很大的角速度,实车表现为猛打方向然后过冲。
cmd.header.stamp 用节点的 clock_,仿真时间下才不会出现时间戳倒退;frame_id 跟输入位姿保持一致,避免上层做二次变换。路径为空时返回零速而不是抛异常,这是让 controller_server 自己走失败处理逻辑,比让插件崩掉温和得多。
5. 踩坑排查:加载不到、参数不生效、生命周期错位
这一章全部是失败现场。每条按“现象 → 原因 → 解决”写,现象都是日志里能直接看到的,原因基本都落在前面几章的导出链和生命周期上。
5.1 插件加载不到:先查导出链,再怀疑代码
现象:编译 100% 通过,controller_server 一启动就退回默认控制器,日志里只有一句插件类找不到,没有任何堆栈。
原因:最常见有三种。一是 CMakeLists.txt 少了 pluginlib_export_plugin_description_file(nav2_core nav2_pure_pursuit_controller.xml),XML 根本没进索引;二是第一个参数写成了自己的包名而不是 nav2_core,描述文件挂错了位置;三是 install(TARGETS ...) 把 .so 装到了 bin 而 pluginlib 只扫 lib。
解决:按顺序查,别一上来就改代码。先确认安装空间里 lib 目录下确实有那个 .so;再确认 XML 在安装空间里存在且被 export 语句登记;最后打开 XML 核对 type 和 base_class_type 是否逐字符对上类定义。这三步都过了,才轮到 PLUGINLIB_EXPORT_CLASS 宏是否写了。
5.2 参数改了没反应:默认值与键名的错位
现象:改了配置里的前视距离,机器人行为一点没变,日志里也没有任何“未知参数”的警告。
原因:declare_parameter_if_not_declared 的逻辑是“没声明就补默认值”,所以只要配置里的键名和 plugin_name_ + ".lookahead_dist" 对不上,插件就会安静地用 0.4,不报错。插件名多写一个下划线、大小写不一致、把参数写在别的命名空间下,都会命中这一条。
解决:把节点上的参数列表打出来,逐字比对键名前缀;再用参数查询确认插件实际读到的是不是配置里那个值。改配置之后要重启 controller_server,参数在 configure 阶段读取,热改配置不会触发重读。
注意:这类问题不会出现在日志里,属于典型的黑匣子故障。养成“改参数必查实际值”的习惯,比事后翻代码省时间。
5.3 重激活后不发布:cleanup 与 activate 没成对
现象:第一次启动一切正常,手动 deactivate 再 activate 之后,received_global_plan 主题上再也没有消息,也没有报错。
原因:cleanup 里 global_pub_.reset() 释放了 publisher,而重激活只走 deactivate → activate,configure 不会重跑;activate 里如果只打日志不重建 publisher,后续发布就作用在空指针上。
解决:activate 里重建 publisher,或者把 reset 挪到 cleanup 并在 activate 无条件重建,保证每次激活后资源都是新的。排查时可以直接看发布计数,激活后计数不涨就是这个问题。
5.4 到点前画龙或原地打转:三个参数一起看
现象:直线段左右摆,弯道切内圈,接近目标点时原地小幅打转。
原因:lookahead_dist 相对 desired_linear_vel 太短,前视点几乎贴到车上,曲率算出来剧烈跳变;同时 max_angular_vel 限幅在 1.0,急弯处角速度被截断,跟踪误差积累,车就开始绕圈找点;transform_tolerance 只有 0.1,TF 发布稍有抖动,transformGlobalPlan 就返回空路径,表现为走走停停。
解决:先降速到 0.1 m/s 确认闭环本身没问题;再按速度比例上调前视距离,0.2 m/s 配 0.4 m 是个起点,提速后同步上调;transform_tolerance
