API 参考

类 XGO_DOG

__init__(port, baud=115200, version="xgomini", verbose=False)

初始化串口连接，检测固件版本并设置参数限制。

• port：串口号（字符串），默认树莓派上port="ttyAMA0"。
• baud：波特率（默认 115200）。
• version：手动指定型号（"xgomini"、"xgolite"），当自动检测失败时使用"xgomini"。
• verbose：若为 True，打印所有收发的数据。

属性:

运动控制

所有接受数值参数的方法均支持负数，表示相反方向。

move_x(step, runtime=0)

沿 X 轴（前进/后退）连续移动。

• step：速度，映射范围为 -VX_LIMIT 到 +VX_LIMIT。
• runtime：若大于 0，移动指定时长后自动停止。

move_y(step, runtime=0)

沿 Y 轴（左/右）连续移动。

turn(step, runtime=0)

绕偏航轴连续旋转。

• step：角速度，正值为左转。

forward(step) / back(step) / left(step) / right(step)

仅需绝对值的快捷方法，内部调用带符号的对应函数。

turnleft(step) / turnright(step)

正向/反向旋转的快捷方法。

move_x_by(distance, vx=18, k=0.035, mintime=0.55)

以 vx 速度移动 distance（单位：米）。持续时间为 k*|distance| + mintime。

move_y_by(distance, vy=18, k=0.0373, mintime=0.5)

横向移动的对应方法。

turn_by(theta, mintime, vyaw=16, k=0.08)

相对旋转 theta 度。持续时间 = |theta|*k + mintime。

move_by(distance, vx, vy, k, mintime)

组合 X/Y 移动。朝 distance 方向以 vx、vy 速度分量移动。

turn_to(theta, vyaw=60, emax=4)

闭环绝对旋转。利用比例控制旋转至 init_yaw + theta。

• theta：相对于初始偏航的目标角度。
• vyaw：最大旋转速度。
• emax：允许误差（度）。

move_set_vel(vx=18, vy=0, vyaw=0, runtime=0)

同时设置三个方向的速度。若 runtime>0，则到时自动停止。注意，vx 和 vy 会自动加上 vel_x_offset 和 vel_y_offset。

stop()

停止所有平移和旋转。

set_move_mintime(mintime)

修改 move_by 系列方法的最短移动时间。

set_vel_offset(vel_x_offset=0, vel_y_offset=0)

设置 X/Y 方向的速度永久补偿值，影响 move_set_vel。

set_yaw_init()

将当前偏航角记录为新的零位参考，供后续 turn_to 使用。

姿态与重心控制

translation(direction, data)

在足端不动的情况下平移机体。

• direction：'x'、'y'、'z'（或这些字符串组成的列表）。
• data：平移量（毫米）。限制因型号而异（见 XGOparam）。

attitude(direction, data)

在足端不动的情况下旋转机体（横滚、俯仰、偏航）。

• direction：'r'、'p'、'y'。
• data：角度（度）。

posture_set_cog(x=0, y=0, z=98)

设置重心在 X、Y、Z 轴上的偏移（默认 Z = 98 毫米）。

posture_set_cog2(x=0, y=0)

仅设置 X/Y 方向的重心偏移。

posture_set_euler(roll=0, pitch=0, yaw=0)

同时设置三个欧拉角。

步态与动作

gait_type(mode)

切换步态："trot"（小跑）、"walk"（行走）、"high_walk"（高抬腿行走）、"slow_trot"（慢跑）。

pace(mode)

改变踏步频率："normal"（正常）、"slow"（慢速）、"high"（高速）。

mark_time(data)

让机器人原地踏步。data 控制踏步高度（0 为关闭）。高度范围：Mini 为 10–35 mm，Lite 为 10–25 mm。

action(action_id, wait=False)

执行预设动作（1–255）。若 wait=True，会阻塞等待动作预估时长结束。

perform(mode)

开启/关闭循环执行动作。mode：0 关闭，1 开启。

reset()

停止所有运动并复位机体姿态。

机械臂控制

机械臂具备 3 个自由度外加爪子。使用前需调用 arm_init(L1, L2) 设置连杆长度。

arm_init(L1, L2, offset1=0, offset2=0)

初始化机械臂几何参数。

