文档首页/ 具身智能开发平台 CloudRobo/ 最佳实践/ 通过仿真开发环境调试自定义机器人/ 任务场景搭建
更新时间：2026-09-23 GMT+08:00
查看PDF
分享

任务场景搭建

任务场景搭建是用户可以基于自己的机器人，加上已有的场景和物品等，搭建自己想要的场景，搭建出来的场景可以作为资产保存复用。

一、进入开发环境

  1. 在左侧导航栏选择“数据准备 > 数据生产”。
  2. 选择“任务场景搭建”页签，进入任务场景搭建页面。
  3. 单击右上角“创建任务”。

    环境可以选择自己想要的场景如厨房等，机器人就是将自定义机器人导入仿真环境创建的机器人，物品资产可以选自己希望机器人抓取放置的物品，也可以增加table等，示例如下。

    任务创建成功进入仿真器，如下图所示。如果任务创建时，排查机器人资产中有没有metadata.json以及内容是否正确填充，如必须含robot_type字段，当前的metadata.json后续还需随流程继续调整相机等配置。

    创建出来的场景如图所示，可以把几个物体移动到自己想要的地方，如桌子上等。

    建议开发环境挂载的OBS地址也使用刚刚的机器人资产的OBS地址，则您调试完成后会自动保存到资产中心（整体调试完成后建议将install build log等中间产物清理掉）。

    开发环境绑定的OBS地址会直接挂载到/obs目录，该目录则是您的临时调试地址，当您调试完成后，将/obs/robot_abc/Assets/robots/拷贝到/data/workspace/eail/Assets/robots目录则能够在仿真环境里正式生效。

  4. 同时打开仿真环境和开发环境。

    开发环境界面参考：

  5. 在开发环境${robot_name}_description的上层路径执行（如abc_description），启动rviz。

    编译运行如果abc_gripper_controller报错不影响，因为夹爪控制器会在之后写。也可以colcon build --packages-select abc_description，只编译机器人描述包。

    source /opt/ros/humble/setup.bash
colcon build
source install/setup.bash
ros2 launch abc_description display.launch.py

  6. 标记tool_link。

    tool_link是轨迹生成算法需要用到的“指尖末端位置”。修改urdf，找到夹爪的link，如果是单臂，添加tool_link；如果是双臂，添加left_tool_link、right_tool_link。

  7. 再次打开rviz，找到tool_link，调整角度必须如下图所示的xyz方向（对应红蓝绿三种颜色），修改rpy xyz坐标，直至tool_link位置契合直接末端位置，如图所示。

    四元数xyzw初始值为（0, 0, 0, 1），调整后z轴（蓝色）朝上，如图所示。双臂机器人同理，并非对称结构。

    检查点：

    • 机器人模型正常显示，没有大面积错位。
    • 终端没有Package [xxx] does not exist报错。
    • joint tree连通。
    • mesh没有缺失。
    • tool_link方向和位置合适。

  8. 可以在开发环境终端打开rviz可视化，拖动右侧组件的不同关节的值，也可以鼠标放在进度条，滚轮调整值，摆出你想要的初始姿态。该值用于后续步骤所需的配置文件${robot_name}.yaml的参数值填充，后处理脚本步骤调试后再进入play模式机器人则会带初始姿态。

二、进入Metaengine环境，robot importer导入URDF

  1. 如果创建任务时已经使用了最新的robot工程，则无需执行拷贝，如果您在过程中修改了robot工程，则需要将更新后的/obs/Assets/robots/robot_abc手动拷贝到/data/workspace/eail/Assets/robots/robot_abc

    登录仿真界面使用robot Importer导入/data/workspace/eail/Assets/robots/robot_abc/abc_description/urdf

    然后就会进行资产的拷贝，拷贝出来的资产会在robots/UrdfImporter下。

    如果文件未加载出来，可单击绿点然后手动刷新。

    prefab导入进去之后会坍塌，因为没有初始位姿，所以进入play模式会坍塌，所以需要进行后续的后处理，给机器人一个初始的姿态。

  2. 把prefab 和 urdfimporter导出来.

    在/data/workspace/eail/Assets/UrdfImporter/下可得到资产文件，在/data/workspace/eail/Assets/robots/下得到prefab，将此文件拷贝回/obs/Assets/robots/robot_abc，同步保存至OBS。

