云计算百科
云计算领域专业知识百科平台
当前位置：网硕互联帮助中心 > 服务器百科 > 正文

【科沃斯-八界】- 科沃斯八界开源机器人场景深度体验

2026-10-13 分类：服务器百科 阅读(7) 评论(0)

科沃斯八界开发者开源共创大赛

科沃斯八界开源机器人场景深度体验

  • 引言
  • 一、八界 – 介绍
  • 二、八界到家第一步
  • 三、开发环境配置
    • 3.1 开源仓库下载
    • 3.2 开发环境说明
    • 3.3 第一个程序测试
  • 四、各种Demo 测试
    • 4.1 新手上路
    • 4.2 Python 版本玩具配送示例
    • 4.3 Python 桌面整理示例
    • 4.4 Python 玄关鞋子整理
    • 4.5 Python 玩具收纳整理
  • 五、创意场景测试
    • 5.1 八界机器人任务脚本（玩具收纳完整优化版）
      • 5.1.1 脚本功能
      • 5.1.2 完整执行链路：
      • 5.1.3 目录与结构
      • 5.1.4 配置区
      • 5.1.5 命令行参数
      • 5.1.6 重试策略总结
      • 5.1.7 运行方式：
    • 5.2 餐桌纸巾送物任务
      • 5.2.1 脚本功能
      • 5.2.2 执行链路
      • 5.2.3 脚本结构
      • 5.2.4 功能概览
      • 5.2.5 配置区
      • 5.2.6 命令行参数
      • 5.2.7 运行方式
    • 5.3 八界机器人整理玄关鞋子代码示例
      • 5.3.1 脚本功能
      • 5.3.2 执行链路
      • 5.3.3脚本结构
      • 5.3.4 功能概览
      • 5.3.5 配置区
      • 5.3.6 命令行参数
      • 5.2.7 运行方式
    • 5.4 餐桌玩具收纳整理
      • 5.4.1 脚本功能
      • 5.4.2 执行链路
      • 5.4.3 脚本结构
      • 5.4.4 功能概览
      • 5.4.5 配置区
      • 5.4.6 命令行参数
      • 5.4.7 运行方式
    • 5.5 玩具收纳和鞋子整理
      • 5.5.1 脚本功能
      • 5.5.2执行链路
      • 5.5.3 脚本结构
      • 5.5.4 功能概览
      • 5.5.5 配置区
      • 5.5.6 命令行参数
      • 5.5.7 运行方式
  • 六、测评小结

引言

CSDN 推送了「科沃斯八界开发者开源共创大赛」的调查问卷信息，里面附有一份科沃斯机器人测评征文的调查问卷链接。当时只是顺手填写了一下，填完便没再放在心上。没想到过了一段时间，CSDN 的工作人员联系到我，告知我被科沃斯选中，成为参与测评的KOL之一。说实话，我从未想过自己也能有这样的机会，心里既惊喜又期待，忍不住连声感叹。 在八界开源机器人正式到手之前，我先去科沃斯官网做了一番功课：了解它的核心参数、外观设计、开源生态以及所支持的环境等信息。当时心里就在想，这台机器人个头不小，开源能力又丰富，想必会非常好玩。事实证明，等它真正到手之后，果然没有让我失望！

一、八界 – 介绍

在中秋假期第一天，八界到了。因为上一位KOL已经完成了测评，所以这台八界是经过一轮流转后到我手上的。收到快递时，包装箱比预想中大不少，外箱上印着科沃斯的品牌标识和八界的型号信息，整体保护得很到位，四周都有泡沫缓冲，看得出官方在运输环节考虑得很周全。

拆开外箱，里面是两层结构：上层是配件盒，下层是主机。配件盒里整齐地放着玩具收纳筐、充电底座。主机被厚实的防尘袋包裹着，取出时能明显感受到它的分量——整机用料扎实，外壳是磨砂质感的工程塑料，边角处理得比较圆润，没有毛刺感，做工属于机器人里比较讲究的那一档。

把八界移除包装，推出包装箱，第一眼印象就是「大」。它的底盘比常见的扫地机器人宽出一圈。机身正面有一块小屏幕，开机后会显示系统状态和基础交互信息，进入首页之后屏幕上显示了八个功能，以及设备的状态信息。整体设计语言偏简洁硬朗，科技感比较强。 在这里插入图片描述

开机之后，系统启动速度很快，进入主界面后能看到基于开源系统定制的桌面环境。初步把玩下来，触控响应灵敏，菜单逻辑清晰，对开发者来说上手门槛不高。考虑到它同时具备移动底盘、开放接口和可编程能力，这台机器人的可玩性确实比普通家用机器人高出一大截，也让我对后续的深度测评更期待了。

  • 外观介绍
部位外观描述功能/设计要点
整体形态 圆柱形底座 + 直立式机身，配色以米白+深灰黑为主，底部带蓝色环形氛围灯 人形化比例，兼顾稳定性和通过性；视觉上亲和，适合家庭/办公场景
机身尺寸 直径 465 mm × 高度 850~1290 mm 高度可升降，站立时接近成人腰部到胸部之间
头部 顶部模块化设计，含黑色光耦区、语音模组孔阵、顶部散热格栅 承载头部 RGBD 相机、语音拾音、光耦碰撞检测
头部 RGBD 相机 顶部前方一个黑色方块相机模组 用于头部视角的场景感知、VLM 感知、放置框识别
手部 RGBD 相机 机械臂末端靠近夹爪的位置，一个小型相机模组 用于抓取前的近距离观测（ARM 视角）
机械臂 深灰黑色六自由度机械臂，位于机身正面上半部分，可折叠收纳 臂展 800 mm，用于抓取、放置、精细操作
末端夹爪 两指平行开合夹爪，银灰色，夹爪内侧带传感器与 UV 灯 开合行程 0~100 mm，可检测抓紧/滑动/掉落，支持 UV 清洁
机身主体 正面为黑色面板（内嵌 7 寸触摸屏），侧面为米白色外壳 屏幕用于交互；外壳内有嵌入式主板与算力模块
升降平台 机身中段可升降的柱状结构 440 mm 行程，速度 50 mm/s，让机械臂覆盖 0~850 mm 高度平面
底盘 圆形底座 + 双驱轮 + 万向轮，前部有激光雷达窗口 静音双驱底盘，最小通过宽度 60 cm，最大速度 0.4 m/s
激光雷达 底盘前部一个圆形窗口 dToF 激光雷达，用于 SLAM 建图与导航
避障传感器 底盘四周分布面阵 ToF、线激光、撞板 多模态避障，保障移动安全
下视传感器 底盘底部 8 颗 防止跌落、检测台阶
屏幕 机身正面 7 寸触摸屏，多点触控 显示状态、交互反馈、建图控制
语音模组 头部/机身上的麦克风阵列和扬声器 六环麦克风 + 单声道扬声器，支持声纹识别
充电桩 黑色底座式充电桩，带金属触点和导向槽 机器人自动回充对接触点
线缆 充电桩连接到墙面插座 常规 220V 供电
整体风格 简洁、科技感、家电化，符合科沃斯一贯的工业设计语言 适合在室内环境中长期放置
  • 外观图片 八界原图

二、八界到家第一步

  • 1、恢复出厂设置 先恢复出厂设置，避免被上一位 KOL 的数据影响

  • 2、自检 第一步就是通过屏幕上面的一键检测，检查八界的各个硬件、传感器、以及补光灯，激光雷达等是否正常 在这里插入图片描述

  • 3、建图 第二步就是连接 WIFI 建图，后续的所有功能都依赖这个地图。导航，定位等 建图最好是将八界推回充电桩后在执行，以及将八界放到墙边，他将以充电桩开始建图，不想让他去的地方，可以关门，或者使用凳子拦截它 在这里插入图片描述

  • 4、语义地图示例 由于忘记拍照留存，所以画图示意一下 玩具收纳区，玄关都是建图完成之后手动改了一下的

在这里插入图片描述

  • 5、面板功能测试 完成建图之后，我也将面板上面的所有功能都测试了一遍，以及将所有相关的设置都看了一遍，增强对八界的了解

  • 6、可视化控制平台测试

    • 可视化平台链接 在这里插入图片描述

    • 可视化平台截图 在这里插入图片描述

    • 机器人控制 最开始测试的时候还是在控制机器人的各种基础操作 在这里插入图片描述

三、开发环境配置

3.1 开源仓库下载

  • 仓库地址 ：https://atomgit.com/ecovacs-bajie/bajie_sdk.git

  • 仓库结构 ：

    bajie_sdk/
    ├── python/
    │ ├── beginner_journey/ # 从连接到抓放闭环的 Notebook 课程
    │ ├── desk_demo/ # 桌面整理
    │ ├── delivery_demo/ # 玩具递送
    │ ├── shoe_sorting/ # 鞋履整理
    │ ├── toy_storage/ # 玩具收纳
    │ └── bajie_sdk-3.0.0-*.whl # x86_64 / aarch64 Python SDK
    ├── cpp/
    │ ├── depend/ # 公开头文件与预编译动态库
    │ ├── desk_demo/ # 桌面整理
    │ ├── delivery_demo/ # 玩具递送
    │ ├── shoe_sorting_demo/ # 鞋履整理
    │ └── toy_storage_demo/ # 玩具收纳
    ├── img/ # 项目与场景图片
    ├── LICENSE
    └── NOTICE

  • 仓库图片 ： 在这里插入图片描述

