xgorobot

# XGO 机器狗控制 控制 XGO 系列机器狗（Mini/Lite/Mini3W/Rider），涵盖运动控制、视觉识别、AI 功能、传感器读取等完整能力。 ## 执行环境（强制） **必须使用指定的虚拟环境 Python：** ### 标准执行命令（必须使用） ```bash # 统一执行模板（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 ``` **预置脚本示例：** ```bash 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 ``` **自定义代码示例：** ```bash 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/` 目录下是否有匹配的预置脚本，直接执行：** ```bash 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 图片理解示例：** ```bash # 问图中某物体的位置 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` | 照片已保存: {path} | | `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/) | 脚本 | 功能 | 参数 | |------|------|------|