XGO 机器狗控制

控制 XGO 系列机器狗（Mini/Lite/Mini3W/Rider），涵盖运动控制、视觉识别、AI 功能、传感器读取等完整能力。

执行环境（强制）

必须使用指定的虚拟环境 Python：

标准执行命令（必须使用）

# 统一执行模板（cd到skill目录 + 超时保护）
cd /home/pi/.npm-global/lib/node_modules/openclaw/skills/xgorobot && timeout 30 /home/pi/RaspberryPi-CM5/blocklyvenv/bin/python -u scripts/xxx.py

预置脚本示例：

cd /home/pi/.npm-global/lib/node_modules/openclaw/skills/xgorobot && timeout 30 /home/pi/RaspberryPi-CM5/blocklyvenv/bin/python -u scripts/motion/forward.py --step 15

自定义代码示例：

cd /home/pi/.npm-global/lib/node_modules/openclaw/skills/xgorobot && timeout 30 /home/pi/RaspberryPi-CM5/blocklyvenv/bin/python -u /tmp/my_script.py

重要： - 不要用 sudo（openclaw 不支持） - 必须用 timeout 30 包裹，防止脚本卡死 - 如果仍然卡住，检查机器狗是否开机、串口连接是否正常

---

执行策略（重要）

优先级 1：使用预置脚本

优先检查 scripts/ 目录下是否有匹配的预置脚本，直接执行：

cd /home/pi/.npm-global/lib/node_modules/openclaw/skills/xgorobot && timeout 30 /home/pi/RaspberryPi-CM5/blocklyvenv/bin/python -u scripts/motion/forward.py --step 15

优先级 2：开放式识别优先用 AI 图片理解

当需要识别/理解任意物体时，优先使用 photo_understand.py：

场景	用 AI 图片理解	用 YOLO/传统视觉
识别任意物体（纸巾、胡萝卜、杯子...）	✓ 推荐	✗ 类别有限
判断物体位置（左/中/右）	✓ 推荐	✗ 需额外计算
理解场景/回答问题	✓ 推荐	✗ 不支持
实时追踪已知类别（人/球）	✗ 太慢	✓ 推荐
快速检测有无人脸	✗ 太慢	✓ 推荐

AI 图片理解示例：

# 问图中某物体的位置
cd /home/pi/.npm-global/lib/node_modules/openclaw/skills/xgorobot && timeout 30 /home/pi/RaspberryPi-CM5/blocklyvenv/bin/python -u scripts/ai/photo_understand.py --prompt "图中纸巾在什么位置？只回答：左边/中间/右边/没有"

# 识别图中有哪些物体
cd /home/pi/.npm-global/lib/node_modules/openclaw/skills/xgorobot && timeout 30 /home/pi/RaspberryPi-CM5/blocklyvenv/bin/python -u scripts/ai/photo_understand.py --prompt "图中有哪些物品？列出名称"

# 判断场景
cd /home/pi/.npm-global/lib/node_modules/openclaw/skills/xgorobot && timeout 30 /home/pi/RaspberryPi-CM5/blocklyvenv/bin/python -u scripts/ai/photo_understand.py --prompt "这是室内还是室外？"

简单说： YOLO 只能识别 80 种固定类别，AI 图片理解能识别任何东西并回答问题。

优先级 3：预置脚本不满足时才生成代码

当预置脚本参数无法满足需求，或需要组合多个功能时，参考 lib/ 目录的 API 编写新代码。

---

预置脚本列表

基础运动 (scripts/motion/)

脚本	功能	参数
forward.py	前进	--step 15 (0-25) --duration 2
backward.py	后退	--step 15 (0-25) --duration 2
left.py	左移	--step 10 (0-18) --duration 2
right.py	右移	--step 10 (0-18) --duration 2
turn.py	旋转	--speed 50 (-100~100，正左负右) --duration 1
turn_left.py	左转	--speed 50 (0-100) --duration 1
turn_right.py	右转	--speed 50 (0-100) --duration 1
stop.py	停止	无参数
reset.py	复位	无参数

