From 8019d6f8d6b4004ab09137b35faa87a3117f2b56 Mon Sep 17 00:00:00 2001 From: cen617-code <1057290604@qq.com> Date: Sat, 10 Oct 2026 16:34:40 +0800 Subject: [PATCH] release: SkillFactory v0.0.2 --- README.md | 17 +- configs/parts/example_arm.json | 443 +++++++++++++++ configs/parts/example_gripper.json | 232 ++++++++ configs/parts/example_hand.json | 330 +++++++++++ configs/parts/example_head.json | 254 +++++++++ configs/parts/example_mobile_base.json | 303 ++++++++++ configs/parts/example_sensor.json | 105 ++++ configs/parts/example_torso.json | 201 +++++++ configs/parts/go2_fl.json | 475 ++++++++++++++++ configs/software/part_position_control.json | 277 +++++++++ configs/software/part_rgb_perception.json | 127 +++++ configs/software/wheel_velocity_control.json | 189 +++++++ docs/leg_interface.md | 4 +- docs/schemas/part_spec.v2.schema.json | 224 ++++++++ docs/schemas/software_spec.v2.schema.json | 141 +++++ docs/software_hardware_spec.md | 219 ++++++++ .../examples/generate_part_descriptions.py | 311 ++++++++++ scripts/migrate_leg_description.py | 186 ++++++ scripts/validate_descriptions.py | 531 ++++++++++++++++++ source/SkillFactory/config/extension.toml | 6 +- source/SkillFactory/docs/CHANGELOG.rst | 17 + tests/test_part_contracts.py | 388 +++++++++++++ 22 files changed, 4974 insertions(+), 6 deletions(-) create mode 100644 configs/parts/example_arm.json create mode 100644 configs/parts/example_gripper.json create mode 100644 configs/parts/example_hand.json create mode 100644 configs/parts/example_head.json create mode 100644 configs/parts/example_mobile_base.json create mode 100644 configs/parts/example_sensor.json create mode 100644 configs/parts/example_torso.json create mode 100644 configs/parts/go2_fl.json create mode 100644 configs/software/part_position_control.json create mode 100644 configs/software/part_rgb_perception.json create mode 100644 configs/software/wheel_velocity_control.json create mode 100644 docs/schemas/part_spec.v2.schema.json create mode 100644 docs/schemas/software_spec.v2.schema.json create mode 100644 docs/software_hardware_spec.md create mode 100644 scripts/examples/generate_part_descriptions.py create mode 100644 scripts/migrate_leg_description.py create mode 100644 scripts/validate_descriptions.py create mode 100644 tests/test_part_contracts.py diff --git a/README.md b/README.md index d914100..c483348 100644 --- a/README.md +++ b/README.md @@ -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/` 入口保留。 diff --git a/configs/parts/example_arm.json b/configs/parts/example_arm.json new file mode 100644 index 0000000..2264020 --- /dev/null +++ b/configs/parts/example_arm.json @@ -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 + } + } +} diff --git a/configs/parts/example_gripper.json b/configs/parts/example_gripper.json new file mode 100644 index 0000000..6b7a547 --- /dev/null +++ b/configs/parts/example_gripper.json @@ -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 + } + } +} diff --git a/configs/parts/example_hand.json b/configs/parts/example_hand.json new file mode 100644 index 0000000..e1d9562 --- /dev/null +++ b/configs/parts/example_hand.json @@ -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 + } + } +} diff --git a/configs/parts/example_head.json b/configs/parts/example_head.json new file mode 100644 index 0000000..2c85e7c --- /dev/null +++ b/configs/parts/example_head.json @@ -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 + } + } +} diff --git a/configs/parts/example_mobile_base.json b/configs/parts/example_mobile_base.json new file mode 100644 index 0000000..843bdff --- /dev/null +++ b/configs/parts/example_mobile_base.json @@ -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 + } + } +} diff --git a/configs/parts/example_sensor.json b/configs/parts/example_sensor.json new file mode 100644 index 0000000..bf1fce4 --- /dev/null +++ b/configs/parts/example_sensor.json @@ -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 + } + } +} diff --git a/configs/parts/example_torso.json b/configs/parts/example_torso.json new file mode 100644 index 0000000..1791c8e --- /dev/null +++ b/configs/parts/example_torso.json @@ -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 + } + } +} diff --git a/configs/parts/go2_fl.json b/configs/parts/go2_fl.json new file mode 100644 index 0000000..3c5b6f2 --- /dev/null +++ b/configs/parts/go2_fl.json @@ -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" + } + } +} diff --git a/configs/software/part_position_control.json b/configs/software/part_position_control.json new file mode 100644 index 0000000..ecd222f --- /dev/null +++ b/configs/software/part_position_control.json @@ -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 + } +} diff --git a/configs/software/part_rgb_perception.json b/configs/software/part_rgb_perception.json new file mode 100644 index 0000000..accd990 --- /dev/null +++ b/configs/software/part_rgb_perception.json @@ -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 + } +} diff --git a/configs/software/wheel_velocity_control.json b/configs/software/wheel_velocity_control.json new file mode 100644 index 0000000..92812af --- /dev/null +++ b/configs/software/wheel_velocity_control.json @@ -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 + } +} diff --git a/docs/leg_interface.md b/docs/leg_interface.md index b112991..bd4891a 100644 --- a/docs/leg_interface.md +++ b/docs/leg_interface.md @@ -1,4 +1,6 @@ -# 单腿接口与验收 +# 单腿运行与验收 + +软硬件描述规范的唯一入口为 [统一软硬件描述规范 v2](software_hardware_spec.md)。本文只记录当前单腿兼容运行链路的实现、验收证据与限制,不是独立规范,也不代表通用 v2 adapter 已实现。 ## 1. 实现范围 diff --git a/docs/schemas/part_spec.v2.schema.json b/docs/schemas/part_spec.v2.schema.json new file mode 100644 index 0000000..77ddff5 --- /dev/null +++ b/docs/schemas/part_spec.v2.schema.json @@ -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"}} + } + ] + } + } + } + } +} diff --git a/docs/schemas/software_spec.v2.schema.json b/docs/schemas/software_spec.v2.schema.json new file mode 100644 index 0000000..254ff25 --- /dev/null +++ b/docs/schemas/software_spec.v2.schema.json @@ -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"}}]} + } + } + ] + } + } + } + } +} diff --git a/docs/software_hardware_spec.md b/docs/software_hardware_spec.md new file mode 100644 index 0000000..1725ca0 --- /dev/null +++ b/docs/software_hardware_spec.md @@ -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" + 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() diff --git a/source/SkillFactory/config/extension.toml b/source/SkillFactory/config/extension.toml index ad8c1c0..9f53085 100644 --- a/source/SkillFactory/config/extension.toml +++ b/source/SkillFactory/config/extension.toml @@ -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" = {} diff --git a/source/SkillFactory/docs/CHANGELOG.rst b/source/SkillFactory/docs/CHANGELOG.rst index a6d3951..8fc8694 100644 --- a/source/SkillFactory/docs/CHANGELOG.rst +++ b/source/SkillFactory/docs/CHANGELOG.rst @@ -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 ~~~~~ diff --git a/tests/test_part_contracts.py b/tests/test_part_contracts.py new file mode 100644 index 0000000..3a0afce --- /dev/null +++ b/tests/test_part_contracts.py @@ -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