三、prefab后处理

  1. （可选）碰撞简化，如果FPS高可直接跳过此步骤。

    在开发环境，简化碰撞。

    python3 /obs/scripts/simplify_robot_collisions.py \
/data/workspace/eail/Assets/robots/robot_abc_origin.prefab \
--project-root "/data/workspace/eail" \
--assetinfo-mode decompose --quality high

    确认不报错后添加--apply，如下图所示。

    执行完脚本可以检查

    • AssetProcessorBatch 输出中错误数量为 0。
    • Play 模式帧率明显改善。
    • 碰撞可视化中主要 link 的碰撞范围大致合理。
    • 机器人没有因为碰撞异常而抖动或飞走。

  2. 书写prefab后处理的配置文件${robot_name}.yaml。

    其中yaml中需要按照固定模板

    单臂是

    topic_controller:  arm:    topic_name: "/arm_position_controller/commands"

    双臂是

    left_arm 
right_arm

    yaml必须写：

    topic_controller:  left_arm:    topic_name: "/left_arm_position_controller/commands"   right_arm:    topic_name: "/right_arm_position_controller/commands"

    参考样例的custom_robot中的robot_ur5e中的ur5e.yaml。

    表1 字段说明

    字段

    作用

    填写要点

    fixed_base

    固定基座link。

    必须是articulation根节点，不能是中间link。

    topic_controller

    ROS2关节控制组。

    joint_names必须和URDF中一致。

    moveit_controller

    MoveIt轨迹控制器名。

    后续MoveIt配置必须用同名。

    init_joints

    初始关节角。

    不能全填0，手臂会伸直下垂。

    camera

    相机参数。

    CameraLink必须和URDF中link名一致。

    书写abc.yaml，类似下图所示，fixed_base一般是urdf的机器人根节点，选中根节点可以看到坐标，保证机器人的方向是面延红线，就是红色轴就是机器人的面朝方向或者视线方向，最后关节参数就是之前在rviz里看到的初始姿态，您自己想要的姿态。

    这里的moveit_controller名字要和moveit里面的配置一样，这里的topic的名字需要同步写入metadata.json，方便后续录制数据。这里的关节也就是规划组的关节，关节初始值就是之前在rviz里滑动关节看到想要的初始姿态的关节值。这里的字段如

    topic_controller:
  arm:
    topic_name:

    请不要修改。如图是ur5e的示例。这里的"/hand_position_controller/commands"和后续夹爪文件cpp要对应。

    topic_controller:
  arm:
    topic_name: "/arm_position_controller/commands"
    joint_names:
    - "shoulder_pan_joint"
    - "shoulder_lift_joint"
    - "elbow_joint"
    - "wrist_1_joint"
    - "wrist_2_joint"
    - "wrist_3_joint"
  hand:
    topic_name: "/hand_position_controller/commands"
    joint_names:
    - "left_finger_joint"
    - "right_finger_joint"

    双臂的话就是类似于这种，这里的前缀字段也不要修改，这里要包含left和right。这里的"/left_gripper_position_controller/commands"和"/right_gripper_position_controller/commands"也要和后续夹爪cpp文件中对应。

    topic_controller:
  right_gripper:
    topic_name: "/right_gripper_position_controller/commands"
    joint_names:
    - "right_gripper_finger_joint1"
    - "right_gripper_finger_joint2"
  left_gripper:
    topic_name: "/left_gripper_position_controller/commands"
    joint_names:
    - "left_gripper_finger_joint1"
    - "left_gripper_finger_joint2"
  left_arm:
    topic_name: "/left_arm_position_controller/commands"
    joint_names:
  right_arm:
    topic_name: "/right_arm_position_controller/commands"
    joint_names:

  3. 执行命令，运行 prefab 转换。

    执行脚本前检查：

    • 已准备好abc.yaml 或对应配置。
    • fixed_base 名称能在 O3DE prefab 实体中找到。
    • topic_controller 的 joint_names 与 URDF / prefab 中的 Joint Name 一致。
    • moveit_controller 名称已记下，MoveIt 中必须使用同名 controller。
    • O3DE Play 模式中机器人稳定，相机和关节状态正常。 
      python3 /obs/scripts/file_convert.py \