姿态控制 (scripts/motion/)

脚本	功能	参数
squat.py	蹲下	--height 80 (75-120mm)
stand.py	站立	--height 115 (75-120mm)
tilt.py	倾斜	--roll 0 --pitch 0 --yaw 0
attitude.py	姿态控制	--roll 10 (-20~20) --pitch 5 (-22~22) --yaw 0 (-16~16)
translation.py	机身平移	--axis z (x/y/z) --distance 95
mark_time.py	原地踏步	--height 20 (10-35mm) --duration 3

周期运动 (scripts/motion/)

脚本	功能	参数
periodic_tran.py	周期平移	--axis z (x/y/z) --period 2 (1.5-8秒) --duration 5
periodic_rot.py	周期旋转	--axis r (r/p/y) --period 2 (1.5-8秒) --duration 5

步态与速度 (scripts/motion/)

脚本	功能	参数
gait_type.py	步态类型	--mode trot (trot/walk/high_walk/slow_trot)
pace.py	步频控制	--mode normal (normal/slow/high)
imu.py	IMU平衡	--mode 1 (0=关, 1=开)

单腿与舵机 (scripts/motion/)

脚本	功能	参数
leg.py	单腿控制	--id 1 (1-4) --x 0 --y 0 --z 95
motor.py	舵机控制	--id 11 (11-43,51) --angle 45
motor_speed.py	舵机速度	--speed 128 (1-255)
load_motor.py	加载舵机	--leg 1 (1-5)
unload_motor.py	卸载舵机	--leg 1 (1-5)

机械臂 (scripts/motion/) - Mini/Mini3W

脚本	功能	参数
arm.py	机械臂控制	--action open (open/close/up/down)

---

预设动作 (scripts/action/)

脚本	功能	参数
action.py	执行动作ID	--id 1 (1-23/128-141/255)
sit.py	坐下	无参数
lie_down.py	趴下	无参数
stand.py	起立	无参数
wave.py	招手	无参数
pee.py	撒尿	无参数
pushup.py	俯卧撑	无参数
pray.py	祈祷	无参数
swing.py	摇摆	--duration 5
crawl.py	匍匐	无参数
stretch.py	伸展	无参数
spin.py	旋转	无参数

---

视觉识别 (scripts/vision/)

脚本	功能	参数	输出
take_photo.py	拍照	--filename photo.jpg	照片已保存:
camera_preview.py	摄像头预览	--duration 10	预览窗口显示
face_detect.py	人脸检测	--continuous (持续模式)	检测到人脸: x=, y=, w=, h= 或 未检测到人脸
face_count.py	人脸计数	无	共检测到 N 张人脸 + 每张人脸位置
gesture_detect.py	手势识别	--continuous	识别到手势: {手势} 位置=({x},{y}) 或 无
color_detect.py	颜色识别	--color R (R/G/B/Y) --continuous	检测到{颜色}: 位置=({x},{y}), 半径={r}
line_detect.py	巡线检测	--color K (K黑/W白/R/G/B/Y) --continuous	巡线: x={x}, angle={角度}
qr_scan.py	二维码扫描	--continuous	二维码内容: {内容} 或 无
yolo_detect.py	目标检测	--continuous	检测到: {类别} 位置=({x},{y}) 或 无
emotion_detect.py	情绪识别	--continuous	情绪: {情绪} 位置=({x},{y}) 或 无

视觉追踪 (scripts/vision/)

脚本	功能	参数	输出
find_ball.py	寻找小球	--color R --timeout 30	✓ 找到{颜色}色小球 或 ✗ 超时未找到
find_person.py	寻找人类	--timeout 45	✓ 找到人类 或 ✗ 超时未找到
catch_ball.py	抓取小球	--color R --timeout 60	✓ 抓取成功 或 ✗ 抓取失败

