XGO Duck AI 支持通过实体手柄控制运动，本页适用于 0.2.36。请先完成 AI 版安装、舵机设置和校准。首次测试时支撑好机器人，确保周围有活动空间，并让 Torque off 易于操作。
配对与启用
- 在手机或电脑打开
http://<板子IP>:9527/gamepad.html，也可以从驾驶舱的 设置 → 手柄 进入。设备地址以机器人自己的 Network URL 为准。 - 让 Xbox 蓝牙手柄或 Switch Pro 手柄进入配对模式，点击 Scan for controllers。扫描在 30 秒后停止。
- 在目标手柄旁点击 Pair & connect。已配对的设备可使用 Connect、Disconnect 或 Forget。
- 等待 Input ready，让两个摇杆回中并松开按键，点击 Enable gamepad control。
- 配对和启用手柄输入不会自动使能电机；根据需要明确选择 Default pose 或 Walk / get up，先检查站立再进行低速测试。
默认控制
| 输入 | 默认动作 |
|---|---|
| 左摇杆前后 / 左右 | 前后移动 / 横向移动 |
| 右摇杆左右 | 转向 |
| Menu / Start | 行走 / 起身 |
| 下方主按键（Xbox A 位置） | 默认姿态 |
| 右侧主按键（Xbox B 位置） | Torque off，舵机卸力 |
摇杆回中会将移动指令归零，机器人仍可能保持姿态；需要卸力时使用 Torque off。名称按 Xbox 标签和实体位置描述，Switch 手柄的印字可能不同；摇杆无需按住 LB 即可使用。
手柄控制启用期间，网页周期性发送的移动指令会被忽略；网页模式按钮和 Torque off 仍可使用。手柄断开、更换、输入过期或后台连接失败时，控制会卸力并释放手柄输入；重新连接后需要再次明确启用。进入舵机设置或校准也会释放手柄控制。
前向运动还受 ToF 前向限制影响。轮滑模式需要实际安装配套结构，不能横向移动；具体动作和范围以设备所用版本为准。
修改按键
关闭手柄控制，在 Walk / get up、Default pose、Torque off、Pick 或 Roulade 旁点击 Bind。松开已按的键，并在 15 秒内按一次目标键。拾取和翻滚默认未分配，使用时需要处于直立行走状态；Torque off 不可清除。重复绑定、多个键同时按下、超时或断连不会替换原有设置。
按键映射保存在本机 data/gamepad-bindings.json，可跨应用或设备重启保留；更新同一只机器人前应备份其数据。
兼容性与检查
- Xbox 手柄需要蓝牙型号；旧款专有无线型号需要合适的接收器和驱动。
- Switch Pro 需要与开发板内核匹配的
hid-nintendo驱动；独立左右 Joy-Con 不会由服务合并为双摇杆手柄。 - 其他手柄需要 Linux 提供标准双摇杆输入；实际兼容性以设备测试为准。
Unitree-*遥控器可使用 Connect BLE。Unitree-35630A已验证，其他固件版本需要另外确认。
AI 版由硬件支持安装流程准备手柄服务。连接异常时，可先查看硬件服务是否运行，再检查手柄电量、配对和驱动：
systemctl is-active xgoduck-ai-hardware.service