Files
SkillFactory/docs/software_hardware_spec.md
T
chenlin 9fe9d27865 feat: checkpoint contact-cycle evaluation and RootXY PPO progress
Consolidate next-stage docs, archive superseded narratives, and preserve frozen document inputs. Retain invalid P2 pairs, partial RootXY training, failed attempts and nonselectable checkpoints as explicit limitations.

Include supervised evaluation/training, desktop GPU admission, bounded evidence and atomic-publication monitor repairs with CPU regressions. Ignore local dotenv configuration.

Validation: 1403 passed, 6 skipped for contact-cycle and related contracts/CLI tests. Full-suite legacy ABI and registration tests require Python 3.12/Torch 2.10/pxr; no runtime checks relaxed. No new physical run or accepted skill.
2026-10-15 14:18:17 +08:00

21 KiB
Raw Blame History

SkillFactory 统一软硬件描述规范 v2

1. 设计目标与实现边界

以部件的结构、能力和语义端口为契约,不以“腿”“三个关节”“单个足端”作为统一接口的前提。同一格式可描述腿、机械臂、手、夹爪、躯干、颈部、头部、移动底座、纯传感器模块和其他部件;软件通过能力匹配选择可用部件。

已落地: PartSpec v2 / SoftwareSpec v2、JSON Schema、跨文件语义校验、不同部位的设计示例、现有 Go2 单腿描述迁移与回归测试。仓库只保留本规范及两份 v2 Schema,不再并列维护旧版规范。

尚未落地: v2 通用仿真/训练 adapter、描述驱动 launcher、实机驱动、v2 通用冻结发布、跨部件协调训练。设计模板不是厂家资产;静态契约匹配不证明机械结构可制造、物理模型准确或策略已训练。当前专用单腿链路的进度见当前状态,参考+学习残差的46D契约见运行接口,两者均不代表v2通用adapter已实现。旧Reach绑定leg-token-v1;受载站立使用独立观测及六维测力,已带候选专属漂移豁免发布1.0.0,原始30mm门槛并非通过。旧实现/验收详述已归入历史资料,不作为另一份统一规范。

2. 分层模型

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。

4.1 字段分组

字段 内容与约束
schema_version/kind 固定 2/robot_part
part_id/part_type 标识与部位分类;类型含 leg、arm、hand、gripper、torso、neck、head、mobile_base、sensor、other
description_role asset_reference 为真实来源引用;design_template 为未绑定厂家模型的设计模板
source format/root/path/package、许可、revision 与可选 SHA256;来源格式可为 URDF/USD/MJCF;模板必须 format=design、路径/hash/revision 为 null
topology root body、完整 body 列表、joint 列表、tree/closed_chain 与显式闭链约束
frames/root_frame body 局部 frame、xyz[m] 与单位四元数;root_frame 必须属于 root body
attachment fixed/floating/external、安装 frame、可选源安装关节与辅助支链;可选源 parent → root 零位变换
actuators 独立执行器声明顺序、受驱动关节、neutral position、支持的 command 模式及尺度/offset/PD gains
end_effectors 任意数量、frame、语义 role 与可选接触/gap 方法;不再使用单个 foot_body
sensors 任意数量、kind、明确 outputs 语义、frame、目标实体/IDs、更新周期;不是按部位猜测传感器
timing control_dt_s 必填;physics_dt_s 可为 null;有仿真步长时控制步长必须为其正整数倍
safety 软限位比例、非法命令 reject、超时 hold/zero_effort/disable 与超时阈值;阈值不短于一个控制步
scales 可选长度/已知质量尺度;未知为 null,不得冒充真实测量或厂家值

4.2 拓扑、自由度与耦合

每个 joint 描述 id/source_name/type/parent/child/origin/actuation/position_unit/axis/limits_origin/limits/coupling。

  • joint origin 是父 body 到零位 joint/child frame 的变换;轴在 joint 局部 frame 表达。revolute/continuous 为 rad、prismatic 为 m;fixed 的单位/轴/限位为 null。
  • 当前核心采用标量 joint + floating root表示:球关节等多 DoF 需先拆解为显式坐标或新增专用 profile,不得伪装为一个标量 revolute。
  • actuation 区分 active、passive、coupled、fixed。J 是所有非 fixed 运动关节数;A 是独立执行器数。J≠A 合法,动作按 A 而非 J 排列。
  • 每个 active joint 恰好一个独立 actuator;passive/coupled/fixed joint 不得被直接驱动。actuators 数组顺序是输出通道顺序,topology.joints 中非 fixed 的声明顺序是状态通道顺序;不得按名称重排。
  • 耦合显式声明 q_child = multiplier × q_reference + offset,引用同单位的非 fixed joint,依赖图无环。mimic/欠驱动能力可被规范描述,但当前单腿 importer 不支持。
  • joints 始终形成覆盖所有 body 的无环 spanning tree。闭链用独立 loop_closure frame 约束表示;不得把循环塞进树。约束可描述不等于当前后端会求解它。
  • 有源模型时,几何、质量、惯性、碰撞体和真实限位以来源资产为准;limits_origin=source 表示导入时核对/读取来源,允许未解析限位为 null。declared 的运动关节必须有完整限位,且这些模板值不是厂家数据。
  • bounded 关节的 position 范围必须 lower<upper;continuous position=null;限速/限 effort 为正。已有完整惯性须由 importer 检验正定,缺失惯性必须保持未知标志,不得估算后称为厂家数据。

