企业官网建设流程全解析

Microduck 是一个由强化学习（RL）驱动的紧凑双足机器人，支持通过蓝牙游戏手柄直接操控行走、原地转向和急停。不同手柄的轴号和键位经常不一致，本文教你用jstest快速查出真实轴号，再修改 gamepad_input.py 顶部的几个常量，即可适配任意蓝牙手柄。

为什么你的手柄"不按套路出牌"

仓库默认按键布局（左摇杆 = 轴 0/1，右摇杆横轴 = 轴 2，A=0、B=1、Start=11）是在 Xbox 手柄的蓝牙模式下验证过的。但蓝牙下 Linux 内核分配的轴/键编号经常和有线xpad布局不同，表现就是：推摇杆没反应、按 A 却触发了别的动作。

好消息是：Microduck 把映射逻辑全部集中在常量里，重映射不需要改任何逻辑代码。官方说明见 gamepad.md。

前置条件：先确保能用 SSH 连上 Pi

重映射需要 SSH 会话，所以要先关闭无头模式（无头模式下手柄一连上 Wi-Fi 就会被关闭，你根本连不上 Pi）：

make gamepad-headless-disable

然后通过 SSH 登录树莓派，并确保手柄已开机、蓝牙已配对连接（配对方法在 gamepad.md 中有完整步骤）。

第一步：安装并运行 jstest

在 Pi 上安装 joystick 工具包：

sudo apt install -y joystick

然后运行：

jstest /dev/input/js0

接着逐个动作测试：分别推左摇杆、推右摇杆、按每个键，观察屏幕上变化的Axis N/Button N，把编号记下来：

💡 小技巧：jstest 会实时显示每个轴的数值。把摇杆从中间推到最远端，记录数值范围；扳机键记下"按下"时的数值，用于后面的阈值设置。

第二步：修改 gamepad_input.py 中的常量

打开 gamepad_input.py，文件顶部就是所有映射常量，只需改动这几处：

• 摇杆轴号：_AXIS_LX / _AXIS_LY / _AXIS_RX，对应 jstest 里左摇杆 XY 和右摇杆横轴的Axis编号。
• 按键编号：XBOX_BUTTONS 是"键名 → 编号"的字典，至少更新你用到的键（A、B、BACK、START 等）。
• 扳机轴：TRIGGER_AXES 填入LT/RT的轴号；TRIGGER_PRESS_THRESHOLD填"按下扳机"时的原始轴值。
• 方向符号：VX_SIGN / VY_SIGN / VTHETA_SIGN。如果某个方向反了（比如推前却往后走），把对应值在+1.0/-1.0之间翻转即可，不用动其他代码。

顺带一提，死区常量DEADZONE = 0.12（低于此比例的摇杆偏移会被当居中处理）如果碰到摇杆漂移问题，可以适当调大。

第三步：设置"哪个键干什么"

键号解决"是哪个键"，动作绑定解决"干什么"。在 main.py 中：

GAMEPAD_BUTTON_MOVES = {"A": "walk"}

把键名换成你想绑定的技能，例如让 X 键触发走路就改成{"X": "walk"}。

另外两个固定功能键由GamepadInputSource的构造参数控制（见 gamepad_input.py）：

• stop_button：急停，默认"B"（写入停止标志）
• imu_button：切换 IMU/陀螺仪显示，默认"BACK"

改完后执行make run实测：手柄连接时会自动接管键盘输入，按A切换walk技能、推左摇杆控制前后/左右、推右摇杆控制原地转向。

常见问题速查

速度上限统一由 constants.py 中的VX_MAX/VY_MAX/VTHETA_MAX_STATIONARY/VTHETA_MAX_MOVING控制，键盘、手柄、仿真三者一致，重映射时无需改动。

小结

整个重映射流程只有三步：jstest查编号 → 改 gamepad_input.py 顶部常量 → （可选）调整 main.py 的动作绑定。改的是常量而非逻辑，风险低、可回退，掌握这套方法后，任何能接上 Linux joystick API 的蓝牙手柄都能驱动 Microduck 行走。