04 xgolib 机器人控制

让机器狗动起来，核心就是调用 xgolib 运动库。本章从最常用的基础运动讲起，再到轮足（Rider/RA）的高级控制，并附各机型的参数范围与机型兼容判断，让你写的运动代码在每个机型上都能跑对。

本章包含：

🧭 阅读路径：四足机型（Mini/Lite/Mini3W）看 4.1；轮足（Rider/RA）看 4.2；要把一套代码跑在多种机型上，务必看 4.3。

前置条件：

• 完成第一章，已能 SSH 登录机器狗；

• 机器狗已开机并处于待机状态（运动指令会直接驱动硬件）；

• 知道自己的机型（Mini / Lite / Rider / RA）。

4.1 基础运动（四足机型）

为什么需要 xgolib：机器狗的舵机、IMU、电池都接在一个串口（UART）上，你没法直接“逐根舵机发指令”。xgolib 把这层串口协议封装成一个对象——创建 XGO() 实例就等于“握住了整只狗的控制权”，之后一行代码就能让它前进、转向或做动作，省去自己处理串口分包、校验、机型差异的麻烦。

xgolib 是 LuwuDynamics 开源的机器狗运动库，PyPI 包名 xgolib（官方托管仓库 LuwuDynamics/xgo_doglib，主打 XGOMini / XGOLite / XGORider / XGOMini3W，新版已移除 xgoedu 支持，安装 pip3 install xgolib）。Luwu-OS 内置版本（当前 1.1.10）位于 /opt/luwu-os/libs/xgolib/，统一入口 XGO() 自动选择机型（__all__ = ['XGO', 'XGO_DOG', 'XGO_RIDER']）。

4.1.1 最小试跑脚本（先看到机器狗动起来）

把下面这段存成 test_move.py，用 python3 test_move.py 跑：

from xgolib import XGO
import time

dog = XGO()          # 自动识别机型并连接串口
print("已连接机型:", dog.read_firmware())

dog.forward(18)      # 速度 18，开始前进
time.sleep(2)        # 持续前进 2 秒
dog.stop()           # 停下
print("完成：机器狗应前进约 2 秒后停止")

✅ 预期效果：终端先打印 已连接机型: M...（固件号），接着机器狗向前走约 2 秒后停下，最后打印完成提示。如果报错或狗不动，先看 4.1.9 常见报错。

⚠️ 第一次运行先确保机器狗电量充足、处于待机、周围无遮挡；速度建议从 10 这种小值试起，确认方向正确后再加大。

4.1.2 连接与基础移动

XGO() 是唯一入口，负责打开串口、探测机型、建立连接：

from xgolib import XGO
dog = XGO()          # 自动检测机型（扫描 /dev/ttyAMA5、/dev/ttyAMA0）
# 也可手动指定机型：XGO("xgomini") / XGO("xgolite") ...

移动类是速度指令：传入速度值，runtime>0 时自动运行该时长后停下；传 0 即停止。

dog.move_x(10, runtime=2)   # 前进速度，约 2 秒后自动停（xgomini: -25~25）
dog.move_y(5, runtime=2)    # 横移速度（-18~18）
dog.turn(10, runtime=1)     # 原地转向速度（-100~100）
dog.move_x(0)               # 手动停止

4.1.3 方向语义（前进 / 后退 / 左移 / 右移）

不区分轴，直接用语义化方法，内部等同 move_x / move_y：

dog.move('x', 10)   # 通用方向：'x' / 'y'
dog.forward(10)     # 前进（等同 move_x）
dog.back(10)        # 后退
dog.left(10)        # 左移
dog.right(10)       # 右移

4.1.4 姿态与平移（四足机身）

• 姿态 attitude：控制机身俯仰 / 横滚 / 偏航角度（xgomini: Roll ±20° / Pitch ±22° / Yaw ±16°）

• 平移 translation：控制机体在 X / Y / Z 轴上的位移与高度（xgomini: X ±35 / Y ±19.5 / Z 75~120mm）

dog.attitude('p', 15)                # 俯仰单轴
dog.attitude(['y', 'p'], [5, 10])    # 偏航+俯仰多轴

dog.translation('x', 10)    # 前后（-35~35）
dog.translation('y', 5)     # 左右（-19.5~19.5）
dog.translation('z', 90)    # 高度（75~120）

4.1.5 步态、动作与表演

dog.gait_type('trot')       # 步态：trot / walk / high_walk / slow_trot

dog.action(13, wait=True)   # 播一个预设动作（ID 1~255，wait=True 阻塞到播完）

dog.perform(1)              # 开启循环表演（自动轮播动作）；perform(0) 停止

dog.pace(0)                 # 原地踏步（0 停止 / 1 开始）
dog.mark_time(10)           # 踏步高度（xgomini: 10~35）

💡 动作编号由固件动作表决定，不同机型 / 版本可用的 ID 不同，建议先用小 ID 试播一次确认。

4.1.6 机械臂（带臂机型，如 XGO-MINI）