--json "/data/workspace/eail/Assets/robots/robot_abc_origin.prefab" \
--yaml /data/workspace/eail/Assets/robots/robot_abc/abc.yaml \
--out "/data/workspace/eail/Assets/robots/robot_abc/robot_abc.prefab"

    在/data/workspace/eail/Assets/robots/robot_abc下可得到prefab文件，将此文件拷贝回/obs/robot_abc/Assets/robots/robot_abc，同步保存至OBS。

    执行后处理，删除/data/workspace/eail/Assets/robots下的初始的origin.prefab，并且进入仿真器ME删除初始instantiate的机器人prefab，重新导入新生成的prefab。

    确认后处理的prefab单击右上角的play模式不会坍塌。

    产物：机器人有初始值、相机、可以正常直立的prefab，此文件要通过共享保存出来，更新到机器人资产

    检查：

四、在安装了moveit assistant的本地或调试环境启动moveit，生成moveit所需的config文件夹

  1. 生成moveit配置包。

    执行命令,启动moveit assistant。

    source install/setup.bash
ros2 launch moveit_setup_assistant setup_assistant.launch.py

    可以看到moveit界面，初次配置单击左侧create，如果配置错了之后可以单击右侧edit选中如abc_config包。

    选abc_description下的urdf导入进去。

    在 GUI 中配置：

    1. Self-Collisions：默认即可
    2. Virtual Joint、Robot Poses、End Effectors、Passive Joints、Perception、Launch Files 按需要跳过
    3. Planning Groups：机械臂 planning group 使用 chain，夹爪 group 使用 joint，双臂左右分开建组，其中单臂就叫arm/abc_arm，双臂是abc_left_arm和abc_right_arm，必须要包含left和right。
    4. ROS2 Controllers / MoveIt Controllers（最容易出错）：
      • controller 名称必须和步骤 4 的 moveit_controller 一致，必须要是和前面的yaml，比如abc.yaml的moveit_controller一样，建议就可以叫arm_controller。
      • type 选 joint_trajectory_controller/JointTrajectoryController
      • MoveIt type 选 FollowJointTrajectory
    5. Author / Package：作者也必须要填写，最后填包名如 ur5e_config

    如图是添加规划组

    规划组（Planning groups）用来指定机器人的不同部分。如哪一部分是手臂，哪一部分是末端执行器等。

    1. 输入 Group Name 可以为 arm，双臂可以叫abc_left_arm和abc_right_arm
    2. 选择 kdl_kinematics_plugin/KDLKinematicsPlugin 作为运动学求解器。

    添加手爪（gripper）规划组，注意步骤与手臂部分有所区别。

    1. 单击“Add Group”按钮。
    2. 输入“Group Name”为hand。
    3. 保持其余选项不变。
    4. 单击“Add Links”按钮。
    5. 选择如left_finger_joint, 和right_finger_joint，一个爪子的两个手指，将它们添加到右侧的 Selected Links 列表
    6. 单击“Save”。

    双臂的示例如图所示，双臂需要包含left和right。

    标记末端执行器

    这一步尤其要注意名字和abc.yaml中moveit_controller保持一致，就可以叫abc_arm_controller，把规划的关节都选上，这里的关节和abc.yaml一样。

    作者也需要写的，写规范的邮箱即可。

    最后会生成这样的包。

  2. moveit包后处理。

    Setup Assistant生成的包缺少 Pilz 规划器、关节限速等，需要脚本补丁。

    python3 patch_moveit_config.py \