---

传感器读取 (scripts/sensor/)

脚本	功能	输出
battery.py	读取电量	百分比
read_roll.py	读取Roll角	横滚角度
read_pitch.py	读取Pitch角	俯仰角度
read_yaw.py	读取Yaw角	偏航角度
read_imu.py	读取IMU	--axis all (roll/pitch/yaw/all)
read_motor.py	读取舵机角度	所有舵机当前角度

---

屏幕显示 (scripts/display/)

脚本	功能	参数
text.py	显示文字	--text "Hello" --x 5 --y 5 --color WHITE --size 15
clear.py	清除屏幕	无参数
picture.py	显示本地图片	--filename photo.jpg --x 0 --y 0
http_image.py	显示网络图片	--url "http://..." --x 0 --y 0

---

音频播放 (scripts/audio/)

脚本	功能	参数
play.py	播放本地音频	--filename music.mp3
play_http.py	播放网络音频	--url "http://..."
play_music.py	播放背景音乐(Dream.mp3)	无参数

---

AI功能 (scripts/ai/) - 需要 DASHSCOPE_API_KEY

脚本	功能	参数	输出
photo_understand.py	AI拍照理解	--prompt "提问内容"	问题: {prompt} / 回答: {AI回答}
speech_recognition.py	语音识别	--seconds 3	识别结果:
text_to_speech.py	AI语音合成	--text "你好" --voice Cherry	语音播放（自然人声，需API）
generate_image.py	AI生成图片	--prompt "一只猫"	图片已保存:
goto_target.py	AI走向目标	--target "黄色小鸡" --timeout 60	✓ 已到达目标 或 ✗ 未能到达

语音输出选择： 机器狗说话优先用 text_to_speech.py

photo_understand.py 常用 prompt 示例：

任务	prompt 示例
物体位置	--prompt "图中纸巾在什么位置？只回答：左边/中间/右边/没有"
物体列举	--prompt "图中有哪些物品？列出名称"
物体计数	--prompt "图中有几个苹果？只回答数字"
颜色判断	--prompt "图中最大的物体是什么颜色？"
场景理解	--prompt "这是什么地方？简要描述"
是非判断	--prompt "图中有人吗？只回答有/没有"
物体对比	--prompt "图中哪个物体更大？"

API密钥通过环境变量 DASHSCOPE_API_KEY 自动读取，也可用 --api-key 参数覆盖

---

Mini3W专用 (scripts/mini3w/)

脚本	功能	参数
enable_wheel.py	轮控开关	--mode 0 (0=启用, 1=禁用)
wheel_control.py	轮控制	--w1 128 --w2 128 --w3 128 --w4 128
extern_motor.py	外接电机	--position 100

---

Rider专用 (scripts/rider/)

运动控制

脚本	功能	参数
move.py	前后移动	--speed 0.5 --runtime 3
turn.py	原地旋转	--speed 90 --runtime 2
roll.py	Roll姿态	--angle 10
height.py	身高调整	--height 90
reset.py	重置	无参数
reset_odom.py	重置里程计	无参数

模式控制

脚本	功能	参数
action.py	预设动作	--id 1 (1-6/255)
balance_roll.py	Roll自平衡	--mode 1 (0=关, 1=开)
perform.py	表演模式	--mode 1 (0=关, 1=开)
calibration.py	软件标定	--state start/end

周期运动

脚本	功能	参数
periodic_roll.py	周期Roll	--period 1.5 --duration 5
periodic_z.py	周期升降	--period 1.5 --duration 5

传感器与LED

脚本	功能	参数
battery.py	读取电量	无参数
read_roll.py	读取Roll	无参数
read_pitch.py	读取Pitch	无参数
read_yaw.py	读取Yaw	无参数
led.py	LED控制	--index 0 --r 255 --g 0 --b 0