4.3 安装、末端和传感器

  • attachment.mode=fixed 表示根与挂载参考固定,不表示冻结内部关节;floating 表示根可动,external 表示位姿由外部系统提供。源切口可以是固定关节,不再要求 mount 一定是受控关节。
  • frame 的 pose 都相对所属 body。源 parent 零位变换可引用部件外 body;它不是当前世界 pose,也不是已完成的跨部件装配约束。
  • 末端 role 可为 support/tool/fingertip/grasp/gaze/sensor_mount/other;腿可多接触点,手可多指尖,躯干可无末端。contact 为 null 时不宣称能算 gap;mesh_distance 必须由相应 adapter 提供,不能用 sphere 近似偷偷替代。
  • 传感器输出须明确,如 joint.position、joint.velocity、contact.normal_force、contact.wrench、image.rgb8。camera 不自动等于 RGB,相应 outputs 必须存在;normal_force 不自动等于 wrench。
  • 关节传感器的 target 必须列出覆盖的 joints。软件请求的 joint/contact state 要求目标实体被真实声明的传感输出覆盖,不能用另一个部位的传感器凑数。
  • 源路径/hash 是来源记录;静态预检不读取原源模型或校验其内容 hash。资产构建/加载仍须单独验证来源、资源、许可、映射、物理参数和派生 hash。

5. 软件描述:SoftwareSpec v2

机器格式:schemas/software_spec.v2.schema.json。

5.1 身份、绑定和能力要求

kind=part_software,身份用 software_id/software_version;当前 v2 格式交付阶段为 design/prototype,trained_skill=false/frozen=false。本版本不提供已训练/冻结发布流程。第二阶段的独立 skillfactory.skillbundle.v1 有自己的证据门槛,不伪装成已获运行支持的 v2 SoftwareSpec。

hardware_bindings 是可替换候选列表,binding_mode=alternatives:每个部件独立满足同一 profile,不能把候选 A 的传感器与候选 B 的执行器合并满足要求。不是同时装配,也不代表已经学会跨部件迁移。

requirements 必须声明:

  • 支持的部位、运动 joint 类型、拓扑、挂载模式和耦合能力;
  • 必需的执行模式、sensor kinds/outputs、effector roles;
  • 每个部件的容量 Jmax/Amax/Emax/Smax(允许 0)。容量覆盖硬件全部相应实体,不只是某个 selector 子集;实际数量超过容量直接拒绝。

不要求所有部位共用一个神经网络或一个固定 D。统一的是描述格式和语义匹配,任务特征布局由 profile 决定。

5.2 语义端口与形状

每个 port 必须描述 name、direction、kind、entity、selector、required、dtype、shape、frame、representation、features、mask、command。

维度 语义 示例
B 批量实例数 所有端口的第一维
Jmax 非 fixed 运动关节槽 joint_state [B,Jmax,2]
Amax 独立执行器槽 command [B,Amax,1]
Emax 末端槽 position goal [B,Emax,3]、pose goal 可定义 7 个特征
Smax 传感器槽 RGB [B,Smax,480,640,3]
D / 固定 tensor 轴 profile 的明确整数维度 features 数目必须与最后一维精确一致
  • entity 分 part/joint/actuator/end_effector/sensor。实体端口必须使用对应容量轴,不得把手的 Jmax 当成动作 Amax。part 级 context 为 [B,D],不强制实体轴。
  • selector 支持 all/ids/role/sensor_kind/sensor_output。按硬件数组顺序过滤,不按 selector.values 重排;不同候选可通过 role 或 all 适配不同名字。
  • features 是有序 {name, quantity, unit, normalization};必须声明每个特征的物理语义与归一化。tensor 表示 RGB 等非逐标量数据,features 必须为空;具体布局/编码由命名的 contract 定义。
  • joint_position/joint_velocity 表示按槽 joint type 决定 rad/m、rad/s/m/s;actuator_command 表示按 actuator mode 决定单位。软件必须消费对应硬件类型/单位元数据,不能将混合关节槽都按 rad 计算。
  • normalization 是契约中的明确规则名。示例 identity 为不归一化;command_scale_offset 按 actuator scale/offset 映射。自定义规则必须由对应 adapter 解释;未知规则在执行前拒绝,不得只接受字符串就声称能推理。
  • 每个实体数据端口必须引用同 entity/selector 的 bool [B,capacity] 输入 mask。padding 不驱动、不参与损失/概率/路由,adapter 必须屏蔽无效槽中的非有限垃圾值;有效槽非有限值必须拒绝。
  • required=false 允许 selector 选不到实体,adapter 必须返回无效 mask;不是允许把需要的力/图像伪造为零。0 容量实体不得声明端口;纯传感模块可以完全没有 joint/command/effector ports。
  • 同 shape 不代表兼容:完整特征顺序、quantity、unit、normalization、frame、selector、控制模式和 contract version 都必须匹配;checkpoint 加载还需完整接口/硬件绑定指纹,不可只比维数。