--package-path /data/workspace/eail/Assets/robots/robot_abc/abc_config \
--prefab-config /data/workspace/eail/Assets/robots/robot_abc/abc.yaml

    这个脚本执行完要确认/data/workspace/eail/Assets/robots/robot_abc/abc_config/launch有demo_me.launch.py文件，/data/workspace/eail/Assets/robots/robot_abc/下有robot_profile.yaml配置文件。

    因为robot_profile.yaml 由平台提供的 patch_moveit_config.py 自动生成，属于轨迹生成内部运行配置。

    禁止手工修改、删除或新增 robot_profile.yaml 中的字段。

    否则后续创建轨迹生成任务可能失败。如果发现配置文件确实与自己的机器人实际不符合，应修改对应的原始配置，机器人 MoveIt、SRDF、Prefab、控制器或夹爪配置发生变化后，请重新运行 patch_moveit_config.py。不得通过直接修改 robot_profile.yaml 的方式修改 Planning Group、Link、Topic 或其他机器人接口。

    要注意是补丁脚本修改了比如ur5e_config/config/joint_limits.yaml中参数，因为每个关节的加速度限制默认没有启用，所以改成了true和5.0，意思是每个关节启用最大加速度限制，最大允许值为 5.0。5.0为默认值，实际使用时请根据机器人关节规格调整。如果是下面这种默认不启用加速度限制，将无法规划。

     has_acceleration_limits: false
    max_acceleration: 0

    执行完脚本后请检查

    - srdf文件只有一个

    - config/joint_limits.yaml 中 velocity 和 acceleration limits 已启用且不为 0。

    - config/moveit_controllers.yaml 开头有 trajectory_execution。

    - demo_me.launch.py 中 pipelines 包含 ompl 和 pilz_industrial_motion_planner。

    - demo_me.launch.py 中加载了 config/moveit_controllers.yaml。

    - 如果有夹爪控制节点，reference-config 中的 gripper_controller_node 已配置正确。

    生成完config包可以编译。

五、联调me和moveit，起demo_me.launch.py

执行命令

source install/setup.bash
ros2 launch abc_config demo_me.launch.py

仿真环境的仿真器先不要进入play模式，把map改成base_link

在 RViz 中测试：

  1. Add中选择Motionplanning，然后选规划组Planning Group（如左臂、右臂、夹爪）。
  2. 进入仿真器单击进入play模式，再返回rviz。
  3. 拖动目标姿态。
  4. Plan → Execute。

拖动rviz机器人末端小球，规划执行路径，会发现仿真器里机器人也跟着动，每次务必要在调试环境终端Ctrl+C终止进程，否则会影响轨迹生成任务。

期望：RViz 规划路径 → O3DE 中机器人跟随运动 → 手臂移动夹爪开合都正常 → 无 controller 报错

六、调试夹爪控制器

  1. 书写${robot_name}_gripper_controller

    其中可以使用用单臂双臂的代码模板，比如，ur5e的0.4夹爪系数就是打开rviz，移动left_finger_joint打开左指头，最大值的坐标是0.04/0.1这样计算得来的；轨迹生成算法默认设置了0.1是打开，0是闭合。注意：ur5e的左右夹爪最大行程是8，则不要让它抓取太大的物体，否则夹爪容易卡住难以闭合，或者可以在仿真器把抓取的物体的大小调小。

    单臂夹爪

    单臂要求：

    恰好扫描到 1 个 std_msgs::msg::Float64 subscription

    例如：

    hand_gripper_subscriber_ =    this->create_subscription<std_msgs::msg::Float64>(        "hand_gripper_controller",        10,        ...    );

    最终 profile：

    arm_type: single
arm_config:
  planning_group: arm
  tool_link: tool_link
  gripper_controller: hand_gripper_controller

    双臂夹爪要求：

    恰好扫描到 2 个 Float64 subscription

    并且：

    一个 topic 名包含 left 另一个 topic 名包含 right

    例如：

    create_subscription<std_msgs::msg::Float64>(    "left_gripper_controller",    ...); create_subscription<std_msgs::msg::Float64>(    "right_gripper_controller",    ...);

    当前脚本要求能够通过 `left` / `right` 唯一区分左右夹爪。

    最终补丁脚本生成的配置文件robot_profile.yaml中类似：

    arm_type:dual