• L1：第一节连杆长度（mm）。
• L2：第二节连杆长度（mm）。
• offset1、offset2：可选角度补偿，用于校准。

arm(arm_x, arm_z)

直角坐标控制：水平移动机械臂末端至 arm_x，垂直移动至 arm_z（单位 mm，相对于肩部）。

arm_polar(arm_theta, arm_r)

极坐标控制：arm_theta（度，水平角度）和 arm_r（mm，距肩部距离）。

arm_set_polar(rlen, z, runtime=-1)

将臂末端移至目标径向距离 rlen 和高度 z，可选插值运动。若 runtime 为 0，瞬间移动；若 <0，则根据距离自动计算时长。

arm_set_polar_offset(dlen, dz, runtime=0)

在当前臂位置基础上偏移 dlen (mm) 和 dz (mm)。内部调用 arm_set_polar。

arm_set_angle2(th2, th3)

直接设置第二、三关节角度（度）。

arm_set_grab(angle, runtime=-1)

控制爪子。angle 为角度。若提供 runtime，则平滑过渡。

claw(pos)

旧版爪子控制接口（0–255 原始值）。

arm_mode(mode)

切换机械臂控制模式：0 为直角坐标模式，1 为极坐标模式。

arm_speed(speed)

设置机械臂舵机运动速度（1–255）。

arm_pos_update()

根据当前关节角度重新计算并存储机械臂末端位置（内部使用）。

舵机与电机控制

motor(motor_id, data)

控制单个舵机。

• ID 格式：11（腿1下关节）、12（腿1中关节）、13（腿1上关节），… 41、42、43，以及 51（爪子）、52、53（臂舵机）。
• data：目标角度（度），会被限制在舵机极限范围内。

亦可传入 ID 列表和角度列表进行批量控制。

motor_speed(speed)

全局舵机速度设置（1–255）。

servo_set_angle(servo_id, angle)

更健壮的舵机控制接口，使用预定义的映射参数。支持标准舵机（ID<90）和扩展舵机（ID≥90）。

• servo_id：11–43（腿）、51–54（臂/爪）或 91–99（外部扩展）。

unload_motor(leg_id) / load_motor(leg_id)

释放或锁定某条腿的舵机（腿编号 1–4，5 为机械臂）。

unload_allmotor() / load_allmotor()

释放/锁定所有舵机。

腿部控制

leg(leg_id, data)

控制单条腿的三维运动。

• leg_id：1（右前）、2（左前）、3（右后）、4（左后）。
• data：[x, y, z] 偏移量（毫米）。

moveToMid()

将所有腿移至默认的中立位置。

传感器读取

所有读取方法会阻塞至数据返回（超时约1秒），返回数值。

read_battery()

电池电量百分比（0–100）。

read_firmware()

固件版本字符串。

read_roll() / read_pitch() / read_yaw()

IMU 欧拉角（度）。

read_imu()

返回包含 9 个值的列表：[加速度x, 加速度y, 加速度z (m/s²), 陀螺仪x, 陀螺仪y, 陀螺仪z (度/秒), 横滚, 俯仰, 偏航 (弧度)]。

read_motor()

返回 15 个舵机角度列表（度），顺序为：腿1‑下、腿1‑中、…、腿4‑上、臂‑爪、臂‑2、臂‑3。

read_analog() / read_digital()

读取外部模拟/数字输入值（0–255）。

read_rotate_state()

若机器人正在执行 move_to 旋转则返回 1，否则返回 0。

特殊功能

bt_rename(name)

修改机器人蓝牙广播名称（仅支持 ASCII 字符，最长 10 个字符）。

set_origin()

将当前朝向设为原点，供 turn_to 作为零位参考。

calibration(state)

进入（"start" 或 1）或退出（"end" 或 0）标定模式。请谨慎使用。

upgrade(filename)

发送固件升级文件。实验性功能——不建议在生产环境中使用。

enable_wheel_control(mode)

启用/禁用轮式控制模式（适用于 MINI3W 型号）。

wheel_control(data)

设置轮子速度：data = [右前, 左前, 右后, 左后]（0–255）。

extern_motor(position)

控制外部电机（MINI3W）。

参数与限制

限制值存储在 XGOparam 中，不同型号有所区别。关键参数：