Files
SkillFactory/docs/software_hardware_spec.md

220 lines
21 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# SkillFactory 统一软硬件描述规范 v2
## 1. 设计目标与实现边界
以**部件的结构、能力和语义端口**为契约,不以“腿”“三个关节”“单个足端”作为统一接口的前提。同一格式可描述腿、机械臂、手、夹爪、躯干、颈部、头部、移动底座、纯传感器模块和其他部件;软件通过能力匹配选择可用部件。
**已落地:** PartSpec v2 / SoftwareSpec v2、JSON Schema、跨文件语义校验、不同部位的设计示例、现有 Go2 单腿描述迁移与回归测试。仓库只保留本规范及两份 v2 Schema,不再并列维护旧版规范。
**尚未落地:** v2 通用仿真/训练 adapter、描述驱动 launcher、实机驱动、v2 通用冻结发布、跨部件协调训练。设计模板不是厂家资产;静态契约匹配不证明机械结构可制造、物理模型准确或策略已训练。当前专用单腿链路的进度见[当前状态](current_status.md),参考+学习残差的46D契约见[运行接口](contact_cycle_runtime.md),两者均不代表v2通用adapter已实现。旧Reach绑定leg-token-v1;受载站立使用独立观测及六维测力,已[带候选专属漂移豁免发布1.0.0](../releases/go2_fl_loaded_stand-1.0.0/DEVIATIONS.md),原始30mm门槛并非通过。旧实现/验收详述已归入[历史资料](README.md#历史资料),不作为另一份统一规范。
## 2. 分层模型
```text
PartSpec v2(部件结构、frame、执行器、末端、传感器、时间、安全)
↓ 能力协商、引用和顺序校验
SoftwareSpec v2(要求、容量、语义端口、控制模式、adapter、产物)
↓ adapter 必须显式实现,未实现时拒绝执行
具体后端:Isaac / 其他仿真 / 实机驱动
↓ 各自提供证据
运行验收 → 训练/泛化验收 → 冻结与部署验收
```
| 层 | 决定的内容 | 不应决定的内容 |
| --- | --- | --- |
| 通用核心 | ID、类型、拓扑、实体引用、单位、frame、数量、语义、安全与版本 | 某厂家命名、固定 DoF、固定足端数量、特定网络维数 |
| 软件 profile | 输入/输出端口、任务目标、支持的能力、特征顺序、归一化、容量 | 擅自修改硬件限位、把缺失传感器当成存在 |
| 后端 adapter | 资产加载、索引映射、张量/设备、坐标转换、控制器和 reset 实现 | 静默支持未验证拓扑、猜测单位、假装已部署 |
`part_type` 是分类元数据;真正的适配依据是能力。机械臂与腿可以共用 position profile,手可有更多运动关节但更少独立执行器,传感器模块可以没有关节、执行器和末端。**允许零 DoF、零末端、多末端和多传感器。**
## 3. 文件、命名与版本规则
- UTF-8 JSON;拒绝重复 key、未知核心字段、非有限数值和不支持的版本。整数字段必须使用整数写法,不接受 `2.0` 或 bool。
- 全局 `part_id/software_id` 使用小写 `[a-z][a-z0-9_]*`;局部实体 ID 允许大小写 `[A-Za-z][A-Za-z0-9_]*`,兼容真实 URDF 命名。各实体集合内部 ID 必须唯一。
- 元数据物理量使用 SI:m、kg、s、rad、N、N·m;四元数 **xyzw**、右手坐标。角度不得混入 degree;直线关节不得按 rad 解释。
- `source.root` 可为机器路径并允许 `~`,相对值按工作目录解释;`source.path` 相对该 root,解析后不可逃逸或越界 symlink。来源许可可显式引用上级仓库文件。
- 软件 `spec_path/checkpoint.path` 相对仓库根目录,不允许逃逸或越界 symlink。
- `extensions` 只接受 namespaced key,如 `skillfactory.example`。这是注释/来源扩展区,不能藏入未经协商的控制、安全或物理能力;必须影响执行的扩展需制定 profile 和相应校验器。
- PartSpec v2、SoftwareSpec v2、旧 LegSpec v1、旧 asset manifest v2、旧 token `FEATURE_SCHEMA` v1 分属不同版本域。**同为数字 2 不代表是同一种对象。** `kind` 必须匹配。
- 同版本拒绝未知字段。核心含义改变需升级 schema;端口顺序/单位/归一化改变需升级 `interface.contract_version`,不能只改 shape 或软件实现版本后继续加载旧权重。
## 4. 硬件描述:PartSpec v2
机器格式:[`schemas/part_spec.v2.schema.json`](schemas/part_spec.v2.schema.json)。
### 4.1 字段分组
| 字段 | 内容与约束 |
| --- | --- |
| `schema_version/kind` | 固定 `2/robot_part` |
| `part_id/part_type` | 标识与部位分类;类型含 leg、arm、hand、gripper、torso、neck、head、mobile_base、sensor、other |
| `description_role` | `asset_reference` 为真实来源引用;`design_template` 为未绑定厂家模型的设计模板 |
| `source` | format/root/path/package、许可、revision 与可选 SHA256;来源格式可为 URDF/USD/MJCF;模板必须 format=design、路径/hash/revision 为 null |
| `topology` | root body、完整 body 列表、joint 列表、tree/closed_chain 与显式闭链约束 |
| `frames/root_frame` | body 局部 frame、xyz[m] 与单位四元数;root_frame 必须属于 root body |
| `attachment` | fixed/floating/external、安装 frame、可选源安装关节与辅助支链;可选源 parent → root 零位变换 |
| `actuators` | 独立执行器声明顺序、受驱动关节、neutral position、支持的 command 模式及尺度/offset/PD gains |
| `end_effectors` | 任意数量、frame、语义 role 与可选接触/gap 方法;不再使用单个 `foot_body` |
| `sensors` | 任意数量、kind、明确 outputs 语义、frame、目标实体/IDs、更新周期;不是按部位猜测传感器 |
| `timing` | control_dt_s 必填;physics_dt_s 可为 null;有仿真步长时控制步长必须为其正整数倍 |
| `safety` | 软限位比例、非法命令 reject、超时 hold/zero_effort/disable 与超时阈值;阈值不短于一个控制步 |
| `scales` | 可选长度/已知质量尺度;未知为 null,不得冒充真实测量或厂家值 |
### 4.2 拓扑、自由度与耦合
每个 joint 描述 `id/source_name/type/parent/child/origin/actuation/position_unit/axis/limits_origin/limits/coupling`。
- joint `origin` 是父 body 到零位 joint/child frame 的变换;轴在 joint 局部 frame 表达。revolute/continuous 为 rad、prismatic 为 m;fixed 的单位/轴/限位为 null。
- 当前核心采用**标量 joint + floating root**表示:球关节等多 DoF 需先拆解为显式坐标或新增专用 profile,不得伪装为一个标量 revolute。
- `actuation` 区分 active、passive、coupled、fixed。J 是所有非 fixed 运动关节数;A 是独立执行器数。**J≠A 合法,动作按 A 而非 J 排列。**
- 每个 active joint 恰好一个独立 actuator;passive/coupled/fixed joint 不得被直接驱动。`actuators` 数组顺序是输出通道顺序,`topology.joints` 中非 fixed 的声明顺序是状态通道顺序;不得按名称重排。
- 耦合显式声明 `q_child = multiplier × q_reference + offset`,引用同单位的非 fixed joint,依赖图无环。mimic/欠驱动能力可被规范描述,但当前单腿 importer 不支持。
- joints 始终形成覆盖所有 body 的无环 spanning tree。闭链用独立 `loop_closure` frame 约束表示;不得把循环塞进树。约束可描述不等于当前后端会求解它。
- 有源模型时,几何、质量、惯性、碰撞体和真实限位以来源资产为准;`limits_origin=source` 表示导入时核对/读取来源,允许未解析限位为 null。`declared` 的运动关节必须有完整限位,且这些模板值不是厂家数据。
- bounded 关节的 position 范围必须 lower<upper;continuous position=null;限速/限 effort 为正。已有完整惯性须由 importer 检验正定,缺失惯性必须保持未知标志,不得估算后称为厂家数据。
### 4.3 安装、末端和传感器
- `attachment.mode=fixed` 表示根与挂载参考固定,**不表示冻结内部关节**;floating 表示根可动,external 表示位姿由外部系统提供。源切口可以是固定关节,不再要求 mount 一定是受控关节。
- frame 的 pose 都相对所属 body。源 parent 零位变换可引用部件外 body;它不是当前世界 pose,也不是已完成的跨部件装配约束。
- 末端 role 可为 support/tool/fingertip/grasp/gaze/sensor_mount/other;腿可多接触点,手可多指尖,躯干可无末端。contact 为 null 时不宣称能算 gap;mesh_distance 必须由相应 adapter 提供,不能用 sphere 近似偷偷替代。
- 传感器输出须明确,如 `joint.position`、`joint.velocity`、`contact.normal_force`、`contact.wrench`、`image.rgb8`。**camera 不自动等于 RGB,相应 outputs 必须存在;normal_force 不自动等于 wrench。**
- 关节传感器的 target 必须列出覆盖的 joints。软件请求的 joint/contact state 要求目标实体被真实声明的传感输出覆盖,不能用另一个部位的传感器凑数。
- 源路径/hash 是来源记录;静态预检不读取原源模型或校验其内容 hash。资产构建/加载仍须单独验证来源、资源、许可、映射、物理参数和派生 hash。
## 5. 软件描述:SoftwareSpec v2
机器格式:[`schemas/software_spec.v2.schema.json`](schemas/software_spec.v2.schema.json)。
### 5.1 身份、绑定和能力要求
`kind=part_software`,身份用 `software_id/software_version`;当前 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`](../configs/parts/go2_fl.json) | 3 / 3 / 1 | 从已有真实 Go2 bundle 迁移,保留 fixed 辅助支链和来源 hash |
| [`example_arm.json`](../configs/parts/example_arm.json) | 6 / 6 / 1 | 六轴臂,tool role,无默认地面接触传感器 |
| [`example_hand.json`](../configs/parts/example_hand.json) | 4 / 2 / 2 | 分支双指、显式耦合、多个 fingertip,动作数少于关节数 |
| [`example_gripper.json`](../configs/parts/example_gripper.json) | 2 / 1 / 2 | prismatic、m/N、两钳口耦合 |
| [`example_torso.json`](../configs/parts/example_torso.json) | 2 / 2 / 0 | 不要求末端 |
| [`example_head.json`](../configs/parts/example_head.json) | 2 / 2 / 1 | gaze + camera/IMU,同一硬件可绑定运动或感知 profile |
| [`example_mobile_base.json`](../configs/parts/example_mobile_base.json) | 4 / 4 / 0 | continuous 轮关节、velocity、floating root |
| [`example_sensor.json`](../configs/parts/example_sensor.json) | 0 / 0 / 0 | external 安装、纯 camera/IMU 模块 |
除 Go2 外,`example_*` 都是明确的 **synthetic design_template**,不引用厂家名称、不伪造实测参数、不提供可运行策略。
软件示例:
- [`part_position_control.json`](../configs/software/part_position_control.json):同一可配置关节/执行器端口 contract 绑定腿、臂、手、夹爪、躯干、头部;含可选多末端位置目标。
- [`wheel_velocity_control.json`](../configs/software/wheel_velocity_control.json):轮式底座独立 velocity profile;不是把腿 position 动作改名。
- [`part_rgb_perception.json`](../configs/software/part_rgb_perception.json):头部/纯传感器共用按 `image.rgb8` 输出能力选择的感知端口,无 command port。
v2 的新端口不冒充旧 `[B,Jmax,25]` / `[B,1,16]` token,不自动加载旧模型。`configs/legs/`、`legs/spec.py` 和现有任务/训练 CLI 保留为兼容运行输入与实现,不再附带独立 v1 规范或软件描述。通用校验器只接受 PartSpec/SoftwareSpec v2;旧数据先显式迁移,不静默跨版本。旧专用 Go2 manifest v1 也不被当成通用 PartSpec。
## 7. 校验与迁移
### 7.1 静态校验
```bash
# 已安装 jsonschema 的 Python 3.12 即可,无需 Kit/Torch
python3 scripts/validate_descriptions.py \
--hardware configs/parts/*.json \
--software configs/software/part_position_control.json \
configs/software/wheel_velocity_control.json \
configs/software/part_rgb_perception.json
# 当前应失败,明确指出 v2 adapter 未实现;不可用静态通过冒充可运行
python3 scripts/validate_descriptions.py \
--software configs/software/part_position_control.json --require-runtime
```
预检覆盖:schema、唯一 ID、拓扑连通/无环、frame 与目标引用、单位/轴/四元数、耦合关系、独立驱动覆盖、末端/传感器引用、时间关系、逐候选能力协商、容量、特征布局、mask/selector、传感覆盖、命令冲突与可选 checkpoint hash。
**不覆盖:**来源模型内容/许可存在、实际物理参数、碰撞可用性、动态稳定性、传感器分辨率/校准/延迟实测、设备驱动、adapter 坐标/控制行为、制造与安全证明、训练和泛化。语义字符串的执行规则必须由实现后的 adapter 检查。
### 7.2 从现有单腿迁移
```bash
export PYTHONPATH="$PWD/source/SkillFactory${PYTHONPATH:+:$PYTHONPATH}"
LAB=/home/cen/IsaacLab/isaaclab.sh
# 先按 README 提取旧 bundle;然后输出到一个尚不存在的新文件
"$LAB" -p scripts/migrate_leg_description.py \
--bundle assets/generated/legs/go2_fl --output /tmp/go2_fl.part.v2.json
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 "$LAB" -p -m pytest tests -q
"$LAB" -p -m ruff check source/SkillFactory scripts tests
```
迁移校验旧 bundle 的资源/派生 hash,保留 actuator 声明顺序、完整 fixed 支链、安装变换、碰撞索引、控制参数和来源记录;**不重新认证源厂家模型,也不新增通用后端**。迁移生成的 watchdog 策略是 v2 要求,不是旧 runtime 已实现能力。
设计示例由 [`scripts/examples/generate_part_descriptions.py`](../scripts/examples/generate_part_descriptions.py) 确定性生成,可输出到新目录复核;默认拒绝覆盖现有文件。校验/回归实现分别见 [`scripts/validate_descriptions.py`](../scripts/validate_descriptions.py)、[`tests/test_part_contracts.py`](../tests/test_part_contracts.py)。
## 8. 后续扩展规则
增加新部位通常只需新增 PartSpec、选择已有能力/profile,不得复制一个新的“arm-only/hand-only”核心 schema。新任务增加命名端口 contract;真正的新物理类别(柔性结构、多 DoF 未拆解 joint、复杂传动)或新安全/控制语义需显式扩展 profile/核心版本。
装配设计可利用各部件安装 frame 与源 parent 变换,但当前尚未实现 AssemblySpec、跨部件资源冲突、共享传感、控制权仲裁和协调软件。整机组合需显式规定装配图、命名空间、clock 同步和命令所有权,不能把 alternatives 列表当成已经装配完成。
落地顺序:通用部件 importer/实体 adapter → 精确端口/坐标/安全实现与仿真验收 → 跨 DoF/多末端训练及留出评估 → 装配与跨部件协调 → 单独制定冻结产物和实机部署验收。