XGO 机器狗控制

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

执行环境（强制）

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

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

CODEBLOCK0

预置脚本示例：
CODEBLOCK1

自定义代码示例：
CODEBLOCK2

重要：

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

---

执行策略（重要）

优先级 1：使用预置脚本

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

CODEBLOCK3

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

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

场景	用 AI 图片理解	用 YOLO/传统视觉
识别任意物体（纸巾、胡萝卜、杯子...）	✓ 推荐	✗ 类别有限
判断物体位置（左/中/右）

✓ 推荐 | ✗ 需额外计算 |
| 理解场景/回答问题 | ✓ 推荐 | ✗ 不支持 |
| 实时追踪已知类别（人/球） | ✗ 太慢 | ✓ 推荐 |
| 快速检测有无人脸 | ✗ 太慢 | ✓ 推荐 |

AI 图片理解示例：

CODEBLOCK4

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

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

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

---

预置脚本列表

基础运动 (scripts/motion/)

脚本	功能	参数
INLINECODE4	前进	INLINECODE5 (0-25) INLINECODE6
INLINECODE7

后退 | --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/)

脚本	功能	参数
INLINECODE27	蹲下	INLINECODE28 (75-120mm)
INLINECODE29

站立 | --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/)

脚本	功能	参数
INLINECODE45	周期平移	INLINECODE46 (x/y/z) --period 2 (1.5-8秒) INLINECODE48
INLINECODE49

周期旋转 | --axis r (r/p/y) --period 2 (1.5-8秒) --duration 5 |

步态与速度 (scripts/motion/)

脚本	功能	参数
INLINECODE53	步态类型	INLINECODE54 (trot/walk/highwalk/slowtrot)
INLINECODE55

步频控制 | --mode normal (normal/slow/high) | | imu.py | IMU平衡 | --mode 1 (0=关, 1=开) |

单腿与舵机 (scripts/motion/)

脚本	功能	参数
INLINECODE59	单腿控制	INLINECODE60 (1-4) --x 0 --y 0 INLINECODE63
INLINECODE64

舵机控制 | --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

脚本	功能	参数
INLINECODE73	机械臂控制	INLINECODE74 (open/close/up/down)

---

预设动作 (scripts/action/)

脚本	功能	参数
INLINECODE75	执行动作ID	INLINECODE76 (1-23/128-141/255)
INLINECODE77

坐下 | 无参数 | | 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/)

脚本	功能	参数	输出
INLINECODE89	拍照	INLINECODE90	照片已保存: {path}
INLINECODE91

摄像头预览 | --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/)

脚本	功能	参数	输出
INLINECODE110	寻找小球	INLINECODE111 INLINECODE112	✓ 找到{颜色}色小球 或 ✗ 超时未找到
INLINECODE113

寻找人类 | --timeout 45 | ✓ 找到人类 或 ✗ 超时未找到 | | catch_ball.py | 抓取小球 | --color R --timeout 60 | ✓ 抓取成功 或 ✗ 抓取失败 |

---

传感器读取 (scripts/sensor/)

脚本	功能	输出
INLINECODE118	读取电量	百分比
INLINECODE119

读取Roll角 | 横滚角度 | | read_pitch.py | 读取Pitch角 | 俯仰角度 | | read_yaw.py | 读取Yaw角 | 偏航角度 | | read_imu.py | 读取IMU | --axis all (roll/pitch/yaw/all) | | read_motor.py | 读取舵机角度 | 所有舵机当前角度 |

---

屏幕显示 (scripts/display/)

脚本	功能	参数
INLINECODE125	显示文字	INLINECODE126 --x 5 --y 5 --color WHITE INLINECODE130
INLINECODE131

清除屏幕 | 无参数 | | picture.py | 显示本地图片 | --filename photo.jpg --x 0 --y 0 | | http_image.py | 显示网络图片 | --url "http://..." --x 0 --y 0 |

---

音频播放 (scripts/audio/)

脚本	功能	参数
INLINECODE140	播放本地音频	INLINECODE141
INLINECODE142

播放网络音频 | --url "http://..." | | play_music.py | 播放背景音乐(Dream.mp3) | 无参数 |

---

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

脚本	功能	参数	输出
INLINECODE145	AI拍照理解	INLINECODE146	问题: {prompt} / 回答: {AI回答}
INLINECODE147

