这篇是一步到位的教程 + 踩坑笔记：在 Ubuntu 上用 Xbox Series X|S 手柄 控制 ROS1 的 turtlesim。
重点覆盖：xone 驱动、linux-modules-extra 缺失导致的“手柄灯闪一下但不工作”、ROS 手柄控制节点启动与排错，以及一个很容易踩的“必须按住使能键”的新手误区。

---

1. 环境说明

• 系统：Ubuntu 20.04/22.04（示例为 20.04）

• ROS：ROS1（Noetic/ Melodic 均可，示例用 Noetic）

• 手柄：Xbox Series X|S（微软新款）

• 连接：USB 或蓝牙（文中以 USB 为例）

• 驱动：xone（针对 Xbox One/Series 的内核模块）

如果你用 Xbox 360，优先使用 xpad（内核自带）；xboxdrv 对新款手柄兼容性差，不推荐。

---

2. 为什么不是 xboxdrv / 仅靠 xpad？

• xboxdrv：主要面向 Xbox 360，多年无人维护；对 Xbox One/Series 识别/映射不可靠，很多情况下直接认不出。

• xpad（内核自带）：对 360 很稳；对新款能“勉强用”，但震动/电量/部分映射不全。

• xone：专为 Xbox One/Series 设计（USB/官方无线接收器），功能更完整，是新款手柄首选。

一句话建议：Xbox 360→xpad；Xbox One/Series→xone（USB/接收器）或 xpadneo（蓝牙）。

---

3. 安装 xone 驱动

3.1 依赖

sudo apt update
sudo apt install dkms linux-headers-$(uname -r) git

3.2 克隆并安装

git clone https://github.com/medusalix/xone
cd xone
sudo ./install.sh --release

3.3 基本验证

ls /dev/input/js*

看到 /dev/input/js0 说明系统已经生成了手柄事件设备。

---

4. 关键踩坑：灯闪一下但不工作 → 缺少 linux-modules-extra 包

现象：安装 xone 后，插手柄指示灯闪着，但 /dev/input/js0 不出现或 ROS 读不到数据。joy_node 中常见 Couldn't set gain on joystick force feedback 提示。

原因：系统缺少与你当前内核版本匹配的 linux-modules-extra 包，它包含大量额外驱动模块（包括 force feedback、HID 等）。

解决方案：

uname -r  # 查当前内核版本
sudo apt update
sudo apt install linux-modules-extra-$(uname -r)

该操作不会改变内核版本，只是为当前内核补齐驱动模块，并会触发 DKMS 与 initramfs 更新。

安装完成后，建议重启并重新安装 xone，重新安装前需要拔掉手柄有线连接：

cd ~/xone
sudo ./uninstall.sh
sudo ./install.sh --release

---

5. 手柄调试

sudo apt install jstest-gtk
jstest-gtk

检查摇杆、按键是否响应。

---

6. 安装 ROS 包

sudo apt install ros-$(rosversion -d)-turtlesim \
                 ros-$(rosversion -d)-joy \
                 ros-$(rosversion -d)-teleop-twist-joy

---

7. 启动 ROS 控制

终端 1：

roscore
# 另开终端
rosrun turtlesim turtlesim_node

终端 2：

rosrun joy joy_node dev:=/dev/input/js0

看到：

Opened joystick: /dev/input/js0 (Microsoft Xbox Controller)

表示识别成功。

终端 3：

rosrun teleop_twist_joy teleop_node \
  _enable_button:=4 _enable_turbo_button:=5 \
  _axis_linear:=1  _axis_angular:=0 \
  _scale_linear:=2.0 _scale_angular:=2.0 \
  _scale_linear_turbo:=4.0 _scale_angular_turbo:=4.0 \
  cmd_vel:=/turtle1/cmd_vel

新手常见误区提醒：默认 teleop_twist_joy 需要按住 使能键 才会输出速度指令。如果参数未改动，可能是 A 键（索引 0）；本教程改成了 LB（索引 4）。如果你只推摇杆而不按使能键，小乌龟不会动！

操作：按住 LB 推左摇杆控制方向，RB 为加速模式。

---

8. 快速排错

• 没有 /dev/input/js0 → 检查 linux-modules-extra 是否安装、xone 是否加载成功。

• /joy 无数据 → 检查 joy_node 输出，是否正确指定设备路径。

• /turtle1/cmd_vel 无数据 → 检查是否按住使能键，以及参数映射。

---

9. 一键启动 launch

<launch>
  <node pkg="turtlesim" type="turtlesim_node" name="turtlesim" />
  <node pkg="joy" type="joy_node" name="joy_node">
    <param name="dev" value="/dev/input/js0" />
  </node>
  <node pkg="teleop_twist_joy" type="teleop_node" name="teleop_twist_joy" output="screen">
    <param name="axis_linear" value="1" />
    <param name="axis_angular" value="0" />
    <param name="scale_linear" value="2.0" />
    <param name="scale_angular" value="2.0" />
    <param name="scale_linear_turbo" value="4.0" />
    <param name="scale_angular_turbo" value="4.0" />
    <param name="enable_button" value="4" />
    <param name="enable_turbo_button" value="5" />
    <remap from="cmd_vel" to="/turtle1/cmd_vel" />
  </node>
</launch>

---

10. Xbox 系列驱动对照表

手柄	推荐驱动	连接	备注
Xbox 360	xpad（内核自带）	USB / 官方无线接收器	稳定、免编译
Xbox One	xone（USB/接收器） / xpadneo（蓝牙）	USB / 蓝牙	功能全
Xbox Series X	S	xone（USB/接收器） / xpadneo（蓝牙）	USB / 蓝牙

结论：xboxdrv 主要支持 360，新款常常不识别；控制 ROS 请用 xone 或 xpadneo。

---

11. 总结

• 新款 Xbox Series → 首选 xone。

• “灯闪不工作” → 多数是缺少 linux-modules-extra-$(uname -r)，安装后重装 xone。

• ROS 控制 → joy_node + teleop_twist_joy，记住 按住使能键才能动。

• 调试 → rostopic echo /joy 和 /turtle1/cmd_vel 最直观。