810 lines
22 KiB
Plaintext
810 lines
22 KiB
Plaintext
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"$id": "kk-policy-bundle/1",
|
|
"title": "A robot application bundle: <name>/ and <name>.app",
|
|
"description": "Robot application formats: legacy policy bundles and self-contained native robot applications. Each version declares its actual supported runtimes.",
|
|
"x-files": [
|
|
{
|
|
"path": "^bundle\\.json$",
|
|
"required": true,
|
|
"format": "json",
|
|
"is": "this schema's document: every file, its size and SHA-256, and which host takes what"
|
|
},
|
|
{
|
|
"path": "^README\\.md$",
|
|
"required": true,
|
|
"format": "markdown",
|
|
"is": "the integration guide, from deploy/fsm/BUNDLE_README.md"
|
|
},
|
|
{
|
|
"path": "^controller\\.toml$",
|
|
"required": true,
|
|
"format": "toml",
|
|
"is": "the FSM: modes, the rules that switch between them, the keys and buttons",
|
|
"namedBy": "fsm"
|
|
},
|
|
{
|
|
"path": "^manual\\.en\\.json$",
|
|
"required": true,
|
|
"format": "json",
|
|
"schema": "#/$defs/manual",
|
|
"is": "every key and button the bundle reads and what it does, in English, generated at build time",
|
|
"namedBy": "manuals.en"
|
|
},
|
|
{
|
|
"path": "^manual\\.[a-z]{2}(-[A-Za-z]+)?\\.json$",
|
|
"required": false,
|
|
"format": "json",
|
|
"schema": "#/$defs/manual",
|
|
"is": "a translation of manual.en.json, added with `deploy.py --translate`",
|
|
"namedBy": "manuals.<language>"
|
|
},
|
|
{
|
|
"path": "^reference\\.json$",
|
|
"required": false,
|
|
"format": "json",
|
|
"is": "kk-policy-reference/1: recorded frames every host replays to measure that it agrees; absent only where onnxruntime was not installed at build time",
|
|
"namedBy": "reference"
|
|
},
|
|
{
|
|
"path": "^[^/]+\\.trajectory\\.json$",
|
|
"required": false,
|
|
"format": "json",
|
|
"is": "a recording a reference-guided mode is driven by, beside the contracts",
|
|
"namedBy": "modes.<mode>.trajectory"
|
|
},
|
|
{
|
|
"path": "^[a-z][a-z0-9_]*\\.json$",
|
|
"required": true,
|
|
"format": "json",
|
|
"is": "one mode's contract (the export's layout.json): observation layout, joint order, gains, controls",
|
|
"namedBy": "modes.<mode>.contract"
|
|
},
|
|
{
|
|
"path": "^models/[a-z][a-z0-9_]*\\.onnx$",
|
|
"required": true,
|
|
"format": "onnx",
|
|
"is": "a policy, for the browser and play; one per export, shared by the modes on it",
|
|
"namedBy": "modes.<mode>.models.onnx"
|
|
},
|
|
{
|
|
"path": "^models/[a-z][a-z0-9_]*\\.rknn$",
|
|
"required": false,
|
|
"format": "rknn",
|
|
"is": "the same policy converted for the RK3576 NPU; a mode without one runs on a stub on the board",
|
|
"namedBy": "modes.<mode>.models.rknn"
|
|
},
|
|
{
|
|
"path": "^runtime/web/controller\\.wasm$",
|
|
"required": true,
|
|
"format": "wasm",
|
|
"is": "the controller for a browser; one build for every CPU",
|
|
"namedBy": "runtimes.web.wasm"
|
|
},
|
|
{
|
|
"path": "^runtime/web/controller\\.js$",
|
|
"required": true,
|
|
"format": "javascript",
|
|
"is": "its wasm-bindgen binding",
|
|
"namedBy": "runtimes.web.glue"
|
|
},
|
|
{
|
|
"path": "^runtime/mjlab/macosx-[a-z0-9._-]+/controller\\.so$",
|
|
"required": false,
|
|
"format": "mach-o",
|
|
"is": "the same for macOS: macosx-universal2 is cross-built with zig, arm64 and x86_64 in one file, and loaded on any Mac whatever version its Python's platform string carries; a Mac that built the bundle adds its own under its exact platform",
|
|
"namedBy": "runtimes.mjlab.extensions.<platform>.file"
|
|
},
|
|
{
|
|
"path": "^runtime/mjlab/[a-z0-9._-]+/controller\\.so$",
|
|
"required": false,
|
|
"format": "elf-shared-object",
|
|
"is": "the controller as a Python extension (abi3) for play --app, one per platform it was built on",
|
|
"namedBy": "runtimes.mjlab.extensions.<platform>.file"
|
|
},
|
|
{
|
|
"path": "^runtime/mjlab/win-[a-z0-9_]+/controller\\.pyd$",
|
|
"required": false,
|
|
"format": "pe-dll",
|
|
"is": "the same, for play --app on Windows: cross-built with MinGW, importing python3.dll and nothing outside Windows itself",
|
|
"namedBy": "runtimes.mjlab.extensions.<platform>.file"
|
|
},
|
|
{
|
|
"path": "^runtime/board/controller$",
|
|
"required": false,
|
|
"format": "elf-aarch64",
|
|
"is": "the robot's whole program, cross-compiled; absent until deploy/fsm/docker-build.sh has run, which bundle.json's notes then say",
|
|
"namedBy": "runtimes.board.file"
|
|
}
|
|
],
|
|
"$defs": {
|
|
"mode": {
|
|
"type": "object",
|
|
"required": [
|
|
"models",
|
|
"contract",
|
|
"observation",
|
|
"action"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"models": {
|
|
"description": "The mode's policy in every format a host runs: `onnx` always, `rknn` once converted.",
|
|
"type": "object",
|
|
"required": [
|
|
"onnx"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"onnx": {
|
|
"type": "string",
|
|
"pattern": "^models/[a-z][a-z0-9_]*\\.onnx$"
|
|
},
|
|
"rknn": {
|
|
"type": "string",
|
|
"pattern": "^models/[a-z][a-z0-9_]*\\.rknn$"
|
|
}
|
|
}
|
|
},
|
|
"contract": {
|
|
"type": "string",
|
|
"pattern": "^[a-z][a-z0-9_]*\\.json$"
|
|
},
|
|
"observation": {
|
|
"type": "integer"
|
|
},
|
|
"action": {
|
|
"type": "integer"
|
|
},
|
|
"trajectory": {
|
|
"type": "string",
|
|
"pattern": "\\.trajectory\\.json$"
|
|
}
|
|
}
|
|
},
|
|
"webRuntime": {
|
|
"type": "object",
|
|
"required": [
|
|
"model",
|
|
"glue",
|
|
"wasm",
|
|
"commit",
|
|
"unverifiedByTheConsumer"
|
|
],
|
|
"properties": {
|
|
"model": {
|
|
"const": "onnx"
|
|
},
|
|
"glue": {
|
|
"const": "runtime/web/controller.js"
|
|
},
|
|
"wasm": {
|
|
"const": "runtime/web/controller.wasm"
|
|
},
|
|
"commit": {
|
|
"type": "string"
|
|
},
|
|
"unverifiedByTheConsumer": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
},
|
|
"mjlabRuntime": {
|
|
"type": "object",
|
|
"required": [
|
|
"model",
|
|
"extensions",
|
|
"commit"
|
|
],
|
|
"properties": {
|
|
"model": {
|
|
"const": "onnx"
|
|
},
|
|
"extensions": {
|
|
"description": "By `sysconfig.get_platform()` of the machine it runs on: the build machine's, and `win-amd64` and `macosx-universal2`, cross-built. macOS is keyed without a version (`mjrl.app_play.extension_for`).",
|
|
"type": "object",
|
|
"minProperties": 1,
|
|
"additionalProperties": {
|
|
"type": "object",
|
|
"required": [
|
|
"file",
|
|
"abi"
|
|
],
|
|
"properties": {
|
|
"file": {
|
|
"type": "string",
|
|
"pattern": "^runtime/mjlab/[a-z0-9._-]+/controller\\.(so|pyd)$"
|
|
},
|
|
"abi": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"commit": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
},
|
|
"boardRuntime": {
|
|
"type": "object",
|
|
"required": [
|
|
"model",
|
|
"file",
|
|
"platform",
|
|
"commit"
|
|
],
|
|
"properties": {
|
|
"model": {
|
|
"const": "rknn"
|
|
},
|
|
"file": {
|
|
"const": "runtime/board/controller"
|
|
},
|
|
"platform": {
|
|
"const": "aarch64-unknown-linux-gnu"
|
|
},
|
|
"commit": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
},
|
|
"manual": {
|
|
"description": "manual.<language>.json. A translation keeps every field of manual.en.json and changes only the text ones: source, summary, enter, leave, keyboard, pad, does. The pad and the keyboard are listed apart, in each mode and among the switches (since 2026-09-29).",
|
|
"type": "object",
|
|
"required": [
|
|
"schema",
|
|
"language",
|
|
"bundle",
|
|
"source",
|
|
"modes",
|
|
"switches"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"schema": {
|
|
"const": "kk-bundle-manual/1"
|
|
},
|
|
"language": {
|
|
"type": "string",
|
|
"pattern": "^[a-z]{2}(-[A-Za-z]+)?$"
|
|
},
|
|
"bundle": {
|
|
"type": "string"
|
|
},
|
|
"source": {
|
|
"type": "string"
|
|
},
|
|
"modes": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"items": {
|
|
"type": "object",
|
|
"required": [
|
|
"mode",
|
|
"task",
|
|
"default",
|
|
"summary",
|
|
"enter",
|
|
"leave",
|
|
"keyboard",
|
|
"controls",
|
|
"keys"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"mode": {
|
|
"type": "string"
|
|
},
|
|
"task": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"default": {
|
|
"type": "boolean"
|
|
},
|
|
"summary": {
|
|
"type": "string"
|
|
},
|
|
"enter": {
|
|
"type": "string"
|
|
},
|
|
"leave": {
|
|
"type": "string"
|
|
},
|
|
"keyboard": {
|
|
"type": "string"
|
|
},
|
|
"controls": {
|
|
"description": "The pad in this mode: each control and what it does.",
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"required": [
|
|
"control",
|
|
"pad",
|
|
"does"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"control": {
|
|
"type": "string"
|
|
},
|
|
"pad": {
|
|
"type": "string"
|
|
},
|
|
"does": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"keys": {
|
|
"description": "The keyboard in this mode: each keystroke, as printed on the keys, and what it does.",
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"required": [
|
|
"key",
|
|
"does"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"key": {
|
|
"type": "string"
|
|
},
|
|
"does": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"switches": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"required": [
|
|
"device",
|
|
"control",
|
|
"with",
|
|
"keys",
|
|
"pad",
|
|
"does",
|
|
"from"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"device": {
|
|
"enum": [
|
|
"pad",
|
|
"keyboard"
|
|
]
|
|
},
|
|
"control": {
|
|
"type": "string"
|
|
},
|
|
"with": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"keys": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"pad": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"does": {
|
|
"type": "string"
|
|
},
|
|
"from": {
|
|
"type": [
|
|
"array",
|
|
"null"
|
|
],
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"policyBundle": {
|
|
"type": "object",
|
|
"required": [
|
|
"schema",
|
|
"runtimes",
|
|
"fsm",
|
|
"modes",
|
|
"notes",
|
|
"files",
|
|
"manuals",
|
|
"reference"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"schema": {
|
|
"const": "kk-policy-bundle/1"
|
|
},
|
|
"runtimes": {
|
|
"description": "Each host's build of the controller, keyed by host. A host whose build this bundle does not carry has no entry, and `notes` says how to add it.",
|
|
"type": "object",
|
|
"required": [
|
|
"web"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"web": {
|
|
"$ref": "#/$defs/webRuntime"
|
|
},
|
|
"mjlab": {
|
|
"$ref": "#/$defs/mjlabRuntime"
|
|
},
|
|
"board": {
|
|
"$ref": "#/$defs/boardRuntime"
|
|
}
|
|
}
|
|
},
|
|
"fsm": {
|
|
"const": "controller.toml"
|
|
},
|
|
"modes": {
|
|
"description": "Every state that runs a model, by the name controller.toml gives it.",
|
|
"type": "object",
|
|
"minProperties": 1,
|
|
"patternProperties": {
|
|
"^[a-z][a-z0-9_]*$": {
|
|
"$ref": "#/$defs/mode"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"notes": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"reference": {
|
|
"description": "The reference vectors' file, or null when none could be recorded.",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"manuals": {
|
|
"description": "The manual per language. English is always there; a translation is added after the build.",
|
|
"type": "object",
|
|
"required": [
|
|
"en"
|
|
],
|
|
"patternProperties": {
|
|
"^[a-z]{2}(-[A-Za-z]+)?$": {
|
|
"type": "string",
|
|
"pattern": "^manual\\.[a-z]{2}(-[A-Za-z]+)?\\.json$"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"built_from": {
|
|
"description": "Where every mode came from, for a bundle built from deploy/manifests.json.",
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "object",
|
|
"required": [
|
|
"task",
|
|
"from",
|
|
"export"
|
|
],
|
|
"properties": {
|
|
"task": {
|
|
"type": "string"
|
|
},
|
|
"from": {
|
|
"type": "string"
|
|
},
|
|
"export": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"files": {
|
|
"description": "Every file in the bundle but bundle.json itself, by its path inside it.",
|
|
"type": "object",
|
|
"minProperties": 1,
|
|
"additionalProperties": {
|
|
"type": "object",
|
|
"required": [
|
|
"bytes",
|
|
"sha256"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"bytes": {
|
|
"type": "integer"
|
|
},
|
|
"sha256": {
|
|
"type": "string",
|
|
"pattern": "^[0-9a-f]{64}$"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"robotApp": {
|
|
"type": "object",
|
|
"required": [
|
|
"schema",
|
|
"robot_id",
|
|
"model",
|
|
"default_mode",
|
|
"modes",
|
|
"controller",
|
|
"manuals",
|
|
"reference",
|
|
"verification",
|
|
"runtimes",
|
|
"capabilities",
|
|
"source",
|
|
"files"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"schema": {
|
|
"const": "mjrl-robot-app/1"
|
|
},
|
|
"robot_id": {
|
|
"type": "string",
|
|
"pattern": "^[a-z][a-z0-9_]*$"
|
|
},
|
|
"model": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*[\\\\:]).+$"
|
|
},
|
|
"default_mode": {
|
|
"type": "string"
|
|
},
|
|
"modes": {
|
|
"type": "object",
|
|
"minProperties": 1,
|
|
"patternProperties": {
|
|
"^[a-z][a-z0-9_]*$": {
|
|
"type": "object",
|
|
"required": [
|
|
"control_mode",
|
|
"contract"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"control_mode": {
|
|
"enum": [
|
|
"rl_onnx",
|
|
"ik_mocap",
|
|
"wheeled_velocity",
|
|
"cpg_keyframe",
|
|
"model_viewer"
|
|
]
|
|
},
|
|
"contract": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*[\\\\:]).+$"
|
|
},
|
|
"controls": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*[\\\\:]).+$"
|
|
},
|
|
"policy": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*[\\\\:]).+$"
|
|
},
|
|
"layout": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*[\\\\:]).+$"
|
|
},
|
|
"verification": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*[\\\\:]).+$"
|
|
}
|
|
},
|
|
"allOf": [
|
|
{
|
|
"if": {
|
|
"properties": {
|
|
"control_mode": {
|
|
"const": "rl_onnx"
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"required": [
|
|
"policy",
|
|
"layout"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"if": {
|
|
"properties": {
|
|
"control_mode": {
|
|
"not": {
|
|
"const": "model_viewer"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"required": [
|
|
"verification"
|
|
]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"controller": {
|
|
"const": "controller.toml"
|
|
},
|
|
"manuals": {
|
|
"description": "The manual per language. English is always there; a translation is added after the build.",
|
|
"type": "object",
|
|
"required": [
|
|
"en"
|
|
],
|
|
"patternProperties": {
|
|
"^[a-z]{2}(-[A-Za-z]+)?$": {
|
|
"type": "string",
|
|
"pattern": "^manual\\.[a-z]{2}(-[A-Za-z]+)?\\.json$"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"reference": {
|
|
"const": "reference.json"
|
|
},
|
|
"verification": {
|
|
"enum": [
|
|
"verification.json",
|
|
null
|
|
]
|
|
},
|
|
"runtimes": {
|
|
"type": "object",
|
|
"required": [
|
|
"native"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"native": {
|
|
"type": "object",
|
|
"required": [
|
|
"file",
|
|
"language",
|
|
"python",
|
|
"dependencies",
|
|
"platforms"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"file": {
|
|
"const": "runtime/controller.pyz"
|
|
},
|
|
"language": {
|
|
"const": "python"
|
|
},
|
|
"python": {
|
|
"type": "string"
|
|
},
|
|
"dependencies": {
|
|
"const": "runtime/requirements.txt"
|
|
},
|
|
"platforms": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"uniqueItems": true,
|
|
"items": {
|
|
"enum": [
|
|
"linux",
|
|
"windows",
|
|
"macos"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"capabilities": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"uniqueItems": true,
|
|
"items": {
|
|
"enum": [
|
|
"rl_onnx",
|
|
"ik_mocap",
|
|
"wheeled_velocity",
|
|
"cpg_keyframe",
|
|
"model_viewer"
|
|
]
|
|
}
|
|
},
|
|
"source": {
|
|
"type": "object",
|
|
"required": [
|
|
"model_sha256"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"model_sha256": {
|
|
"type": "string",
|
|
"pattern": "^[0-9a-f]{64}$"
|
|
}
|
|
}
|
|
},
|
|
"files": {
|
|
"description": "Every file in the bundle but bundle.json itself, by its path inside it.",
|
|
"type": "object",
|
|
"minProperties": 1,
|
|
"additionalProperties": {
|
|
"type": "object",
|
|
"required": [
|
|
"bytes",
|
|
"sha256"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"bytes": {
|
|
"type": "integer"
|
|
},
|
|
"sha256": {
|
|
"type": "string",
|
|
"pattern": "^[0-9a-f]{64}$"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"licenses": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"uniqueItems": true,
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Inventoried platform and explicitly supplied asset/policy license and attribution files."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"oneOf": [
|
|
{
|
|
"$ref": "#/$defs/policyBundle"
|
|
},
|
|
{
|
|
"$ref": "#/$defs/robotApp"
|
|
}
|
|
]
|
|
}
|