dog.arm(120, 150)           # 直角坐标控制（x, z）
dog.arm_polar(200, 130)     # 极坐标控制（角度 theta, 距离 r）
dog.arm_mode(1)             # 机械臂模式切换
dog.arm_speed(50)           # 机械臂速度（0~100）
dog.claw(245)               # 夹爪（0=张开, 255=闭合）

4.1.7 读取状态

batt = dog.read_battery()    # 电量 0~100
fw = dog.read_firmware()     # 固件版本字符串，如 'M107'
roll = dog.read_roll()       # 当前横滚角

其他通用控制：dog.stop() 停止所有运动、dog.imu(1) 自平衡开关（1=开, 0=关）、dog.reset() 复位到初始姿态。

4.1.8 参数范围表（与机型有关，来自 xgolib_dog.py 的 changePara()）

4.1.9 常见报错

4.2 高级控制（XGO-RIDER / RA 轮足）

RA 与 Rider 指同一款轮足机器人。ra_* 与 rider_* 都是定义在 XGO_RIDER 类上的方法（ra_* 是面向 RA 的别名包装），通过 XGO("ra") 或 XGO("rider") 得到的就是 XGO_RIDER 实例：

from xgolib import XGO

dog = XGO("ra")   # 返回 XGO_RIDER 实例（内部 version="xgorider"）

# --- RA 接口（范围 -87~+87 等，见方法 docstring）---
dog.ra_mode(0)       # 模式切换：0=轮足模式, 1=小车模式
dog.ra_move_x(87)    # 前后移动，速度 -87~+87
dog.ra_turn(87)      # 旋转，速度 -87~+87
dog.ra_height(50)    # 底盘高度，范围 0~100
dog.ra_roll(10)      # 横滚角 Roll，-87~+87
dog.ra_pitch(10)     # 俯仰角 Pitch，-87~+87
dog.ra_action(1)     # 预设动作：1=左右摇摆, 2=高低起伏, 3=前进后退,
                     # 4=四方蛇形, 5=升降旋转, 6=圆周晃动, 255=重置
dog.ra_perform(1)    # 开启/关闭表演模式（动作轮播）
dog.ra_imu(1)        # 自平衡开关
dog.ra_led(0, [255, 0, 0])   # 灯带颜色（index, RGB 列表）
dog.ra_reset()       # 复位

# --- Rider 原生接口（rider_*）---
dog.rider_move_x(1.0)        # 前进速度（VX ±1.5）
dog.rider_turn(90)           # 转向速度（VYAW ±360）
dog.rider_height(90)         # 底盘高度（Z 60~120mm）
dog.rider_roll(10)           # 横滚角（Roll ±17°）
dog.rider_action(1)          # 预设动作（1~255）
dog.rider_perform(1)         # 表演模式开/关
dog.rider_balance_roll(1)    # 自平衡开关（IMU）
dog.rider_reset_odom()       # 里程计归零
dog.rider_led(0, [0, 255, 0])        # 灯带
dog.rider_read_battery()     # 电量
dog.rider_read_roll()        # 读取横滚角
dog.rider_read_pitch()       # 读取俯仰角
dog.rider_read_yaw()         # 读取偏航角

XGO_RIDER 也继承全部通用运动方法（move_x/move_y/turn/translation/attitude/action 等），但参数范围按 xgorider 参数表（VX ±1.5 / VY ±1.0 / VYAW ±360 / Z 60~120mm / Roll ±17°）。

4.3 机型兼容

XGO(version="auto", port=None, baud=0, verbose=False)：

• version：不传则自动扫描串口（SCAN_PORTS = ["/dev/ttyAMA5", "/dev/ttyAMA0"]）并探测固件

• 支持的机型别名（短名/全名）：

ℹ️ XGO("xgomini3w") 是有效别名（xgomini3w / xgomini3W 映射到 MINI3W 机型；xgolib 1.1.10 已支持）。注意区分：launcher/devicetable.h 机型注册表中的 xgomini3w 用于示例程序的机型过滤。

from xgolib import XGO, XGO_RIDER

dog = XGO()          # 自动检测机型
# 也可手动指定：XGO("xgomini") / XGO("xgolite") / XGO("mini3w") / XGO("rider") / XGO("ra")

# 按机型分支逻辑
if isinstance(dog, XGO_RIDER):
    dog.rider_roll(10)          # 轮足：用 rider_*/ra_* 接口
else:
    dog.attitude('r', 10)       # 四足：用 attitude/translation 等

# 固件版本检测
fw = dog.read_firmware()        # 返回 ASCII 固件字符串，如 'M107' / 'RA100' / 'MW300'
if fw.upper().startswith('RA'):
    pass  # RA 机型逻辑

系统层面的机型判断可调用 configs/detect_device.py（launcher 也在用）：

python3 /opt/luwu-os/configs/detect_device.py
# 输出机型字符串：xgomini / xgolite / xgomini2sw / xgorider / unknown
# 优先级：串口实时探测 > configs/device.ini 手动覆盖 > unknown

4.4 调试与验证小贴士

写运动代码时最怕「一键跑全身」——狗一动可能撞到人或自己摔倒。建议：

⚠️ 任何运动测试先确认电量充足、周围无遮挡、狗处于待机状态；一旦出现异常尽快按 dog.stop() 或直接断电。