5.3 统一坐标与动态协议

port.frame 可为 part_root/world/entity/none。位置目标不默认是足端,不默认在 world;姿态使用 xyzw;必要的空间速度和 wrench profile 应明确:

  • twist 顺序 [vx,vy,vz,wx,wy,wz],分别 m/s、rad/s;
  • wrench 顺序 [Fx,Fy,Fz,Tx,Ty,Tz],分别 N、N·m,必须注明参考 frame/作用原点;
  • contact.normal_force 是法向接触力,不能当作含切向摩擦的完整 wrench;控制器 applied/commanded effort 不等于实测电机 effort。

移动根的相对线速度必须包含根角速度产生的 ω×r 项;wrench 换原点必须包含力矩平移项。旧固定支座的直接坐标差分公式不能无条件搬到浮动躯干、头部或底座。

未来 adapter 的每个批次应携带 part_id/instance_ids/control_index/timestamp/description_revision,以区别部件、实例、时刻与描述修订;旧 v1 张量接口未增加这一 envelope。对跨时刻传感器数据,adapter 必须标记有效性/时间差,不能把旧帧当当前状态。

reset 按 profile 声明 indexed_isolated 或 not_applicable;仿真 indexed reset 必须隔离未选实例、清动作历史,空集合 no-op;真实硬件不得把仿真 reset 当成可直接发送的动作。action_history=last_applied 是最后已执行动作,不是最后拟议动作;timeout bootstrap 规则仍由训练 adapter 区分 timeout 与真 termination。

5.4 控制、安全、周期和可执行性

  • command 仅允许 actuator output;每个独立 actuator 一个命令来源,重叠命令直接拒绝。
  • 模式为 position_pd/position/velocity/effort,必须是目标 actuator 已声明的模式。prismatic 的 effort 为 N,rotary 为 N·m;只有 position_pd 要求显式 PD gains。
  • normalized command 使用 dimensionless [-1,1] 执行裁剪,再计算 target = offset + scale × clipped_command;position 要再次按软限位裁剪,velocity/effort 受硬限速/限 effort。PPO 仍保留未裁剪采样值的 log-prob。
  • physical command 不做隐式尺度映射,明确单位/可选 clip,但仍必须执行硬件安全约束。未解析安全限位、未实现 watchdog、缺失有效传感器、未知转换或控制模式都必须拒绝执行。
  • 安全策略是要求,不是已实现证明。hold/zero_effort/disable 都不是所有机构的天然安全状态,需要具体部位/实机验收;不能用模板值宣称满足实机安全。
  • runtime.timing 支持 common_control_dt 或 per_part;前者对每个候选核对控制周期,后者由实际选中的部件决定。无需让头部相机和腿共享物理步长;跨部件异步协调不由 alternatives 绑定自动提供。
  • runtime.devices/dependencies 是所需/拟支持的环境,不是当前机器探测结果;参考机器配置和已验证运行版本仍另行记录,不编造 GPU/显存最低要求。
  • runtime.implementation=available 必须有注册且验收过的 adapter。当前未注册任何 v2 adapter,校验器拒绝假称 available;--require-runtime 也会拒绝仅通过静态协商的 v2 profile。
  • 当前 artifact.checkpoint 可为 null 或带 path/hash 的引用。校验只验证文件 hash,不反序列化、不证明权重兼容或收敛;trained/frozen 发布另设里程碑。

6. 多部位示例与运行兼容边界