---

组合任务 (scripts/combo/)

脚本	功能	参数
ai_find_step.py	AI智能踩物	--target "纸巾" --leg 1 (1=左前,2=右前) --speed 100 (越小越机械)
follow_face.py	人脸追踪	无参数，按C退出
follow_color.py	颜色追踪	--color R (R/G/B/Y)
gesture_control.py	手势控制	无参数，按C退出
line_follow.py	巡线行走	--color K (K黑/W白)
qr_patrol.py	二维码巡逻	无参数，按C退出

---

Python 库参考（用于编写新代码）

当预置脚本无法满足需求时，参考以下源码编写代码：

模块	文件路径	功能说明
运动控制	lib/xgolib/xgolib_dog.py	XGO_DOG 类：四足机器狗运动、姿态、机械臂控制
Rider控制	lib/xgolib/xgolib_rider.py	XGO_RIDER 类：双轮足机器人专用
视觉传感器	lib/edulib.py	XGOEDU 类：摄像头、屏幕、按键、各种识别功能

这些文件包含完整的方法签名、参数范围和注释，是最准确的 API 参考。

代码模板（必须遵循）

import sys
sys.path.insert(0, '/home/pi/.npm-global/lib/node_modules/openclaw/skills/xgorobot/lib')
from xgolib import XGO       # 通用类，自动识别机型
from edulib import XGOEDU    # 视觉/屏幕/按键

# 初始化（不带参数，自动检测）
dog = XGO()
edu = XGOEDU()

重要：sys.path.insert 和 XGO() 不带参数是必须的，否则会出错或卡死

机型识别

XGO 类自动识别机型，无需手动指定：

dog = XGO()  # 自动检测串口和机型
firmware = dog.read_firmware()  # 首字母: M=Mini, L=Lite, W=Mini3W, R=Rider

机型	特征	固件首字母
XGO-Mini	12自由度，有机械臂	M
XGO-Lite	轻量版，无机械臂	L
XGO-Mini3W	支持轮控模式	W
XGO-Rider	双轮足，非四足	R

快速参考

运动控制 (XGO)

dog = XGO()

# 基础运动
dog.forward(step)      # 前进 0-25
dog.back(step)         # 后退 0-25
dog.left(step)         # 左移 0-18
dog.right(step)        # 右移 0-18
dog.turnleft(step)     # 左转 0-100
dog.turnright(step)    # 右转 0-100
dog.stop()             # 停止

# 姿态控制
dog.translation('z', height)  # 身高 75-120mm
dog.attitude('r', angle)      # Roll 姿态
dog.attitude('p', angle)      # Pitch 姿态
dog.attitude('y', angle)      # Yaw 姿态

# 预设动作
dog.action(id)         # 执行预设动作 1-255
dog.reset()            # 恢复初始姿态

# 机械臂 (Mini/Mini3W)
dog.arm(x, z)          # 机械臂位置
dog.claw(pos)          # 夹爪开合 0-255

# 状态读取
dog.read_battery()     # 电量
dog.read_roll()        # Roll 角度
dog.read_pitch()       # Pitch 角度
dog.read_yaw()         # Yaw 角度

视觉传感器 (XGOEDU)

edu = XGOEDU()

# 屏幕显示
edu.lcd_clear()                          # 清屏
edu.lcd_text(x, y, text, color, size)    # 显示文字
edu.lcd_picture(filename, x, y)          # 显示图片
edu.lcd_line(x1, y1, x2, y2, color)      # 画线
edu.lcd_rectangle(x1, y1, x2, y2)        # 画矩形

# 按键检测
edu.xgoButton("a")  # 左上 (True/False)
edu.xgoButton("b")  # 右上
edu.xgoButton("c")  # 左下 (常用作退出)
edu.xgoButton("d")  # 右下