left_arm_config:  
  planning_group: abc_left_arm
  tool_link: left_tool_link
  gripper_controller: left_gripper_controller
right_arm_config:  
  planning_group: abc_right_arm
  tool_link: right_tool_link
  gripper_controller: right_gripper_controller

    其中夹爪映射系数：用于将上层下发的夹爪开口宽度转换为 URDF 中夹爪驱动关节的位置，不能一概而论。其中 type = prismatic 关节是平移夹取东西，revolute 关节是旋转闭合夹取东西。其次看lower / upper是多少，这是关节的限制。不过最直观的方法依旧是起RVIZ看机器人的状态。

    如果确认自己的夹爪是平移的，可以查看自己的URDF中gripper关节，比如ur5e的joint的范围是-0.04到0.04，通过rviz也是可以看到的。然后拖动关节值，可以看到0.04的时候开，0的时候闭合。在ur5e的案例中，夹爪最大开口宽度 width 定义为 0.1 m，并希望最大开口对应关节位置 0.04 m，因此夹爪宽度到关节位置的比例系数为：

    0.04 / 0.1 = 0.4

    要注意不一定都是0的时候闭合，甚至可以是负数。但是无论如何我们只要保证夹爪的系数如下就好，这里的开关的关节值都是可以通过RVIZ滑动关节来查看。

    k*x + b = y 
x = 0.1, y = 开的关节值 
x = 0.0，y = 关的关节值 
求k b

    对于旋转式 / 连杆式夹爪，夹爪文件的width就不是位移了，而是转角，单位是rad。不过方法依旧是通用的，只要保证0.1代入进去的值代表开，把0代入的值代表关即可。

  2. 调试夹爪控制器

    编译后运行，调试命令例如：

     ros2 topic pub --once /gripper_controller std_msgs/msg/Float64 "{data: 0.0}"

    参考ur5e机器人，仿真器进入play模式后，在开发环境输入命令，可以看到夹爪正常开闭，就证明夹爪控制器包没有问题。

    ros2 topic pub --once /hand_position_controller/commands std_msgs/msg/Float64MultiArray "{data: [0.04, 0.04]}"

    这是夹爪打开状态

    ros2 topic pub --once /hand_position_controller/commands std_msgs/msg/Float64MultiArray "{data: [0.0, 0.0]}"

    这是夹爪闭合状态。

    metadata.json从一开始就需要写出初版，可以没有相机配置，但是需要有robot_type和已知的ros topic不断补充，这些topic要和夹爪控制器保持一致。其中robot_type比较重要，目前作为自定义机器人和内置机器人的区分。

七、保存

保存dev调试环境调试完的所有文件到用户OBS。

整理刚刚保存的文件，清理掉install log等无用的编译产物，只保留要求的产物，以样例格式罗列，更新资产中心的机器人资产（如果您挂载到开发环境的已是资产中心关联的机器人资产OBS路径，则清理无用产物和整理格式即可直接保存；如果您未使用机器人资产关联的路径，此处只能到OBS更新，资产中心不支持直接更新）

更新机器人资产挂载的OBS路径下的机器人文件（后续再搭场景的时候就用最新的机器人本体）

其中/data/workspace/eail/Assets/robots/ 下应保证只有一个机器人子目录，例如 robot_abc/，没有其他目录也没有其他文件；该目录中存放该机器人的完整工程文件包含 robot_profile.yaml 等配置文件。确认一个自定义机器人运行目录应只包含当前机器人对应的一份 Prefab。当前任务使用的 UrdfImporter 目录中也应只保留当前机器人对应的资源目录。请勿在同一个任务输入目录中同时保留多个历史版本的 Prefab、Robot Profile 或 UrdfImporter 机器人资源。

进入仿真器单击File单击save，在前端界面单击保存至空间资产，保存出来的目录结构下有Assets和Levels两个目录。

相关文档