示例 J / A / E 关键差异
configs/parts/go2_fl.json 3 / 3 / 1 从已有真实 Go2 bundle 迁移,保留 fixed 辅助支链和来源 hash
example_arm.json 6 / 6 / 1 六轴臂,tool role,无默认地面接触传感器
example_hand.json 4 / 2 / 2 分支双指、显式耦合、多个 fingertip,动作数少于关节数
example_gripper.json 2 / 1 / 2 prismatic、m/N、两钳口耦合
example_torso.json 2 / 2 / 0 不要求末端
example_head.json 2 / 2 / 1 gaze + camera/IMU,同一硬件可绑定运动或感知 profile
example_mobile_base.json 4 / 4 / 0 continuous 轮关节、velocity、floating root
example_sensor.json 0 / 0 / 0 external 安装、纯 camera/IMU 模块

除 Go2 外,example_* 都是明确的 synthetic design_template,不引用厂家名称、不伪造实测参数、不提供可运行策略。

软件示例:

  • part_position_control.json:同一可配置关节/执行器端口 contract 绑定腿、臂、手、夹爪、躯干、头部;含可选多末端位置目标。
  • wheel_velocity_control.json:轮式底座独立 velocity profile;不是把腿 position 动作改名。
  • part_rgb_perception.json:头部/纯传感器共用按 image.rgb8 输出能力选择的感知端口,无 command port。

v2 的新端口不冒充旧 [B,Jmax,25] / [B,1,16] token,不自动加载旧模型。configs/legs/、legs/spec.py 和现有任务/训练 CLI 保留为兼容运行输入与实现,不再附带独立 v1 规范或软件描述。通用校验器只接受 PartSpec/SoftwareSpec v2;旧数据先显式迁移,不静默跨版本。旧专用 Go2 manifest v1 也不被当成通用 PartSpec。

7. 校验与迁移

7.1 静态校验

# 已安装 jsonschema 的 Python 3.12 即可,无需 Kit/Torch
python3 scripts/validate_descriptions.py \
  --hardware configs/parts/*.json \
  --software configs/software/part_position_control.json \
             configs/software/wheel_velocity_control.json \
             configs/software/part_rgb_perception.json

# 当前应失败,明确指出 v2 adapter 未实现;不可用静态通过冒充可运行
python3 scripts/validate_descriptions.py \
  --software configs/software/part_position_control.json --require-runtime

预检覆盖:schema、唯一 ID、拓扑连通/无环、frame 与目标引用、单位/轴/四元数、耦合关系、独立驱动覆盖、末端/传感器引用、时间关系、逐候选能力协商、容量、特征布局、mask/selector、传感覆盖、命令冲突与可选 checkpoint hash。

**不覆盖:**来源模型内容/许可存在、实际物理参数、碰撞可用性、动态稳定性、传感器分辨率/校准/延迟实测、设备驱动、adapter 坐标/控制行为、制造与安全证明、训练和泛化。语义字符串的执行规则必须由实现后的 adapter 检查。

7.2 从现有单腿迁移

export PYTHONPATH="$PWD/source/SkillFactory${PYTHONPATH:+:$PYTHONPATH}"
LAB=/home/cen/IsaacLab/isaaclab.sh
# 先按 README 提取旧 bundle;然后输出到一个尚不存在的新文件
"$LAB" -p scripts/migrate_leg_description.py \
  --bundle assets/generated/legs/go2_fl --output /tmp/go2_fl.part.v2.json

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 "$LAB" -p -m pytest tests -q
"$LAB" -p -m ruff check source/SkillFactory scripts tests

迁移校验旧 bundle 的资源/派生 hash,保留 actuator 声明顺序、完整 fixed 支链、安装变换、碰撞索引、控制参数和来源记录;不重新认证源厂家模型,也不新增通用后端。迁移生成的 watchdog 策略是 v2 要求,不是旧 runtime 已实现能力。

设计示例由 scripts/examples/generate_part_descriptions.py 确定性生成,可输出到新目录复核;默认拒绝覆盖现有文件。校验/回归实现分别见 scripts/validate_descriptions.py、tests/test_part_contracts.py。

8. 后续扩展规则

增加新部位通常只需新增 PartSpec、选择已有能力/profile,不得复制一个新的“arm-only/hand-only”核心 schema。新任务增加命名端口 contract;真正的新物理类别(柔性结构、多 DoF 未拆解 joint、复杂传动)或新安全/控制语义需显式扩展 profile/核心版本。

装配设计可利用各部件安装 frame 与源 parent 变换,但当前尚未实现 AssemblySpec、跨部件资源冲突、共享传感、控制权仲裁和协调软件。整机组合需显式规定装配图、命名空间、clock 同步和命令所有权,不能把 alternatives 列表当成已经装配完成。

落地顺序:通用部件 importer/实体 adapter → 精确端口/坐标/安全实现与仿真验收 → 跨 DoF/多末端训练及留出评估 → 装配与跨部件协调 → 单独制定冻结产物和实机部署验收。