# 摄像头
edu.xgoCamera(True/False)  # 开关摄像头预览
edu.xgoTakePhoto(filename) # 拍照

# 识别功能
edu.gestureRecognition()    # 手势识别 -> ('5', (x,y)) 或 None
edu.ColorRecognition(mode)  # 颜色识别 mode='R'/'G'/'B'/'Y' -> ((x,y), radius)
edu.LineRecognition(mode)   # 巡线 mode='K'(黑)/'W'(白) -> {'x':, 'angle':}
edu.QRRecognition()         # 二维码 -> ['内容1', '内容2'] 或 []
edu.AprilTagRecognition()   # AprilTag -> tag_id 或 None
edu.face_detect()           # 人脸检测 -> [x, y, w, h] 或 None
edu.emotion()               # 情绪识别 -> ('Happy', (x,y)) 或 None
edu.agesex()                # 年龄性别 -> ('Male', '(25-32)', (x,y)) 或 None
edu.yoloFast()              # 目标检测 -> ('person', (x,y)) 或 None
edu.posenetRecognition()    # 骨骼检测 -> [angle1, angle2, ...] 或 None

典型代码模板

基础控制

import sys
sys.path.insert(0, '/home/pi/.npm-global/lib/node_modules/openclaw/skills/xgorobot/lib')
from xgolib import XGO
from edulib import XGOEDU
import time

dog = XGO()
edu = XGOEDU()

# 显示提示
edu.lcd_text(10, 100, "按C键退出", "YELLOW", 20)

# 主循环
while not edu.xgoButton("c"):
    # 你的控制逻辑
    time.sleep(0.1)

dog.stop()
dog.reset()

视觉追踪

import sys
sys.path.insert(0, '/home/pi/.npm-global/lib/node_modules/openclaw/skills/xgorobot/lib')
from xgolib import XGO
from edulib import XGOEDU
import time

dog = XGO()
edu = XGOEDU()

while not edu.xgoButton("c"):
    result = edu.ColorRecognition(mode='R')  # 追踪红色
    (x, y), radius = result

    if radius > 10:  # 检测到目标
        error = x - 160  # 偏离中心
        if error > 30:
            dog.turnright(30)
        elif error < -30:
            dog.turnleft(30)
        else:
            dog.forward(10)
    else:
        dog.stop()

    time.sleep(0.1)

dog.stop()

巡线行走

import sys
sys.path.insert(0, '/home/pi/.npm-global/lib/node_modules/openclaw/skills/xgorobot/lib')
from xgolib import XGO
from edulib import XGOEDU
import time

dog = XGO()
edu = XGOEDU()

while not edu.xgoButton("c"):
    result = edu.LineRecognition(mode='K')  # 黑线
    x = result['x']

    if x > 0:
        offset = x - 160
        if offset > 20:
            dog.turn(-20)
        elif offset < -20:
            dog.turn(20)
        else:
            dog.turn(0)
        dog.forward(10)
    else:
        dog.stop()

    time.sleep(0.05)

dog.stop()

注意事项

1. API 细节：完整参数和返回值请直接查看 lib/ 下的源码文件
2. 串口独占：XGO_DOG 占用串口，但可与 XGOEDU 同时使用
3. 初始化顺序：建议先初始化 XGO_DOG，再初始化 XGOEDU
4. 摄像头资源：视觉识别函数会自动管理摄像头
5. 按键退出：用 edu.xgoButton("c") 作为程序退出条件

机型差异

功能	Mini	Lite	Mini3W	Rider
机械臂	✓	✗	✓	✗
轮控模式	✗	✗	✓	-
Y轴平移	✓	✓	✓	✗
四足行走	✓	✓	✓	✗

• Lite：无机械臂，调用 arm() 或 claw() 无效
• Mini3W：可用 enable_wheel_control() 切换轮控模式
• Rider：统一使用 XGO() 类，调用 rider_* 方法（如 rider_move_x()），无侧移功能