3.2 开发环境说明

项目说明
操作系统 Windows10 下 Vmware 虚拟机 安装的 Ubuntu 22.04
编程语言 Python 3.10.12
SDK 版本 3.0.0
八界 SDK bajie_sdk-3.0.0-cp310-cp310-linux_x86_64.whl
安装SDK python3 -m pip install ./bajie_sdk-3.0.0-cp310-cp310-linux_aarch64.whl
验证安装 python3 -c “import bajie_sdk; from importlib.metadata import version; print(‘ok’, bajie_sdk.name, version(‘bajie-sdk’))”

3.3 第一个程序测试

我根据 Clone 下来的开发文档步骤走了一下，准备开始测试，开始运行程序时才发现，所有的操作必须先离开充电桩，以及在空闲没有任务时，才能执行各种操作；所以后面每次做测试前，我这边都加了是否在八界机器人充电桩上，八界机器人是否空闲以及八界机器人的电量判断

from bajie_sdk import BajieRobot
import math

robot = BajieRobot(ws_url="ws://192.168.31.179:9900/) # 或 ws_url="ws://<IP>:9900/"
if not robot.Connect(timeout_sec=8.0):
raise RuntimeError("连接失败")

info = robot.eco_robotInfo()
print("电量:", info.battery)
print("工作状态:", info.workState)
print("异常告警:", info.alarm)
print("地图坐标:", info.pos)

# 原地旋转一圈（360° = 2π rad），无需地图
st = robot.eco_moveChassis(move_distance=0.0, move_angle=2 * math.pi, timeout_sec=30.0)
print("旋转完成:", st.task_id, st.error_info.code)
robot.Disconnect()

打印日志如下

[bajie_sdk] WebSocket 已连接（192.168.31.179:9900）
Connect: 等待 robot_info 推送上报（最多 8s）…
Connect: robot_info 接收完毕
电量: BatteryInfo(value=98, isCharge=0, mode=3)
工作状态: WorkState(task_id='', name='', cmd='idle')
异常告警: []
地图坐标: Position(room='客厅', x=1.3967406749725342, y=0.18024346232414246, yaw=-1.8191909790039062)
旋转完成: chassis_move_1745712345678_1 0
[bajie_sdk] WebSocket 连接已关闭

四、各种Demo 测试

4.1 新手上路

阶段Notebook你会获得什么
认知 00_认识八界机器人与SDK.ipynb SDK 和机器人任务的基本心智模型
环境 01_准备环境与安装SDK.ipynb Python、wheel、导入验证
连接 02_第一次连接机器人.ipynb 连接、断开、基础状态
查询 03_学会查接口和字段.ipynb 自己查方法、查类型、生成 JSON 模板
安全 04_机器人状态与安全检查.ipynb 任务前 checklist
感知 05_拍照与图像理解.ipynb、06_开放词检测入门.ipynb 拍照、看图、检测框
行动 07_导航与基础本体控制.ipynb、08_同步任务_异步回调与任务控制.ipynb mission、任务控制、回调
闭环 09_抓取放置最小闭环.ipynb 从检测到抓放的最小链路
迁移 10_进阶任务与现有Demo导读.ipynb 读懂现有 demo 并迁移到脚本

一开始我以为：

  • SDK 就是一堆函数，调就完事。
  • 连上机器人，发命令，机器人就动。
  • 出错了看报错就行。

学完之后发现：

  • SDK 分两类能力，走的协议都不一样：
    • Mission 类：导航、拍照、抓取、放置、本体控制 → 走 WebSocket，会产生 task_id，要等 finish。
    • 感知类：OVD 检测、VLM 感知、embedding、相似度 → 走 HTTP，不产生 mission。
  • 机器人是物理设备，不是纯软件。命令发出去之后要等它真的执行完。
  • 出错不只是代码问题，还可能是电量、告警、地图、充电状态、场地障碍。
  • 连的 IP 不是屏幕上的安卓 IP，而是 Linux 板 IP，默认 ws://10.10.10.11:9900/。

4.2 Python 版本玩具配送示例

delivery_demo 是一个结构清晰、有重试、有异常处理、有语音反馈的完整业务流程示例。 它展示了从“会调单个 eco_* 接口”到“能编排一个真实机器人任务”的跨越，是学习 SDK 高阶用法的最佳入口之一。

  • 功能概览

    步骤能力
    1 原地找玩具：eco_findObject
    2 手部观测：eco_lookto(CameraType.ARM)
    3 手部拍照：eco_captureImages(CameraType.ARM)
    4 OVD 识别：eco_detect_objects
    5 精准抓取：eco_pick
    6 语义导航到桌子：eco_navigateToSemanticArea
    7 头部拍照：eco_captureImages(CameraType.HEAD)
    8 PutWhere 推荐：eco_put_where_summary
    9 语义放置：eco_place_with_view

  • 目录结构与职责

    delivery_demo/
    ├── delivery_demo.py # CLI 入口，参数解析
    ├── workflow.py # 流程编排：连接、单轮执行、重试、收尾
    ├── planning.py # 搜索与位姿选择
    ├── execution.py # 观测、抓取、导航、放置的具体执行
    ├── models.py # 配置数据结构 DeliveryConfig
    ├── errors.py # 异常定义
    └── README.md # 使用说明

  • 重试策略

    • 搜索不到玩具时，会执行 eco_finishRobotPose，然后正常结束配送流程。
    • 抓取流程最多重试 3 次。每次重试都会重新执行手部观测、手部拍照、OVD 识别和精准抓取。
    • 抓取中遇到 36897/物体掉落时，仅判定为本次抓取尝试失败，继续进入下一次抓取重试。
    • 抓取成功后才会执行语义导航到桌子。
    • 放置流程最多重试 3 次。每次重试都会重新执行头部拍照、PutWhere 推荐和语义放置。
    • 若连续 3 次抓取失败或连续 3 次放置失败，流程抛出 RobotMissionError 并结束。

  • 运行方式 在仓库根目录执行：

    python3 bajie_demo/python/delivery_demo/delivery_demo.py \\
    –ws-url ws://10.10.10.12:9900/

4.3 Python 桌面整理示例

desk_demo 是一个 VLM 驱动的桌面整理闭环： 感知 → 规划 → 执行 → 评判 → 不达标就再来一轮。 它展示了从“会调单个接口”到“能编排带 AI 决策的完整机器人任务”的跨越，是几个 demo 里最值得精读的一个。

  • 功能概览

    步骤能力对应接口
    1 重定位 eco_relocate
    2 准备姿态 eco_prepareRobotPose
    3 语义导航到桌子 eco_navigateToSemanticArea
    4 升高机身 eco_setRobotHeight(0.44)
    5 头部选角（多角度采样） eco_setRobotHead + eco_captureImages + eco_vlm_suggest_angle
    6 头部拍照 eco_captureImages(CameraType.HEAD)
    7 VLM 桌面感知 eco_vlm_perception
    8 VLM 整理规划 eco_vlm_desk_sort_plan
    9 6D 姿态计算 eco_computeObjectPose
    10 手臂对准 eco_lookto(CameraType.ARM)
    11 手臂拍照 eco_captureImages(CameraType.ARM)
    12 bbox 匹配 eco_vlm_match
    13 抓取 eco_pick
    14 精准放置 eco_place_3D
    15 容器放置 eco_place_in
    16 整理效果评判 eco_vlm_judge
    17 机械臂归位 eco_setRobotArmMode(ARM_HOME)
    18 结束姿态 eco_finishRobotPose
    19 语音播报 eco_robotSpeech

  • 目录结构与职责

    desk_demo/
    ├── desk_demo.py # CLI 入口，参数解析
    ├── workflow.py # 主工作流：重定位、准备姿态、循环、结束姿态
    ├── perception.py # 感知工作流：导航、升高、选角、拍照、VLM 感知
    ├── planning.py # 规划：eco_vlm_desk_sort_plan → intent_steps
    ├── execution.py # 执行：6D 姿态、观测、bbox 匹配、抓取、放置
    ├── judge.py # 评判：eco_vlm_judge
    ├── models.py # DeskConfig
    ├── errors.py # DeskDemoError 及子类
    ├── retry_utils.py # 统一重试 + 错误码分类
    ├── speech.py # 固定文案语音播报
    ├── grab_items.py # 读取可抓清单，拼接 memory_input
    ├── grab_items.md # 可抓物品清单
    ├── ref_utils.py # 工具：task_id、JSON 读写、RGB 转换
    └── README.md # 使用说明

  • 运行方式

    • 前置条件

      • 代码与 SDK 部署位置一致（同在 PC 或同在机器人板端）。
      • 已完成语义建图。
      • 机身电量 > 30%，且未处于充电状态。
      • PC 端触发时，PC 和机器人连同一个 WiFi。
      • 准备可抓物品：小型玩偶、闹钟、马克笔、魔方（非贵重、非易碎）。
      • 如果用的是 Qwen 系列模型，注意它可能把 房间0的桌子1 写成 房间 0的桌子 1，导致区域匹配失败。建议在可视化平台把家具名改成不含数字的，如 书桌。

    • PC 端运行

      cd bajie_demo/python/desk_demo

      python3 desk_demo.py \\
      –ws-url ws://192.168.1.107:9900/ \\
      –area-name "房间0的桌子1" \\
      –user-input "把玩偶放到日历前面"

    • 机器人端运行

      cd bajie_demo/python/desk_demo

      python3 desk_demo.py \\
      –ws-url ws://127.0.0.1:9900/ \\
      –area-name "房间0的桌子1" \\
      –user-input "把玩偶放到日历前面"

4.4 Python 玄关鞋子整理

shoe_sorting 是一个 鞋子成对整理 的完整示例： SHOE 检测 → 配对 → 线面投影 → 摆放规划 → 自定义跨视图匹配 → 抓取 → 6D 放置。 它的核心不是“抓一个东西”，而是 成对识别 + 跨视图匹配 + 按线面摆放，是几个 demo 里感知链路最细、最适合学视觉匹配与规划的一个。

  • 完整链路：

    取消任务 → 准备姿态
    → 解析整理区域（语义区域 或 临时创建）
    → 循环（最多 3 次规划尝试）：
    语义导航到区域
    头部拍照
    SHOE OVD 检测鞋子
    鞋子配对（标签优先 + pairwise 兜底）
    线面投影 + 摆放规划 eco_shoe_placement_plan
    逐步骤执行：
    手臂对准 → 手臂拍照 → 臂图检测 → 跨视图匹配 → 抓取 → 6D 放置
    → 结束姿态 → 清理临时语义区域

  • 功能概览

    步骤能力对应接口
    1 取消所有任务 eco_cancelAllMissions
    2 准备姿态 eco_prepareRobotPose
    3 解析/创建整理区域 eco_manageSemanticMap(QUERY/ADD)
    4 语义导航 eco_navigateToSemanticArea
    5 头部拍照 eco_captureImages(CameraType.HEAD)
    6 SHOE 检测 eco_detect_objects(entry=OvdEndpoint.SHOE)
    7 鞋子配对 eco_pairwise + 自定义 pair_shoes
    8 线面投影 project_place_line_and_plane
    9 摆放规划 eco_shoe_placement_plan
    10 6D 姿态 eco_computeObjectPose
    11 手臂对准 eco_lookto(CameraType.ARM)
    12 手臂拍照 eco_captureImages(CameraType.ARM)
    13 臂图检测 eco_detect_objects(entry=OvdEndpoint.SHOE)
    14 跨视图匹配 自定义 custom_match_obj_views
    15 抓取 eco_pick
    16 6D 放置 eco_place_3D
    17 结束姿态 eco_prepareRobotPose
    18 清理临时区域 eco_manageSemanticMap(DELETE)
    19 语音播报 eco_robotSpeech

  • 目录结构与职责

    shoe_sorting/
    ├── shoe_sorting_demo.py # 入口 + 主流程编排
    ├── planning.py # 配对、线面投影、摆放规划
    ├── execution.py # 对准、抓取、放置、重试
    ├── matching.py # 自定义跨视图匹配（6D + 方向 + 视觉）
    ├── pairing.py # 鞋子配对（标签优先 + pairwise 兜底）
    ├── visualize_plans.py # 可视化：配对、规划、线面投影
    └── README.md # 使用说明

  • 分层思路：

    层文件职责
    入口/编排层 shoe_sorting_demo.py 参数解析、区域解析、3 次规划循环、逐步骤执行
    规划层 planning.py 配对、线面投影、eco_shoe_placement_plan
    执行层 execution.py 对准、抓取、放置、mission_retry
    匹配层 matching.py 自定义跨视图匹配
    配对层 pairing.py 鞋子配对
    可视化层 visualize_plans.py 画配对线、规划框、线面投影

  • 运行方式

    • 前置条件

      • 已完成语义建图，机身电量 > 30%。
      • 在可视化平台语义地图模块，点击“鞋子整理”，划出鞋子整理区域。
      • area_name 填语义地图中的区域名（单个，非家具），如“玄关”。

    • PC 端运行

      cd bajie_demo/python

      python3 -m shoe_sorting.shoe_sorting_demo \\
      –ws-url ws://192.168.1.107:9900/ \\
      –area-name "玄关" \\
      –vis-out /tmp/shoe_vis

    • 机器人端运行

      python3 -m shoe_sorting.shoe_sorting_demo \\
      –ws-url ws://127.0.0.1:9900/ \\
      –area-name "玄关" \\
      –vis-out /tmp/shoe_vis

    • 参数说明

      参数默认值说明
      –ws-url SDK 默认 机器人 WebSocket 地址
      –area-name "" 语义区域名；留空则整理机器人正前方区域
      –vis-out "" 可视化前缀，会生成 PREFIX_pairs.png、PREFIX_plan.png、PREFIX_placement.png
      –no-voice False 禁用语音播报

  • demo 运行发现问题 鞋子多了不能完全配对，鞋子数量会识别失败有差距，还有就是鞋子不能完全摆放到一条直线上去，以及鞋子抓取会有问题

4.5 Python 玩具收纳整理

toy_storage 是一个 循环收纳玩具 的完整示例： 搜索筐 → 搜索玩具（过滤筐内）→ 抓取 → 放置 → 再搜 → 直到找不到玩具。 它的核心是 filter_boxes 防重复 + 抓取/放置双重重试 + 循环直到清空，是学习“自动化流水线式机器人任务”的最佳入口。

  • 完整链路：

    重定位
    → 循环（最多 max_rounds 轮）：
    搜索收纳筐 eco_findObject
    搜索玩具（过滤筐内）eco_findObject(filter_boxes=…)
    抓取（最多 3 次）：
    手臂归位 → 手部观测 → 手臂拍照 → OVD 检测 → 精准抓取
    放置（最多 3 次）：
    头部观测 → 头部拍照 → PutWhere 摘要 → 语义放置
    → 找不到玩具 → 结束姿态

  • 功能概览

    步骤能力对应接口
    0 重定位 eco_relocate
    1 搜索收纳筐 eco_findObject
    2 搜索玩具（过滤筐内） eco_findObject(filter_boxes=…)
    3 手臂归位 eco_setRobotArmMode(ARM_HOME)
    4 手部观测玩具 eco_lookto(CameraType.ARM)
    5 手臂拍照 eco_captureImages(CameraType.ARM)
    6 OVD 检测玩具 eco_detect_objects
    7 精准抓取 eco_pick
    8 头部观测收纳筐 eco_lookto(CameraType.HEAD)
    9 头部拍照 eco_captureImages(CameraType.HEAD)
    10 PutWhere 摘要 eco_put_where_summary
    11 语义放置 eco_place_in
    12 结束姿态 eco_finishRobotPose
    13 语音播报 eco_robotSpeech

  • 目录结构与职责

    toy_storage/
    ├── toy_storage_demo.py # CLI 入口，参数解析
    ├── workflow.py # 流程编排：连接、轮次循环、收尾
    ├── planning.py # 搜索与位姿选择
    ├── execution.py # 观测、抓取、放置执行
    ├── models.py # ToyStorageConfig
    ├── errors.py # ToyStorageError 及子类
    └── README.md # 使用说明

  • 分层思路：

    层文件职责
    入口层 toy_storage_demo.py 解析参数，构造 ToyStorageConfig，调用 toy_storage
    编排层 workflow.py 重定位、轮次循环、抓取/放置重试、结束姿态
    规划层 planning.py 搜索、位姿选择、filter_boxes 构造
    执行层 execution.py 手臂归位、观测、拍照、检测、抓取、放置
    配置层 models.py ToyStorageConfig
    异常层 errors.py ToyStorageError 及子类

  • 运行方式

    • PC 端运行

      python3 bajie_demo/python/toy_storage/toy_storage_demo.py \\
      –ws-url ws://10.10.10.12:9900/ \\
      –max-rounds 1

    • 机器人端运行

      python3 bajie_demo/python/toy_storage/toy_storage_demo.py \\
      –ws-url ws://127.0.0.1:9900/ \\
      –max-rounds 1

      把示例 IP 换成机器人实际 Linux 板 IP；机器人本机运行用 127.0.0.1。

    • 参数说明

      参数默认值说明
      –ws-url SDK 默认 机器人 WebSocket 地址
      –user-id toy_demo_user PutWhere 请求里的用户标识
      –area-name "" 可选语义区域名；不传表示全局搜索
      –direction 里 语义放置方向
      –carrier "" PutWhere 的 carrier 字段
      –carrier-direct "" PutWhere 的 carrier_direct 字段
      –pick-index 0 OVD 结果中用于抓取的目标索引
      –search-pose-index -1 search 返回多位姿时的选择索引（最后一个）
      –connect-timeout-sec 15.0 连接超时
      –max-rounds 0 最大轮数；0 表示无限循环直到 Ctrl+C

  • 视频示例

    八界 科沃斯首款开源机器人

五、创意场景测试

5.1 八界机器人任务脚本（玩具收纳完整优化版）

5.1.1 脚本功能

这是一个 面向真实机器人的完整玩具收纳任务脚本： 连接 → 状态检查 → 下桩 → 扫视识别收纳筐 → 两阶段收纳 → 准备回充 → 回家充电。 它不只是一个 demo，而是一个可以直接跑在机器人上的生产化脚本，展示了从“会调 SDK”到“能编排完整任务”的跨越。

5.1.2 完整执行链路：

```text
[1/6] 连接机器人
↓
[2/6] 状态检查：电量 ≥ 30%、空闲、告警、地图、是否在充电
↓
[3.1] 下桩判断：在充电桩上 或 电量 ≥ 99.5% → 下桩
↓
[3.2] 走到玩具收纳区 + 原地旋转 360°（每 60° 拍一张头部图）识别收纳筐
↓
[3.3] 收拾玩具收纳区附近的玩具（全局搜索，排除筐内）
↓
[3.4] 全局扫描其他区域玩具，一起整理到收纳筐
↓
[3.5] 玩具收纳完成，恢复结束姿态
↓
[END] 回家充电（最多重试 3 次）
```

5.1.3 目录与结构

单文件，内部按功能分成若干块：

```text
八界机器人任务脚本（玩具收纳完整优化版）.py
├── 日志模块（_LogColor / _LogLevel / Logger）
├── 配置区（ROBOT_IP / DEFAULT_WS_URL / 扫视参数 / 重试参数）
├── 通用工具（print_section / check_mission_status / sleep_with_countdown / is_robot_charging / _safe_rotate）
├── 异常 & 搜索（ToyMissionError / search_pose / select_pose / to_filter_box）
├── 抓取 / 放置（reset_arm_home / hand_observe / arm_capture_and_pick / head_place_flow / 重试包装）
├── 重定位 / 结束姿态 / 语音（do_relocate / do_finish_pose / speak）
├── 3.2 扫视（_detect_basket_in_frame / do_scan_basket）
├── 收纳筐 6D 位姿（_compute_basket_pose_from_scan / _resolve_basket_pose）
├── 通用收拾循环（_pick_and_place_one_toy / _tidy_loop）
├── 3.3 玩具收纳区收拾（do_step_3_tidy_toys）
├── 3.4 全局扫描（do_step_4_global_scan）
├── 3.5 准备回充（do_step_5_ready_recharge）
├── 1/2/3.1 连接 / 状态检查 / 下桩（do_connect / do_preflight / do_step_1_leave_and_forward）
├── END 回充（do_end_recharge）
└── 主流程（parse_args / main）
```

5.1.4 配置区

| 配置项 | 默认值 | 说明 |
|:—|:—|:—|
| `ROBOT_IP` | `192.168.31.179` | 机器人 IP |
| `DEFAULT_WS_URL` | `ws://192.168.31.179:9900/` | WebSocket 地址 |
| `DEFAULT_MIN_BATTERY` | `30.0` | 最低电量 |
| `DEFAULT_CONNECT_TIMEOUT` | `8.0` | 连接超时 |
| `DEFAULT_REFRESH_TIMEOUT` | `5.0` | 状态刷新超时 |
| `MISSION_TIMEOUT` | `60.0` | 单次 mission 超时 |
| `RECHARGE_TIMEOUT` | `300.0` | 回充超时 |
| `RECHARGE_MAX_RETRY` | `3` | 回充最大重试 |
| `RECHARGE_RETRY_INTERVAL` | `10` | 回充重试间隔 |
| `DEFAULT_TOY_AREA` | `玩具收纳区` | 默认语义区域名 |
| `SCAN_STEP_DEG` | `60.0` | 扫视步进角度 |
| `SCAN_STEPS` | `6` | 扫视步数（360/60） |
| `SCAN_MAX_ANGLE_PER_CALL` | `170°` | 单次旋转最大角度 |
| `BASKET_LABEL` | `收纳筐` | 收纳筐标签 |
| `TOY_LABEL` | `玩具` | 玩具标签 |
| `BASKET_DETECT_TIMEOUT` | `15.0` | 收纳筐检测超时 |
| `MAX_GRAB_RETRIES` | `3` | 抓取最大重试 |
| `MAX_PLACE_RETRIES` | `3` | 放置最大重试 |
| `BATTERY_FULL_THRESHOLD` | `99.5` | 电量视为“满”的阈值 |
| `_SLEEP_BETWEEN_MISSIONS` | `2.0` | mission 间休眠 |

5.1.5 命令行参数

| 参数 | 默认值 | 说明 |
|:—|:—|:—|
| `–ws-url` | `ws://192.168.31.179:9900/` | WebSocket 地址 |
| `–min-battery` | `30.0` | 最低电量 |
| `–connect-timeout` | `8.0` | 连接超时 |
| `–area-name` | `玩具收纳区` | 玩具收纳区语义区域名 |
| `–recharge-retry` | `3` | 回充最大重试 |
| `–max-rounds` | `0` | 3.3 最大轮数（0=无限） |
| `–global-max-rounds` | `0` | 3.4 最大轮数（0=无限） |
| `–pick-index` | `0` | OVD 抓取目标索引 |
| `–search-pose-index` | `-1` | search 位姿索引 |
| `–carrier` | `""` | PutWhere carrier |
| `–carrier-direct` | `""` | PutWhere carrier_direct |
| `–scan-step-deg` | `60.0` | 扫视步进角度 |
| `–skip-step-33` | `False` | 跳过 3.3 |
| `–skip-step-34` | `False` | 跳过 3.4 |
| `–skip-step-35` | `False` | 跳过 3.5 |
| `–skip-preflight` | `False` | 跳过状态检查 |
| `–no-speech` | `False` | 关闭语音 |
| `–speech` | `False` | 显式开启语音 |
| `–yes` / `-y` | `False` | 跳过确认 |
| `–no-color` | `False` | 关闭日志颜色 |
| `–log-level` | `INFO` | 日志级别 |

5.1.6 重试策略总结

| 阶段 | 最大次数 | 失败处理 |
|:—|:—|:—|
| 连接 | 1 次 | 失败返回 1 |
| 状态检查 | 1 次 | 失败返回 2 |
| 下桩 | 1 次 | 失败返回 3 |
| 导航到收纳区 | 1 次 | 失败返回 None，3.3/3.4 fallback |
| 扫视旋转 | 每段 1 次 | 失败中断扫视 |
| 搜索玩具 | 1 次 | 找不到 → `eco_finishRobotPose` → 正常结束 |
| 抓取 | 3 次 | 每次完整重做 |
| 抓取中物体掉落 | 计入 3 次 | 只算本次失败 |
| 放置 | 3 次 | 每次完整重做 |
| 连续 3 次失败 | — | 抛 `ToyMissionError` |
| 回充 | 3 次 | 失败返回 6 |

5.1.7 运行方式：

```text
python3 toy_mission_v3.py
python3 toy_mission_v3.py –yes # 跳过确认
python3 toy_mission_v3.py –no-speech # 关闭机器人语音
python3 toy_mission_v3.py –skip-step-34 # 只做收纳区
python3 toy_mission_v3.py –global-max-rounds 20 # 限制全局轮数
python3 toy_mission_v3.py –log-level DEBUG # 调试日志
python3 toy_mission_v3.py –no-color # 关闭日志颜色
```

5.2 餐桌纸巾送物任务

5.2.1 脚本功能

这是一个 面向真实机器人的餐桌纸巾送物任务脚本： 连接 → 状态检查 → 下桩 → 餐桌抓纸巾 → 卧室放床头柜 → 结束姿态 → 回家充电。 它展示了从“会调 SDK”到“能编排完整送物任务”的跨越，是学习 取物—送物闭环 的最佳入口。

一句话：让机器人下桩 → 走到餐桌 → 识别并抓起纸巾 → 走到卧室 → 对准床头柜 → 把纸巾放到床头柜台面 → 恢复结束姿态 → 回家充电。

这是一个典型的“取物—送物”任务，偏向“家居场景”：

  • 起点：餐桌（语义区域）
  • 目标物：纸巾
  • 终点：卧室床头柜（语义区域 + 家具）
  • 放置面：床头柜台面

5.2.2 执行链路

[1/6] 连接机器人（ws://192.168.31.179:9900/）
↓
[2/6] 状态检查（电量 ≥ 30%、空闲、告警、地图坐标、是否充电）
↓
[3.1] 下桩判断（在充电桩上 或 电量 ≥ 99.5% → eco_leaveDock）
↓
┌── 第 N 包纸巾（N = 1..max_tissues）──────────────────────┐
│ │
│ [3.2] 走到餐桌（eco_navigateToSemanticArea） │
│ ↓ │
│ 头部俯视 + 拍照 + OVD 识别纸巾 │
│ ↓ │
│ [3.3] eco_findObject 搜纸巾 3D 位姿 → 抓取（最多 3 次） │
│ ↓ │
│ [3.4] 走到卧室（eco_navigateToSemanticArea） │
│ ↓ │
│ eco_findObject 搜床头柜 3D 位姿 │
│ ↓ │
│ 头部对准床头柜（eco_lookto HEAD） │
│ ↓ │
│ 头部拍照（用于放置） │
│ ↓ │
│ [3.5] PutWhere 生成放置框 → eco_place_in（最多 3 次） │
│ │
└──────────────────────────────────────────────────────────┘
↓
[3.6] 恢复结束姿态（eco_finishRobotPose）
↓
[END] 回家充电（eco_startRecharge，最多重试 3 次）

5.2.3 脚本结构

单文件，内部按功能分块：

餐桌纸巾送到卧室.py
├── 日志模块（_LogColor / _LogLevel / Logger）
├── 配置区（ROBOT_IP / 区域名 / 标签 / 头部角度 / 重试参数）
├── 通用工具（print_section / check_mission_status / is_robot_charging / sleep_with_countdown / _bbox_score / _bbox_area）
├── 异常 & 搜索（DeliveryError / search_pose / select_pose / assert_search_ok）
├── 抓取（reset_arm_home / hand_observe / arm_capture_and_pick / _grab_with_retries）
├── 3.2 走到餐桌 + 扫描识别纸巾（do_scan_tissue）
├── 3.3 抓取纸巾（do_grab_tissue）
├── 3.4 走到卧室 + 对准床头柜（do_navigate_and_observe_nightstand）
├── 3.5 放到床头柜（do_place_tissue_on_nightstand）
├── 3.6 恢复结束姿态（do_step_finish_pose）
├── 语音（speak）
├── 1/2/3.1 连接 / 状态检查 / 下桩（do_connect / do_preflight / do_step_1_leave_dock）
├── END 回家充电（do_end_recharge）
└── 主流程（parse_args / main）

5.2.4 功能概览

步骤能力对应接口
1 连接机器人 BajieRobot(ws_url).Connect()
2 状态检查 eco_refreshRobotInfo / eco_robotBattery / eco_robotWorkState / eco_robotAlarm / eco_robotPosition / eco_robotMapInfo
3.1 下桩 eco_leaveDock
3.2 走到餐桌 eco_navigateToSemanticArea
3.2 头部俯视 eco_setRobotHead
3.2 头部拍照 eco_captureImages(CameraType.HEAD)
3.2 OVD 识别纸巾 eco_detect_objects
3.3 搜索纸巾 3D 位姿 eco_findObject
3.3 手部观测 eco_lookto(CameraType.ARM)
3.3 手臂拍照 + OVD + 抓取 eco_captureImages + eco_detect_objects + eco_pick
3.4 走到卧室 eco_navigateToSemanticArea
3.4 搜索床头柜 3D 位姿 eco_findObject
3.4 头部对准床头柜 eco_lookto(CameraType.HEAD)
3.4 头部拍照 eco_captureImages(CameraType.HEAD)
3.5 PutWhere 生成放置框 eco_put_where_summary
3.5 语义放置 eco_place_in
3.6 恢复结束姿态 eco_finishRobotPose
END 回家充电 eco_startRecharge
全程 语音播报 eco_robotSpeech
收尾 取消任务 + 断开 eco_cancelAllMissions + Disconnect

5.2.5 配置区

配置项默认值说明
ROBOT_IP 192.168.31.179 机器人 IP
DEFAULT_WS_URL ws://192.168.31.179:9900/ WebSocket 地址
DEFAULT_MIN_BATTERY 30.0 最低电量
DEFAULT_CONNECT_TIMEOUT 8.0 连接超时
DEFAULT_REFRESH_TIMEOUT 5.0 状态刷新超时
MISSION_TIMEOUT 60.0 单次 mission 超时
RECHARGE_TIMEOUT 300.0 回充超时
RECHARGE_MAX_RETRY 3 回充最大重试
RECHARGE_RETRY_INTERVAL 10 回充重试间隔
DEFAULT_TABLE_AREA 餐桌 餐桌语义区域名
DEFAULT_BEDROOM_AREA 卧室 卧室语义区域名
TISSUE_LABEL 纸巾 目标物标签
NIGHTSTAND_LABEL 床头柜 用于在卧室图像里找床头柜
NIGHTSTAND_CARRIER 床头柜 PutWhere carrier
HEAD_LOOK_DOWN_RAD 0.9 头部俯视角度（弧度）
MAX_GRAB_RETRIES 3 抓取最大重试
MAX_PLACE_RETRIES 3 放置最大重试
BATTERY_FULL_THRESHOLD 99.5 电量视为“满”的阈值
_SLEEP_BETWEEN_MISSIONS 2.0 mission 间休眠

5.2.6 命令行参数

参数默认值说明
–ws-url ws://192.168.31.179:9900/ WebSocket 地址
–min-battery 30.0 最低电量
–connect-timeout 8.0 连接超时
–table-area 餐桌 餐桌语义区域名
–bedroom-area 卧室 卧室语义区域名
–recharge-retry 3 回充最大重试
–max-tissues 1 最多送几包纸巾
–search-pose-index -1 search 位姿索引
–carrier 床头柜 PutWhere carrier
–carrier-direct 上 PutWhere carrier_direct
–skip-step-33 False 跳过 3.3 抓取纸巾
–skip-step-34 False 跳过 3.4 走到卧室
–skip-step-35 False 跳过 3.5 放置纸巾
–skip-step-36 False 跳过 3.6 恢复结束姿态
–skip-preflight False 跳过状态检查
–no-speech False 关闭语音
–speech False 显式开启语音
–yes / -y False 跳过确认
–no-color False 关闭日志颜色
–log-level INFO 日志级别

5.2.7 运行方式

python3 餐桌纸巾送到卧室.py # 基本运行

python3 餐桌纸巾送到卧室.py –yes # 跳过确认

python3 餐桌纸巾送到卧室.py –yes –no-speech# 关闭语音

python3 餐桌纸巾送到卧室.py –yes –table-area "餐厅桌子" –bedroom-area "主卧"# 自定义区域名

python3 餐桌纸巾送到卧室.py –yes –max-tissues 3# 送多包纸巾

5.3 八界机器人整理玄关鞋子代码示例

5.3.1 脚本功能

这是一个 面向真实机器人的玄关鞋子整理脚本： 连接 → 状态检查 → 下桩 → 玄关导航 → SHOE 检测 → 配对 → 规划 → 逐只抓放 → 结束姿态 → 回家充电。 它把 shoe_sorting demo 的分层逻辑整合成单文件，并加上状态检查、下桩、可选玩具区、回充，是学习 成对整理 + 跨视图匹配 + 线面规划 的最佳入口。

一句话：让机器人走到玄关，用 SHOE 检测识别鞋子，按“成对 + 前沿线方向”规划摆放，逐只抓起来放到指定区域，最后恢复姿态并回家充电。

5.3.2 执行链路

[1] 连接机器人（ws://192.168.31.179:9900/）
↓
[2] 状态检查（电量 ≥ 30%、空闲、告警、地图坐标、是否充电）
↓
[3.1] 在充电桩 或 电量 100% → 下桩 eco_leaveDock；否则跳过
↓
[3.2] （可选）导航到玩具整理区
↓
[3.3] 玄关鞋子整理：
cancelAllMissions + prepareRobotPose
resolve_organize_area（语义区域 或 临时创建）
┌── 规划尝试 1..3 ──────────────────────────────┐
│ 导航到玄关 │
│ 头部拍照 │
│ SHOE 检测鞋子 │
│ 鞋子配对（name 分组 + pairwise 兜底） │
│ 抓放规划 eco_shoe_placement_plan │
│ 逐步骤执行： │
│ 臂对准 → 臂拍 → 臂检 → 跨视匹配 → 抓 → 放 │
└────────────────────────────────────────────────┘
↓
[3.3 收尾] 恢复结束姿态
↓
[END] 回家充电（最多 3 次）

5.3.3脚本结构

单文件，内部按功能分块：

八界机器人整理玄关鞋子.py
├── 配置区（DEFAULT_CARRIER_BOX / DEFAULT_FRONT_EDGE / SHOE_MATCHING_CONFIG）
├── 日志 & 语音（log / say）
├── 数学工具（quat_wxyz_to_rotmat / rotmat_to_quatf / normalize_or_raise / bbox_center / _bbox_key / _relative_to_map / _quat_x_axis_yaw）
├── Mission 状态与重试（mission_succeeded / mission_retry）
├── 状态检查（check_status）
├── 语义区域解析（resolve_organize_area）
├── 鞋子配对（pair_shoes）
├── 头图参考框归约（head_image_ref_bboxes_for_move_steps）
├── 抓放规划（get_shoe_move_steps）
├── 跨视图匹配（_long_axis_xoy / cosine_similarity / _batch_extract_pose_and_emb / _score_candidate / custom_match_obj_views）
├── 放置位姿计算（front_edge_horizontal_x_axis / place_quat_from_front_edge / place_position_pixel_ray_ground_z0）
├── 抓取（pick_with_arm_review / NamedBboxWithShoe）
├── 单步执行（execute_pick_and_place）
├── 主流程（shoe_sort）
└── CLI（main）

5.3.4 功能概览

步骤能力对应接口
1 连接机器人 BajieRobot(ws_url).Connect()
2 状态检查 eco_refreshRobotInfo / eco_robotBattery / eco_robotWorkState / eco_robotAlarm / eco_robotPosition / eco_robotMapInfo
3.1 下桩 eco_leaveDock
3.2 导航到玩具整理区（可选） eco_navigateToSemanticArea
3.3 取消任务 + 准备姿态 eco_cancelAllMissions / eco_prepareRobotPose
3.3 解析/创建整理区域 eco_manageSemanticMap(QUERY/ADD)
3.3 导航到玄关 eco_navigateToSemanticArea
3.3 头部拍照 eco_captureImages(CameraType.HEAD)
3.3 SHOE 检测鞋子 eco_detect_objects(entry=OvdEndpoint.SHOE)
3.3 鞋子配对 eco_pairwise + 自定义 pair_shoes
3.3 线面投影 project_place_line_and_plane
3.3 抓放规划 eco_shoe_placement_plan
3.3 6D 姿态 eco_computeObjectPose
3.3 视觉特征 eco_build_embeddings
3.3 手臂对准 eco_lookto(CameraType.ARM)
3.3 手臂拍照 eco_captureImages(CameraType.ARM)
3.3 臂图检测 eco_detect_objects(entry=OvdEndpoint.SHOE)
3.3 跨视图匹配 自定义 custom_match_obj_views
3.3 抓取 eco_pick
3.3 6D 放置 eco_place_3D
收尾 恢复结束姿态 eco_prepareRobotPose
END 回家充电 eco_startRecharge
全程 语音播报 eco_robotSpeech
收尾 取消任务 + 清理临时区域 + 断开 eco_cancelAllMissions / eco_manageSemanticMap(DELETE) / Disconnect

5.3.5 配置区

配置项默认值说明
DEFAULT_CARRIER_BOX [[1.2,0.6,0],[1.2,-0.6,0],[0.6,-0.6,0],[0.6,0.6,0]] 默认放置区多边形
DEFAULT_FRONT_EDGE [[0.6,-0.6,0],[0.6,0.6,0]] 默认前沿线
DEFAULT_TOY_AREA "" 玩具整理区（留空跳过）
SHOE_MATCHING_CONFIG 见下 跨视图匹配权重

SHOE_MATCHING_CONFIG：

字段默认值说明
spatial_sigma 0.8 空间距离高斯 σ
direction_sigma_deg 80.0 方向角高斯 σ
w_spatial 0.40 空间距离权重
w_direction 0.30 方向权重
w_visual 0.30 视觉相似度权重
combined_score_threshold 0.10 匹配最低分阈值

5.3.6 命令行参数

参数默认值说明
–ws-url ws://192.168.31.179:9900/ 机器人 WebSocket 地址
–area-name 玄关 语义区域名
–toy-area-name "" 可选的玩具整理区，先去这里再去玄关
–min-battery 30 最低电量
–no-voice False 关闭语音

5.2.7 运行方式

### 基本运行
python3 八界机器人整理玄关鞋子.py
### 指定 IP
python3 八界机器人整理玄关鞋子.py \\
–ws-url ws://192.168.31.179:9900/
### 指定区域
python3 八界机器人整理玄关鞋子.py \\
–area-name "玄关"
### 先去玩具区再去玄关
python3 八界机器人整理玄关鞋子.py \\
–toy-area-name "玩具收纳区"
### 关闭语音
python3 八界机器人整理玄关鞋子.py –no-voice
### 提高电量阈值
python3 八界机器人整理玄关鞋子.py –min-battery 50

5.4 餐桌玩具收纳整理

5.4.1 脚本功能

这是一个 面向真实机器人的餐桌玩具收纳任务脚本： 连接 → 状态检查 → 下桩 → 餐桌导航 → 桌面扫描 → 循环抓放 → 结束姿态 → 回家充电。 它展示了从“会调 SDK”到“能编排完整收纳任务”的跨越，是学习 桌面扫描 + 循环抓放 + 防重复 的最佳入口。

一句话：让机器人下桩 → 走到餐桌 → 扫描桌面识别玩具 → 逐个抓起玩具 → 送到玩具收纳区放进收纳筐 → 恢复结束姿态 → 回家充电。

5.4.2 执行链路

[1/6] 连接机器人（ws://192.168.31.179:9900/）
↓
[2/6] 状态检查（电量 ≥ 30%、空闲、告警、地图坐标、是否充电）
↓
[3.1] 下桩判断（在充电桩 或 电量 ≥ 99.5% → eco_leaveDock）
↓
[3.2] 走到餐桌前 + 头部俯视 + 桌面扫描识别玩具
↓
[3.3] 逐个抓取玩具 → 送往玩具收纳筐：
搜收纳筐 → 搜玩具（排除筐内）→ 抓取（最多 3 次）→ 放置（最多 3 次）
循环直到桌面无玩具或达到 max_toys
↓
[3.4] 恢复结束姿态
↓
[END] 回家充电（最多 3 次）

5.4.3 脚本结构

单文件，内部按功能分块：

八界机器人任务脚本（餐桌玩具收纳整理）.py
├── 日志模块（_LogColor / _LogLevel / Logger）
├── 配置区（ROBOT_IP / 区域名 / 标签 / 头部角度 / 重试参数）
├── 通用工具（print_section / check_mission_status / is_robot_charging / sleep_with_countdown / _bbox_score / _bbox_area / _safe_rotate）
├── 异常 & 搜索（TableTidyError / search_pose / select_pose / assert_search_ok / to_filter_box）
├── 抓取（reset_arm_home / hand_observe / arm_capture_and_pick / _grab_with_retries）
├── 放置（head_place_flow / _place_with_retries）
├── 结束姿态 & 语音（do_finish_pose / speak）
├── 3.2 走到餐桌 + 桌面扫描（_set_head_down / _detect_toys_in_frame / do_scan_table_toys）
├── 3.3 逐个抓取玩具 → 收纳筐（_resolve_basket_pose / do_step_3_tidy_table_toys）
├── 3.4 恢复结束姿态（do_step_4_finish_pose）
├── 1/2/3.1 连接 / 状态检查 / 下桩（do_connect / do_preflight / do_step_1_leave_and_forward）
├── END 回家充电（do_end_recharge）
└── 主流程（parse_args / main）

5.4.4 功能概览

步骤能力对应接口
1 连接机器人 BajieRobot(ws_url).Connect()
2 状态检查 eco_refreshRobotInfo / eco_robotBattery / eco_robotWorkState / eco_robotAlarm / eco_robotPosition / eco_robotMapInfo
3.1 下桩 eco_leaveDock
3.2 走到餐桌 eco_navigateToSemanticArea
3.2 头部俯视 eco_setRobotHead(0.9)
3.2 头部拍照 eco_captureImages(CameraType.HEAD)
3.2 OVD 识别玩具 eco_detect_objects
3.3 搜收纳筐 eco_findObject
3.3 搜桌面玩具（排除筐内） eco_findObject(filter_boxes=…)
3.3 手臂归位 eco_setRobotArmMode(ARM_HOME)
3.3 手部观测 eco_lookto(CameraType.ARM)
3.3 手臂拍照 + OVD + 抓取 eco_captureImages + eco_detect_objects + eco_pick
3.3 头部观测收纳筐 eco_lookto(CameraType.HEAD)
3.3 头部拍照 eco_captureImages(CameraType.HEAD)
3.3 PutWhere 摘要 eco_put_where_summary
3.3 语义放置 eco_place_in
3.4 恢复结束姿态 eco_finishRobotPose
END 回家充电 eco_startRecharge
全程 语音播报 eco_robotSpeech
收尾 取消任务 + 断开 eco_cancelAllMissions + Disconnect

5.4.5 配置区

配置项默认值说明
ROBOT_IP 192.168.31.179 机器人 IP
DEFAULT_WS_URL ws://192.168.31.179:9900/ WebSocket 地址
DEFAULT_MIN_BATTERY 30.0 最低电量
DEFAULT_CONNECT_TIMEOUT 8.0 连接超时
DEFAULT_REFRESH_TIMEOUT 5.0 状态刷新超时
MISSION_TIMEOUT 60.0 单次 mission 超时
RECHARGE_TIMEOUT 300.0 回充超时
RECHARGE_MAX_RETRY 3 回充最大重试
RECHARGE_RETRY_INTERVAL 10 回充重试间隔
DEFAULT_TABLE_AREA 餐桌 餐桌语义区域名
DEFAULT_BASKET_AREA 玩具收纳区 玩具收纳区语义区域名
SCAN_STEP_DEG 60.0 扫视步进角度
SCAN_MAX_ANGLE_PER_CALL 170° 单次旋转最大角度
BASKET_LABEL 收纳筐 收纳筐标签
TOY_LABEL 玩具 玩具标签
TABLE_SCAN_ATTEMPTS 2 桌面扫描尝试次数
MAX_GRAB_RETRIES 3 抓取最大重试
MAX_PLACE_RETRIES 3 放置最大重试
BATTERY_FULL_THRESHOLD 99.5 电量视为“满”的阈值
HEAD_LOOK_DOWN_RAD 0.9 头部俯视角度
_SLEEP_BETWEEN_MISSIONS 2.0 mission 间休眠

5.4.6 命令行参数

参数默认值说明
–ws-url ws://192.168.31.179:9900/ WebSocket 地址
–min-battery 30.0 最低电量
–connect-timeout 8.0 连接超时
–table-area 餐桌 餐桌语义区域名
–basket-area 玩具收纳区 玩具收纳区语义区域名
–recharge-retry 3 回充最大重试
–max-toys 0 最多抓取玩具数（0=不限制）
–search-pose-index -1 search 位姿索引
–carrier "" PutWhere carrier
–carrier-direct "" PutWhere carrier_direct
–skip-step-33 False 跳过 3.3
–skip-step-34 False 跳过 3.4
–skip-preflight False 跳过状态检查
–no-speech False 关闭语音
–speech False 显式开启语音
–yes / -y False 跳过确认
–no-color False 关闭日志颜色
–log-level INFO 日志级别

5.4.7 运行方式

### 基本运行
python3 八界机器人任务脚本（餐桌玩具收纳整理）.py
### 跳过确认
python3 八界机器人任务脚本（餐桌玩具收纳整理）.py –yes
### 关闭语音
python3 八界机器人任务脚本（餐桌玩具收纳整理）.py –yes –no-speech
### 自定义区域
python3 八界机器人任务脚本（餐桌玩具收纳整理）.py –yes \\
–table-area "餐厅桌子" \\
–basket-area "玩具收纳区"### 限制最多抓 3 个
python3 八界机器人任务脚本（餐桌玩具收纳整理）.py –yes –max-toys 3
### 只扫描不抓取
python3 八界机器人任务脚本（餐桌玩具收纳整理）.py –yes –skip-step-33
### 调试日志
python3 八界机器人任务脚本（餐桌玩具收纳整理）.py –yes –log-level DEBUG
### 指定 IP
python3 八界机器人任务脚本（餐桌玩具收纳整理）.py –ws-url ws://192.168.1.107:9900/

5.5 玩具收纳和鞋子整理

5.5.1 脚本功能

这是一个 面向真实机器人的家庭整理一体化脚本： 连接 → 状态检查 → 下桩 → 玩具收纳（扫视 + 循环抓放）→ 等待 → 玄关鞋子整理（扫视 + 配对 + 规划 + 只抓后跟）→ 结束姿态 → 回家充电。 它把玩具收纳和鞋子整理串成一条完整链路，并新增了阶段等待和只抓后跟，是学习 多阶段任务编排 + 鞋子精细抓取 的最佳入口。

一句话：让机器人下桩 → 走到玩具收纳区 → 360° 扫视识别收纳筐 → 收拾玩具 → 等待 1 分钟 → 走到玄关 → 360° 扫视找鞋 → 鞋子配对 + 规划 → 逐只抓放 → 恢复结束姿态 → 回家充电。

这是一个两阶段一体化任务：

阶段任务目标
A 玩具收纳 把散落玩具收进玩具收纳筐
B 等待 静默 60 秒，给机器人/环境缓冲
C 玄关鞋子整理 把玄关鞋子成对摆放整齐

5.5.2执行链路

[1/5] 连接机器人（ws://192.168.31.179:9900/）
↓
[2/5] 状态检查（电量 ≥ 30%、空闲、告警、地图坐标、是否充电）
↓
[3.1] 下桩判断（在充电桩上 → eco_leaveDock）
↓
########## 阶段 A：玩具收纳 ##########
[3.2] 走到玩具收纳区 + 360° 扫视识别收纳筐
[3.3] 收拾玩具到收纳筐：
搜玩具（排除筐内）→ 抓取（最多 3 次）→ 放置（最多 3 次）
循环直到无玩具或达到 max_rounds
[3.4] 结束姿态
↓
########## 阶段 B：等待 60 秒 ##########
↓
########## 阶段 C：玄关鞋子整理 ##########
[4] 导航到玄关
[4.1] 原地 360° 扫视寻找鞋子
[5] 头部拍照 → SHOE 检测 → 鞋子配对 → 抓放规划
[6] 循环执行每步：臂对准 → 臂拍 → 臂检 → 跨视匹配 → 抓（只抓后跟）→ 放
[7] 结束姿态 → 清理临时语义区域
↓
[END] 回家充电（最多 3 次）

5.5.3 脚本结构

单文件，内部按功能分块：

玩具 + 玄关鞋子 一体化脚本.py
├── 全局配置（ROBOT_IP / 区域名 / 标签 / 扫视参数 / 重试参数 / heel_half_only）
├── 通用工具（log / print_section / say / sleep_with_countdown / check_mission_status / mission_succeeded）
├── 数学工具（quat_wxyz_to_rotmat / rotmat_to_quatf / normalize_or_raise / bbox_center / _bbox_key / _relative_to_map / _quat_x_axis_yaw / _bbox_score / _bbox_area）
├── 异常 & 重试（HomeTidyError / safe_mission_call / mission_retry）
├── 状态检查（is_robot_charging / do_preflight）
├── 旋转工具（_safe_rotate）
├── 搜索（select_pose / assert_search_ok / search_pose / to_filter_box）
│
├── ================ 阶段 A：玩具收纳 ================
│ ├── 3.1 下桩（do_step_1_leave_dock）
│ ├── 3.2 扫视识别收纳筐（_detect_basket_in_frame / do_scan_basket / _compute_basket_pose_from_scan）
│ ├── 玩具抓放（reset_arm_home / hand_observe / arm_capture_and_pick / head_place_flow / _grab_with_retries / _place_with_retries / do_finish_pose）
│ └── 3.3 收拾玩具（do_step_3_tidy_toys）
│
├── ================ 阶段 C：玄关鞋子整理 ================
│ ├── 360° 扫视找鞋（_detect_shoe_in_frame / do_scan_shoes_360）
│ ├── 语义区域解析（resolve_organize_area）
│ ├── 鞋子配对（pair_shoes）
│ ├── 头图参考框归约（head_image_ref_bboxes_for_move_steps）
│ ├── 抓放规划（get_shoe_move_steps）
│ ├── 跨视图匹配（_long_axis_xoy / cosine_similarity / _batch_extract_pose_and_emb / _score_candidate / custom_match_obj_views）
│ ├── 放置位姿（front_edge_horizontal_x_axis / place_quat_from_front_edge / place_position_pixel_ray_ground_z0）
│ ├── 只抓后跟（_crop_bbox_to_heel_half / _estimate_heel_side_from_pose）
│ ├── 抓取（NamedBboxWithShoe / pick_with_arm_review）
│ ├── 单步执行（execute_pick_and_place）
│ └── 鞋子主流程（do_step_shoe_sort）
│
├── END 回家充电（do_end_recharge）
└── 主流程（parse_args / main）

5.5.4 功能概览

步骤能力对应接口
1 连接机器人 BajieRobot(ws_url).Connect()
2 状态检查 eco_refreshRobotInfo / eco_robotBattery / eco_robotWorkState / eco_robotAlarm / eco_robotPosition / eco_robotMapInfo
3.1 下桩 eco_leaveDock
A-3.2 走到玩具收纳区 eco_navigateToSemanticArea
A-3.2 360° 扫视识别收纳筐 eco_moveChassis + eco_captureImages + eco_detect_objects
A-3.2 用扫视缓存算收纳筐 6D 位姿 eco_computeObjectPose
A-3.3 搜玩具（排除筐内） eco_findObject(filter_boxes=…)
A-3.3 手臂归位 eco_setRobotArmMode(ARM_HOME)
A-3.3 手部观测 eco_lookto(CameraType.ARM)
A-3.3 手臂拍照 + OVD + 抓取 eco_captureImages + eco_detect_objects + eco_pick
A-3.3 头部观测收纳筐 eco_lookto(CameraType.HEAD)
A-3.3 头部拍照 eco_captureImages(CameraType.HEAD)
A-3.3 PutWhere 摘要 eco_put_where_summary
A-3.3 语义放置 eco_place_in
A-3.4 结束姿态 eco_finishRobotPose
B 等待 60 秒 time.sleep
C-4 导航到玄关 eco_navigateToSemanticArea
C-4.1 360° 扫视找鞋 eco_moveChassis + eco_captureImages + eco_detect_objects(entry=SHOE)
C-5 头部拍照 eco_captureImages(CameraType.HEAD)
C-5 SHOE 检测 eco_detect_objects(entry=OvdEndpoint.SHOE)
C-5 鞋子配对 eco_pairwise + 自定义 pair_shoes
C-5 线面投影 project_place_line_and_plane
C-5 抓放规划 eco_shoe_placement_plan
C-5 6D 姿态 eco_computeObjectPose
C-5 视觉特征 eco_build_embeddings
C-6 手臂对准 eco_lookto(CameraType.ARM)
C-6 手臂拍照 eco_captureImages(CameraType.ARM)
C-6 臂图检测 eco_detect_objects(entry=OvdEndpoint.SHOE)
C-6 跨视图匹配 自定义 custom_match_obj_views
C-6 只抓后跟 _crop_bbox_to_heel_half + _estimate_heel_side_from_pose
C-6 抓取 eco_pick
C-6 6D 放置 eco_place_3D
C-7 恢复结束姿态 eco_prepareRobotPose
C-7 清理临时区域 eco_manageSemanticMap(DELETE)
END 回家充电 eco_startRecharge
全程 语音播报 eco_robotSpeech
收尾 取消任务 + 断开 eco_cancelAllMissions + Disconnect

5.5.5 配置区

配置项默认值说明
ROBOT_IP 192.168.31.179 机器人 IP
DEFAULT_WS_URL ws://192.168.31.179:9900/ WebSocket 地址
DEFAULT_MIN_BATTERY 30.0 最低电量
DEFAULT_CONNECT_TIMEOUT 15.0 连接超时
DEFAULT_REFRESH_TIMEOUT 5.0 状态刷新超时
MISSION_TIMEOUT 60.0 单次 mission 超时
RECHARGE_TIMEOUT 300.0 回充超时
RECHARGE_MAX_RETRY 3 回充最大重试
RECHARGE_RETRY_INTERVAL 10 回充重试间隔
DEFAULT_TOY_AREA 玩具收纳区 玩具收纳区
DEFAULT_SHOE_AREA 玄关 玄关鞋子区
SCAN_STEP_DEG 60.0 玩具扫视步进角度
SHOE_SCAN_STEP_DEG 60.0 鞋子扫视步进角度
SCAN_MAX_ANGLE_PER_CALL 170° 单次旋转最大角度
BASKET_LABEL 收纳筐 收纳筐标签
TOY_LABEL 玩具 玩具标签
SHOE_LABEL 鞋子 鞋子标签
DEFAULT_CARRIER_BOX [[1.2,0.6,0],[1.2,-0.6,0],[0.6,-0.6,0],[0.6,0.6,0]] 默认放置区
DEFAULT_FRONT_EDGE [[0.6,-0.6,0],[0.6,0.6,0]] 默认前沿线
SHOE_MATCHING_CONFIG 见下 跨视图匹配权重
STAGE_INTERVAL_SEC 60 玩具→鞋子间隔
MAX_GRAB_RETRIES 3 抓取最大重试
MAX_PLACE_RETRIES 3 放置最大重试
HEEL_HALF_ONLY_DEFAULT True 鞋子只抓后跟那一半

SHOE_MATCHING_CONFIG：

字段默认值说明
spatial_sigma 0.8 空间距离高斯 σ
direction_sigma_deg 80.0 方向角高斯 σ
w_spatial 0.40 空间距离权重
w_direction 0.30 方向权重
w_visual 0.30 视觉相似度权重
combined_score_threshold 0.10 匹配最低分阈值

5.5.6 命令行参数

参数默认值说明
–ws-url ws://192.168.31.179:9900/ WebSocket 地址
–toy-area-name 玩具收纳区 玩具收纳区
–shoe-area-name 玄关 玄关鞋子区
–min-battery 30.0 最低电量
–connect-timeout 15.0 连接超时
–recharge-retry 3 回充最大重试
–max-rounds 0 玩具收纳最大轮数（0=无限）
–pick-index 0 OVD 抓取目标索引
–search-pose-index -1 search 位姿索引
–carrier "" PutWhere carrier
–carrier-direct "" PutWhere carrier_direct
–scan-step-deg 60.0 玩具扫视步进角度
–shoe-scan-step-deg 60.0 鞋子扫视步进角度
–stage-interval 60 玩具→鞋子间隔秒数
–skip-toy False 跳过玩具阶段
–skip-shoe False 跳过鞋子阶段
–no-voice False 关闭语音
–skip-preflight False 跳过状态检查
–yes / -y False 跳过确认
–heel-half-only True 鞋子只抓后跟那一半（默认开启）
–no-heel-half — 鞋子抓取使用完整 bbox

5.5.7 运行方式

### 基本运行
python3 玩具 + 玄关鞋子 一体化脚本.py
### 跳过确认
python3 玩具 + 玄关鞋子 一体化脚本.py –yes
### 关闭语音
python3 玩具 + 玄关鞋子 一体化脚本.py –yes –no-voice
### 自定义区域
python3 玩具 + 玄关鞋子 一体化脚本.py \\
–toy-area-name "玩具收纳区" \\
–shoe-area-name "玄关"
### 只做玩具
python3 玩具 + 玄关鞋子 一体化脚本.py –skip-shoe
### 只做鞋子
python3 玩具 + 玄关鞋子 一体化脚本.py –skip-toy
### 关闭只抓后跟
python3 玩具 + 玄关鞋子 一体化脚本.py –no-heel-half
### 调整阶段间隔
python3 玩具 + 玄关鞋子 一体化脚本.py –stage-interval 30
### 指定 IP
python3 玩具 + 玄关鞋子 一体化脚本.py –ws-url ws://192.168.1.107:9900/

六、测评小结

八界机器人 SDK 是一套面向真实物理机器人的 Python 开发套件，它不只是“发命令—收结果”的接口集合，而是一整套从感知、规划、执行到评判的完整能力体系。 它已经能做到：

  • 看：eco_captureImages、eco_detect_objects、eco_vlm_perception
  • 想：eco_vlm_desk_sort_plan、eco_shoe_placement_plan、eco_findObject
  • 动：eco_moveChassis、eco_navigateToSemanticArea、eco_lookto
  • 抓放：eco_pick、eco_place_3D、eco_place_in、eco_place_with_view
  • 评判：eco_vlm_judge
  • 闭环：感知 → 规划 → 执行 → 评判 → 再规划 从 demo 到单文件脚本，已经能跑通：

玩具收纳 / 玄关鞋子整理 / 餐桌玩具收纳 / 纸巾送物 / 桌面整理 / 玩具配送

一句话：它已经具备“让机器人完成一个真实家庭任务”的完整能力，而不是停留在“调通一个接口”。

八界机器人 SDK 已经具备从感知、规划、执行到评判的完整能力，学习路径清晰，demo 分层优秀，错误码体系完善，真实任务脚本已能跑通“连接 → 状态检查 → 下桩 → 任务 → 结束姿态 → 回充”的完整生命周期。

  • 我的建议：
    • 优 1、开箱即用 2、语义导航基本上无误，这个很好 3、文档资料齐全，SDK 对开发者友好，命名清晰
    • 补充 1、八界没有视频流，这个不太友好 2、补光灯应该能使用接口主动开启，但是只能在黑暗情况下使用； 3、八界对话应该更普适一些，每次连续对话，八界的回复就显得很没有耐心，有情绪； 4、八界应该增加在 Windows 环境下可以开发的sdk，因为肯定有开发者存在不熟悉 Linux 环境情况； 5、机器导航会充电桩时，检测充电桩好像是通过红外检测的，红外有个很不好的地方，就是外部光线太强很容易影响；这边在打开窗帘的情况下测试下来，回充成功率在60-70%左右，确实有点低了。

「一起来加入八界开源生态吧!八界开源社区: www.ecovacs-tech.com 」

赞(0)
未经允许不得转载：网硕互联帮助中心 » 【科沃斯-八界】- 科沃斯八界开源机器人场景深度体验
分享到： 更多 (0)
标签：

相关推荐

评论 抢沙发

评论前必须登录！

 

热门标签

服务器(6180)运维(4091)人工智能(3823)linux(2126)java(1699)开发语言(1630)python(1487)网络(1280)c++(1086)数据库(1042)算法(1034)前端(892)大数据(806)ai(664)学习(649)安全(602)深度学习(520)spring boot(509)后端(502)笔记(495)C语言(454)windows(452)架构(440)机器学习(417)ubuntu(391)docker(371)嵌入式硬件(369)经验分享(355)单片机(348)javascript(323)

置顶推荐

热门文章

最新文章