面向读者

验证等级

仅配置验证。 本案例校验 robot manifest、解析真实 URDF，并检查可移植词汇。 不会启动 PyBullet，也不验证驱动、动力学、IK 或规划。

文件说明

  • run.yaml 添加一个二关节机械臂及其初始关节位置。
  • main.py 断言 joints、links、frames、groups 和实例状态。
  • Robot manifest 声明可复用机器人契约。

逐行阅读组件 manifest

yaml
schema: fastsim-component/1
id: robot://fastsim/component-demo-arm   # 稳定 robot identity。
version: 1.0.0                           # 不可变组件发布版。
kind: robot                              # 允许放到 scenario.scene.robots。
semantics:
  joints: [joint_1, joint_2]             # 可移植关节名称。
  links: [base_link, link_1, link_2]     # 可移植 link 名称。
  frames: [base_link, link_2]            # 面向应用的具名 frame。
  joint_units:
    joint_1: rad                         # joint_1 的状态/控制单位。
    joint_2: rad                         # joint_2 的状态/控制单位。
  groups:
    arm: [joint_1, joint_2]              # 有顺序的机械臂控制 group。
variants:
  pybullet:
    resources:
      model:
        uri: ../../_shared/assets/two_joint_arm.urdf
        format: model/vnd.urdf+xml
        role: simulation

优质 robot manifest 会分离可移植意图与后端表达。应用代码使用稳定的关节、link、 frame 和 group 名称；每个后端 variant 提供自身可读取的模型。更复杂机器人可声明 base、left_arm、right_arm、gripper 等多个 group，而不改变 Run 结构。

编写自己的 robot 时，让这些名称成为你希望用户依赖的公共词汇。manifest 不是 controller 实现，也不会掩盖原生 actuator 缺失或动力学参数错误。

逐行阅读 run.yaml

yaml
schema: fastsim/2
name: robot-component
backend: pybullet                        # 选择 PyBullet 兼容模型。

runtime:
  physics_hz: 60                         # 物理频率声明。
  control_hz: 30                         # 控制接收频率。
  seed: 104                              # 可复现随机种子。

scenario:
  scene:
    robots:
      arm:                               # 本地实体别名：robots.arm。
        use: robot://fastsim/component-demo-arm
        pose:
          xyz_m: [0.0, 0.0, 0.0]       # 机器人世界根位置，单位米。
          quat_xyzw: [0.0, 0.0, 0.0, 1.0]
        initial_state:
          joints:
            joint_1: 0.20               # 弧度，由 manifest 声明。
            joint_2: -0.40              # 允许负角度。

arm 是实例别名，不必等于组件名称。同一个 Run 可以用不同别名创建多个相同机器人。

main.py 验证什么

程序仅使用 from fastsim.config import load_project，编译 Run 并断言：

  • 所选组件为 kind: robot；
  • 有序的关节、link 和 frame 声明可供上层读取；
  • group arm 按顺序解析为两个关节；
  • 初始关节映射进入不可变实体记录。

运行

bash
cd demo/components/04_robot_component
fastsim config validate run.yaml --json
fastsim config expand run.yaml
fastsim config explain run.yaml scenario.scene.robots.arm.initial_state.joints.joint_1
fastsim config lock run.yaml --output run.lock.yaml
fastsim config verify-lock run.lock.yaml --json
python main.py

预期输出

text
Entity: robots.arm
Joints: ('joint_1', 'joint_2')
Links: ('base_link', 'link_1', 'link_2')
Frames: ('base_link', 'link_2')
Group 'arm': ('joint_1', 'joint_2')

常见错误

  • initial_state 中未在 semantics.joints 声明的关节会被拒绝。
  • group 顺序决定向量控制信号含义，必须有意识地定义并记录。
  • frame 声明只是名称契约，不证明所有资产 variant 已正确标定；还需原生接入验收。
  • Robot 组件描述机器人实体。冰箱或笔记本电脑应使用 articulation:// 组件。

下一步

上一个：Articulation 组件 · 下一个：Environment 组件