release: SkillFactory v0.0.2

This commit is contained in:
2026-10-10 16:34:40 +08:00
parent 7f39abb613
commit 8019d6f8d6
22 changed files with 4974 additions and 6 deletions
+15 -2
View File
@@ -1,9 +1,21 @@
# SkillFactory v0.0.1
# SkillFactory v0.0.2
仓库:[chenlin/SkillFactory](https://gitea.robotquan.com/chenlin/SkillFactory)。
真实单腿资产的导入、固定支座仿真与共享策略训练原型。当前覆盖 **Go2 FL / Go1 FL**;第一周 Go2 基准已完成验收,共享 PPO 仅通过短更新测试,**尚无已收敛、冻结或验证泛化的 Skill**。
## 统一软硬件描述规范
唯一规范入口:[`docs/software_hardware_spec.md`](docs/software_hardware_spec.md)。最新机器格式为 PartSpec / SoftwareSpec **v2**,示例位于 `configs/parts/` 与 `configs/software/`;旧版规范及 Schema 已移除。发布版本 `v0.0.2` 与描述格式版本 `v2` 独立。
```bash
# Python 3.12,需已有 jsonschema;无需启动 Kit
python3 scripts/validate_descriptions.py \
--hardware configs/parts/*.json --software configs/software/*.json
```
通用 v2 adapter 尚未实现;下述单腿仿真继续使用保留的 `configs/legs/` 运行输入。设计模板、静态校验通过均不等于已支持对应部位的仿真、训练或实机部署。
## 运行环境
本机已验证:Isaac Sim 6.0.1、Isaac Lab 3.0.0(core 6.1.17)、Python 3.12、Torch 2.10 CUDA、Kit `PhysxCfg`。不修改外部 Lab/Unitree,不安装新运行时。
@@ -59,7 +71,8 @@ PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 ANCHOR_RUNTIME_TESTS=1 "$LAB" -p -m pytest test
"$LAB" -p -m ruff check source/SkillFactory scripts tests
```
- [`docs/leg_interface.md`](docs/leg_interface.md):资产/token/动作契约、验收阈值与证据、实现边界。
- [`docs/software_hardware_spec.md`](docs/software_hardware_spec.md):统一软硬件描述规范 v2;支持腿/臂/手/夹爪/躯干/头部/底座/传感器的结构与语义端口,示例在 `configs/parts/`。v2 adapter 尚未实现,当前可运行的仍是单腿 v1。
- [`docs/leg_interface.md`](docs/leg_interface.md):现有单腿兼容运行链路、验收阈值与证据;不作为另一份描述规范。
- `SkillFactory-LegSkill-v0`:结构化 token 与专用 PPO 原型入口;不能直接交给仅接受平坦观测的旧 RSL-RL trainer。
- `SkillFactory-SingleLegAnchor-Go2-v0`:保留 `[B,19]` 验收接口。
- `Template-Skillfactory-v0`:原 Cartpole 与 `scripts/rsl_rl/` 入口保留。
+443
View File
@@ -0,0 +1,443 @@
{
"schema_version": 2,
"kind": "robot_part",
"part_id": "example_arm",
"part_type": "arm",
"description_role": "design_template",
"source": {
"format": "design",
"root": null,
"path": null,
"package_name": null,
"license_file": null,
"license_id": "LicenseRef-Design-Template",
"revision": null,
"sha256": null
},
"topology": {
"structure": "tree",
"root_body": "base",
"bodies": [
"base",
"link_0",
"link_1",
"link_2",
"link_3",
"link_4",
"link_5"
],
"joints": [
{
"id": "joint_0",
"source_name": "joint_0",
"type": "revolute",
"parent": "base",
"child": "link_0",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": null
},
{
"id": "joint_1",
"source_name": "joint_1",
"type": "revolute",
"parent": "link_0",
"child": "link_1",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": null
},
{
"id": "joint_2",
"source_name": "joint_2",
"type": "revolute",
"parent": "link_1",
"child": "link_2",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": null
},
{
"id": "joint_3",
"source_name": "joint_3",
"type": "revolute",
"parent": "link_2",
"child": "link_3",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": null
},
{
"id": "joint_4",
"source_name": "joint_4",
"type": "revolute",
"parent": "link_3",
"child": "link_4",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": null
},
{
"id": "joint_5",
"source_name": "joint_5",
"type": "revolute",
"parent": "link_4",
"child": "link_5",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": null
}
],
"constraints": []
},
"frames": [
{
"id": "root",
"body": "base",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
},
{
"id": "tool_frame",
"body": "link_5",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
}
],
"root_frame": "root",
"attachment": {
"mode": "fixed",
"frame_id": "root",
"source_mount_joint": null,
"auxiliary_root_joints": []
},
"actuators": [
{
"id": "drive_joint_0",
"joint_id": "joint_0",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
},
{
"id": "drive_joint_1",
"joint_id": "joint_1",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
},
{
"id": "drive_joint_2",
"joint_id": "joint_2",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
},
{
"id": "drive_joint_3",
"joint_id": "joint_3",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
},
{
"id": "drive_joint_4",
"joint_id": "joint_4",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
},
{
"id": "drive_joint_5",
"joint_id": "joint_5",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
}
],
"end_effectors": [
{
"id": "tool",
"role": "tool",
"frame_id": "tool_frame",
"contact": null
}
],
"sensors": [
{
"id": "joint_state",
"kind": "joint_state",
"outputs": [
"joint.position",
"joint.velocity"
],
"frame_id": "root",
"target": {
"entity": "joint",
"ids": [
"joint_0",
"joint_1",
"joint_2",
"joint_3",
"joint_4",
"joint_5"
]
},
"update_period_s": 0.002
}
],
"timing": {
"physics_dt_s": 0.002,
"control_dt_s": 0.01
},
"safety": {
"soft_limit_factor": 0.9,
"on_invalid_command": "reject",
"on_timeout": "disable",
"command_timeout_s": 0.05
},
"scales": {
"length_m": null,
"known_mass_kg": null
},
"extensions": {
"skillfactory.example": {
"synthetic": true,
"not_manufacturer_data": true
}
}
}
+232
View File
@@ -0,0 +1,232 @@
{
"schema_version": 2,
"kind": "robot_part",
"part_id": "example_gripper",
"part_type": "gripper",
"description_role": "design_template",
"source": {
"format": "design",
"root": null,
"path": null,
"package_name": null,
"license_file": null,
"license_id": "LicenseRef-Design-Template",
"revision": null,
"sha256": null
},
"topology": {
"structure": "tree",
"root_body": "base",
"bodies": [
"base",
"link_0",
"link_1"
],
"joints": [
{
"id": "joint_0",
"source_name": "joint_0",
"type": "prismatic",
"parent": "base",
"child": "link_0",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "m",
"axis": [
1,
0,
0
],
"limits_origin": "declared",
"limits": {
"position": [
0,
0.04
],
"velocity": 1,
"effort": 10
},
"coupling": null
},
{
"id": "joint_1",
"source_name": "joint_1",
"type": "prismatic",
"parent": "base",
"child": "link_1",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "coupled",
"position_unit": "m",
"axis": [
1,
0,
0
],
"limits_origin": "declared",
"limits": {
"position": [
0,
0.04
],
"velocity": 1,
"effort": 10
},
"coupling": {
"joint_id": "joint_0",
"multiplier": -1,
"offset": 0.04
}
}
],
"constraints": []
},
"frames": [
{
"id": "root",
"body": "base",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
},
{
"id": "jaw_a_frame",
"body": "link_0",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
},
{
"id": "jaw_b_frame",
"body": "link_1",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
}
],
"root_frame": "root",
"attachment": {
"mode": "fixed",
"frame_id": "root",
"source_mount_joint": null,
"auxiliary_root_joints": []
},
"actuators": [
{
"id": "drive_joint_0",
"joint_id": "joint_0",
"neutral_position": 0.02,
"commands": {
"position_pd": {
"unit": "m",
"scale": 0.01,
"offset": 0.02,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
}
],
"end_effectors": [
{
"id": "jaw_a",
"role": "grasp",
"frame_id": "jaw_a_frame",
"contact": null
},
{
"id": "jaw_b",
"role": "grasp",
"frame_id": "jaw_b_frame",
"contact": null
}
],
"sensors": [
{
"id": "joint_state",
"kind": "joint_state",
"outputs": [
"joint.position",
"joint.velocity"
],
"frame_id": "root",
"target": {
"entity": "joint",
"ids": [
"joint_0",
"joint_1"
]
},
"update_period_s": 0.002
}
],
"timing": {
"physics_dt_s": 0.002,
"control_dt_s": 0.01
},
"safety": {
"soft_limit_factor": 0.9,
"on_invalid_command": "reject",
"on_timeout": "disable",
"command_timeout_s": 0.05
},
"scales": {
"length_m": null,
"known_mass_kg": null
},
"extensions": {
"skillfactory.example": {
"synthetic": true,
"not_manufacturer_data": true
}
}
}
+330
View File
@@ -0,0 +1,330 @@
{
"schema_version": 2,
"kind": "robot_part",
"part_id": "example_hand",
"part_type": "hand",
"description_role": "design_template",
"source": {
"format": "design",
"root": null,
"path": null,
"package_name": null,
"license_file": null,
"license_id": "LicenseRef-Design-Template",
"revision": null,
"sha256": null
},
"topology": {
"structure": "tree",
"root_body": "base",
"bodies": [
"base",
"link_0",
"link_1",
"link_2",
"link_3"
],
"joints": [
{
"id": "joint_0",
"source_name": "joint_0",
"type": "revolute",
"parent": "base",
"child": "link_0",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": null
},
{
"id": "joint_1",
"source_name": "joint_1",
"type": "revolute",
"parent": "link_0",
"child": "link_1",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "coupled",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": {
"joint_id": "joint_0",
"multiplier": 0.5,
"offset": 0
}
},
{
"id": "joint_2",
"source_name": "joint_2",
"type": "revolute",
"parent": "base",
"child": "link_2",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": null
},
{
"id": "joint_3",
"source_name": "joint_3",
"type": "revolute",
"parent": "link_2",
"child": "link_3",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "coupled",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": {
"joint_id": "joint_2",
"multiplier": 0.5,
"offset": 0
}
}
],
"constraints": []
},
"frames": [
{
"id": "root",
"body": "base",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
},
{
"id": "finger_a_frame",
"body": "link_1",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
},
{
"id": "finger_b_frame",
"body": "link_3",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
}
],
"root_frame": "root",
"attachment": {
"mode": "fixed",
"frame_id": "root",
"source_mount_joint": null,
"auxiliary_root_joints": []
},
"actuators": [
{
"id": "drive_joint_0",
"joint_id": "joint_0",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
},
{
"id": "drive_joint_2",
"joint_id": "joint_2",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
}
],
"end_effectors": [
{
"id": "finger_a",
"role": "fingertip",
"frame_id": "finger_a_frame",
"contact": null
},
{
"id": "finger_b",
"role": "fingertip",
"frame_id": "finger_b_frame",
"contact": null
}
],
"sensors": [
{
"id": "joint_state",
"kind": "joint_state",
"outputs": [
"joint.position",
"joint.velocity"
],
"frame_id": "root",
"target": {
"entity": "joint",
"ids": [
"joint_0",
"joint_1",
"joint_2",
"joint_3"
]
},
"update_period_s": 0.002
}
],
"timing": {
"physics_dt_s": 0.002,
"control_dt_s": 0.01
},
"safety": {
"soft_limit_factor": 0.9,
"on_invalid_command": "reject",
"on_timeout": "disable",
"command_timeout_s": 0.05
},
"scales": {
"length_m": null,
"known_mass_kg": null
},
"extensions": {
"skillfactory.example": {
"synthetic": true,
"not_manufacturer_data": true
}
}
}
+254
View File
@@ -0,0 +1,254 @@
{
"schema_version": 2,
"kind": "robot_part",
"part_id": "example_head",
"part_type": "head",
"description_role": "design_template",
"source": {
"format": "design",
"root": null,
"path": null,
"package_name": null,
"license_file": null,
"license_id": "LicenseRef-Design-Template",
"revision": null,
"sha256": null
},
"topology": {
"structure": "tree",
"root_body": "base",
"bodies": [
"base",
"link_0",
"link_1"
],
"joints": [
{
"id": "joint_0",
"source_name": "joint_0",
"type": "revolute",
"parent": "base",
"child": "link_0",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": null
},
{
"id": "joint_1",
"source_name": "joint_1",
"type": "revolute",
"parent": "link_0",
"child": "link_1",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": null
}
],
"constraints": []
},
"frames": [
{
"id": "root",
"body": "base",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
},
{
"id": "gaze_frame",
"body": "link_1",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
}
],
"root_frame": "root",
"attachment": {
"mode": "fixed",
"frame_id": "root",
"source_mount_joint": null,
"auxiliary_root_joints": []
},
"actuators": [
{
"id": "drive_joint_0",
"joint_id": "joint_0",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
},
{
"id": "drive_joint_1",
"joint_id": "joint_1",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
}
],
"end_effectors": [
{
"id": "gaze",
"role": "gaze",
"frame_id": "gaze_frame",
"contact": null
}
],
"sensors": [
{
"id": "joint_state",
"kind": "joint_state",
"outputs": [
"joint.position",
"joint.velocity"
],
"frame_id": "root",
"target": {
"entity": "joint",
"ids": [
"joint_0",
"joint_1"
]
},
"update_period_s": 0.002
},
{
"id": "camera",
"kind": "camera",
"outputs": [
"image.rgb8"
],
"frame_id": "root",
"target": {
"entity": "part",
"ids": [
"example_head"
]
},
"update_period_s": 0.02
},
{
"id": "imu",
"kind": "imu",
"outputs": [
"imu.acceleration",
"imu.angular_velocity"
],
"frame_id": "root",
"target": {
"entity": "part",
"ids": [
"example_head"
]
},
"update_period_s": 0.02
}
],
"timing": {
"physics_dt_s": 0.002,
"control_dt_s": 0.01
},
"safety": {
"soft_limit_factor": 0.9,
"on_invalid_command": "reject",
"on_timeout": "disable",
"command_timeout_s": 0.05
},
"scales": {
"length_m": null,
"known_mass_kg": null
},
"extensions": {
"skillfactory.example": {
"synthetic": true,
"not_manufacturer_data": true
}
}
}
+303
View File
@@ -0,0 +1,303 @@
{
"schema_version": 2,
"kind": "robot_part",
"part_id": "example_mobile_base",
"part_type": "mobile_base",
"description_role": "design_template",
"source": {
"format": "design",
"root": null,
"path": null,
"package_name": null,
"license_file": null,
"license_id": "LicenseRef-Design-Template",
"revision": null,
"sha256": null
},
"topology": {
"structure": "tree",
"root_body": "base",
"bodies": [
"base",
"link_0",
"link_1",
"link_2",
"link_3"
],
"joints": [
{
"id": "joint_0",
"source_name": "joint_0",
"type": "continuous",
"parent": "base",
"child": "link_0",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": null,
"velocity": 10,
"effort": 10
},
"coupling": null
},
{
"id": "joint_1",
"source_name": "joint_1",
"type": "continuous",
"parent": "base",
"child": "link_1",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": null,
"velocity": 10,
"effort": 10
},
"coupling": null
},
{
"id": "joint_2",
"source_name": "joint_2",
"type": "continuous",
"parent": "base",
"child": "link_2",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": null,
"velocity": 10,
"effort": 10
},
"coupling": null
},
{
"id": "joint_3",
"source_name": "joint_3",
"type": "continuous",
"parent": "base",
"child": "link_3",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": null,
"velocity": 10,
"effort": 10
},
"coupling": null
}
],
"constraints": []
},
"frames": [
{
"id": "root",
"body": "base",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
}
],
"root_frame": "root",
"attachment": {
"mode": "floating",
"frame_id": "root",
"source_mount_joint": null,
"auxiliary_root_joints": []
},
"actuators": [
{
"id": "drive_joint_0",
"joint_id": "joint_0",
"neutral_position": 0.0,
"commands": {
"velocity": {
"unit": "rad/s",
"scale": 0.25,
"offset": 0,
"gains": null
}
}
},
{
"id": "drive_joint_1",
"joint_id": "joint_1",
"neutral_position": 0.0,
"commands": {
"velocity": {
"unit": "rad/s",
"scale": 0.25,
"offset": 0,
"gains": null
}
}
},
{
"id": "drive_joint_2",
"joint_id": "joint_2",
"neutral_position": 0.0,
"commands": {
"velocity": {
"unit": "rad/s",
"scale": 0.25,
"offset": 0,
"gains": null
}
}
},
{
"id": "drive_joint_3",
"joint_id": "joint_3",
"neutral_position": 0.0,
"commands": {
"velocity": {
"unit": "rad/s",
"scale": 0.25,
"offset": 0,
"gains": null
}
}
}
],
"end_effectors": [],
"sensors": [
{
"id": "joint_state",
"kind": "joint_state",
"outputs": [
"joint.position",
"joint.velocity"
],
"frame_id": "root",
"target": {
"entity": "joint",
"ids": [
"joint_0",
"joint_1",
"joint_2",
"joint_3"
]
},
"update_period_s": 0.002
},
{
"id": "imu",
"kind": "imu",
"outputs": [
"imu.acceleration",
"imu.angular_velocity"
],
"frame_id": "root",
"target": {
"entity": "part",
"ids": [
"example_mobile_base"
]
},
"update_period_s": 0.02
}
],
"timing": {
"physics_dt_s": 0.002,
"control_dt_s": 0.01
},
"safety": {
"soft_limit_factor": 0.9,
"on_invalid_command": "reject",
"on_timeout": "disable",
"command_timeout_s": 0.05
},
"scales": {
"length_m": null,
"known_mass_kg": null
},
"extensions": {
"skillfactory.example": {
"synthetic": true,
"not_manufacturer_data": true
}
}
}
+105
View File
@@ -0,0 +1,105 @@
{
"schema_version": 2,
"kind": "robot_part",
"part_id": "example_sensor",
"part_type": "sensor",
"description_role": "design_template",
"source": {
"format": "design",
"root": null,
"path": null,
"package_name": null,
"license_file": null,
"license_id": "LicenseRef-Design-Template",
"revision": null,
"sha256": null
},
"topology": {
"structure": "tree",
"root_body": "base",
"bodies": [
"base"
],
"joints": [],
"constraints": []
},
"frames": [
{
"id": "root",
"body": "base",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
}
],
"root_frame": "root",
"attachment": {
"mode": "external",
"frame_id": "root",
"source_mount_joint": null,
"auxiliary_root_joints": []
},
"actuators": [],
"end_effectors": [],
"sensors": [
{
"id": "camera",
"kind": "camera",
"outputs": [
"image.rgb8"
],
"frame_id": "root",
"target": {
"entity": "part",
"ids": [
"example_sensor"
]
},
"update_period_s": 0.02
},
{
"id": "imu",
"kind": "imu",
"outputs": [
"imu.acceleration",
"imu.angular_velocity"
],
"frame_id": "root",
"target": {
"entity": "part",
"ids": [
"example_sensor"
]
},
"update_period_s": 0.02
}
],
"timing": {
"physics_dt_s": 0.002,
"control_dt_s": 0.01
},
"safety": {
"soft_limit_factor": 0.9,
"on_invalid_command": "reject",
"on_timeout": "disable",
"command_timeout_s": 0.05
},
"scales": {
"length_m": null,
"known_mass_kg": null
},
"extensions": {
"skillfactory.example": {
"synthetic": true,
"not_manufacturer_data": true
}
}
}
+201
View File
@@ -0,0 +1,201 @@
{
"schema_version": 2,
"kind": "robot_part",
"part_id": "example_torso",
"part_type": "torso",
"description_role": "design_template",
"source": {
"format": "design",
"root": null,
"path": null,
"package_name": null,
"license_file": null,
"license_id": "LicenseRef-Design-Template",
"revision": null,
"sha256": null
},
"topology": {
"structure": "tree",
"root_body": "base",
"bodies": [
"base",
"link_0",
"link_1"
],
"joints": [
{
"id": "joint_0",
"source_name": "joint_0",
"type": "revolute",
"parent": "base",
"child": "link_0",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": null
},
{
"id": "joint_1",
"source_name": "joint_1",
"type": "revolute",
"parent": "link_0",
"child": "link_1",
"origin": {
"xyz": [
0,
0,
0.1
],
"quat_xyzw": [
0,
0,
0,
1
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0,
1,
0
],
"limits_origin": "declared",
"limits": {
"position": [
-1.5,
1.5
],
"velocity": 10,
"effort": 10
},
"coupling": null
}
],
"constraints": []
},
"frames": [
{
"id": "root",
"body": "base",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
}
],
"root_frame": "root",
"attachment": {
"mode": "fixed",
"frame_id": "root",
"source_mount_joint": null,
"auxiliary_root_joints": []
},
"actuators": [
{
"id": "drive_joint_0",
"joint_id": "joint_0",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
},
{
"id": "drive_joint_1",
"joint_id": "joint_1",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25,
"kd": 0.5
}
}
}
}
],
"end_effectors": [],
"sensors": [
{
"id": "joint_state",
"kind": "joint_state",
"outputs": [
"joint.position",
"joint.velocity"
],
"frame_id": "root",
"target": {
"entity": "joint",
"ids": [
"joint_0",
"joint_1"
]
},
"update_period_s": 0.002
}
],
"timing": {
"physics_dt_s": 0.002,
"control_dt_s": 0.01
},
"safety": {
"soft_limit_factor": 0.9,
"on_invalid_command": "reject",
"on_timeout": "disable",
"command_timeout_s": 0.05
},
"scales": {
"length_m": null,
"known_mass_kg": null
},
"extensions": {
"skillfactory.example": {
"synthetic": true,
"not_manufacturer_data": true
}
}
}
+475
View File
@@ -0,0 +1,475 @@
{
"schema_version": 2,
"kind": "robot_part",
"part_id": "go2_fl",
"part_type": "leg",
"description_role": "asset_reference",
"source": {
"format": "urdf",
"root": "/home/cen/Embodied_Workspace/unitree_ros/robots/go2_description",
"path": "urdf/go2_description.urdf",
"package_name": "go2_description",
"license_file": "../../LICENSE",
"license_id": "BSD-3-Clause",
"revision": "daadf41ee9afce8f90fdc09a98506012691fa122",
"sha256": "7d19fe48e2e689ee1a032ab99f2a4a8b671d87e73de48d3e65811682a5b48b9e"
},
"topology": {
"structure": "tree",
"root_body": "anchor_base",
"bodies": [
"anchor_base",
"FL_calf",
"FL_calf_rotor",
"FL_calflower",
"FL_calflower1",
"FL_foot",
"FL_hip",
"FL_hip_rotor",
"FL_thigh",
"FL_thigh_rotor"
],
"joints": [
{
"id": "FL_hip_joint",
"source_name": "FL_hip_joint",
"type": "revolute",
"parent": "anchor_base",
"child": "FL_hip",
"origin": {
"xyz": [
0.0,
0.0,
0.0
],
"quat_xyzw": [
0.0,
0.0,
0.0,
1.0
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
1.0,
0.0,
0.0
],
"limits_origin": "source",
"limits": {
"position": [
-1.0472,
1.0472
],
"velocity": 30.1,
"effort": 23.7
},
"coupling": null
},
{
"id": "FL_hip_rotor_joint",
"source_name": "FL_hip_rotor_joint",
"type": "fixed",
"parent": "anchor_base",
"child": "FL_hip_rotor",
"origin": {
"xyz": [
-0.08125,
0.00025,
0.0
],
"quat_xyzw": [
0.0,
0.0,
0.0,
1.0
]
},
"actuation": "fixed",
"position_unit": null,
"axis": null,
"limits_origin": "source",
"limits": null,
"coupling": null
},
{
"id": "FL_thigh_joint",
"source_name": "FL_thigh_joint",
"type": "revolute",
"parent": "FL_hip",
"child": "FL_thigh",
"origin": {
"xyz": [
0.0,
0.0955,
0.0
],
"quat_xyzw": [
0.0,
0.0,
0.0,
1.0
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0.0,
1.0,
0.0
],
"limits_origin": "source",
"limits": {
"position": [
-1.5708,
3.4907
],
"velocity": 30.1,
"effort": 23.7
},
"coupling": null
},
{
"id": "FL_thigh_rotor_joint",
"source_name": "FL_thigh_rotor_joint",
"type": "fixed",
"parent": "FL_hip",
"child": "FL_thigh_rotor",
"origin": {
"xyz": [
0.0,
-0.00015,
0.0
],
"quat_xyzw": [
0.0,
0.0,
0.0,
1.0
]
},
"actuation": "fixed",
"position_unit": null,
"axis": null,
"limits_origin": "source",
"limits": null,
"coupling": null
},
{
"id": "FL_calf_joint",
"source_name": "FL_calf_joint",
"type": "revolute",
"parent": "FL_thigh",
"child": "FL_calf",
"origin": {
"xyz": [
0.0,
0.0,
-0.213
],
"quat_xyzw": [
0.0,
0.0,
0.0,
1.0
]
},
"actuation": "active",
"position_unit": "rad",
"axis": [
0.0,
1.0,
0.0
],
"limits_origin": "source",
"limits": {
"position": [
-2.7227,
-0.83776
],
"velocity": 15.7,
"effort": 45.43
},
"coupling": null
},
{
"id": "FL_calf_rotor_joint",
"source_name": "FL_calf_rotor_joint",
"type": "fixed",
"parent": "FL_thigh",
"child": "FL_calf_rotor",
"origin": {
"xyz": [
0.0,
-0.03235,
0.0
],
"quat_xyzw": [
0.0,
0.0,
0.0,
1.0
]
},
"actuation": "fixed",
"position_unit": null,
"axis": null,
"limits_origin": "source",
"limits": null,
"coupling": null
},
{
"id": "FL_calflower_joint",
"source_name": "FL_calflower_joint",
"type": "fixed",
"parent": "FL_calf",
"child": "FL_calflower",
"origin": {
"xyz": [
0.02,
0.0,
-0.148
],
"quat_xyzw": [
0.0,
0.024997395914712332,
0.0,
0.9996875162757026
]
},
"actuation": "fixed",
"position_unit": null,
"axis": null,
"limits_origin": "source",
"limits": null,
"coupling": null
},
{
"id": "FL_foot_joint",
"source_name": "FL_foot_joint",
"type": "fixed",
"parent": "FL_calf",
"child": "FL_foot",
"origin": {
"xyz": [
0.0,
0.0,
-0.213
],
"quat_xyzw": [
0.0,
0.0,
0.0,
1.0
]
},
"actuation": "fixed",
"position_unit": null,
"axis": null,
"limits_origin": "source",
"limits": null,
"coupling": null
},
{
"id": "FL_calflower1_joint",
"source_name": "FL_calflower1_joint",
"type": "fixed",
"parent": "FL_calflower",
"child": "FL_calflower1",
"origin": {
"xyz": [
-0.01,
0.0,
-0.04
],
"quat_xyzw": [
0.0,
0.23770262642713458,
0.0,
0.9713379748520297
]
},
"actuation": "fixed",
"position_unit": null,
"axis": null,
"limits_origin": "source",
"limits": null,
"coupling": null
}
],
"constraints": []
},
"frames": [
{
"id": "root",
"body": "anchor_base",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
},
{
"id": "foot_link",
"body": "FL_foot",
"xyz": [
0,
0,
0
],
"quat_xyzw": [
0,
0,
0,
1
]
}
],
"root_frame": "root",
"attachment": {
"mode": "fixed",
"frame_id": "root",
"source_mount_joint": "FL_hip_joint",
"auxiliary_root_joints": [
"FL_hip_rotor_joint"
],
"source_parent_transform": {
"body": "base",
"xyz": [
0.1934,
0.0465,
0.0
],
"quat_xyzw": [
0.0,
0.0,
0.0,
1.0
]
}
},
"actuators": [
{
"id": "drive_FL_hip_joint",
"joint_id": "FL_hip_joint",
"neutral_position": 0.0,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.0,
"gains": {
"kp": 25.0,
"kd": 0.5
}
}
}
},
{
"id": "drive_FL_thigh_joint",
"joint_id": "FL_thigh_joint",
"neutral_position": 0.8,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": 0.8,
"gains": {
"kp": 25.0,
"kd": 0.5
}
}
}
},
{
"id": "drive_FL_calf_joint",
"joint_id": "FL_calf_joint",
"neutral_position": -1.5,
"commands": {
"position_pd": {
"unit": "rad",
"scale": 0.25,
"offset": -1.5,
"gains": {
"kp": 25.0,
"kd": 0.5
}
}
}
}
],
"end_effectors": [
{
"id": "foot",
"role": "support",
"frame_id": "foot_link",
"contact": {
"source_collision_index": 0,
"gap_method": "sphere"
}
}
],
"sensors": [
{
"id": "joint_state",
"kind": "joint_state",
"outputs": [
"joint.position",
"joint.velocity"
],
"frame_id": "root",
"target": {
"entity": "joint",
"ids": [
"FL_hip_joint",
"FL_thigh_joint",
"FL_calf_joint"
]
},
"update_period_s": 0.002
},
{
"id": "foot_contact",
"kind": "contact_normal",
"outputs": [
"contact.normal_force"
],
"frame_id": "foot_link",
"target": {
"entity": "end_effector",
"ids": [
"foot"
]
},
"update_period_s": 0.002
}
],
"timing": {
"physics_dt_s": 0.002,
"control_dt_s": 0.01
},
"safety": {
"soft_limit_factor": 0.9,
"on_invalid_command": "reject",
"on_timeout": "hold",
"command_timeout_s": 0.05
},
"scales": {
"length_m": 0.5455,
"known_mass_kg": 2.291
},
"extensions": {
"skillfactory.legacy": {
"profile": "single_leg_v1",
"derived_urdf_sha256": "d9de15364ee90ea65f028203177cb1506b9b23ce1bba303a1e3c936ad2e6f921",
"watchdog_policy": "v2 requirement only; not implemented by the legacy runtime"
}
}
}
+277
View File
@@ -0,0 +1,277 @@
{
"schema_version": 2,
"kind": "part_software",
"software_id": "part_position_control",
"software_version": "0.0.2",
"status": "design",
"binding_mode": "alternatives",
"hardware_bindings": [
{
"part_id": "go2_fl",
"spec_path": "configs/parts/go2_fl.json"
},
{
"part_id": "example_arm",
"spec_path": "configs/parts/example_arm.json"
},
{
"part_id": "example_hand",
"spec_path": "configs/parts/example_hand.json"
},
{
"part_id": "example_gripper",
"spec_path": "configs/parts/example_gripper.json"
},
{
"part_id": "example_torso",
"spec_path": "configs/parts/example_torso.json"
},
{
"part_id": "example_head",
"spec_path": "configs/parts/example_head.json"
}
],
"requirements": {
"part_types": [
"leg",
"arm",
"hand",
"gripper",
"torso",
"head"
],
"joint_types": [
"revolute",
"prismatic"
],
"topologies": [
"tree"
],
"attachment_modes": [
"fixed",
"external",
"floating"
],
"supports_coupling": true,
"required_control_modes": [
"position_pd"
],
"required_sensor_kinds": [
"joint_state"
],
"required_sensor_outputs": [
"joint.position",
"joint.velocity"
],
"required_effector_roles": [],
"capacities": {
"Jmax": 32,
"Amax": 32,
"Emax": 8,
"Smax": 8
}
},
"interface": {
"contract_id": "part_position_control",
"contract_version": 1,
"quaternion_order": "xyzw",
"ports": [
{
"name": "joint_mask",
"direction": "input",
"kind": "mask",
"entity": "joint",
"selector": {
"type": "all",
"values": []
},
"required": true,
"dtype": "bool",
"shape": [
"B",
"Jmax"
],
"frame": "none",
"representation": "tensor",
"features": [],
"mask": null,
"command": null
},
{
"name": "joint_state",
"direction": "input",
"kind": "state",
"entity": "joint",
"selector": {
"type": "all",
"values": []
},
"required": true,
"dtype": "float32",
"shape": [
"B",
"Jmax",
2
],
"frame": "none",
"representation": "features",
"features": [
{
"name": "position",
"quantity": "joint.position",
"unit": "joint_position",
"normalization": "identity"
},
{
"name": "velocity",
"quantity": "joint.velocity",
"unit": "joint_velocity",
"normalization": "identity"
}
],
"mask": "joint_mask",
"command": null
},
{
"name": "actuator_mask",
"direction": "input",
"kind": "mask",
"entity": "actuator",
"selector": {
"type": "all",
"values": []
},
"required": true,
"dtype": "bool",
"shape": [
"B",
"Amax"
],
"frame": "none",
"representation": "tensor",
"features": [],
"mask": null,
"command": null
},
{
"name": "command",
"direction": "output",
"kind": "command",
"entity": "actuator",
"selector": {
"type": "all",
"values": []
},
"required": true,
"dtype": "float32",
"shape": [
"B",
"Amax",
1
],
"frame": "none",
"representation": "features",
"features": [
{
"name": "command",
"quantity": "actuator.command",
"unit": "1",
"normalization": "command_scale_offset"
}
],
"mask": "actuator_mask",
"command": {
"mode": "position_pd",
"encoding": "normalized",
"clip": [
-1,
1
]
}
},
{
"name": "effector_mask",
"direction": "input",
"kind": "mask",
"entity": "end_effector",
"selector": {
"type": "all",
"values": []
},
"required": false,
"dtype": "bool",
"shape": [
"B",
"Emax"
],
"frame": "none",
"representation": "tensor",
"features": [],
"mask": null,
"command": null
},
{
"name": "target_position",
"direction": "input",
"kind": "goal",
"entity": "end_effector",
"selector": {
"type": "all",
"values": []
},
"required": false,
"dtype": "float32",
"shape": [
"B",
"Emax",
3
],
"frame": "part_root",
"representation": "features",
"features": [
{
"name": "x",
"quantity": "goal.position.x",
"unit": "m",
"normalization": "identity"
},
{
"name": "y",
"quantity": "goal.position.y",
"unit": "m",
"normalization": "identity"
},
{
"name": "z",
"quantity": "goal.position.z",
"unit": "m",
"normalization": "identity"
}
],
"mask": "effector_mask",
"command": null
}
],
"reset": "indexed_isolated",
"action_history": "last_applied"
},
"runtime": {
"adapter_id": null,
"implementation": "unimplemented",
"dependencies": {},
"devices": [
"cpu",
"cuda"
],
"timing": {
"policy": "per_part",
"control_dt_s": null
}
},
"artifact": {
"format": "none",
"checkpoint": null,
"trained_skill": false,
"frozen": false
}
}
+127
View File
@@ -0,0 +1,127 @@
{
"schema_version": 2,
"kind": "part_software",
"software_id": "part_rgb_perception",
"software_version": "0.0.2",
"status": "design",
"binding_mode": "alternatives",
"hardware_bindings": [
{
"part_id": "example_head",
"spec_path": "configs/parts/example_head.json"
},
{
"part_id": "example_sensor",
"spec_path": "configs/parts/example_sensor.json"
}
],
"requirements": {
"part_types": [
"head",
"sensor"
],
"joint_types": [
"revolute"
],
"topologies": [
"tree"
],
"attachment_modes": [
"fixed",
"external",
"floating"
],
"supports_coupling": true,
"required_control_modes": [],
"required_sensor_kinds": [
"camera"
],
"required_sensor_outputs": [
"image.rgb8"
],
"required_effector_roles": [],
"capacities": {
"Jmax": 32,
"Amax": 2,
"Emax": 1,
"Smax": 8
}
},
"interface": {
"contract_id": "part_rgb_perception",
"contract_version": 1,
"quaternion_order": "xyzw",
"ports": [
{
"name": "camera_mask",
"direction": "input",
"kind": "mask",
"entity": "sensor",
"selector": {
"type": "sensor_output",
"values": [
"image.rgb8"
]
},
"required": true,
"dtype": "bool",
"shape": [
"B",
"Smax"
],
"frame": "none",
"representation": "tensor",
"features": [],
"mask": null,
"command": null
},
{
"name": "rgb_image",
"direction": "input",
"kind": "image",
"entity": "sensor",
"selector": {
"type": "sensor_output",
"values": [
"image.rgb8"
]
},
"required": true,
"dtype": "uint8",
"shape": [
"B",
"Smax",
480,
640,
3
],
"frame": "none",
"representation": "tensor",
"features": [],
"mask": "camera_mask",
"command": null
}
],
"reset": "not_applicable",
"action_history": "none"
},
"runtime": {
"adapter_id": null,
"implementation": "unimplemented",
"dependencies": {},
"devices": [
"cpu",
"cuda"
],
"timing": {
"policy": "per_part",
"control_dt_s": null
}
},
"artifact": {
"format": "none",
"checkpoint": null,
"trained_skill": false,
"frozen": false
}
}
@@ -0,0 +1,189 @@
{
"schema_version": 2,
"kind": "part_software",
"software_id": "wheel_velocity_control",
"software_version": "0.0.2",
"status": "design",
"binding_mode": "alternatives",
"hardware_bindings": [
{
"part_id": "example_mobile_base",
"spec_path": "configs/parts/example_mobile_base.json"
}
],
"requirements": {
"part_types": [
"mobile_base"
],
"joint_types": [
"continuous"
],
"topologies": [
"tree"
],
"attachment_modes": [
"fixed",
"external",
"floating"
],
"supports_coupling": true,
"required_control_modes": [
"velocity"
],
"required_sensor_kinds": [
"joint_state"
],
"required_sensor_outputs": [
"joint.position",
"joint.velocity"
],
"required_effector_roles": [],
"capacities": {
"Jmax": 32,
"Amax": 32,
"Emax": 8,
"Smax": 8
}
},
"interface": {
"contract_id": "wheel_velocity_control",
"contract_version": 1,
"quaternion_order": "xyzw",
"ports": [
{
"name": "joint_mask",
"direction": "input",
"kind": "mask",
"entity": "joint",
"selector": {
"type": "all",
"values": []
},
"required": true,
"dtype": "bool",
"shape": [
"B",
"Jmax"
],
"frame": "none",
"representation": "tensor",
"features": [],
"mask": null,
"command": null
},
{
"name": "joint_state",
"direction": "input",
"kind": "state",
"entity": "joint",
"selector": {
"type": "all",
"values": []
},
"required": true,
"dtype": "float32",
"shape": [
"B",
"Jmax",
2
],
"frame": "none",
"representation": "features",
"features": [
{
"name": "position",
"quantity": "joint.position",
"unit": "joint_position",
"normalization": "identity"
},
{
"name": "velocity",
"quantity": "joint.velocity",
"unit": "joint_velocity",
"normalization": "identity"
}
],
"mask": "joint_mask",
"command": null
},
{
"name": "actuator_mask",
"direction": "input",
"kind": "mask",
"entity": "actuator",
"selector": {
"type": "all",
"values": []
},
"required": true,
"dtype": "bool",
"shape": [
"B",
"Amax"
],
"frame": "none",
"representation": "tensor",
"features": [],
"mask": null,
"command": null
},
{
"name": "command",
"direction": "output",
"kind": "command",
"entity": "actuator",
"selector": {
"type": "all",
"values": []
},
"required": true,
"dtype": "float32",
"shape": [
"B",
"Amax",
1
],
"frame": "none",
"representation": "features",
"features": [
{
"name": "command",
"quantity": "actuator.command",
"unit": "1",
"normalization": "command_scale_offset"
}
],
"mask": "actuator_mask",
"command": {
"mode": "velocity",
"encoding": "normalized",
"clip": [
-1,
1
]
}
}
],
"reset": "indexed_isolated",
"action_history": "last_applied"
},
"runtime": {
"adapter_id": null,
"implementation": "unimplemented",
"dependencies": {},
"devices": [
"cpu",
"cuda"
],
"timing": {
"policy": "per_part",
"control_dt_s": null
}
},
"artifact": {
"format": "none",
"checkpoint": null,
"trained_skill": false,
"frozen": false
}
}
+3 -1
View File
@@ -1,4 +1,6 @@
# 单腿接口与验收
# 单腿运行与验收
软硬件描述规范的唯一入口为 [统一软硬件描述规范 v2](software_hardware_spec.md)。本文只记录当前单腿兼容运行链路的实现、验收证据与限制,不是独立规范,也不代表通用 v2 adapter 已实现。
## 1. 实现范围
+224
View File
@@ -0,0 +1,224 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "SkillFactory PartSpec v2 — body-part independent hardware contract",
"type": "object", "additionalProperties": false,
"required": ["schema_version", "kind", "part_id", "part_type", "description_role", "source", "topology", "frames", "root_frame", "attachment", "actuators", "end_effectors", "sensors", "timing", "safety", "scales"],
"properties": {
"schema_version": {"type": "integer", "const": 2},
"kind": {"const": "robot_part"},
"part_id": {"type": "string", "pattern": "^[a-z][a-z0-9_]*$"},
"part_type": {"enum": ["leg", "arm", "hand", "gripper", "torso", "neck", "head", "mobile_base", "sensor", "other"]},
"description_role": {"enum": ["asset_reference", "design_template"]},
"source": {
"type": "object", "additionalProperties": false,
"required": ["format", "root", "path", "package_name", "license_file", "license_id", "revision", "sha256"],
"properties": {
"format": {"enum": ["urdf", "usd", "mjcf", "design"]},
"root": {"type": ["string", "null"], "minLength": 1},
"path": {"type": ["string", "null"], "minLength": 1, "pattern": "^[^/]"},
"package_name": {"type": ["string", "null"], "minLength": 1},
"license_file": {"type": ["string", "null"], "minLength": 1},
"license_id": {"$ref": "#/$defs/text"},
"revision": {"type": ["string", "null"], "minLength": 1},
"sha256": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"}
}
},
"topology": {
"type": "object", "additionalProperties": false,
"required": ["structure", "root_body", "bodies", "joints", "constraints"],
"properties": {
"structure": {"enum": ["tree", "closed_chain"]},
"root_body": {"$ref": "#/$defs/local_id"},
"bodies": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/$defs/local_id"}},
"joints": {"type": "array", "items": {"$ref": "#/$defs/joint"}},
"constraints": {
"type": "array", "items": {
"type": "object", "additionalProperties": false,
"required": ["id", "type", "parent_frame", "child_frame"],
"properties": {
"id": {"$ref": "#/$defs/local_id"}, "type": {"const": "loop_closure"},
"parent_frame": {"$ref": "#/$defs/local_id"}, "child_frame": {"$ref": "#/$defs/local_id"}
}
}
}
}
},
"frames": {
"type": "array", "minItems": 1, "items": {
"type": "object", "additionalProperties": false,
"required": ["id", "body", "xyz", "quat_xyzw"],
"properties": {
"id": {"$ref": "#/$defs/local_id"}, "body": {"$ref": "#/$defs/local_id"},
"xyz": {"$ref": "#/$defs/vector3"}, "quat_xyzw": {"$ref": "#/$defs/quaternion"}
}
}
},
"root_frame": {"$ref": "#/$defs/local_id"},
"attachment": {
"type": "object", "additionalProperties": false,
"required": ["mode", "frame_id", "source_mount_joint", "auxiliary_root_joints"],
"properties": {
"mode": {"enum": ["fixed", "floating", "external"]},
"frame_id": {"$ref": "#/$defs/local_id"},
"source_mount_joint": {"type": ["string", "null"], "minLength": 1},
"auxiliary_root_joints": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/text"}},
"source_parent_transform": {
"type": "object", "additionalProperties": false, "required": ["body", "xyz", "quat_xyzw"],
"properties": {
"body": {"$ref": "#/$defs/text"}, "xyz": {"$ref": "#/$defs/vector3"},
"quat_xyzw": {"$ref": "#/$defs/quaternion"}
}
}
}
},
"actuators": {
"type": "array", "items": {
"type": "object", "additionalProperties": false,
"required": ["id", "joint_id", "neutral_position", "commands"],
"properties": {
"id": {"$ref": "#/$defs/local_id"}, "joint_id": {"$ref": "#/$defs/local_id"},
"neutral_position": {"type": "number"},
"commands": {
"type": "object", "minProperties": 1, "additionalProperties": false,
"properties": {
"position_pd": {"$ref": "#/$defs/command"}, "position": {"$ref": "#/$defs/command"},
"velocity": {"$ref": "#/$defs/command"}, "effort": {"$ref": "#/$defs/command"}
}
}
}
}
},
"end_effectors": {
"type": "array", "items": {
"type": "object", "additionalProperties": false,
"required": ["id", "role", "frame_id", "contact"],
"properties": {
"id": {"$ref": "#/$defs/local_id"},
"role": {"enum": ["support", "tool", "fingertip", "grasp", "gaze", "sensor_mount", "other"]},
"frame_id": {"$ref": "#/$defs/local_id"},
"contact": {
"oneOf": [
{"type": "null"},
{"type": "object", "additionalProperties": false,
"required": ["source_collision_index", "gap_method"],
"properties": {
"source_collision_index": {"type": "integer", "minimum": 0},
"gap_method": {"enum": ["sphere", "box", "mesh_distance", "none"]}
}
}
]
}
}
}
},
"sensors": {
"type": "array", "items": {
"type": "object", "additionalProperties": false,
"required": ["id", "kind", "outputs", "frame_id", "target", "update_period_s"],
"properties": {
"id": {"$ref": "#/$defs/local_id"},
"kind": {"enum": ["joint_state", "contact_normal", "wrench", "imu", "camera", "tactile", "lidar", "other"]},
"outputs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/$defs/text"}},
"frame_id": {"$ref": "#/$defs/local_id"},
"target": {
"type": "object", "additionalProperties": false, "required": ["entity", "ids"],
"properties": {
"entity": {"enum": ["part", "joint", "end_effector"]},
"ids": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/$defs/local_id"}}
}
},
"update_period_s": {"type": "number", "exclusiveMinimum": 0}
}
}
},
"timing": {
"type": "object", "additionalProperties": false, "required": ["physics_dt_s", "control_dt_s"],
"properties": {
"physics_dt_s": {"type": ["number", "null"], "exclusiveMinimum": 0},
"control_dt_s": {"type": "number", "exclusiveMinimum": 0}
}
},
"safety": {
"type": "object", "additionalProperties": false,
"required": ["soft_limit_factor", "on_invalid_command", "on_timeout", "command_timeout_s"],
"properties": {
"soft_limit_factor": {"type": "number", "exclusiveMinimum": 0, "maximum": 1},
"on_invalid_command": {"const": "reject"},
"on_timeout": {"enum": ["hold", "zero_effort", "disable"]},
"command_timeout_s": {"type": "number", "exclusiveMinimum": 0}
}
},
"scales": {
"type": "object", "additionalProperties": false, "required": ["length_m", "known_mass_kg"],
"properties": {
"length_m": {"type": ["number", "null"], "exclusiveMinimum": 0},
"known_mass_kg": {"type": ["number", "null"], "exclusiveMinimum": 0}
}
},
"extensions": {"type": "object", "patternProperties": {"^[a-z][a-z0-9_]*\\.[a-z0-9_.]+$": {}}, "additionalProperties": false}
},
"allOf": [
{
"if": {"properties": {"description_role": {"const": "design_template"}}},
"then": {"properties": {"source": {"properties": {"format": {"const": "design"}, "root": {"type": "null"}, "path": {"type": "null"}, "package_name": {"type": "null"}, "license_file": {"type": "null"}, "revision": {"type": "null"}, "sha256": {"type": "null"}}}}},
"else": {"properties": {"source": {"properties": {"format": {"enum": ["urdf", "usd", "mjcf"]}, "root": {"type": "string"}, "path": {"type": "string"}, "license_file": {"type": "string"}}}}}
}
],
"$defs": {
"text": {"type": "string", "minLength": 1, "pattern": "\\S"},
"local_id": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"},
"vector3": {"type": "array", "minItems": 3, "maxItems": 3, "items": {"type": "number"}},
"quaternion": {"type": "array", "minItems": 4, "maxItems": 4, "items": {"type": "number"}},
"command": {
"type": "object", "additionalProperties": false, "required": ["unit", "scale", "offset", "gains"],
"properties": {
"unit": {"enum": ["rad", "m", "rad/s", "m/s", "N*m", "N"]},
"scale": {"type": "number", "exclusiveMinimum": 0}, "offset": {"type": "number"},
"gains": {
"oneOf": [
{"type": "null"},
{"type": "object", "additionalProperties": false, "required": ["kp", "kd"],
"properties": {"kp": {"type": "number", "exclusiveMinimum": 0}, "kd": {"type": "number", "minimum": 0}}
}
]
}
}
},
"joint": {
"type": "object", "additionalProperties": false,
"required": ["id", "source_name", "type", "parent", "child", "origin", "actuation", "position_unit", "axis", "limits_origin", "limits", "coupling"],
"properties": {
"id": {"$ref": "#/$defs/local_id"}, "source_name": {"$ref": "#/$defs/text"},
"type": {"enum": ["fixed", "revolute", "continuous", "prismatic"]},
"parent": {"$ref": "#/$defs/local_id"}, "child": {"$ref": "#/$defs/local_id"},
"origin": {
"type": "object", "additionalProperties": false, "required": ["xyz", "quat_xyzw"],
"properties": {"xyz": {"$ref": "#/$defs/vector3"}, "quat_xyzw": {"$ref": "#/$defs/quaternion"}}
},
"actuation": {"enum": ["fixed", "active", "passive", "coupled"]},
"position_unit": {"enum": ["rad", "m", null]},
"axis": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/vector3"}]},
"limits_origin": {"enum": ["source", "declared"]},
"limits": {
"oneOf": [
{"type": "null"},
{"type": "object", "additionalProperties": false, "required": ["position", "velocity", "effort"],
"properties": {
"position": {"oneOf": [{"type": "null"}, {"type": "array", "minItems": 2, "maxItems": 2, "items": {"type": "number"}}]},
"velocity": {"type": "number", "exclusiveMinimum": 0}, "effort": {"type": "number", "exclusiveMinimum": 0}
}
}
]
},
"coupling": {
"oneOf": [
{"type": "null"},
{"type": "object", "additionalProperties": false, "required": ["joint_id", "multiplier", "offset"],
"properties": {"joint_id": {"$ref": "#/$defs/local_id"}, "multiplier": {"type": "number"}, "offset": {"type": "number"}}
}
]
}
}
}
}
}
+141
View File
@@ -0,0 +1,141 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "SkillFactory SoftwareSpec v2 — capability-negotiated body-part ports",
"type": "object", "additionalProperties": false,
"required": ["schema_version", "kind", "software_id", "software_version", "status", "binding_mode", "hardware_bindings", "requirements", "interface", "runtime", "artifact"],
"properties": {
"schema_version": {"type": "integer", "const": 2},
"kind": {"const": "part_software"},
"software_id": {"type": "string", "pattern": "^[a-z][a-z0-9_]*$"},
"software_version": {"type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"},
"status": {"enum": ["design", "prototype"]},
"binding_mode": {"const": "alternatives"},
"hardware_bindings": {
"type": "array", "minItems": 1, "uniqueItems": true, "items": {
"type": "object", "additionalProperties": false, "required": ["part_id", "spec_path"],
"properties": {
"part_id": {"type": "string", "pattern": "^[a-z][a-z0-9_]*$"},
"spec_path": {"$ref": "#/$defs/repo_path"}
}
}
},
"requirements": {
"type": "object", "additionalProperties": false,
"required": ["part_types", "joint_types", "topologies", "attachment_modes", "supports_coupling", "required_control_modes", "required_sensor_kinds", "required_sensor_outputs", "required_effector_roles", "capacities"],
"properties": {
"part_types": {"$ref": "#/$defs/names"},
"joint_types": {"type": "array", "uniqueItems": true, "items": {"enum": ["revolute", "continuous", "prismatic"]}},
"topologies": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"enum": ["tree", "closed_chain"]}},
"attachment_modes": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"enum": ["fixed", "floating", "external"]}},
"supports_coupling": {"type": "boolean"},
"required_control_modes": {"type": "array", "uniqueItems": true, "items": {"enum": ["position_pd", "position", "velocity", "effort"]}},
"required_sensor_kinds": {"$ref": "#/$defs/names"},
"required_sensor_outputs": {"$ref": "#/$defs/names"},
"required_effector_roles": {"$ref": "#/$defs/names"},
"capacities": {
"type": "object", "additionalProperties": false, "required": ["Jmax", "Amax", "Emax", "Smax"],
"properties": {
"Jmax": {"type": "integer", "minimum": 0}, "Amax": {"type": "integer", "minimum": 0},
"Emax": {"type": "integer", "minimum": 0}, "Smax": {"type": "integer", "minimum": 0}
}
}
}
},
"interface": {
"type": "object", "additionalProperties": false,
"required": ["contract_id", "contract_version", "quaternion_order", "ports", "reset", "action_history"],
"properties": {
"contract_id": {"$ref": "#/$defs/id"},
"contract_version": {"type": "integer", "minimum": 1},
"quaternion_order": {"const": "xyzw"},
"ports": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/port"}},
"reset": {"enum": ["indexed_isolated", "not_applicable"]},
"action_history": {"enum": ["last_applied", "none"]}
}
},
"runtime": {
"type": "object", "additionalProperties": false,
"required": ["adapter_id", "implementation", "dependencies", "devices", "timing"],
"properties": {
"adapter_id": {"type": ["string", "null"], "minLength": 1},
"implementation": {"enum": ["available", "unimplemented"]},
"dependencies": {"type": "object", "additionalProperties": {"type": "string", "minLength": 1}},
"devices": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"enum": ["cpu", "cuda"]}},
"timing": {
"type": "object", "additionalProperties": false, "required": ["policy", "control_dt_s"],
"properties": {
"policy": {"enum": ["common_control_dt", "per_part"]},
"control_dt_s": {"type": ["number", "null"], "exclusiveMinimum": 0}
}
}
}
},
"artifact": {
"type": "object", "additionalProperties": false,
"required": ["format", "checkpoint", "trained_skill", "frozen"],
"properties": {
"format": {"type": "string", "minLength": 1},
"checkpoint": {
"oneOf": [
{"type": "null"},
{"type": "object", "additionalProperties": false, "required": ["path", "sha256"],
"properties": {"path": {"$ref": "#/$defs/repo_path"}, "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}}
}
]
},
"trained_skill": {"const": false}, "frozen": {"const": false}
}
},
"extensions": {"type": "object", "patternProperties": {"^[a-z][a-z0-9_]*\\.[a-z0-9_.]+$": {}}, "additionalProperties": false}
},
"$defs": {
"id": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"},
"text": {"type": "string", "minLength": 1, "pattern": "\\S"},
"names": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/text"}},
"repo_path": {"type": "string", "pattern": "^(?:[A-Za-z0-9_-]+/)*[A-Za-z0-9_.-]+$"},
"selector": {
"type": "object", "additionalProperties": false, "required": ["type", "values"],
"properties": {"type": {"enum": ["all", "ids", "role", "sensor_kind", "sensor_output"]}, "values": {"$ref": "#/$defs/names"}}
},
"feature": {
"type": "object", "additionalProperties": false, "required": ["name", "quantity", "unit", "normalization"],
"properties": {
"name": {"$ref": "#/$defs/id"}, "quantity": {"$ref": "#/$defs/text"},
"unit": {"enum": ["1", "m", "s", "kg", "rad", "m/s", "rad/s", "m/s^2", "rad/s^2", "N", "N*m", "kg*m^2", "N*m/rad", "N*m*s/rad", "N/m", "N*s/m", "joint_position", "joint_velocity", "joint_effort", "actuator_command"]},
"normalization": {"$ref": "#/$defs/text"}
}
},
"port": {
"type": "object", "additionalProperties": false,
"required": ["name", "direction", "kind", "entity", "selector", "required", "dtype", "shape", "frame", "representation", "features", "mask", "command"],
"properties": {
"name": {"$ref": "#/$defs/id"}, "direction": {"enum": ["input", "output"]},
"kind": {"enum": ["description", "state", "mask", "goal", "command", "context", "image"]},
"entity": {"enum": ["part", "joint", "actuator", "end_effector", "sensor"]},
"selector": {"$ref": "#/$defs/selector"}, "required": {"type": "boolean"},
"dtype": {"enum": ["float32", "bool", "uint8", "int64"]},
"shape": {
"type": "array", "minItems": 1, "items": {
"oneOf": [{"type": "integer", "minimum": 1}, {"enum": ["B", "Jmax", "Amax", "Emax", "Smax"]}]
}
},
"frame": {"enum": ["part_root", "world", "entity", "none"]},
"representation": {"enum": ["features", "tensor"]},
"features": {"type": "array", "items": {"$ref": "#/$defs/feature"}},
"mask": {"type": ["string", "null"], "pattern": "^[A-Za-z][A-Za-z0-9_]*$"},
"command": {
"oneOf": [
{"type": "null"},
{"type": "object", "additionalProperties": false, "required": ["mode", "encoding", "clip"],
"properties": {
"mode": {"enum": ["position_pd", "position", "velocity", "effort"]},
"encoding": {"enum": ["normalized", "physical"]},
"clip": {"oneOf": [{"type": "null"}, {"type": "array", "minItems": 2, "maxItems": 2, "items": {"type": "number"}}]}
}
}
]
}
}
}
}
}
+219
View File
@@ -0,0 +1,219 @@
# SkillFactory 统一软硬件描述规范 v2
## 1. 设计目标与实现边界
以**部件的结构、能力和语义端口**为契约,不以“腿”“三个关节”“单个足端”作为统一接口的前提。同一格式可描述腿、机械臂、手、夹爪、躯干、颈部、头部、移动底座、纯传感器模块和其他部件;软件通过能力匹配选择可用部件。
**已落地:** PartSpec v2 / SoftwareSpec v2、JSON Schema、跨文件语义校验、不同部位的设计示例、现有 Go2 单腿描述迁移与回归测试。仓库只保留本规范及两份 v2 Schema,不再并列维护旧版规范。
**尚未落地:** v2 通用仿真/训练 adapter、描述驱动 launcher、实机驱动、冻结 SkillBundle、跨部件协调训练。设计模板不是厂家资产;静态契约匹配不证明机械结构可制造、物理模型准确或策略已训练。当前可运行的仍是 [既有单腿任务](leg_interface.md);该文档仅记录实现和运行验收,不是另一份软硬件描述规范。
## 2. 分层模型
```text
PartSpec v2(部件结构、frame、执行器、末端、传感器、时间、安全)
↓ 能力协商、引用和顺序校验
SoftwareSpec v2(要求、容量、语义端口、控制模式、adapter、产物)
↓ adapter 必须显式实现,未实现时拒绝执行
具体后端:Isaac / 其他仿真 / 实机驱动
↓ 各自提供证据
运行验收 → 训练/泛化验收 → 冻结与部署验收
```
| 层 | 决定的内容 | 不应决定的内容 |
| --- | --- | --- |
| 通用核心 | ID、类型、拓扑、实体引用、单位、frame、数量、语义、安全与版本 | 某厂家命名、固定 DoF、固定足端数量、特定网络维数 |
| 软件 profile | 输入/输出端口、任务目标、支持的能力、特征顺序、归一化、容量 | 擅自修改硬件限位、把缺失传感器当成存在 |
| 后端 adapter | 资产加载、索引映射、张量/设备、坐标转换、控制器和 reset 实现 | 静默支持未验证拓扑、猜测单位、假装已部署 |
`part_type` 是分类元数据;真正的适配依据是能力。机械臂与腿可以共用 position profile,手可有更多运动关节但更少独立执行器,传感器模块可以没有关节、执行器和末端。**允许零 DoF、零末端、多末端和多传感器。**
## 3. 文件、命名与版本规则
- UTF-8 JSON;拒绝重复 key、未知核心字段、非有限数值和不支持的版本。整数字段必须使用整数写法,不接受 `2.0` 或 bool。
- 全局 `part_id/software_id` 使用小写 `[a-z][a-z0-9_]*`;局部实体 ID 允许大小写 `[A-Za-z][A-Za-z0-9_]*`,兼容真实 URDF 命名。各实体集合内部 ID 必须唯一。
- 元数据物理量使用 SI:m、kg、s、rad、N、N·m;四元数 **xyzw**、右手坐标。角度不得混入 degree;直线关节不得按 rad 解释。
- `source.root` 可为机器路径并允许 `~`,相对值按工作目录解释;`source.path` 相对该 root,解析后不可逃逸或越界 symlink。来源许可可显式引用上级仓库文件。
- 软件 `spec_path/checkpoint.path` 相对仓库根目录,不允许逃逸或越界 symlink。
- `extensions` 只接受 namespaced key,如 `skillfactory.example`。这是注释/来源扩展区,不能藏入未经协商的控制、安全或物理能力;必须影响执行的扩展需制定 profile 和相应校验器。
- PartSpec v2、SoftwareSpec v2、旧 LegSpec v1、旧 asset manifest v2、旧 token `FEATURE_SCHEMA` v1 分属不同版本域。**同为数字 2 不代表是同一种对象。** `kind` 必须匹配。
- 同版本拒绝未知字段。核心含义改变需升级 schema;端口顺序/单位/归一化改变需升级 `interface.contract_version`,不能只改 shape 或软件实现版本后继续加载旧权重。
## 4. 硬件描述:PartSpec v2
机器格式:[`schemas/part_spec.v2.schema.json`](schemas/part_spec.v2.schema.json)。
### 4.1 字段分组
| 字段 | 内容与约束 |
| --- | --- |
| `schema_version/kind` | 固定 `2/robot_part` |
| `part_id/part_type` | 标识与部位分类;类型含 leg、arm、hand、gripper、torso、neck、head、mobile_base、sensor、other |
| `description_role` | `asset_reference` 为真实来源引用;`design_template` 为未绑定厂家模型的设计模板 |
| `source` | format/root/path/package、许可、revision 与可选 SHA256;来源格式可为 URDF/USD/MJCF;模板必须 format=design、路径/hash/revision 为 null |
| `topology` | root body、完整 body 列表、joint 列表、tree/closed_chain 与显式闭链约束 |
| `frames/root_frame` | body 局部 frame、xyz[m] 与单位四元数;root_frame 必须属于 root body |
| `attachment` | fixed/floating/external、安装 frame、可选源安装关节与辅助支链;可选源 parent → root 零位变换 |
| `actuators` | 独立执行器声明顺序、受驱动关节、neutral position、支持的 command 模式及尺度/offset/PD gains |
| `end_effectors` | 任意数量、frame、语义 role 与可选接触/gap 方法;不再使用单个 `foot_body` |
| `sensors` | 任意数量、kind、明确 outputs 语义、frame、目标实体/IDs、更新周期;不是按部位猜测传感器 |
| `timing` | control_dt_s 必填;physics_dt_s 可为 null;有仿真步长时控制步长必须为其正整数倍 |
| `safety` | 软限位比例、非法命令 reject、超时 hold/zero_effort/disable 与超时阈值;阈值不短于一个控制步 |
| `scales` | 可选长度/已知质量尺度;未知为 null,不得冒充真实测量或厂家值 |
### 4.2 拓扑、自由度与耦合
每个 joint 描述 `id/source_name/type/parent/child/origin/actuation/position_unit/axis/limits_origin/limits/coupling`。
- joint `origin` 是父 body 到零位 joint/child frame 的变换;轴在 joint 局部 frame 表达。revolute/continuous 为 rad、prismatic 为 m;fixed 的单位/轴/限位为 null。
- 当前核心采用**标量 joint + floating root**表示:球关节等多 DoF 需先拆解为显式坐标或新增专用 profile,不得伪装为一个标量 revolute。
- `actuation` 区分 active、passive、coupled、fixed。J 是所有非 fixed 运动关节数;A 是独立执行器数。**J≠A 合法,动作按 A 而非 J 排列。**
- 每个 active joint 恰好一个独立 actuator;passive/coupled/fixed joint 不得被直接驱动。`actuators` 数组顺序是输出通道顺序,`topology.joints` 中非 fixed 的声明顺序是状态通道顺序;不得按名称重排。
- 耦合显式声明 `q_child = multiplier × q_reference + offset`,引用同单位的非 fixed joint,依赖图无环。mimic/欠驱动能力可被规范描述,但当前单腿 importer 不支持。
- joints 始终形成覆盖所有 body 的无环 spanning tree。闭链用独立 `loop_closure` frame 约束表示;不得把循环塞进树。约束可描述不等于当前后端会求解它。
- 有源模型时,几何、质量、惯性、碰撞体和真实限位以来源资产为准;`limits_origin=source` 表示导入时核对/读取来源,允许未解析限位为 null。`declared` 的运动关节必须有完整限位,且这些模板值不是厂家数据。
- bounded 关节的 position 范围必须 lower<upper;continuous position=null;限速/限 effort 为正。已有完整惯性须由 importer 检验正定,缺失惯性必须保持未知标志,不得估算后称为厂家数据。
### 4.3 安装、末端和传感器
- `attachment.mode=fixed` 表示根与挂载参考固定,**不表示冻结内部关节**;floating 表示根可动,external 表示位姿由外部系统提供。源切口可以是固定关节,不再要求 mount 一定是受控关节。
- frame 的 pose 都相对所属 body。源 parent 零位变换可引用部件外 body;它不是当前世界 pose,也不是已完成的跨部件装配约束。
- 末端 role 可为 support/tool/fingertip/grasp/gaze/sensor_mount/other;腿可多接触点,手可多指尖,躯干可无末端。contact 为 null 时不宣称能算 gap;mesh_distance 必须由相应 adapter 提供,不能用 sphere 近似偷偷替代。
- 传感器输出须明确,如 `joint.position`、`joint.velocity`、`contact.normal_force`、`contact.wrench`、`image.rgb8`。**camera 不自动等于 RGB,相应 outputs 必须存在;normal_force 不自动等于 wrench。**
- 关节传感器的 target 必须列出覆盖的 joints。软件请求的 joint/contact state 要求目标实体被真实声明的传感输出覆盖,不能用另一个部位的传感器凑数。
- 源路径/hash 是来源记录;静态预检不读取原源模型或校验其内容 hash。资产构建/加载仍须单独验证来源、资源、许可、映射、物理参数和派生 hash。
## 5. 软件描述:SoftwareSpec v2
机器格式:[`schemas/software_spec.v2.schema.json`](schemas/software_spec.v2.schema.json)。
### 5.1 身份、绑定和能力要求
`kind=part_software`,身份用 `software_id/software_version`;当前交付阶段为 design/prototype,`trained_skill=false/frozen=false`。本版本不提供已训练/冻结发布流程,未来需要单独制定证据门槛。
`hardware_bindings` 是可替换候选列表,`binding_mode=alternatives`:每个部件**独立满足**同一 profile,不能把候选 A 的传感器与候选 B 的执行器合并满足要求。不是同时装配,也不代表已经学会跨部件迁移。
`requirements` 必须声明:
- 支持的部位、运动 joint 类型、拓扑、挂载模式和耦合能力;
- 必需的执行模式、sensor kinds/outputs、effector roles;
- 每个部件的容量 `Jmax/Amax/Emax/Smax`(允许 0)。容量覆盖硬件全部相应实体,不只是某个 selector 子集;实际数量超过容量直接拒绝。
不要求所有部位共用一个神经网络或一个固定 D。统一的是描述格式和语义匹配,任务特征布局由 profile 决定。
### 5.2 语义端口与形状
每个 port 必须描述 name、direction、kind、entity、selector、required、dtype、shape、frame、representation、features、mask、command。
| 维度 | 语义 | 示例 |
| --- | --- | --- |
| B | 批量实例数 | 所有端口的第一维 |
| Jmax | 非 fixed 运动关节槽 | joint_state `[B,Jmax,2]` |
| Amax | 独立执行器槽 | command `[B,Amax,1]` |
| Emax | 末端槽 | position goal `[B,Emax,3]`、pose goal 可定义 7 个特征 |
| Smax | 传感器槽 | RGB `[B,Smax,480,640,3]` |
| D / 固定 tensor 轴 | profile 的明确整数维度 | features 数目必须与最后一维精确一致 |
- entity 分 part/joint/actuator/end_effector/sensor。实体端口必须使用对应容量轴,不得把手的 Jmax 当成动作 Amax。part 级 context 为 `[B,D]`,不强制实体轴。
- selector 支持 all/ids/role/sensor_kind/sensor_output。按硬件数组顺序过滤,**不按 selector.values 重排**;不同候选可通过 role 或 all 适配不同名字。
- features 是有序 `{name, quantity, unit, normalization}`;必须声明每个特征的物理语义与归一化。tensor 表示 RGB 等非逐标量数据,features 必须为空;具体布局/编码由命名的 contract 定义。
- `joint_position/joint_velocity` 表示按槽 joint type 决定 rad/m、rad/s/m/s;`actuator_command` 表示按 actuator mode 决定单位。软件必须消费对应硬件类型/单位元数据,不能将混合关节槽都按 rad 计算。
- normalization 是契约中的明确规则名。示例 identity 为不归一化;command_scale_offset 按 actuator scale/offset 映射。自定义规则必须由对应 adapter 解释;未知规则在执行前拒绝,不得只接受字符串就声称能推理。
- 每个实体数据端口必须引用同 entity/selector 的 bool `[B,capacity]` 输入 mask。padding 不驱动、不参与损失/概率/路由,adapter 必须屏蔽无效槽中的非有限垃圾值;有效槽非有限值必须拒绝。
- `required=false` 允许 selector 选不到实体,adapter 必须返回无效 mask;不是允许把需要的力/图像伪造为零。0 容量实体不得声明端口;纯传感模块可以完全没有 joint/command/effector ports。
- 同 shape 不代表兼容:完整特征顺序、quantity、unit、normalization、frame、selector、控制模式和 contract version 都必须匹配;checkpoint 加载还需完整接口/硬件绑定指纹,不可只比维数。
### 5.3 统一坐标与动态协议
port.frame 可为 part_root/world/entity/none。位置目标不默认是足端,不默认在 world;姿态使用 xyzw;必要的空间速度和 wrench profile 应明确:
- twist 顺序 `[vx,vy,vz,wx,wy,wz]`,分别 m/s、rad/s;
- wrench 顺序 `[Fx,Fy,Fz,Tx,Ty,Tz]`,分别 N、N·m,必须注明参考 frame/作用原点;
- contact.normal_force 是法向接触力,不能当作含切向摩擦的完整 wrench;控制器 applied/commanded effort 不等于实测电机 effort。
移动根的相对线速度必须包含根角速度产生的 `ω×r` 项;wrench 换原点必须包含力矩平移项。旧固定支座的直接坐标差分公式不能无条件搬到浮动躯干、头部或底座。
未来 adapter 的每个批次应携带 `part_id/instance_ids/control_index/timestamp/description_revision`,以区别部件、实例、时刻与描述修订;旧 v1 张量接口未增加这一 envelope。对跨时刻传感器数据,adapter 必须标记有效性/时间差,不能把旧帧当当前状态。
reset 按 profile 声明 indexed_isolated 或 not_applicable;仿真 indexed reset 必须隔离未选实例、清动作历史,空集合 no-op;真实硬件不得把仿真 reset 当成可直接发送的动作。action_history=last_applied 是最后已执行动作,不是最后拟议动作;timeout bootstrap 规则仍由训练 adapter 区分 timeout 与真 termination。
### 5.4 控制、安全、周期和可执行性
- command 仅允许 actuator output;每个独立 actuator 一个命令来源,重叠命令直接拒绝。
- 模式为 position_pd/position/velocity/effort,必须是目标 actuator 已声明的模式。prismatic 的 effort 为 N,rotary 为 N·m;只有 position_pd 要求显式 PD gains。
- normalized command 使用 dimensionless `[-1,1]` 执行裁剪,再计算 `target = offset + scale × clipped_command`;position 要再次按软限位裁剪,velocity/effort 受硬限速/限 effort。PPO 仍保留未裁剪采样值的 log-prob。
- physical command 不做隐式尺度映射,明确单位/可选 clip,但仍必须执行硬件安全约束。未解析安全限位、未实现 watchdog、缺失有效传感器、未知转换或控制模式都必须拒绝执行。
- 安全策略是**要求**,不是已实现证明。hold/zero_effort/disable 都不是所有机构的天然安全状态,需要具体部位/实机验收;不能用模板值宣称满足实机安全。
- runtime.timing 支持 common_control_dt 或 per_part;前者对每个候选核对控制周期,后者由实际选中的部件决定。无需让头部相机和腿共享物理步长;跨部件异步协调不由 alternatives 绑定自动提供。
- runtime.devices/dependencies 是所需/拟支持的环境,不是当前机器探测结果;参考机器配置和已验证运行版本仍另行记录,不编造 GPU/显存最低要求。
- runtime.implementation=available 必须有注册且验收过的 adapter。**当前未注册任何 v2 adapter,校验器拒绝假称 available;`--require-runtime` 也会拒绝仅通过静态协商的 v2 profile。**
- 当前 artifact.checkpoint 可为 null 或带 path/hash 的引用。校验只验证文件 hash,不反序列化、不证明权重兼容或收敛;trained/frozen 发布另设里程碑。
## 6. 多部位示例与运行兼容边界
| 示例 | J / A / E | 关键差异 |
| --- | --- | --- |
| [`configs/parts/go2_fl.json`](../configs/parts/go2_fl.json) | 3 / 3 / 1 | 从已有真实 Go2 bundle 迁移,保留 fixed 辅助支链和来源 hash |
| [`example_arm.json`](../configs/parts/example_arm.json) | 6 / 6 / 1 | 六轴臂,tool role,无默认地面接触传感器 |
| [`example_hand.json`](../configs/parts/example_hand.json) | 4 / 2 / 2 | 分支双指、显式耦合、多个 fingertip,动作数少于关节数 |
| [`example_gripper.json`](../configs/parts/example_gripper.json) | 2 / 1 / 2 | prismatic、m/N、两钳口耦合 |
| [`example_torso.json`](../configs/parts/example_torso.json) | 2 / 2 / 0 | 不要求末端 |
| [`example_head.json`](../configs/parts/example_head.json) | 2 / 2 / 1 | gaze + camera/IMU,同一硬件可绑定运动或感知 profile |
| [`example_mobile_base.json`](../configs/parts/example_mobile_base.json) | 4 / 4 / 0 | continuous 轮关节、velocity、floating root |
| [`example_sensor.json`](../configs/parts/example_sensor.json) | 0 / 0 / 0 | external 安装、纯 camera/IMU 模块 |
除 Go2 外,`example_*` 都是明确的 **synthetic design_template**,不引用厂家名称、不伪造实测参数、不提供可运行策略。
软件示例:
- [`part_position_control.json`](../configs/software/part_position_control.json):同一可配置关节/执行器端口 contract 绑定腿、臂、手、夹爪、躯干、头部;含可选多末端位置目标。
- [`wheel_velocity_control.json`](../configs/software/wheel_velocity_control.json):轮式底座独立 velocity profile;不是把腿 position 动作改名。
- [`part_rgb_perception.json`](../configs/software/part_rgb_perception.json):头部/纯传感器共用按 `image.rgb8` 输出能力选择的感知端口,无 command port。
v2 的新端口不冒充旧 `[B,Jmax,25]` / `[B,1,16]` token,不自动加载旧模型。`configs/legs/`、`legs/spec.py` 和现有任务/训练 CLI 保留为兼容运行输入与实现,不再附带独立 v1 规范或软件描述。通用校验器只接受 PartSpec/SoftwareSpec v2;旧数据先显式迁移,不静默跨版本。旧专用 Go2 manifest v1 也不被当成通用 PartSpec。
## 7. 校验与迁移
### 7.1 静态校验
```bash
# 已安装 jsonschema 的 Python 3.12 即可,无需 Kit/Torch
python3 scripts/validate_descriptions.py \
--hardware configs/parts/*.json \
--software configs/software/part_position_control.json \
configs/software/wheel_velocity_control.json \
configs/software/part_rgb_perception.json
# 当前应失败,明确指出 v2 adapter 未实现;不可用静态通过冒充可运行
python3 scripts/validate_descriptions.py \
--software configs/software/part_position_control.json --require-runtime
```
预检覆盖:schema、唯一 ID、拓扑连通/无环、frame 与目标引用、单位/轴/四元数、耦合关系、独立驱动覆盖、末端/传感器引用、时间关系、逐候选能力协商、容量、特征布局、mask/selector、传感覆盖、命令冲突与可选 checkpoint hash。
**不覆盖:**来源模型内容/许可存在、实际物理参数、碰撞可用性、动态稳定性、传感器分辨率/校准/延迟实测、设备驱动、adapter 坐标/控制行为、制造与安全证明、训练和泛化。语义字符串的执行规则必须由实现后的 adapter 检查。
### 7.2 从现有单腿迁移
```bash
export PYTHONPATH="$PWD/source/SkillFactory${PYTHONPATH:+:$PYTHONPATH}"
LAB=/home/cen/IsaacLab/isaaclab.sh
# 先按 README 提取旧 bundle;然后输出到一个尚不存在的新文件
"$LAB" -p scripts/migrate_leg_description.py \
--bundle assets/generated/legs/go2_fl --output /tmp/go2_fl.part.v2.json
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 "$LAB" -p -m pytest tests -q
"$LAB" -p -m ruff check source/SkillFactory scripts tests
```
迁移校验旧 bundle 的资源/派生 hash,保留 actuator 声明顺序、完整 fixed 支链、安装变换、碰撞索引、控制参数和来源记录;**不重新认证源厂家模型,也不新增通用后端**。迁移生成的 watchdog 策略是 v2 要求,不是旧 runtime 已实现能力。
设计示例由 [`scripts/examples/generate_part_descriptions.py`](../scripts/examples/generate_part_descriptions.py) 确定性生成,可输出到新目录复核;默认拒绝覆盖现有文件。校验/回归实现分别见 [`scripts/validate_descriptions.py`](../scripts/validate_descriptions.py)、[`tests/test_part_contracts.py`](../tests/test_part_contracts.py)。
## 8. 后续扩展规则
增加新部位通常只需新增 PartSpec、选择已有能力/profile,不得复制一个新的“arm-only/hand-only”核心 schema。新任务增加命名端口 contract;真正的新物理类别(柔性结构、多 DoF 未拆解 joint、复杂传动)或新安全/控制语义需显式扩展 profile/核心版本。
装配设计可利用各部件安装 frame 与源 parent 变换,但当前尚未实现 AssemblySpec、跨部件资源冲突、共享传感、控制权仲裁和协调软件。整机组合需显式规定装配图、命名空间、clock 同步和命令所有权,不能把 alternatives 列表当成已经装配完成。
落地顺序:通用部件 importer/实体 adapter → 精确端口/坐标/安全实现与仿真验收 → 跨 DoF/多末端训练及留出评估 → 装配与跨部件协调 → 单独制定冻结产物和实机部署验收。
@@ -0,0 +1,311 @@
#!/usr/bin/env python3
"""Generate explicitly synthetic multi-part design examples, not manufacturer assets or runnable policies."""
from __future__ import annotations
import argparse
import copy
import json
from pathlib import Path
def joint(name, parent, child, joint_type="revolute", coupling=None):
linear = joint_type == "prismatic"
return {
"id": name,
"source_name": name,
"type": joint_type,
"parent": parent,
"child": child,
"origin": {"xyz": [0, 0, 0.1], "quat_xyzw": [0, 0, 0, 1]},
"actuation": "coupled" if coupling else "active",
"position_unit": "m" if linear else "rad",
"axis": [1, 0, 0] if linear else [0, 1, 0],
"limits_origin": "declared",
"limits": {
"position": None if joint_type == "continuous" else ([0, 0.04] if linear else [-1.5, 1.5]),
"velocity": 1 if linear else 10,
"effort": 10,
},
"coupling": coupling,
}
def part(part_type, count, mode="position_pd", joint_type="revolute"):
part_id = f"example_{part_type}"
joints = [joint(f"joint_{i}", "base" if i == 0 else f"link_{i - 1}", f"link_{i}", joint_type) for i in range(count)]
actuators = []
for item in joints:
linear = joint_type == "prismatic"
neutral = 0.02 if linear else 0.0
unit = ("m" if linear else "rad") if mode == "position_pd" else "rad/s"
actuators.append(
{
"id": "drive_" + item["id"],
"joint_id": item["id"],
"neutral_position": neutral,
"commands": {
mode: {
"unit": unit,
"scale": 0.01 if linear else 0.25,
"offset": neutral if mode == "position_pd" else 0,
"gains": {"kp": 25, "kd": 0.5} if mode == "position_pd" else None,
}
},
}
)
root = {"id": "root", "body": "base", "xyz": [0, 0, 0], "quat_xyzw": [0, 0, 0, 1]}
sensors = []
if joints:
sensors.append(
{
"id": "joint_state",
"kind": "joint_state",
"outputs": ["joint.position", "joint.velocity"],
"frame_id": "root",
"target": {"entity": "joint", "ids": [item["id"] for item in joints]},
"update_period_s": 0.002,
}
)
return {
"schema_version": 2,
"kind": "robot_part",
"part_id": part_id,
"part_type": part_type,
"description_role": "design_template",
"source": {
"format": "design",
"root": None,
"path": None,
"package_name": None,
"license_file": None,
"license_id": "LicenseRef-Design-Template",
"revision": None,
"sha256": None,
},
"topology": {
"structure": "tree",
"root_body": "base",
"bodies": ["base", *[item["child"] for item in joints]],
"joints": joints,
"constraints": [],
},
"frames": [root],
"root_frame": "root",
"attachment": {"mode": "fixed", "frame_id": "root", "source_mount_joint": None, "auxiliary_root_joints": []},
"actuators": actuators,
"end_effectors": [],
"sensors": sensors,
"timing": {"physics_dt_s": 0.002, "control_dt_s": 0.01},
"safety": {
"soft_limit_factor": 0.9,
"on_invalid_command": "reject",
"on_timeout": "disable",
"command_timeout_s": 0.05,
},
"scales": {"length_m": None, "known_mass_kg": None},
"extensions": {"skillfactory.example": {"synthetic": True, "not_manufacturer_data": True}},
}
def effector(data, name, body, role):
data["frames"].append({"id": name + "_frame", "body": body, "xyz": [0, 0, 0], "quat_xyzw": [0, 0, 0, 1]})
data["end_effectors"].append({"id": name, "role": role, "frame_id": name + "_frame", "contact": None})
def sensor(data, name, kind, outputs):
data["sensors"].append(
{
"id": name,
"kind": kind,
"outputs": outputs,
"frame_id": "root",
"target": {"entity": "part", "ids": [data["part_id"]]},
"update_period_s": 0.02,
}
)
def feature(name, quantity, unit="1", normalization="identity"):
return {"name": name, "quantity": quantity, "unit": unit, "normalization": normalization}
def port(name, entity, kind, shape, features=(), selector=None, required=True, mask=None, command=None):
return {
"name": name,
"direction": "output" if kind == "command" else "input",
"kind": kind,
"entity": entity,
"selector": selector or {"type": "all", "values": []},
"required": required,
"dtype": "bool" if kind == "mask" else ("uint8" if kind == "image" else "float32"),
"shape": shape,
"frame": "part_root" if kind == "goal" else "none",
"representation": "features" if features else "tensor",
"features": list(features),
"mask": mask,
"command": command,
}
def software(name, bindings, part_types, joint_types, mode=None):
return {
"schema_version": 2,
"kind": "part_software",
"software_id": name,
"software_version": "0.0.2",
"status": "design",
"binding_mode": "alternatives",
"hardware_bindings": [{"part_id": item, "spec_path": f"configs/parts/{item}.json"} for item in bindings],
"requirements": {
"part_types": part_types,
"joint_types": joint_types,
"topologies": ["tree"],
"attachment_modes": ["fixed", "external", "floating"],
"supports_coupling": True,
"required_control_modes": [mode] if mode else [],
"required_sensor_kinds": ["joint_state"] if mode else ["camera"],
"required_sensor_outputs": ["joint.position", "joint.velocity"] if mode else ["image.rgb8"],
"required_effector_roles": [],
"capacities": {"Jmax": 32, "Amax": 32, "Emax": 8, "Smax": 8},
},
"interface": {
"contract_id": name,
"contract_version": 1,
"quaternion_order": "xyzw",
"ports": [],
"reset": "indexed_isolated" if mode else "not_applicable",
"action_history": "last_applied" if mode else "none",
},
"runtime": {
"adapter_id": None,
"implementation": "unimplemented",
"dependencies": {},
"devices": ["cpu", "cuda"],
"timing": {"policy": "per_part", "control_dt_s": None},
},
"artifact": {"format": "none", "checkpoint": None, "trained_skill": False, "frozen": False},
}
def control_ports(mode, include_goal=False):
ports = [
port("joint_mask", "joint", "mask", ["B", "Jmax"]),
port(
"joint_state",
"joint",
"state",
["B", "Jmax", 2],
[
feature("position", "joint.position", "joint_position"),
feature("velocity", "joint.velocity", "joint_velocity"),
],
mask="joint_mask",
),
port("actuator_mask", "actuator", "mask", ["B", "Amax"]),
port(
"command",
"actuator",
"command",
["B", "Amax", 1],
[feature("command", "actuator.command", normalization="command_scale_offset")],
mask="actuator_mask",
command={"mode": mode, "encoding": "normalized", "clip": [-1, 1]},
),
]
if include_goal:
ports.extend(
[
port("effector_mask", "end_effector", "mask", ["B", "Emax"], required=False),
port(
"target_position",
"end_effector",
"goal",
["B", "Emax", 3],
[feature(axis, "goal.position." + axis, "m") for axis in ("x", "y", "z")],
required=False,
mask="effector_mask",
),
]
)
return ports
def build_examples():
arm, torso, head = part("arm", 6), part("torso", 2), part("head", 2)
effector(arm, "tool", "link_5", "tool")
effector(head, "gaze", "link_1", "gaze")
sensor(head, "camera", "camera", ["image.rgb8"])
sensor(head, "imu", "imu", ["imu.acceleration", "imu.angular_velocity"])
hand = part("hand", 4)
# Two independent fingers, each with a coupled distal joint: J=4, A=2, E=2.
hand["topology"]["joints"][2]["parent"] = "base"
for distal, driver in ((1, 0), (3, 2)):
item = hand["topology"]["joints"][distal]
item["actuation"] = "coupled"
item["coupling"] = {"joint_id": f"joint_{driver}", "multiplier": 0.5, "offset": 0}
hand["actuators"] = [item for item in hand["actuators"] if item["joint_id"] in ("joint_0", "joint_2")]
effector(hand, "finger_a", "link_1", "fingertip")
effector(hand, "finger_b", "link_3", "fingertip")
gripper = part("gripper", 2, joint_type="prismatic")
gripper["topology"]["joints"][1].update(
parent="base", actuation="coupled", coupling={"joint_id": "joint_0", "multiplier": -1, "offset": 0.04}
)
gripper["actuators"] = gripper["actuators"][:1]
effector(gripper, "jaw_a", "link_0", "grasp")
effector(gripper, "jaw_b", "link_1", "grasp")
base = part("mobile_base", 4, mode="velocity", joint_type="continuous")
base["attachment"]["mode"] = "floating"
for item in base["topology"]["joints"]:
item["parent"] = "base"
sensor(base, "imu", "imu", ["imu.acceleration", "imu.angular_velocity"])
pod = part("sensor", 0)
pod["attachment"]["mode"] = "external"
sensor(pod, "camera", "camera", ["image.rgb8"])
sensor(pod, "imu", "imu", ["imu.acceleration", "imu.angular_velocity"])
parts = [arm, hand, gripper, torso, head, base, pod]
outputs = {f"configs/parts/{data['part_id']}.json": data for data in parts}
pd = software(
"part_position_control",
["go2_fl", *[data["part_id"] for data in parts[:5]]],
["leg", "arm", "hand", "gripper", "torso", "head"],
["revolute", "prismatic"],
"position_pd",
)
pd["interface"]["ports"] = control_ports("position_pd", include_goal=True)
velocity = software("wheel_velocity_control", ["example_mobile_base"], ["mobile_base"], ["continuous"], "velocity")
velocity["interface"]["ports"] = control_ports("velocity")
vision = software("part_rgb_perception", ["example_head", "example_sensor"], ["head", "sensor"], ["revolute"])
# Capacities cover hardware, even when this profile doesn't command head motors or consume gaze.
vision["requirements"]["capacities"].update(Amax=2, Emax=1)
selector = {"type": "sensor_output", "values": ["image.rgb8"]}
vision["interface"]["ports"] = [
port("camera_mask", "sensor", "mask", ["B", "Smax"], selector=copy.deepcopy(selector)),
port("rgb_image", "sensor", "image", ["B", "Smax", 480, 640, 3], selector=selector, mask="camera_mask"),
]
for data in (pd, velocity, vision):
outputs[f"configs/software/{data['software_id']}.json"] = data
return outputs
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"--output-root",
type=Path,
required=True,
help="Repository-shaped destination; existing files are never overwritten",
)
args = parser.parse_args()
outputs = build_examples()
paths = [(args.output_root / name, data) for name, data in outputs.items()]
if any(path.exists() for path, _ in paths):
parser.error("Refusing to overwrite existing descriptions")
for path, data in paths:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps(data, indent=2, allow_nan=False) + "\n", encoding="utf-8")
print(f"Generated {len(paths)} synthetic design/profile examples; none provides a runtime adapter")
if __name__ == "__main__":
main()
+186
View File
@@ -0,0 +1,186 @@
#!/usr/bin/env python3
"""Export a validated legacy leg bundle as PartSpec v2; this does not create a new runtime adapter."""
from __future__ import annotations
import argparse
import json
import math
from pathlib import Path
def _quaternion(rpy):
r, p, y = (angle / 2 for angle in rpy)
cr, sr, cp, sp, cy, sy = math.cos(r), math.sin(r), math.cos(p), math.sin(p), math.cos(y), math.sin(y)
return [
sr * cp * cy - cr * sp * sy,
cr * sp * cy + sr * cp * sy,
cr * cp * sy - sr * sp * cy,
cr * cp * cy + sr * sp * sy,
]
def part_from_leg_bundle(bundle):
"""Keep all bodies/fixed branches and the independent actuator declaration order."""
if bundle.get("schema_version") != 2 or bundle.get("kind") != "single_leg":
raise ValueError("Expected legacy single_leg asset manifest v2")
spec = bundle["spec"]
records = {joint["name"]: joint for joint in bundle["joints"]}
controls = {joint["name"]: joint for joint in spec["joints"]}
if bundle["joint_order"] != list(controls) or set(records) != set(controls):
raise ValueError("Legacy controlled-joint order mismatch")
joints = []
for node in bundle["tree"]:
fixed = node["type"] == "fixed"
limits = records[node["name"]]["limits"] if not fixed else None
joints.append(
{
"id": node["name"],
"source_name": node["name"],
"type": node["type"],
"parent": node["parent"],
"child": node["child"],
"origin": {"xyz": node["xyz"], "quat_xyzw": _quaternion(node["rpy"])},
"actuation": "fixed" if fixed else "active",
"position_unit": None if fixed else "rad",
"axis": None if fixed else node["axis"],
"limits_origin": "source",
"limits": None
if fixed
else {
"position": [limits["lower"], limits["upper"]],
"velocity": limits["velocity"],
"effort": limits["effort"],
},
"coupling": None,
}
)
dt = spec["physics_dt"] * spec["decimation"]
part = {
"schema_version": 2,
"kind": "robot_part",
"part_id": spec["part_id"],
"part_type": "leg",
"description_role": "asset_reference",
"source": {
"format": "urdf",
"root": spec["source_root"],
"path": spec["urdf"],
"package_name": spec["package_name"],
"license_file": spec["license_file"],
"license_id": spec["license_id"],
"revision": bundle["source"]["commit"],
"sha256": bundle["source"]["sha256"],
},
"topology": {
"structure": "tree",
"root_body": bundle["anchor_body"],
"bodies": [bundle["anchor_body"], *bundle["links"]],
"joints": joints,
"constraints": [],
},
"frames": [
{"id": "root", "body": bundle["anchor_body"], "xyz": [0, 0, 0], "quat_xyzw": [0, 0, 0, 1]},
{"id": "foot_link", "body": bundle["foot"]["body"], "xyz": [0, 0, 0], "quat_xyzw": [0, 0, 0, 1]},
],
"root_frame": "root",
"attachment": {
"mode": "fixed",
"frame_id": "root",
"source_mount_joint": spec["mount_joint"],
"auxiliary_root_joints": spec["auxiliary_root_joints"],
"source_parent_transform": {
"body": bundle["mount"]["source_parent"],
"xyz": bundle["mount"]["source_parent_T_anchor"]["xyz"],
"quat_xyzw": _quaternion(bundle["mount"]["source_parent_T_anchor"]["rpy"]),
},
},
"actuators": [
{
"id": "drive_" + control["name"],
"joint_id": control["name"],
"neutral_position": control["q_default"],
"commands": {
"position_pd": {
"unit": "rad",
"scale": control["action_scale"],
"offset": control["q_default"],
"gains": {"kp": control["kp"], "kd": control["kd"]},
}
},
}
for control in spec["joints"]
],
"end_effectors": [
{
"id": "foot",
"role": "support",
"frame_id": "foot_link",
"contact": {
"source_collision_index": spec["foot_collision_index"],
"gap_method": bundle["foot"]["type"],
},
}
],
"sensors": [
{
"id": "joint_state",
"kind": "joint_state",
"outputs": ["joint.position", "joint.velocity"],
"frame_id": "root",
"target": {"entity": "joint", "ids": bundle["joint_order"]},
"update_period_s": spec["physics_dt"],
},
{
"id": "foot_contact",
"kind": "contact_normal",
"outputs": ["contact.normal_force"],
"frame_id": "foot_link",
"target": {"entity": "end_effector", "ids": ["foot"]},
"update_period_s": spec["physics_dt"],
},
],
"timing": {"physics_dt_s": spec["physics_dt"], "control_dt_s": dt},
"safety": {
"soft_limit_factor": spec["soft_limit_factor"],
"on_invalid_command": "reject",
"on_timeout": "hold",
"command_timeout_s": 5 * dt,
},
"scales": {"length_m": bundle["length_scale_m"], "known_mass_kg": bundle["known_mass_scale_kg"]},
"extensions": {
"skillfactory.legacy": {
"profile": "single_leg_v1",
"derived_urdf_sha256": bundle["derived_urdf_sha256"],
"watchdog_policy": "v2 requirement only; not implemented by the legacy runtime",
}
},
}
return part
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--bundle", type=Path, required=True)
parser.add_argument("--output", type=Path, required=True)
args = parser.parse_args()
from SkillFactory.legs.spec import load_bundle
from validate_descriptions import validate_hardware
output = args.output.resolve()
if output.exists() or output.is_relative_to(args.bundle.resolve()):
parser.error("Output must be a new file outside the legacy bundle")
part = part_from_leg_bundle(load_bundle(args.bundle))
output.parent.mkdir(parents=True, exist_ok=True)
temporary = output.with_suffix(output.suffix + ".tmp")
try:
temporary.write_text(json.dumps(part, indent=2, allow_nan=False) + "\n", encoding="utf-8")
validate_hardware(temporary)
temporary.replace(output)
finally:
temporary.unlink(missing_ok=True)
print(f"PartSpec v2 exported: {output}; legacy simulation/training remains unchanged")
if __name__ == "__main__":
main()
+531
View File
@@ -0,0 +1,531 @@
#!/usr/bin/env python3
"""Validate the current PartSpec/SoftwareSpec v2 contracts; never launch Kit or load weights."""
from __future__ import annotations
import argparse
import hashlib
import json
import math
from pathlib import Path
from jsonschema import Draft202012Validator
ROOT = Path(__file__).resolve().parents[1]
SCHEMAS = ROOT / "docs/schemas"
ENTITY_AXES = {"joint": "Jmax", "actuator": "Amax", "end_effector": "Emax", "sensor": "Smax"}
PART_TYPES = {"leg", "arm", "hand", "gripper", "torso", "neck", "head", "mobile_base", "sensor", "other"}
SENSOR_KINDS = {"joint_state", "contact_normal", "wrench", "imu", "camera", "tactile", "lidar", "other"}
EFFECTOR_ROLES = {"support", "tool", "fingertip", "grasp", "gaze", "sensor_mount", "other"}
def _finite_float(text):
value = float(text)
if not math.isfinite(value):
raise ValueError(f"Non-finite JSON number: {text}")
return value
def _finite_int(text):
value = int(text)
try:
finite = math.isfinite(value)
except OverflowError as error:
raise ValueError("JSON integer exceeds finite physical numeric range") from error
if not finite:
raise ValueError("Non-finite JSON integer")
return value
def _reject_constant(text):
raise ValueError(f"Non-standard JSON constant: {text}")
def _unique_object(pairs):
result = {}
for key, value in pairs:
if key in result:
raise ValueError(f"Duplicate JSON key: {key}")
result[key] = value
return result
def read_json(path):
return json.loads(
Path(path).read_text(encoding="utf-8"),
parse_float=_finite_float,
parse_int=_finite_int,
parse_constant=_reject_constant,
object_pairs_hook=_unique_object,
)
def _structure(path, schema_name):
data = read_json(path)
schema = read_json(SCHEMAS / schema_name)
Draft202012Validator.check_schema(schema)
error = next(Draft202012Validator(schema).iter_errors(data), None)
if error is not None:
location = ".".join(str(part) for part in error.absolute_path) or "<root>"
raise ValueError(f"{path}: {location}: {error.message}")
return data
def _version(path):
data = read_json(path)
if not isinstance(data, dict) or type(data.get("schema_version")) is not int:
raise ValueError("schema_version must be a JSON integer in an object")
if data["schema_version"] != 2:
raise ValueError(
"Only schema_version=2 is supported; migrate legacy leg bundles with migrate_leg_description.py"
)
return data["schema_version"]
def _integers(data, fields):
# JSON Schema considers 1.0 an integer; the Python contracts require int.
for field in fields:
if field in data and type(data[field]) is not int:
raise ValueError(f"{field} must be a JSON integer, not a decimal/bool")
def _indexed(records, field="id"):
result = {item[field]: item for item in records}
if len(result) != len(records):
raise ValueError(f"Duplicate {field} in entity collection")
return result
def _source_path(root, relative):
root = Path(root).expanduser().resolve()
if not (root / relative).resolve().is_relative_to(root):
raise ValueError("Source asset path must remain inside source root")
def validate_hardware(path):
_version(path)
data = _structure(path, "part_spec.v2.schema.json")
_validate_part(data)
return data
def _joint_semantics(joint):
if not math.isclose(math.hypot(*joint["origin"]["quat_xyzw"]), 1.0, abs_tol=1e-5):
raise ValueError("Joint origin quaternion must be normalized xyzw")
fixed = joint["type"] == "fixed"
expected_unit = None if fixed else ("m" if joint["type"] == "prismatic" else "rad")
if joint["position_unit"] != expected_unit or (joint["actuation"] == "fixed") != fixed:
raise ValueError("Joint type, actuation and position unit disagree")
if fixed:
if joint["axis"] is not None or joint["limits"] is not None:
raise ValueError("Fixed joints must not have moving axes/limits")
elif joint["axis"] is None or not math.isclose(math.hypot(*joint["axis"]), 1.0, abs_tol=1e-5):
raise ValueError("Moving joint axis must be a unit vector")
if (joint["coupling"] is not None) != (joint["actuation"] == "coupled"):
raise ValueError("Coupled joints require an explicit coupling, other joints forbid it")
limits = joint["limits"]
if not fixed and joint["limits_origin"] == "declared" and limits is None:
raise ValueError("Declared moving joint limits cannot be missing")
if limits is not None:
position = limits["position"]
if joint["type"] == "continuous":
if position is not None:
raise ValueError("Continuous joints cannot have bounded position limits")
elif position is None or not position[0] < position[1]:
raise ValueError("Bounded joint position limits require lower < upper")
def _tree_semantics(topology, joints):
bodies, root = set(topology["bodies"]), topology["root_body"]
if root not in bodies:
raise ValueError("Missing topology root body")
parents = {}
for joint in joints.values():
_joint_semantics(joint)
parent, child = joint["parent"], joint["child"]
if parent not in bodies or child not in bodies or parent == child or child == root or child in parents:
raise ValueError("Invalid body reference or multiple parents in spanning tree")
parents[child] = parent
if set(parents) != bodies - {root}:
raise ValueError("Disconnected body in spanning tree")
for body in bodies:
seen = set()
while body != root:
if body in seen:
raise ValueError("Cyclic spanning tree; use explicit loop constraints instead")
seen.add(body)
body = parents[body]
if (topology["structure"] == "closed_chain") != bool(topology["constraints"]):
raise ValueError("Closed chains require explicit loop constraints; trees forbid them")
def _coupling_semantics(joints):
for name, joint in joints.items():
coupling = joint["coupling"]
if coupling is None:
continue
target = joints.get(coupling["joint_id"])
if (
target is None
or target["type"] == "fixed"
or target["position_unit"] != joint["position_unit"]
or coupling["multiplier"] == 0
):
raise ValueError("Coupling references an incompatible joint")
seen, current = {name}, target
while current["coupling"] is not None:
if current["id"] in seen:
raise ValueError("Cyclic joint coupling")
seen.add(current["id"])
next_id = current["coupling"]["joint_id"]
if next_id not in joints:
raise ValueError("Missing coupling joint")
current = joints[next_id]
def _actuator_semantics(actuators, joints):
driven = []
for actuator in actuators.values():
joint = joints.get(actuator["joint_id"])
if joint is None or joint["actuation"] != "active":
raise ValueError("Actuator must drive one active joint, not a passive/coupled/fixed joint")
driven.append(joint["id"])
linear = joint["type"] == "prismatic"
units = {"position_pd": "m" if linear else "rad", "position": "m" if linear else "rad"}
units.update(velocity="m/s" if linear else "rad/s", effort="N" if linear else "N*m")
for mode, command in actuator["commands"].items():
if command["unit"] != units[mode]:
raise ValueError("Actuator command unit disagrees with joint type/mode")
if (command["gains"] is not None) != (mode == "position_pd"):
raise ValueError("Only position_pd requires explicit PD gains")
limits = joint["limits"]
if (
limits
and limits["position"]
and not limits["position"][0] <= actuator["neutral_position"] <= limits["position"][1]
):
raise ValueError("Actuator neutral position outside hard limits")
active = {joint["id"] for joint in joints.values() if joint["actuation"] == "active"}
if len(set(driven)) != len(driven) or set(driven) != active:
raise ValueError("Require exactly one independent actuator per active joint")
def _validate_part(data):
source = data["source"]
if data["description_role"] == "asset_reference":
_source_path(source["root"], source["path"])
topology = data["topology"]
joints = _indexed(topology["joints"])
if len({joint["source_name"] for joint in joints.values()}) != len(joints):
raise ValueError("Duplicate source joint names")
_tree_semantics(topology, joints)
_coupling_semantics(joints)
frames = _indexed(data["frames"])
if data["root_frame"] not in frames or frames[data["root_frame"]]["body"] != topology["root_body"]:
raise ValueError("Root frame must belong to root body")
if data["attachment"]["frame_id"] not in frames:
raise ValueError("Missing attachment frame")
parent_transform = data["attachment"].get("source_parent_transform")
if parent_transform is not None and not math.isclose(math.hypot(*parent_transform["quat_xyzw"]), 1.0, abs_tol=1e-5):
raise ValueError("Source parent transform quaternion must be normalized xyzw")
for frame in frames.values():
if frame["body"] not in topology["bodies"]:
raise ValueError("Frame references missing body")
if not math.isclose(math.hypot(*frame["quat_xyzw"]), 1.0, abs_tol=1e-5):
raise ValueError("Frame quaternion must be normalized xyzw")
for constraint in _indexed(topology["constraints"]).values():
if constraint["parent_frame"] not in frames or constraint["child_frame"] not in frames:
raise ValueError("Loop constraint references missing frame")
if frames[constraint["parent_frame"]]["body"] == frames[constraint["child_frame"]]["body"]:
raise ValueError("Loop constraint must connect different bodies")
_actuator_semantics(_indexed(data["actuators"]), joints)
effectors = _indexed(data["end_effectors"])
for effector in effectors.values():
if effector["frame_id"] not in frames:
raise ValueError("End effector references missing frame")
if effector["contact"] is not None:
_integers(effector["contact"], ("source_collision_index",))
targets = {"part": {data["part_id"]}, "joint": set(joints), "end_effector": set(effectors)}
for sensor in _indexed(data["sensors"]).values():
if sensor["frame_id"] not in frames or not set(sensor["target"]["ids"]) <= targets[sensor["target"]["entity"]]:
raise ValueError("Sensor references missing frame/target")
if sensor["kind"] == "joint_state" and sensor["target"]["entity"] != "joint":
raise ValueError("Joint-state sensor must explicitly target joints")
if sensor["kind"] == "contact_normal" and set(sensor["outputs"]) != {"contact.normal_force"}:
raise ValueError("Normal-contact sensors cannot advertise a full wrench or friction output")
prefixes = {
"joint_state": "joint.",
"wrench": "contact.wrench",
"imu": "imu.",
"camera": "image.",
"lidar": "range.",
}
prefix = prefixes.get(sensor["kind"])
if prefix is not None and any(not signal.startswith(prefix) for signal in sensor["outputs"]):
raise ValueError("Sensor output semantics disagree with sensor kind")
timing = data["timing"]
if timing["physics_dt_s"] is not None:
ratio = timing["control_dt_s"] / timing["physics_dt_s"]
if not math.isfinite(ratio) or ratio < 1 or not math.isclose(ratio, round(ratio), abs_tol=1e-8):
raise ValueError("Control dt must be an integer multiple of physics dt")
if data["safety"]["command_timeout_s"] < timing["control_dt_s"]:
raise ValueError("Command timeout must not be shorter than one control step")
def _repo_file(root, relative):
path = (root / relative).resolve()
if not path.is_relative_to(root):
raise ValueError(f"Path escapes repository: {relative}")
if not path.is_file():
raise FileNotFoundError(path)
return path
def _artifact(data, root):
checkpoint = data["artifact"]["checkpoint"]
if checkpoint is not None:
weights = _repo_file(root, checkpoint["path"])
with weights.open("rb") as stream:
actual = hashlib.file_digest(stream, "sha256").hexdigest()
if actual != checkpoint["sha256"]:
raise ValueError("Checkpoint SHA256 mismatch")
def _bindings(data, root):
bindings = data["hardware_bindings"]
ids = [item["part_id"] for item in bindings]
if len(set(ids)) != len(ids):
raise ValueError("Duplicate hardware part_id bindings")
hardware = []
for binding in bindings:
part = validate_hardware(_repo_file(root, binding["spec_path"]))
if part["part_id"] != binding["part_id"]:
raise ValueError("Hardware binding part_id mismatch")
hardware.append(part)
return hardware
def _entities(part):
return {
"part": [{"id": part["part_id"]}],
"joint": [joint for joint in part["topology"]["joints"] if joint["type"] != "fixed"],
"actuator": part["actuators"],
"end_effector": part["end_effectors"],
"sensor": part["sensors"],
}
def _select(port, entities):
records = entities[port["entity"]]
selector, values = port["selector"]["type"], set(port["selector"]["values"])
if selector == "all":
if values:
raise ValueError("all selector must have empty values")
return records
if not values:
raise ValueError("Explicit selectors require nonempty values")
if selector == "ids":
if not values <= {record["id"] for record in records}:
raise ValueError("Port selector references missing entity ID")
return [record for record in records if record["id"] in values]
if selector == "sensor_output":
if port["entity"] != "sensor":
raise ValueError("sensor_output selector requires sensor entity")
return [record for record in records if values <= set(record["outputs"])]
field, expected = ("role", "end_effector") if selector == "role" else ("kind", "sensor")
if port["entity"] != expected:
raise ValueError("role/sensor_kind selector used on incompatible entity")
return [record for record in records if record[field] in values]
def _port_structure(port, ports, capacities):
shape, entity = port["shape"], port["entity"]
prefix = ["B"] if entity == "part" else ["B", ENTITY_AXES[entity]]
if shape[: len(prefix)] != prefix or any(type(dim) is not int or dim < 1 for dim in shape[len(prefix) :]):
raise ValueError("Port shape must use B and its entity capacity axis followed by positive integer dimensions")
if entity != "part" and capacities[ENTITY_AXES[entity]] == 0:
raise ValueError("Declared port has zero entity capacity; omit it from this profile")
if port["representation"] == "features":
if not port["features"] or len(shape) != len(prefix) + 1 or shape[-1] != len(port["features"]):
raise ValueError("Feature port dimension must exactly match ordered features")
_indexed(port["features"], "name")
elif port["features"]:
raise ValueError("Opaque tensor ports must not claim scalar feature layouts")
if port["kind"] == "mask":
if port["dtype"] != "bool" or shape != prefix or port["mask"] is not None or port["representation"] != "tensor":
raise ValueError("Entity masks require bool [B,capacity], no features or nested mask")
if port["direction"] != "input":
raise ValueError("Entity masks are adapter-provided input ports")
elif entity != "part":
mask = ports.get(port["mask"])
if mask is None or mask["kind"] != "mask" or mask["entity"] != entity or mask["selector"] != port["selector"]:
raise ValueError("Entity port requires a matching selector/entity mask")
elif port["mask"] is not None:
raise ValueError("Part-level ports must not use entity masks")
if port["kind"] == "command":
if port["direction"] != "output" or entity != "actuator" or port["command"] is None:
raise ValueError("Commands must be explicit actuator output ports")
if port["dtype"] != "float32" or port["representation"] != "features" or len(port["features"]) != 1:
raise ValueError("Scalar actuator commands require one float32 feature per actuator")
command = port["command"]
if command["encoding"] == "normalized":
if command["clip"] != [-1, 1] or port["features"][0]["unit"] != "1":
raise ValueError("Normalized commands require dimensionless [-1,1] execution clip")
elif command["clip"] is not None and command["clip"][0] >= command["clip"][1]:
raise ValueError("Physical command clip requires lower < upper")
elif port["command"] is not None:
raise ValueError("Non-command ports must not contain command metadata")
def _requirements(requirements, part):
for field, allowed in (
("part_types", PART_TYPES),
("required_sensor_kinds", SENSOR_KINDS),
("required_effector_roles", EFFECTOR_ROLES),
):
if not set(requirements[field]) <= allowed:
raise ValueError(f"Unknown requirement in {field}")
if part["part_type"] not in requirements["part_types"]:
raise ValueError("Software does not support this part type")
if (
part["topology"]["structure"] not in requirements["topologies"]
or part["attachment"]["mode"] not in requirements["attachment_modes"]
):
raise ValueError("Unsupported topology or attachment mode")
entities = _entities(part)
if not {joint["type"] for joint in entities["joint"]} <= set(requirements["joint_types"]):
raise ValueError("Unsupported joint type")
if not requirements["supports_coupling"] and any(joint["coupling"] for joint in entities["joint"]):
raise ValueError("Software does not support coupled joints")
for entity, axis in ENTITY_AXES.items():
if len(entities[entity]) > requirements["capacities"][axis]:
raise ValueError(f"Hardware exceeds {axis} capacity")
if not set(requirements["required_sensor_kinds"]) <= {sensor["kind"] for sensor in part["sensors"]}:
raise ValueError("Missing required sensor capability")
outputs = {output for sensor in part["sensors"] for output in sensor["outputs"]}
if not set(requirements["required_sensor_outputs"]) <= outputs:
raise ValueError("Missing required sensor output semantics")
if not set(requirements["required_effector_roles"]) <= {effector["role"] for effector in part["end_effectors"]}:
raise ValueError("Missing required end-effector role")
for actuator in part["actuators"]:
if not set(requirements["required_control_modes"]) <= set(actuator["commands"]):
raise ValueError("Missing required actuator control mode")
if requirements["required_control_modes"] and not part["actuators"]:
raise ValueError("Control software requires actuators")
return entities
def _signal_coverage(port, selected, entities):
if port["kind"] != "state" or port["representation"] != "features":
return
for feature in port["features"]:
quantity = feature["quantity"]
if quantity in ("joint.position", "joint.velocity"):
dynamic_unit = "joint_position" if quantity == "joint.position" else "joint_velocity"
for record in selected:
if port["entity"] != "joint":
raise ValueError("Joint-state quantities require joint entity ports")
physical_unit = record["position_unit"] + ("/s" if quantity == "joint.velocity" else "")
expected = (dynamic_unit, physical_unit) if feature["normalization"] == "identity" else ("1",)
if feature["unit"] not in expected:
raise ValueError("Joint-state feature unit/normalization disagrees with selected joints")
if not quantity.startswith(("joint.", "contact.")):
continue
covered = set()
for sensor in entities["sensor"]:
if sensor["target"]["entity"] != port["entity"]:
continue
if any(quantity == signal or quantity.startswith(signal + ".") for signal in sensor["outputs"]):
covered.update(sensor["target"]["ids"])
if not {record["id"] for record in selected} <= covered:
raise ValueError(f"State port {port['name']} lacks sensor coverage for {quantity}")
def _port_binding(port, selected, commanded, entities):
if port["required"] and not selected:
raise ValueError(f"Required port {port['name']} selects no entities")
_signal_coverage(port, selected, entities)
if port["kind"] != "command":
return
mode = port["command"]["mode"]
for actuator in selected:
if actuator["id"] in commanded:
raise ValueError("Conflicting command ports target the same actuator")
commanded.add(actuator["id"])
if mode not in actuator["commands"]:
raise ValueError("Command port mode unavailable on selected actuator")
unit = port["features"][0]["unit"]
if port["command"]["encoding"] == "physical" and unit not in (
"actuator_command",
actuator["commands"][mode]["unit"],
):
raise ValueError("Physical command port unit disagrees with selected actuator")
def _software_contract(data, root):
requirements, interface = data["requirements"], data["interface"]
_integers(requirements["capacities"], ENTITY_AXES.values())
_integers(interface, ("contract_version",))
ports = _indexed(interface["ports"], "name")
for port in ports.values():
_port_structure(port, ports, requirements["capacities"])
parts = _bindings(data, root)
for part in parts:
entities = _requirements(requirements, part)
commanded = set()
for port in ports.values():
_port_binding(port, _select(port, entities), commanded, entities)
timing = data["runtime"]["timing"]
steps = [part["timing"]["control_dt_s"] for part in parts]
if timing["policy"] == "per_part":
if timing["control_dt_s"] is not None:
raise ValueError("per_part timing must not declare a single common control dt")
elif any(not math.isclose(step, steps[0], rel_tol=0, abs_tol=1e-12) for step in steps):
raise ValueError("Software requires common control dt across alternative bindings")
elif timing["control_dt_s"] is not None and not math.isclose(
timing["control_dt_s"], steps[0], rel_tol=0, abs_tol=1e-12
):
raise ValueError("Software/hardware control dt mismatch")
runtime = data["runtime"]
if runtime["implementation"] == "available":
raise ValueError("No v2 runtime adapters are registered yet; do not claim availability")
if runtime["adapter_id"] is not None:
raise ValueError("Unimplemented runtime must not advertise a callable adapter")
def validate_software(path, repo_root=ROOT, require_runtime=False):
_version(path)
data = _structure(path, "software_spec.v2.schema.json")
root = Path(repo_root).resolve()
_software_contract(data, root)
if require_runtime:
raise ValueError("v2 description is compatible, but its runtime adapter is unimplemented")
_artifact(data, root)
return data
def main(argv=None):
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--hardware", type=Path, nargs="+", default=[])
parser.add_argument("--software", type=Path, nargs="+", default=[])
parser.add_argument("--repo-root", type=Path, default=ROOT)
parser.add_argument(
"--require-runtime", action="store_true", help="Reject compatible but unimplemented software adapters"
)
args = parser.parse_args(argv)
if not args.hardware and not args.software:
parser.error("Provide --hardware and/or --software")
try:
for path in args.hardware:
validate_hardware(path)
print(f"Hardware description OK: {path}")
for path in args.software:
validate_software(path, args.repo_root, args.require_runtime)
print(f"Software description and bindings OK: {path} (v2 runtime unimplemented)")
except (ValueError, OSError) as error:
parser.exit(1, f"Description validation failed: {error}\n")
print("Static descriptions only; simulation, checkpoint contents and trained-skill quality are NOT verified.")
if __name__ == "__main__":
main()
+3 -3
View File
@@ -1,7 +1,7 @@
[package]
# Semantic Versioning is used: https://semver.org/
version = "0.0.1"
version = "0.0.2"
# Description
category = "isaaclab"
@@ -10,9 +10,9 @@ readme = "README.md"
title = "SkillFactory"
author = "Isaac Lab Project Developers"
maintainer = "Isaac Lab Project Developers"
description="Single-leg asset import, fixed-anchor simulation, and shared-policy training for Isaac Lab"
description="Multi-part hardware/software contracts, fixed-anchor simulation, and shared leg-policy training for Isaac Lab"
repository = "https://gitea.robotquan.com/chenlin/SkillFactory"
keywords = ["isaaclab", "robotics", "single-leg", "shared-policy"]
keywords = ["isaaclab", "robotics", "body-part", "contracts", "single-leg", "shared-policy"]
[dependencies]
"isaaclab" = {}
+17
View File
@@ -1,6 +1,23 @@
Changelog
---------
0.0.2
~~~~~
* Unified PartSpec / SoftwareSpec v2 for legs, arms, hands, grippers, torso, head,
mobile bases and sensor modules, with independent joint/actuator/effector counts.
* Added v2 JSON Schemas, semantic port/capability validation, synthetic examples
and a metadata migration tool for validated legacy leg bundles.
* Kept only the latest description specification and v2 schemas; removed the
superseded v1 documents/software examples/validation branch.
* Preserved existing single-leg runtime inputs and documented their execution
limits separately from the normative contract.
* Added regression tests for topology, coupling, units, masks, sensor coverage,
command conflicts, version boundaries and artifact hashes.
Limitations: v2 runtime adapters and whole-body/real-hardware execution are not
implemented; compatible descriptors and design templates are not trained Skills.
0.0.1
~~~~~
+388
View File
@@ -0,0 +1,388 @@
"""Body-part independent v2 contracts: static capability matching, not simulation claims."""
import copy
import hashlib
import importlib.util
import json
import shutil
from pathlib import Path
import pytest
import tomllib
from jsonschema import Draft202012Validator
ROOT = Path(__file__).resolve().parents[1]
def module(name, relative):
spec = importlib.util.spec_from_file_location(name, ROOT / relative)
result = importlib.util.module_from_spec(spec)
spec.loader.exec_module(result)
return result
validator = module("part_validator", "scripts/validate_descriptions.py")
examples = module("part_examples", "scripts/examples/generate_part_descriptions.py")
migration = module("part_migration", "scripts/migrate_leg_description.py")
def save(path, data):
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps(data, allow_nan=False), encoding="utf-8")
return path
def replace(data, dotted, value):
keys = dotted.split(".")
current = data
for key in keys[:-1]:
current = current[int(key)] if isinstance(current, list) else current[key]
current[int(keys[-1]) if isinstance(current, list) else keys[-1]] = value
@pytest.fixture
def repo(tmp_path):
root = tmp_path / "repo"
shutil.copytree(ROOT / "configs", root / "configs")
return root
@pytest.fixture
def software(repo):
return validator.read_json(repo / "configs/software/part_position_control.json")
@pytest.mark.parametrize("name", ["part_spec.v2.schema.json", "software_spec.v2.schema.json"])
def test_v2_schemas(name):
Draft202012Validator.check_schema(validator.read_json(ROOT / "docs/schemas" / name))
@pytest.mark.parametrize("path", sorted((ROOT / "configs/parts").glob("*.json")), ids=lambda path: path.stem)
def test_different_body_parts_use_same_schema(path):
data = validator.validate_hardware(path)
assert data["schema_version"] == 2 and data["kind"] == "robot_part"
assert data["description_role"] == ("asset_reference" if path.stem == "go2_fl" else "design_template")
@pytest.mark.parametrize("name", ["part_position_control", "wheel_velocity_control", "part_rgb_perception"])
def test_software_profiles(name):
data = validator.validate_software(ROOT / f"configs/software/{name}.json")
assert data["runtime"]["implementation"] == "unimplemented"
assert data["artifact"]["trained_skill"] is False
def test_examples_are_deterministic_and_explicitly_synthetic():
for relative, expected in examples.build_examples().items():
assert validator.read_json(ROOT / relative) == expected
if relative.startswith("configs/parts/"):
assert expected["source"]["format"] == "design"
assert expected["extensions"]["skillfactory.example"]["not_manufacturer_data"] is True
def test_variable_dof_actuation_and_effector_counts():
hand = validator.validate_hardware(ROOT / "configs/parts/example_hand.json")
entities = validator._entities(hand)
assert [len(entities[name]) for name in ("joint", "actuator", "end_effector")] == [4, 2, 2]
assert hand["topology"]["joints"][1]["coupling"]["joint_id"] == "joint_0"
pod = validator.validate_hardware(ROOT / "configs/parts/example_sensor.json")
entities = validator._entities(pod)
assert all(not entities[name] for name in ("joint", "actuator", "end_effector"))
assert len(entities["sensor"]) == 2
torso = validator.validate_hardware(ROOT / "configs/parts/example_torso.json")
assert torso["end_effectors"] == []
@pytest.mark.parametrize(
("field", "value"),
[
("schema_version", 2.0),
("typo", True),
("source.path", "fake_factory_asset.urdf"),
("topology.root_body", "missing"),
("topology.joints.0.parent", "link_5"),
("topology.joints.0.position_unit", "m"),
("topology.joints.0.axis", [0, 0, 0]),
("topology.joints.0.axis", [1e200, 0, 0]),
("topology.joints.0.origin.quat_xyzw", [0, 0, 0, 0]),
("topology.joints.0.limits.position", [1, -1]),
("topology.joints.0.limits", None),
("topology.joints.0.actuation", "passive"),
("frames.0.body", "missing"),
("frames.0.quat_xyzw", [0, 0, 0, 2]),
("attachment.frame_id", "missing"),
("actuators.0.neutral_position", 2),
("actuators.0.commands.position_pd.unit", "m"),
("actuators.0.commands.position_pd.gains", None),
("end_effectors.0.frame_id", "missing"),
("end_effectors.0.contact", {"source_collision_index": 0.0, "gap_method": "sphere"}),
("sensors.0.target.ids", ["missing"]),
("timing.control_dt_s", 0.003),
("safety.command_timeout_s", 0.005),
("extensions", {"unnamespaced": {}}),
],
)
def test_invalid_part_semantics(tmp_path, field, value):
data = validator.read_json(ROOT / "configs/parts/example_arm.json")
replace(data, field, value)
with pytest.raises(ValueError):
validator.validate_hardware(save(tmp_path / "part.json", data))
def test_actuator_coverage_and_duplicate_names(tmp_path):
data = validator.read_json(ROOT / "configs/parts/example_arm.json")
data["actuators"].pop()
with pytest.raises(ValueError, match="one independent actuator"):
validator.validate_hardware(save(tmp_path / "part.json", data))
data = validator.read_json(ROOT / "configs/parts/example_arm.json")
data["actuators"].append(copy.deepcopy(data["actuators"][0]))
with pytest.raises(ValueError, match="Duplicate"):
validator.validate_hardware(save(tmp_path / "part.json", data))
data = validator.read_json(ROOT / "configs/parts/example_arm.json")
data["topology"]["joints"][1]["source_name"] = "joint_0"
with pytest.raises(ValueError, match="source joint names"):
validator.validate_hardware(save(tmp_path / "part.json", data))
def test_coupling_cycles_rejected(tmp_path):
data = validator.read_json(ROOT / "configs/parts/example_hand.json")
data["topology"]["joints"][1]["coupling"]["joint_id"] = "joint_3"
data["topology"]["joints"][3]["coupling"]["joint_id"] = "joint_1"
with pytest.raises(ValueError, match="Cyclic joint coupling"):
validator.validate_hardware(save(tmp_path / "part.json", data))
def test_explicit_closed_chain_frames_not_a_cyclic_tree(tmp_path):
data = validator.read_json(ROOT / "configs/parts/example_arm.json")
data["topology"]["structure"] = "closed_chain"
data["topology"]["constraints"] = [
{"id": "loop", "type": "loop_closure", "parent_frame": "root", "child_frame": "tool_frame"}
]
assert validator.validate_hardware(save(tmp_path / "part.json", data))["topology"]["structure"] == "closed_chain"
data["topology"]["constraints"][0]["child_frame"] = "missing"
with pytest.raises(ValueError, match="Loop constraint"):
validator.validate_hardware(save(tmp_path / "part.json", data))
@pytest.mark.parametrize(
("field", "value"),
[
("requirements.capacities.Jmax", 3),
("requirements.capacities.Amax", 1),
("requirements.capacities.Emax", 1),
("requirements.capacities.Smax", 1),
("requirements.capacities.Amax", 32.0),
("requirements.supports_coupling", False),
("requirements.joint_types", ["revolute"]),
("requirements.required_control_modes", ["effort"]),
("requirements.required_sensor_kinds", ["wrench"]),
("requirements.required_effector_roles", ["tool"]),
("interface.ports.3.shape", ["B", "Jmax", 1]),
("interface.ports.3.mask", "joint_mask"),
("interface.ports.3.command.clip", [-2, 2]),
("interface.ports.3.features.0.unit", "rad"),
("interface.ports.1.features.0.unit", "m"),
("interface.ports.1.features.0.unit", "degree"),
("interface.ports.1.features.1.name", "position"),
("interface.ports.1.shape", ["B", "Jmax", 3]),
("runtime.implementation", "available"),
("runtime.adapter_id", "imaginary_adapter"),
("artifact.trained_skill", True),
],
)
def test_software_binding_and_port_rejections(tmp_path, repo, software, field, value):
replace(software, field, value)
with pytest.raises(ValueError):
validator.validate_software(save(tmp_path / "software.json", software), repo)
def test_overlapping_command_ports_rejected(tmp_path, repo, software):
command = copy.deepcopy(software["interface"]["ports"][3])
command["name"] = "conflicting_command"
software["interface"]["ports"].append(command)
with pytest.raises(ValueError, match="Conflicting command ports"):
validator.validate_software(save(tmp_path / "software.json", software), repo)
def test_per_part_timing_and_explicit_common_control_contract(tmp_path, repo, software):
path = repo / "configs/parts/example_arm.json"
data = validator.read_json(path)
data["timing"]["control_dt_s"] = 0.02
save(path, data)
target = save(tmp_path / "software.json", software)
assert validator.validate_software(target, repo)["runtime"]["timing"]["policy"] == "per_part"
software["runtime"]["timing"]["policy"] = "common_control_dt"
with pytest.raises(ValueError, match="common control dt"):
validator.validate_software(save(target, software), repo)
data["timing"].update(control_dt_s=0.01, physics_dt_s=0.005)
save(path, data)
software["runtime"]["timing"]["control_dt_s"] = 0.01
assert validator.validate_software(save(target, software), repo)
def test_joint_sensor_coverage_is_per_entity_not_just_kind(tmp_path, repo, software):
path = repo / "configs/parts/example_hand.json"
data = validator.read_json(path)
data["sensors"][0]["target"]["ids"] = ["joint_0"]
save(path, data)
with pytest.raises(ValueError, match="sensor coverage"):
validator.validate_software(save(tmp_path / "software.json", software), repo)
def test_camera_requires_rgb_semantics_not_just_camera_kind(tmp_path, repo):
path = repo / "configs/parts/example_sensor.json"
data = validator.read_json(path)
data["sensors"][0]["outputs"] = ["image.depth_m"]
save(path, data)
with pytest.raises(ValueError, match="sensor output semantics"):
validator.validate_software(ROOT / "configs/software/part_rgb_perception.json", repo)
def test_normal_force_cannot_satisfy_wrench_observation(tmp_path, software):
software["hardware_bindings"] = software["hardware_bindings"][:1]
force = copy.deepcopy(software["interface"]["ports"][-1])
force.update(name="force", kind="state", required=True, frame="entity")
force["features"] = [examples.feature(axis, "contact.normal_force." + axis, "N") for axis in ("x", "y", "z")]
software["interface"]["ports"].append(force)
path = save(tmp_path / "software.json", software)
assert validator.validate_software(path)
force["features"][0]["quantity"] = "contact.wrench.fx"
with pytest.raises(ValueError, match="sensor coverage"):
validator.validate_software(save(path, software))
def test_version_boundaries_and_require_runtime(tmp_path, repo, software):
software["hardware_bindings"][0]["spec_path"] = "configs/legs/go2_fl.json"
with pytest.raises(ValueError, match="Only schema_version=2"):
validator.validate_software(save(tmp_path / "software.json", software), repo)
with pytest.raises(ValueError, match="adapter is unimplemented"):
validator.validate_software(ROOT / "configs/software/part_position_control.json", require_runtime=True)
def test_selector_preserves_hardware_order_not_requested_id_order():
data = validator.validate_hardware(ROOT / "configs/parts/example_arm.json")
selector = {"entity": "actuator", "selector": {"type": "ids", "values": ["drive_joint_2", "drive_joint_0"]}}
records = validator._select(selector, validator._entities(data))
assert [item["id"] for item in records] == ["drive_joint_0", "drive_joint_2"]
def test_migration_preserves_actuator_order_fixed_branches_and_mount(tmp_path):
controls = [{"name": name, "q_default": 0.1, "action_scale": 0.25, "kp": 25, "kd": 0.5} for name in ("knee", "hip")]
spec = {
"schema_version": 1,
"part_id": "test_leg",
"source_root": str(tmp_path / "source"),
"urdf": "robot.urdf",
"package_name": "test",
"license_file": "LICENSE",
"license_id": "test",
"mount_joint": "hip",
"auxiliary_root_joints": [],
"joints": controls,
"foot_body": "toe",
"foot_collision_index": 0,
"physics_dt": 0.002,
"decimation": 5,
"soft_limit_factor": 0.9,
}
tree = [
{
"name": name,
"type": kind,
"parent": parent,
"child": child,
"axis": [0, 1, 0],
"xyz": [0, 0, 0],
"rpy": [0, 0, 0],
}
for name, kind, parent, child in (
("hip", "revolute", "anchor_base", "thigh"),
("knee", "revolute", "thigh", "calf"),
("toe_joint", "fixed", "calf", "toe"),
)
]
bundle = {
"schema_version": 2,
"kind": "single_leg",
"spec": spec,
"tree": tree,
"anchor_body": "anchor_base",
"joint_order": ["knee", "hip"],
"links": {"thigh": None, "calf": None, "toe": None},
"joints": [
{"name": item["name"], "limits": {"lower": -1, "upper": 1, "velocity": 10, "effort": 10}}
for item in controls
],
"source": {"commit": None, "sha256": "0" * 64},
"derived_urdf_sha256": "1" * 64,
"mount": {"source_parent": "trunk", "source_parent_T_anchor": {"xyz": [0.1, 0.2, 0.3], "rpy": [0, 0, 0]}},
"foot": {"body": "toe", "type": "sphere"},
"length_scale_m": 0.5,
"known_mass_scale_kg": 0.2,
}
result = migration.part_from_leg_bundle(bundle)
validator.validate_hardware(save(tmp_path / "part.json", result))
assert [item["joint_id"] for item in result["actuators"]] == ["knee", "hip"]
assert [item["id"] for item in result["topology"]["joints"]] == ["hip", "knee", "toe_joint"]
assert result["attachment"]["source_parent_transform"]["xyz"] == [0.1, 0.2, 0.3]
assert result["source"]["sha256"] == "0" * 64
@pytest.mark.parametrize("text", ['{"a": 1, "a": 2}', '{"a": NaN}', '{"a": Infinity}', '{"a": 1e999}'])
def test_invalid_json_values(tmp_path, text):
path = tmp_path / "invalid.json"
path.write_text(text)
with pytest.raises(ValueError):
validator.read_json(path)
def test_checkpoint_hash_without_loading_weights(tmp_path, software, repo):
weights = repo / "sampling_policy.pt"
payload = b"Static validation does not deserialize this fixture."
weights.write_bytes(payload)
software["artifact"]["format"] = "torch_save_state_dict"
software["artifact"]["checkpoint"] = {"path": weights.name, "sha256": hashlib.sha256(payload).hexdigest()}
path = save(tmp_path / "software.json", software)
assert validator.validate_software(path, repo)["artifact"]["trained_skill"] is False
weights.write_bytes(b"tampered")
with pytest.raises(ValueError, match="SHA256"):
validator.validate_software(path, repo)
@pytest.mark.parametrize("invalid", ["id", "duplicate", "missing", "escape"])
def test_invalid_cross_file_bindings(tmp_path, software, repo, invalid):
if invalid == "id":
software["hardware_bindings"][0]["part_id"] = "wrong"
elif invalid == "duplicate":
software["hardware_bindings"][1]["part_id"] = "go2_fl"
elif invalid == "missing":
(repo / "configs/parts/go2_fl.json").unlink()
else:
path = repo / "configs/parts/go2_fl.json"
path.unlink()
path.symlink_to(ROOT / "configs/parts/go2_fl.json")
with pytest.raises((ValueError, OSError)):
validator.validate_software(save(tmp_path / "software.json", software), repo)
def test_cli_success_and_failure(tmp_path, capsys):
validator.main(["--software", str(ROOT / "configs/software/part_position_control.json")])
assert "NOT verified" in capsys.readouterr().out
with pytest.raises(SystemExit) as error:
validator.main(["--hardware", str(tmp_path / "missing.json")])
assert error.value.code == 1
def test_release_has_only_latest_description_specs():
assert {path.name for path in (ROOT / "docs/schemas").glob("*.json")} == {
"part_spec.v2.schema.json",
"software_spec.v2.schema.json",
}
assert not (ROOT / "docs/legacy_single_leg_spec.md").exists()
assert not (ROOT / "configs/software/leg_skill.json").exists()
assert validator.read_json(ROOT / "configs/legs/go2_fl.json")["schema_version"] == 1 # runtime input retained
version = tomllib.loads((ROOT / "source/SkillFactory/config/extension.toml").read_text())["package"]["version"]
assert version == "0.0.2"
assert (ROOT / "README.md").read_text().startswith(f"# SkillFactory v{version}\n")
for path in (ROOT / "configs/software").glob("*.json"):
data = validator.read_json(path)
assert data["schema_version"] == 2 and data["software_version"] == version