语音识别 | --seconds 3 | 识别结果: {文字} | | text_to_speech.py | AI语音合成 | --text "你好" --voice Cherry | 语音播放（自然人声，需API） | | generate_image.py | AI生成图片 | --prompt "一只猫" | 图片已保存: {path} | | goto_target.py | AI走向目标 | --target "黄色小鸡" --timeout 60 | ✓ 已到达目标 或 ✗ 未能到达 |

语音输出选择： 机器狗说话优先用 INLINECODE157

photo_understand.py 常用 prompt 示例：

任务	prompt 示例
物体位置	INLINECODE158
物体列举

--prompt "图中有哪些物品？列出名称" |
| 物体计数 | --prompt "图中有几个苹果？只回答数字" |
| 颜色判断 | --prompt "图中最大的物体是什么颜色？" |
| 场景理解 | --prompt "这是什么地方？简要描述" |
| 是非判断 | --prompt "图中有人吗？只回答有/没有" |
| 物体对比 | --prompt "图中哪个物体更大？" |

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

---

Mini3W专用 (scripts/mini3w/)

脚本	功能	参数
INLINECODE167	轮控开关	INLINECODE168 (0=启用, 1=禁用)
INLINECODE169

轮控制 | --w1 128 --w2 128 --w3 128 --w4 128 | | extern_motor.py | 外接电机 | --position 100 |

---

Rider专用 (scripts/rider/)

运动控制

脚本	功能	参数
INLINECODE176	前后移动	INLINECODE177 INLINECODE178
INLINECODE179

原地旋转 | --speed 90 --runtime 2 |

| roll.py | Roll姿态 | --angle 10 | | height.py | 身高调整 | --height 90 | | reset.py | 重置 | 无参数 | | reset_odom.py | 重置里程计 | 无参数 |

模式控制

脚本	功能	参数
INLINECODE188	预设动作	INLINECODE189 (1-6/255)
INLINECODE190

Roll自平衡 | --mode 1 (0=关, 1=开) |

| perform.py | 表演模式 | --mode 1 (0=关, 1=开) | | calibration.py | 软件标定 | --state start/end |

周期运动

脚本	功能	参数
INLINECODE196	周期Roll	INLINECODE197 INLINECODE198
INLINECODE199

周期升降 | --period 1.5 --duration 5 |

传感器与LED

脚本	功能	参数
INLINECODE202	读取电量	无参数
INLINECODE203

读取Roll | 无参数 |

| read_pitch.py | 读取Pitch | 无参数 | | read_yaw.py | 读取Yaw | 无参数 | | led.py | LED控制 | --index 0 --r 255 --g 0 --b 0 |

---

组合任务 (scripts/combo/)

脚本	功能	参数
INLINECODE211	AI智能踩物	INLINECODE212 --leg 1 (1=左前,2=右前) --speed 100 (越小越机械)
INLINECODE215

人脸追踪 | 无参数，按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 库参考（用于编写新代码）

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

模块	文件路径	功能说明
运动控制	INLINECODE222	XGODOG 类：四足机器狗运动、姿态、机械臂控制
Rider控制

lib/xgolib/xgolib_rider.py | XGORIDER 类：双轮足机器人专用 |
| 视觉传感器 | lib/edulib.py | XGOEDU 类：摄像头、屏幕、按键、各种识别功能 |

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

代码模板（必须遵循）

CODEBLOCK5

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

机型识别

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

CODEBLOCK6

机型	特征	固件首字母
XGO-Mini	12自由度，有机械臂	M
XGO-Lite

轻量版，无机械臂 | L |
| XGO-Mini3W | 支持轮控模式 | W |
| XGO-Rider | 双轮足，非四足 | R |

快速参考

运动控制 (XGO)

CODEBLOCK7

视觉传感器 (XGOEDU)

CODEBLOCK8

典型代码模板

基础控制

CODEBLOCK9

视觉追踪

CODEBLOCK10

巡线行走

CODEBLOCK11

注意事项

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

机型差异

功能	Mini	Lite	Mini3W	Rider
机械臂	✓	✗	✓	✗
轮控模式

✗ | ✗ | ✓ | - | | Y轴平移 | ✓ | ✓ | ✓ | ✗ | | 四足行走 | ✓ | ✓ | ✓ | ✗ |

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