在 ROS 2 机器人开发中手动控制一台小车底盘移动几乎是绕不开的需求。无论是验证底盘驱动是否正常、测试运动学参数还是在自主导航之前做一次人工接管手柄遥控都比敲键盘、发指令直观得多。很多刚开始接触 ROS 2 的开发者会以为“手柄控制小车”需要写很复杂的节点其实 ROS 2 已经提供了非常成熟的方案核心链路就是手柄设备 - joy_node - /joy 话题 - teleop_twist_joy - /cmd_vel 话题 - 底盘驱动。本文就以这套链路为主线完整演示如何把一只普通 USB 游戏手柄变成机器人遥控器覆盖设备识别、参数配置、launch 封装、常见报错排查和工程建议。学完之后你可以把它们迁移到自己的差速小车、麦克纳姆轮小车甚至 Gazebo 仿真环境中。如果你已经掌握了 ROS 2 的话题、节点、工作空间等基础概念只是卡在“怎么让小车动起来”这一步那么这篇文章正好合适。我会把每个环节尽量讲透尤其是一些容易被忽略的细节例如手柄权限、按键映射、使能按钮和参数版本差异。整个实操过程基于 Ubuntu 22.04 ROS 2 Humble代码和命令可以直接复制运行。1. 手柄遥控小车的整体思路与原理1.1 为什么用手柄遥控小车在项目调试阶段最常用的控制方式有键盘遥控、手柄遥控和命令行发布速度指令三种。直接发送/cmd_vel虽然简单但无法应对频繁改变方向、线速度和角速度的连续操作。键盘控制可以使用teleop_twist_keyboard这类工具但按键只有“开”和“关”两种状态很难细腻地调节速度。手柄的方案则更接近真实驾驶体验左摇杆控制线速度右摇杆控制角速度按下某个按钮才输出有效速度逻辑自然且易于扩展。更重要的一点是手柄遥控这种模式可以被沿用到后续的自主导航开发中。比如在 NAV2 导航启动前先用手柄把机器人移动到目标点附近在导航过程中遇到异常又可以用手柄快速接管。因此“手柄 - /cmd_vel - 底盘驱动”这条链路并不只是玩具级别的 Demo它是你在真实机器人上调试、验证和安全兜底的重要手段。1.2 从手柄到轮子的完整链路一条指令从手柄到轮子要经过下面几个环节手柄设备 | | USB / 2.4G / 蓝牙 v joy_node | | 发布 sensor_msgs/msg/Joy v /joy | | 订阅并解析 v teleop_twist_joy | | 发布 geometry_msgs/msg/Twist v /cmd_vel | | 被底盘驱动节点订阅 v 电机驱动 - 轮子转动其中joy_node是 ROS 2 官方提供的游戏手柄驱动节点它负责读取 Linux 系统的 joystick 设备文件例如/dev/input/js0把摇杆和按键数据转换成标准消息发布出来。teleop_twist_joy是另一个官方工具包中的节点它订阅/joy按照我们配置的轴映射和使能按钮把Joy消息转换成Twist速度消息。最后小车底盘上的驱动节点比如diff_drive_controller或你自己的机器人驱动订阅/cmd_vel再将速度指令下发给电机。整个过程中负责核心逻辑的其实是两个现成节点我们真正要做的事情只有三件确认手柄被系统识别、配置正确的轴和按键映射、把输出接到正确的话题上。1.3 消息类型Joy 和 Twist要配置好手柄控制必须理解两种消息类型。Joy消息属于sensor_msgs它由两个数组组成axes浮点数组表示摇杆和扳机的值范围一般是从 -1.0 到 1.0。左右摇杆的水平和垂直方向分别对应不同的索引。buttons整型数组每个元素代表一个按键0 表示未按下1 表示按下。可以用下面命令查看 Joy 消息的完整定义ros2 interface show sensor_msgs/msg/Joy输出中会包含Header、axes和buttons字段。不同手柄的轴和按键索引可能不同所以后面需要借助测试工具一个一个确认。Twist消息属于geometry_msgs它表示三维空间中的线速度和角速度。对差速小车来说我们主要关心linear.x和angular.z分别表示前进/后退的线速度和旋转的角速度。ros2 interface show geometry_msgs/msg/Twist理解这两种消息后再看任何手柄控制配置都会轻松很多。2. 环境准备与依赖安装2.1 软硬件清单本文使用的开发环境如下项目说明操作系统Ubuntu 22.04 LTSROS 2 版本Humble Hawksbill手柄常见 USB 2.4G 无线手柄 / Xbox 兼容手柄小车底盘支持订阅/cmd_vel的差速底盘或 Gazebo 仿真模型测试工具joystick 工具包提供 jstest这里要说明一点ROS 2 每隔一段时间会发布新版本不同版本之间包名和参数格式可能存在差异。本文以 Humble 为例如果你使用的是 Jazzy 或其他版本思路完全一致但个别参数名需要以你环境中的实际定义为准。2.2 安装 joy 与 teleop_twist_joy在已经安装 ROS 2 Humble 的前提下打开一个终端执行sudo apt update sudo apt install ros-humble-joy ros-humble-teleop-twist-joy如果你还没有安装 ROS 2建议先按照 ROS 2 官方文档安装 Humble。国内开发者常用的鱼香ROS一键安装也可以脚本会交互式询问你要安装的版本按提示选择humble即可。不管通过哪种方式最终确认环境变量正常source /opt/ros/humble/setup.bash echo $ROS_DISTRO如果输出humble说明当前终端环境已经可以正常使用 ROS 2 命令。后续每次打开新终端都需要先执行source或者把它写入~/.bashrcecho source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc2.3 安装手柄测试工具我们在做按键映射之前必须先知道手柄的每个轴和按键到底对应哪个索引。Linux 下最常用的测试工具是joystick包它提供了jstest和jscal两个命令。sudo apt install joystick安装完成之后把 USB 手柄接收器插入电脑或者通过蓝牙连接手柄再往下看设备识别。3. 手柄设备识别与权限配置3.1 确认手柄已被系统识别首先查看系统有没有生成 joystick 设备节点ls /dev/input/正常情况下能看到类似js0的设备文件同时可能看到event0、event1等输入设备。如果你的手柄是无线接收器建议先插上接收器等待几秒再执行命令。如果js0没有出现可以用lsusb查看 USB 总线上的设备判断手柄有没有被系统识别lsusb输出中会列出所有 USB 设备注意寻找类似Microsoft Corp. Xbox 360 Wireless Receiver、Sony Interactive Entertainment Wireless Controller或者某些通用手柄厂商的 ID。如果lsusb里能看到设备但/dev/input/里没有js0大概率是手柄驱动没有自动加载或者手柄模式切换不对。很多国产手柄需要切到 XInput 模式才能在 Linux 下被正常识别具体切换方式一般是长按某个组合键不同品牌不同建议先查看手柄说明书。3.2 使用 jstest 查看按键和摇杆映射设备识别成功后用jstest查看具体映射sudo jstest /dev/input/js0终端里会动态显示各个轴的值和按键值。此时你可以慢慢拨动摇杆、按下按键边操作边记录对应索引。以常见的 Xbox 兼容手柄为例在默认驱动下设备映射大致如下轴索引含义0左摇杆水平方向1左摇杆垂直方向2右摇杆水平方向或 LT/RT3右摇杆垂直方向4十字键水平方向5十字键垂直方向按钮索引含义0A 键1B 键2X 键3Y 键4LB 键5RB 键6Back 键7Start 键需要特别注意的是这张表只是常见情况并不适用于所有手柄。不同型号的手柄轴索引可能完全不同尤其是国产手柄和 Switch 兼容手柄。所以最稳妥的做法是实际测试一遍把你想用的摇杆和按键索引记录下来后面配置时直接使用。3.3 配置 udev 规则避免权限问题如果不加任何权限配置很多 Linux 系统上普通用户可能无法访问/dev/input/js0导致启动joy_node时出现Cannot open joystick的报错。虽然可以使用sudo运行节点但在 ROS 2 的调试过程中频繁使用sudo会带来环境变量、日志权限等一系列麻烦所以更推荐用 udev 规则放开手柄设备权限。创建规则文件sudo tee /etc/udev/rules.d/70-joystick.rules EOF KERNELjs*, SUBSYSTEMinput, MODE0666 EOF重载 udev 规则并触发更新sudo udevadm control --reload-rules sudo udevadm trigger重新拔插一次手柄然后运行ls -l /dev/input/js0如果权限位变成了crw-rw-rw-或者自己不再是 root 也能打开设备说明权限配置成功。这条规则本质上是对/dev/input/js*设备赋予全局读写权限安全性要求高的场景可以只给自己用户加入input组而不是直接放开权限但对开发机来说这种配置最方便。4. 核心参数拆解从 /joy 到 /cmd_vel4.1 启动 joy_node 并观察 /joy 消息先启动手柄驱动节点source /opt/ros/humble/setup.bash ros2 run joy joy_node如果一切正常节点会开始持续发布/joy话题。打开另一个终端查看消息内容ros2 topic echo /joy此时你拨动摇杆或按下按键终端里会滚动类似下面的数据--- header: stamp: sec: 123 nanosec: 456789 frame_id: axes: [0.0, -0.0, 1.0, 0.0, -0.0, 0.0, 0.0, 0.0] buttons: [0, 0, 0, 1, 0, 0, 0, 0]axes中某个值变化说明对应的是某个摇杆或扳机buttons中某个值变成 1说明对应按键被按下。如果你觉得这里的索引和期望的不一致可以回到jstest中再核对一次。4.2 teleop_twist_joy 的工作原理teleop_twist_joy节点做的事情可以概括成一句话当enable_button对应的按键被按下时它读取指定摇杆轴的值乘以缩放系数然后发布一条Twist消息到/cmd_vel当使能按键没被按下时发布零速指令。很多新手不理解为什么一定要加一个使能按钮。原因在于如果不加任何保护只要摇杆稍微偏离中心位置小车就会自己动起来。尤其在手柄放在桌上时摇杆可能因为重力或弹簧回中不到位产生微小偏差导致机器人突然低速移动。使能按钮相当于一个“解除保险”的开关只有按住这个按钮摇杆输入才会转换成速度指令。4.3 常用参数说明teleop_twist_joy的参数在不同版本中略有差异但核心参数基本一致。最常用的参数如下参数作用示例值enable_button指定哪个按键作为使能开关0enable_turbo_button指定哪个按键作为高速档开关1axis_linear.x指定哪个轴控制线速度1axis_angular.y指定哪个轴控制角速度0scale_linear.x线速度缩放系数0.5scale_angular.y角速度缩放系数0.6deadzone摇杆死区低于该值视为 00.05在 Humble 以及更新的版本中参数名往往支持嵌套形式例如axis_linear.x表示“x 方向的线速度轴”axis_angular.y表示“y 方向的角速度轴”。在 YAML 参数文件中这种嵌套结构会体现得比较明显。由于不同版本对参数命名可能有调整最可靠的检查方式是先启动teleop_node再用下面的命令查看当前版本支持哪些参数ros2 param list /teleop_twist_joy_node ros2 param describe /teleop_twist_joy_node axis_linear.x这样可以看到参数的具体类型、默认值和描述避免因为版本差异而配置错。5. 完整实战手柄控制小车运动5.1 先用命令行把链路跑通为了快速验证链路是否正常我们不急着写 launch 文件先用三个终端跑起来。终端 1启动手柄驱动source /opt/ros/humble/setup.bash ros2 run joy joy_node终端 2启动速度映射节点source /opt/ros/humble/setup.bash ros2 run teleop_twist_joy teleop_node --ros-args \ -p enable_button:0 \ -p axis_linear.x:1 \ -p axis_angular.y:0 \ -p scale_linear.x:0.5 \ -p scale_angular.y:0.6这里的参数含义是按住手柄的 A 键索引 0作为使能按钮左摇杆的垂直方向索引 1控制线速度左摇杆的水平方向索引 0控制角速度。线速度最大 0.5角速度最大 0.6。终端 3查看最终速度指令source /opt/ros/humble/setup.bash ros2 topic echo /cmd_vel操作方式按住 A 键同时把左摇杆往上推你应该能在终端 3 看到类似下面的 Twist 数据linear: x: 0.3 y: 0.0 z: 0.0 angular: x: 0.0 y: 0.0 z: -0.25松开 A 键后/cmd_vel会变成全零。如果这一步完全符合预期说明手柄控制链路已经打通剩下的事情就是把这个临时命令改写成规范配置。5.2 用 YAML 参数文件管理配置命令行直接写参数虽然方便但不利于维护。实际工程中我更推荐把参数写到 YAML 文件里然后用--params-file加载。创建一个配置文件mkdir -p ~/joy_teleop/config vim ~/joy_teleop/config/joy_teleop.yaml内容如下teleop_twist_joy_node: ros__parameters: enable_button: 0 enable_turbo_button: 1 axis_linear: x: 1 axis_angular: y: 0 scale_linear: x: 0.5 scale_angular: y: 0.6 deadzone: 0.05这里把enable_turbo_button设置为 1也就是 B 键。启动时按住 B 键可以进入高速模式但因为我们没有配置 turbo 对应的缩放系数所以暂时效果和普通模式一样。如果你希望高速档有效可以增加scale_linear_turbo.x和scale_angular_turbo.y参数。加载参数文件启动节点ros2 run teleop_twist_joy teleop_node \ --ros-args --params-file ~/joy_teleop/config/joy_teleop.yaml这种做法的好处是参数和代码分离后续调整速度范围时不需要修改启动命令只需要改 YAML 文件。5.3 编写 launch 文件一键启动每次开三个终端比较麻烦尤其是以后还要同时启动底盘、传感器等节点时更需要用 launch 文件统一管理。我们可以在~/joy_teleop/launch目录下创建一个 launch 文件。mkdir -p ~/joy_teleop/launch vim ~/joy_teleop/launch/joy_teleop.launch.py内容如下from launch import LaunchDescription from launch_ros.actions import Node def generate_launch_description(): return LaunchDescription([ Node( packagejoy, executablejoy_node, namejoy_node, outputscreen ), Node( packageteleop_twist_joy, executableteleop_node, nameteleop_twist_joy_node, parameters[/home/user/joy_teleop/config/joy_teleop.yaml], outputscreen ) ])注意把parameters里的路径改成你自己电脑上的绝对路径否则 launch 文件无法加载参数。然后直接执行ros2 launch ~/joy_teleop/launch/joy_teleop.launch.py如果你的 ROS 2 版本提示不能直接按路径启动也可以把joy_teleop.launch.py和joy_teleop.yaml放入一个功能包的launch和config目录中然后使用ros2 launch 包名 launch文件名的方式启动。这里为了快速实践选择直接给 launch 文件路径配置时按自己的工作空间调整即可。5.4 在真实小车或仿真环境中验证手柄控制链路本身不依赖真实机器人任何订阅/cmd_vel的底盘驱动都能被手柄控制。如果你的底盘使用diff_drive_controller只要保证控制器的cmd_vel_in或者对应订阅话题是/cmd_vel启动手柄节点后即可直接遥控。在连接真实底盘之前最安全的验证方式是关闭底盘驱动只启动手柄链路。使用ros2 topic echo /cmd_vel观察速度指令是否正确。确认速度方向无误、缩放合理后再启动底盘驱动。第一次测试时最好把小车用砖头垫起来让轮子悬空避免意外冲出。如果你有 Gazebo 仿真环境同样只需要保证仿真小车订阅/cmd_vel。例如在 Gazebo 中启动一个差速小车模型再启动手柄节点推摇杆就能看到仿真小车开始运动。这种方法非常适合在没有硬件的情况下验证配置。5.5 自定义一个极简转发节点有些特殊手柄或特殊需求下官方teleop_twist_joy可能不太满足要求。这时候可以自己写一个轻量节点把/joy转成/cmd_vel核心逻辑非常清晰。创建文件joy_to_cmd_vel.py#!/usr/bin/env python3 import rclpy from rclpy.node import Node from sensor_msgs.msg import Joy from geometry_msgs.msg import Twist class JoyToCmdVel(Node): def __init__(self): super().__init__(joy_to_cmd_vel) self.subscription self.create_subscription( Joy, /joy, self.joy_callback, 10 ) self.publisher self.create_publisher( Twist, /cmd_vel, 10 ) self.linear_scale 0.5 self.angular_scale 0.6 def joy_callback(self, msg: Joy): twist Twist() # 只有当 A 键按下时才允许输出速度松开后发布零速 if msg.buttons[0] 1: twist.linear.x msg.axes[1] * self.linear_scale twist.angular.z msg.axes[0] * self.angular_scale self.publisher.publish(twist) def main(argsNone): rclpy.init(argsargs) node JoyToCmdVel() rclpy.spin(node) node.destroy_node() rclpy.shutdown() if __name__ __main__: main()用 Python 直接运行python3 joy_to_cmd_vel.py这个节点的逻辑并不复杂重点在于它演示了 ROS 2 话题通信的基本模式订阅Joy消息解析摇杆和按键发布Twist消息。如果你后续想加入自定义滤波、安全逻辑或者和导航抢占控制权都可以在这个节点的基础上扩展。不过日常使用仍然推荐优先用官方teleop_twist_joy官方实现考虑了更多边界情况参数也更完整。6. 常见问题与排查思路6.1 高频问题速查表问题现象常见原因解决思路/dev/input/下没有js0手柄未被系统识别或驱动未加载检查lsusb切换手柄模式重新插拔普通用户打不开js0设备权限不足配置 udev 规则重载后重新插拔ros2 run joy joy_node报找不到设备设备名变化或者没有连接指定--ros-args -p device_name:/dev/input/jsX按键映射错乱手柄轴/按键索引与默认配置不一致用jstest实际测试并记录索引/cmd_vel始终为 0没有按使能按钮或参数名错误按下enable_button并用ros2 param list检查参数安装包时报unable to locate packageROS 2 源未配置或没有 update检查 ROS 2 源、执行sudo apt update多个手柄互相干扰多个机器人使用相同默认域设置不同的ROS_DOMAIN_ID6.2 详细排查流程如果你遇到手柄控制不生效建议按下面顺序排查第一步确认设备是否存在ls /dev/input/js0如果设备不存在回到第三章查看手柄识别和模式切换。第二步确认权限正常ros2 run joy joy_node如果输出Cannot open joystick: /dev/input/js0: Permission denied说明 udev 规则没有生效重新执行udevadm trigger或者重启一次系统。第三步确认/joy话题有数据ros2 topic echo /joy如果没有数据说明joy_node没有正常工作查看节点日志如果有数据但按键索引不对用jstest重新记录索引。第四步确认/cmd_vel有数据ros2 topic echo /cmd_vel如果没有数据重点检查teleop_twist_joy的参数是否正确尤其是enable_button是否按住了。另外如果当前终端没有sourceROS 2 环境也会出现Package teleop_twist_joy not found之类的报错。第五步如果所有数据都正常但小车不动问题大概率出在底盘驱动本身。检查底盘的/cmd_vel话题名是否一致、底盘有没有使能、电机是否上电。7. 最佳实践与工程建议7.1 必须配置使能按钮手柄遥控最怕的事情是误触。摇杆轻微偏移、手柄被碰倒都有可能让小车突然移动。因此无论使用官方节点还是自己写转发节点都一定要配置使能按钮。不要图省事跳过这一步。真机上还可以额外接一个物理急停开关这个开关应该串联在电机驱动电路上与 ROS 2 软件逻辑无关这样即使节点崩溃也能强制停车。7.2 参数和代码分离配置速度映射时不要每次在命令行手写-p参数。把这些参数统一放到 YAML 文件里再通过 launch 文件加载可以显著降低出错概率。尤其是换一台机器人或换一个手柄时只需要修改 YAML 文件中的轴索引和缩放系数不需要改任何代码。7.3 合理设置限速和死区速度缩放系数不是越大越好。第一次调试时建议把线速度限制在 0.2 到 0.3 左右角速度也不要太大先确认方向正确再逐步提高。同时设置适当的deadzone避免摇杆回中偏差导致小车低速蠕动。对于大多数摇杆0.05 到 0.1 的死区是比较合理的范围。7.4 多控制源切换twist_mux真实项目中一辆小车可能会有多个速度指令来源比如手柄手动控制、Nav2 自动导航、遥控急停模块等。如果多个节点同时向/cmd_vel发布速度就会产生冲突。ROS 2 社区常用twist_mux来解决这个问题它可以让多个 Twist 输入按优先级和锁存机制进行切换确保同一时间只有一个控制源生效。建议在学习完手柄控制后下一步就研究一下twist_mux这是通往工程化控制的重要一环。7.5 调试日志与数据回放调试手柄控制时可以给 launch 节点加上outputscreen把节点日志打印到终端。数据链路出现问题时用ros2 topic info /cmd_vel查看话题发布者和订阅者数量用ros2 node info /teleop_twist_joy_node查看节点连接状态。此外ros2 bag record可以录制/joy和/cmd_vel数据方便后续复现操作过程这在调参和排错时非常有用。8. 总结与下一步进阶现在你已经能够完成“手柄摇杆一动小车轮子就转”的整套流程了。从原理上看整个过程并没有复杂算法核心就是把/joy消息转换成/cmd_vel消息从工程上看关键点则在于设备识别、按键映射、使能逻辑和参数管理。如果你用的是官方joy和teleop_twist_joy包配置会非常快如果你需要定制行为也可以自己写一个订阅Joy、发布Twist的小节点。下一步建议你继续学习两件事一是twist_mux多速度源切换理解手动遥控和自动导航之间如何平滑交接二是把手柄遥控接到完整小车系统里配合 IMU、激光雷达做建图和导航实验。手柄遥控只是机器人控制入口的第一步但也正是这一步能让你真正感受到“一个指令如何变成实际运动”的完整链路。如果在配置过程中遇到问题欢迎在评论区留下你的手柄型号、ROS 2 版本和报错信息大家可以一起交流排查。