docs: add AI agent workflow guide and clean up residual single-robot references
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled

This commit is contained in:
2026-11-05 11:52:07 +08:00
parent c32df70326
commit d5e9004f6c
45 changed files with 252 additions and 231 deletions
+24 -26
View File
@@ -5,22 +5,23 @@ description: Translate a built bundle's manual.en.json into Chinese as manual.zh
# The bundle's manual, in Chinese # The bundle's manual, in Chinese
`scripts/deploy.py` writes `manual.en.json` (`kk-bundle-manual/1`) into every `scripts/deploy.py` writes `manual.en.json` into every bundle (both native
bundle: each pad control and each key the bundle reads, what it does in each `mjrl-robot-app/1` bundles and legacy `kk-policy-bundle/1` bundles): each pad
mode, how each mode is reached and left, and every mode switch. It is generated control and each key the bundle reads, what it does in each mode, how each mode
from the controller's own account of its controls (`padGuide`), so it cannot is reached and left, and every mode switch. It is generated from the
disagree with the bindings. The pad and the keyboard are two paths since controller's own account of its controls, so it cannot disagree with the
2026-09-29 and the manual lists them apart: in each mode `controls` is the pad bindings. The pad and the keyboard are separate paths and the manual lists them
and `keys` the keyboard, and each switch says which `device` it is on. The apart: in each mode `controls` is the pad and `keys` the keyboard, and each
Chinese version is a translation of it, and this skill is how it is made: the switch says which `device` it is on. The Chinese version is a translation of
build cannot write natural Chinese, and a person or an agent can. it, and this skill is how it is made: the build cannot write natural Chinese,
and a person or an agent can.
## Steps ## Steps
1. Find the bundle directory. `deploy.py` prints it 1. Find the bundle directory. `deploy.py` writes `<bundle_parent>/<robot_id>`
(`[deploy] bundled <commit> -> …/out/bundle_<ts>/<name>`) and then prints the (alongside `<robot_id>.app`) and prints the `--translate` command with that
`--translate` command with that path already filled in. It holds path already filled in. The directory holds `manual.en.json` and
`manual.en.json` and `bundle.json`. `bundle.json`.
2. Read `manual.en.json` in full. 2. Read `manual.en.json` in full.
3. Write `manual.zh.json` somewhere outside the bundle (a scratch file): 3. Write `manual.zh.json` somewhere outside the bundle (a scratch file):
- the same JSON, field for field, in the same order; - the same JSON, field for field, in the same order;
@@ -34,22 +35,21 @@ build cannot write natural Chinese, and a person or an agent can.
entry in a mode's `keys` (`W`, `;`, `Space`, `↑`), and the `keys` entry in a mode's `keys` (`W`, `;`, `Space`, `↑`), and the `keys`
lists of `switches` (`Space`, `Ctrl + 1`, `Num 1`). They are identifiers, lists of `switches` (`Space`, `Ctrl + 1`, `Num 1`). They are identifiers,
and the check below refuses a translation that changes one. and the check below refuses a translation that changes one.
4. Add it to the bundle, which checks it and packs the `.app` again: 4. Add it to the bundle, which checks it and packs the `.app` archive again:
```bash ```bash
python scripts/deploy.py --translate out/bundle_<ts>/<name> --language zh --manual <scratch file> python scripts/deploy.py --translate <bundle-dir> --language zh --manual <scratch file>
``` ```
It refuses a file whose non-text fields differ from the English one, and It refuses a file whose non-text fields differ from the English one, and
holds the result to `deploy/app.schema`. Fix what it names and run it again. validates the result against the bundle's schema (`rl/mjrl/platform/app.schema`
5. If the `.app` is going to be committed (bundles are committed under for native apps or `deploy/app.schema` for legacy bundles). Fix what it names
`out/bundle_<ts>/<name>.app`), commit it after this step, not before: the and run it again.
translation changes the archive.
## How to write it ## How to write it
For someone holding a gamepad or sitting at a keyboard, in plain Chinese. Keep For someone holding a gamepad or sitting at a keyboard, in plain Chinese. Keep
mode names as identifiers where they name a mode (`进入 jump`), and say what the mode names as identifiers where they name a mode (`进入 locomotion`), and say what the
mode is in the sentence when the English does. The manual lists each mode's mode is in the sentence when the English does. The manual lists each mode's
keys on their own; say what a key does, never which pad control it is -- the keys on their own; say what a key does, never which pad control it is -- the
English never says that either. English never says that either.
@@ -79,16 +79,14 @@ English never says that either.
| let go of everything: every control back to rest | 全部松开:所有操作回到静止 | | let go of everything: every control back to rest | 全部松开:所有操作回到静止 |
| switch to X; press again to switch back | 进入 X;再按一次退出 | | switch to X; press again to switch back | 进入 X;再按一次退出 |
| (from X, Y only) | (仅在 X、Y 中有效) | | (from X, Y only) | (仅在 X、Y 中有效) |
| leave X, Y -- whichever is on -- back to locomotion | 退出 X、Y 中正在进行的那一个,回到 locomotion | | leave X, Y -- whichever is on -- back to default | 退出 X、Y 中正在进行的那一个,回到默认模式 |
| click A once / double-click A / triple-click A | 单击 A / 双击 A / 三连击 A | | click A once / double-click A / triple-click A | 单击 A / 双击 A / 三连击 A |
| click A four times / click A five times | 四连击 A / 五连击 A | | click A four times / click A five times | 四连击 A / 五连击 A |
| switch to X; double-click again to switch back | 进入 X;再双击一次退出 | | switch to X; double-click again to switch back | 进入 X;再双击一次退出 |
A task's own words -- `closes the left claw as far as it is held`, from its A mode's custom control descriptions from its `controls.yaml` are translated
`controls.yaml` -- are translated like any other text: `按多深,左爪就夹多紧`; like any other text (for example, `drives the elbow joint target` becomes
`holds the carried arm straight out, thumb up, while held` is `驱动肘关节目标位置`). Each mode lists only the controls bound in that mode, so
`按住时手臂向前伸直,拇指朝上`, and thumb-web up is `虎口朝上`. A claw mode lists
only its own side's claw (the left claw's lists `LT` and Space, not `RT`), so
translate what is there and add nothing. translate what is there and add nothing.
## Why a separate step ## Why a separate step
@@ -61,8 +61,8 @@ DIFFERENTIAL_KEYS = {
KeyDirections = tuple[tuple[str, ...], tuple[str, ...]] KeyDirections = tuple[tuple[str, ...], tuple[str, ...]]
#: The keys that let go of everything, as the pad's release button does: Esc. #: The keys that let go of everything, as the pad's release button does: Esc.
#: The keyboard's own, whatever button `--release` gives the pad. It was B until #: The keyboard's own release key, independent of whichever button `--release`
#: Control-agent 3.1 put the right claw there (2026-09-29). #: binds on the gamepad.
RELEASE_KEYS = ("key_escape",) RELEASE_KEYS = ("key_escape",)
#: Seconds a key is held for its direction to reach full deflection; it is back #: Seconds a key is held for its direction to reach full deflection; it is back
@@ -91,8 +91,8 @@ def check(name: str, kind: str, allowed) -> None:
absent = vocabulary.absent() absent = vocabulary.absent()
extra = f"\n {absent[name]}" if name in absent else "" extra = f"\n {absent[name]}" if name in absent else ""
raise SystemExit( raise SystemExit(
f"[controls] {name!r} is not {kind} the robot's pad service publishes.\n" f"[controls] {name!r} is not {kind} in the shared gamepad vocabulary.\n"
f" It publishes: {' '.join(allowed)}{extra}\n" f" Allowed: {' '.join(allowed)}{extra}\n"
f" python -m controller --vocabulary" f" python -m controller --vocabulary"
) )
@@ -177,13 +177,11 @@ def render(task: str, axes: list[str], bind: dict[str, tuple[str, int]],
out.append(" # The wheeled template scales this required pad channel to zero.") out.append(" # The wheeled template scales this required pad channel to zero.")
out.append(f" {axis}: {{ source: {source}, sign: {sign} }}") out.append(f" {axis}: {{ source: {source}, sign: {sign} }}")
out += [ out += [
" # MEASURED: the signs are not measured against the robot's pad service.", " # `controller/xbox.py` uses the evdev convention -- ABS_Y positive is",
" # `controller/xbox.py` states the same evdev convention -- ABS_Y positive", " # **down**, ABS_X positive is **right**. Confirm stick signs on the intended",
" # is **down**, ABS_X positive is **right** -- and the service passes both", " # input device during verification.",
" # through unchanged, negating `dpad_y` and not `Ly`. Pushing the stick on",
" # the robot is what would settle it.",
" #", " #",
" # The service applies a 0.15 deadband and **rescales**, so full deflection", " # The input layer applies a 0.15 deadband and **rescales**, so full deflection",
" # still reaches ±1. A consumer that applies its own on top narrows the", " # still reaches ±1. A consumer that applies its own on top narrows the",
" # range a person can ask for and cannot tell that it has.", " # range a person can ask for and cannot tell that it has.",
" deadzone: device_reported_rescaled", " deadzone: device_reported_rescaled",
+4 -3
View File
@@ -111,9 +111,10 @@ remedy and where the long form lives:
- **D — the task registry.** Loads no simulation dependencies, so it passes even where the GPU is - **D — the task registry.** Loads no simulation dependencies, so it passes even where the GPU is
broken. A failure here is a packaging problem, not a simulation one — which is worth knowing broken. A failure here is a packaging problem, not a simulation one — which is worth knowing
before looking in the wrong place. before looking in the wrong place.
- **E — the Rust toolchain builds the controller's host targets.** `cargo check` of the browser's - **E — the Rust toolchain builds the legacy controller's host targets.** `cargo check` of the
wasm and of `play --app`'s extension, and the wasm-bindgen CLI against `Cargo.lock`. It builds browser's wasm and of the legacy `play --app` extension (`kk-policy-bundle/1`), and the
rather than reading versions, because a missing target or linker passes `cargo --version`. wasm-bindgen CLI against `Cargo.lock`. (Native `mjrl-robot-app/1` bundles run in pure Python.)
It builds rather than reading versions, because a missing target or linker passes `cargo --version`.
- **F — the device build links and loads.** `cargo test --lib -- --list` with the default - **F — the device build links and loads.** `cargo test --lib -- --list` with the default
features: CycloneDDS, libclang, Rockchip's NPU header and a `libddsc` the loader finds. `--list` runs the binary features: CycloneDDS, libclang, Rockchip's NPU header and a `libddsc` the loader finds. `--list` runs the binary
without running a test, so a failing crate test is not reported as an environment fault. without running a test, so a failing crate test is not reported as an environment fault.
+3 -2
View File
@@ -122,7 +122,7 @@ def find_repo():
"""The repository root, if we are standing in it. """The repository root, if we are standing in it.
Identified by pyproject naming this project rather than by the directory Identified by pyproject naming this project rather than by the directory
name, which is routinely different (kk-rl-mjlab, mjrl-lab, a worktree path). name, which is routinely different (mjrl-lab, a custom clone name, or a worktree path).
""" """
here = os.path.abspath(os.getcwd()) here = os.path.abspath(os.getcwd())
while True: while True:
@@ -437,7 +437,8 @@ def main():
"" if steps else ": nothing missing")) "" if steps else ": nothing missing"))
for step in steps: for step in steps:
print(" %s" % step) print(" %s" % step)
print("\n Then verify: python <skill>/scripts/gates.py") print("\n Then verify: python <skill>/scripts/gates.py --python-only")
print(" (omit --python-only to also check legacy Rust targets)")
return 0 return 0
+3 -3
View File
@@ -94,9 +94,9 @@ def locked_version(repo: Path, package: str) -> str | None:
def find_repo(start: Path | None = None) -> Path | None: def find_repo(start: Path | None = None) -> Path | None:
"""The repository root, identified by pyproject rather than directory name. """The repository root, identified by pyproject rather than directory name.
The directory is routinely named something else -- kk-rl-mjlab, a git The directory is routinely named something else -- mjrl-lab, a custom clone
worktree path -- so matching on the name would fail on the machines this is name, or a git worktree path -- so matching on the name would fail on the
most needed on. machines this is most needed on.
""" """
here = (start or Path.cwd()).resolve() here = (start or Path.cwd()).resolve()
for candidate in [here, *here.parents]: for candidate in [here, *here.parents]:
+4 -3
View File
@@ -3,20 +3,21 @@ __pycache__/
*.py[cod] *.py[cod]
*.egg-info/ *.egg-info/
.pytest_cache/ .pytest_cache/
.ruff_cache/
.venv/ .venv/
venv/ venv/
build/ build/
dist/ dist/
# Training artefacts # Training and packaging artefacts
logs/ logs/
runs/ runs/
outputs/ outputs/
# scripts/export.py's default output directory # Default output directory for scripts/deploy.py and onboarding reports
out/ out/
*.pt *.pt
*.onnx *.onnx
# deploy/onnx2rknn.py's output, and the record of what built it # deploy/convert/onnx2rknn.py's output, and the record of what built it
*.rknn *.rknn
*.rknn.json *.rknn.json
wandb/ wandb/
+4 -1
View File
@@ -24,6 +24,7 @@ mjrl-lab/
│ ├── dds/ # legacy wire interface │ ├── dds/ # legacy wire interface
│ └── fsm/ # legacy Rust controller │ └── fsm/ # legacy Rust controller
├── docs/ # manuals and design notes ├── docs/ # manuals and design notes
├── notebooks/ # Colab GPU training notebook and guides
├── rl/ ├── rl/
│ ├── mjlab/ # vendored simulator and manager library │ ├── mjlab/ # vendored simulator and manager library
│ ├── mjrl/ │ ├── mjrl/
@@ -31,7 +32,9 @@ mjrl-lab/
│ │ ├── controllers/ # deterministic controller models │ │ ├── controllers/ # deterministic controller models
│ │ ├── onboarding/ # inspect, build, calibrate, verify │ │ ├── onboarding/ # inspect, build, calibrate, verify
│ │ ├── platform/ # native app assembly and runtime │ │ ├── platform/ # native app assembly and runtime
│ │ └── tasks/ # reusable MDP and curriculum code │ │ ├── sensor/ # native camera and raycast sensors
│ │ ├── tasks/ # reusable MDP and curriculum code
│ │ └── viewer/ # live viewer, telemetry, and video recording
│ └── rsl_rl/ # vendored learning algorithms │ └── rsl_rl/ # vendored learning algorithms
├── scenes/ # built-in world configurations ├── scenes/ # built-in world configurations
├── scripts/ # onboard, train, play, export, deploy ├── scripts/ # onboard, train, play, export, deploy
+17 -1
View File
@@ -14,6 +14,22 @@ on native MuJoCo CPU or MuJoCo Warp GPU.
| 2 | Complete robot model and known kinematics | Deterministic controller and native verification report | | 2 | Complete robot model and known kinematics | Deterministic controller and native verification report |
| 3 | Legged robot with a calibrated stance and explicit control intent | Robot specification and training through a locked morphology template | | 3 | Legged robot with a calibrated stance and explicit control intent | Robot specification and training through a locked morphology template |
## Train with an AI Agent (Recommended)
We recommend opening this repository folder directly in an AI coding agent
(such as Claude Code, Antigravity, Cursor, or Codex) and instructing the AI in
natural language to onboard and train your robot.
The repository includes [AGENTS.md](AGENTS.md), [CLAUDE.md](CLAUDE.md), and
specialized workflow skills under `.claude/skills/` (`setup-env`,
`onboard-asset`, `tier1-adapt`, `tier2-control`, `tier3-train`, `new-task`,
`train`, `controls`, `deploy`, and `bundle-manual`). When opened at the
repository root, the agent automatically follows these rules and verification
gates—you can simply point it at your URDF, MJCF, or mesh directory and ask it
to set up the environment, inspect and calibrate the model, generate
`tasks/<robot_id>/robot_spec.py`, launch or resume PPO training, run measured
replay probes, and package a native `.app` bundle.
## Run the model viewer ## Run the model viewer
From the checkout, with Python 3.10–3.13: From the checkout, with Python 3.10–3.13:
@@ -76,5 +92,5 @@ and unsuccessful trials, with their measured reasons.
- [Tutorial](docs/TUTORIAL.md) for verification, training, and measured replay. - [Tutorial](docs/TUTORIAL.md) for verification, training, and measured replay.
- [Colab](docs/COLAB.md) for GPU training with your own registered robot. - [Colab](docs/COLAB.md) for GPU training with your own registered robot.
- [Hardware and model facts](docs/HARDWARE.md) for calibration and actuator inputs. - [Hardware and model facts](docs/HARDWARE.md) for calibration and actuator inputs.
- [Deployment format](deploy/BUNDLE.md) for application contents and runtime contracts. - [Deploy guide](deploy/README.md) and [deployment format](deploy/BUNDLE.md) for application contents and runtime contracts.
- [Contributing](CONTRIBUTING.md) for repository layout and checks. - [Contributing](CONTRIBUTING.md) for repository layout and checks.
+13 -7
View File
@@ -1,6 +1,6 @@
# MJRL 机器人平台 # MJRL 机器人平台
<!-- tracks: README.md @ sha256:5e58614ff2c467bd --> <!-- tracks: README.md @ sha256:124d41b6e17eb69c -->
[English](README.md) · [接入流程](docs/WORKFLOWS.md) · [命令手册](docs/USAGE.zh.md) [English](README.md) · [接入流程](docs/WORKFLOWS.md) · [命令手册](docs/USAGE.zh.md)
@@ -15,6 +15,12 @@ MuJoCo Warp GPU 上训练运动策略。
| 2 | 完整模型与已知运动学 | 确定性控制器及原生验证报告 | | 2 | 完整模型与已知运动学 | 确定性控制器及原生验证报告 |
| 3 | 站姿已标定且控制意图明确的足式机器人 | 机器人规格及锁定形态模板训练 | | 3 | 站姿已标定且控制意图明确的足式机器人 | 机器人规格及锁定形态模板训练 |
## 使用 AI Agent 进行接入与训练(推荐)
建议使用 AI Agent(如 Claude Code、Antigravity、Cursor、Codex 等)直接打开本仓库根目录文件夹,并通过自然语言指挥 AI 进行机器人接入、训练与打包。
仓库内置了 [AGENTS.md](AGENTS.md)、[CLAUDE.md](CLAUDE.md) 以及位于 `.claude/skills/` 下的专用工作流技能(`setup-env`、`onboard-asset`、`tier1-adapt`、`tier2-control`、`tier3-train`、`new-task`、`train`、`controls`、`deploy`、`bundle-manual`)。在仓库根目录下打开后,AI Agent 会自动读取工作规则与验证门禁——你只需告知 URDF、MJCF 或网格模型路径,即可指挥 AI 自动完成环境配置、模型检查与站姿标定、生成 `tasks/<robot_id>/robot_spec.py`、启动或恢复 PPO 训练、执行量化回放评测以及打包原生 `.app` 应用。
## 运行模型查看应用 ## 运行模型查看应用
在代码库根目录中使用 Python 3.10–3.13: 在代码库根目录中使用 Python 3.10–3.13:
@@ -65,9 +71,9 @@ Python 和所列依赖。现有 Rust 浏览器与板端走独立的旧版包格
## 参考 ## 参考
- [项目指南](docs/PROJECT_GUIDE.zh.md) - [项目指南](docs/PROJECT_GUIDE.zh.md):导航与支持边界说明。
- [教程](docs/TUTORIAL.zh.md) - [教程](docs/TUTORIAL.zh.md):验证、训练与量化回放流程。
- [Colab](docs/COLAB.zh.md) 用于在 GPU 上训练自己注册的机器人 - [Colab](docs/COLAB.zh.md):在 GPU 上训练已注册的机器人。
- [硬件与模型参数](docs/HARDWARE.zh.md) - [硬件与模型参数](docs/HARDWARE.zh.md):标定要求与执行器输入规范。
- [部署包格式](deploy/BUNDLE.md) - [部署指南](deploy/README.zh.md)与[部署包格式](deploy/BUNDLE.md):应用结构与运行时契约。
- [贡献指南](CONTRIBUTING.md) - [贡献指南](CONTRIBUTING.md):目录结构与仓库检查项。
+5 -3
View File
@@ -84,10 +84,12 @@ and settled after Escape.
The packaged runtime reproduced seven 12-second probes, including sampled The packaged runtime reproduced seven 12-second probes, including sampled
joint state and per-axis body-frame tracking metrics. The app includes the joint state and per-axis body-frame tracking metrics. The app includes the
asset license and provenance along with English and Chinese operator manuals. asset license and provenance along with English and Chinese operator manuals.
After building the app, use the repository's native reference checker. Build the app and run the repository's native reference checker:
```bash ```bash
python scripts/deploy.py --check-reference out/platform_release_20261104/go1_example.app python scripts/deploy.py --robot go1_example --checkpoint <checkpoint.pt> \
python scripts/play.py --app out/platform_release_20261104/go1_example.app --headless \ --output out/go1_example_bundle
python scripts/deploy.py --check-reference out/go1_example_bundle/go1_example.app
python scripts/play.py --app out/go1_example_bundle/go1_example.app --headless \
--steps 200 --command 0.4 0 0 --steps 200 --command 0.4 0 0
``` ```
+1 -1
View File
@@ -20,7 +20,7 @@ python scripts/onboard.py calibrate --model assets/multipod_example/multipod.xml
python scripts/onboard.py scaffold-tier3 --config assets/multipod_example/robot.json \ python scripts/onboard.py scaffold-tier3 --config assets/multipod_example/robot.json \
--calibration out/multipod-calibration.json --tasks-root out/multipod-scaffold --calibration out/multipod-calibration.json --tasks-root out/multipod-scaffold
python scripts/train.py --task multipod_example --backend native --device cpu \ python scripts/train.py --task multipod_example --backend native --device cpu \
--num_envs 4 --max-iterations 1 --headless --no-tensorboard --num-envs 4 --max-iterations 1 --headless --no-tensorboard
``` ```
The checked-in robot specification is the calibrated task used by the The checked-in robot specification is the calibrated task used by the
+1 -1
View File
@@ -138,7 +138,7 @@ whether the reader pairs at all -- and a mismatch does not raise, it leaves
The 2026-09-29 refresh is that case again. The `ImuData` fields reached mbus master The 2026-09-29 refresh is that case again. The `ImuData` fields reached mbus master
only in the 2026-09-28 merge, mbus's CHANGELOG has no release entry for them yet, and only in the 2026-09-28 merge, mbus's CHANGELOG has no release entry for them yet, and
the board last read (`deploy/README.md`) ran libmbus 2.4.0, from 2026-09-02. A the board last read ran libmbus 2.4.0, from 2026-09-02. A
controller built from this tree pairs with an `mc_ctrl_driver` / `mc_forwarder` rebuilt controller built from this tree pairs with an `mc_ctrl_driver` / `mc_forwarder` rebuilt
against `d9875988f065` or later, and with nothing older. `check_board.py` compares the against `d9875988f065` or later, and with nothing older. `check_board.py` compares the
board's `idl_motor_control.h` with the one generated here and says which it is. board's `idl_motor_control.h` with the one generated here and says which it is.
+1 -1
View File
@@ -261,7 +261,7 @@ operator fresh either way, so sending it every frame is harmless.
a page that wants to say which keys do something: `controls` is each mode's own a page that wants to say which keys do something: `controls` is each mode's own
account of its bindings -- the lines the robot's controller prints before it account of its bindings -- the lines the robot's controller prints before it
enables the motors -- on one line, the modes that read the pad alike named enables the motors -- on one line, the modes that read the pad alike named
together: `claw_left, claw_right: … | locomotion: …`. Show it as given; together: `stand: … | locomotion: …`. Show it as given;
describing the bundle yourself would be a second copy of its bindings. describing the bundle yourself would be a second copy of its bindings.
`fsm.bindings()` returns `[{name, pad, key, on, with, from, leaves}]` -- the mode `fsm.bindings()` returns `[{name, pad, key, on, with, from, leaves}]` -- the mode
+11 -11
View File
@@ -13,8 +13,8 @@ places they have to run:
| | observation from | inference on | execution to | | | observation from | inference on | execution to |
|---|---|---|---| |---|---|---|---|
| `kk-rl-mjlab`'s `play` | mjlab's simulation | ONNX, on the host | mjlab actuators | | `mjrl-lab`'s `play` | mjlab's simulation | ONNX, on the host | mjlab actuators |
| BEUNLIMITED's web sim | MuJoCo WASM | ONNX, in the browser | the same actuators | | the browser web sim | MuJoCo WASM | ONNX, in the browser | the same actuators |
| the robot | servos and IMU | RKNN, on the NPU | DDS to the motor controller | | the robot | servos and IMU | RKNN, on the NPU | DDS to the motor controller |
That logic existed **three times**: this crate in Rust, `rl-wbc-fsm` in C++, That logic existed **three times**: this crate in Rust, `rl-wbc-fsm` in C++,
@@ -162,7 +162,7 @@ locomotion on `device`:
``` ```
**That list is the sim2real gap, enumerated.** Nobody can see it today. It costs **That list is the sim2real gap, enumerated.** Nobody can see it today. It costs
one field per term in the exported contract — every term kk-rl-mjlab exports is one field per term in the exported contract — every term `mjrl-lab` exports is
`Simulated`, so producing it is nearly free, and the value is entirely on the `Simulated`, so producing it is nearly free, and the value is entirely on the
consuming side. consuming side.
@@ -292,8 +292,8 @@ So transitions become an **ordered rule list**, first match wins:
[[fsm.rule]] when = "in_state:safe" enter = "@initial" [[fsm.rule]] when = "in_state:safe" enter = "@initial"
[[fsm.rule]] when = "warm_start_reached" enter = "@warm_start_ref" [[fsm.rule]] when = "warm_start_reached" enter = "@warm_start_ref"
[[fsm.rule]] when = "in_state:warmstart" enter = "@stay" [[fsm.rule]] when = "in_state:warmstart" enter = "@stay"
[[fsm.rule]] when = "button:jump" enter = "jump" [[fsm.rule]] when = "button:stand" enter = "stand"
[[fsm.rule]] when = "button:claw_left" enter = "claw_left" [[fsm.rule]] when = "button:motion" enter = "motion"
[[fsm.rule]] when = "always" enter = "locomotion" [[fsm.rule]] when = "always" enter = "locomotion"
``` ```
@@ -466,7 +466,7 @@ Built as of this document:
| the two-phase tick, four regimes, per-mode runtimes | `src/control.rs` | | the two-phase tick, four regimes, per-mode runtimes | `src/control.rs` |
| each mode's reading of the pad and keys, command shaping | `src/operator.rs` | | each mode's reading of the pad and keys, command shaping | `src/operator.rs` |
| the pad's manual as data (`pad_guide`) | `src/guide.rs` | | the pad's manual as data (`pad_guide`) | `src/guide.rs` |
| a task's deploy hook, compiled in from `tasks/**/deploy/lib.rs` by `build.rs` | `src/hook.rs` | | an optional task deploy hook, compiled in from `tasks/**/deploy/lib.rs` by `build.rs` | `src/hook.rs` |
| the recorded motion a reference-guided mode is driven by | `src/trajectory.rs` | | the recorded motion a reference-guided mode is driven by | `src/trajectory.rs` |
| a recorded run replayed, and where a host differs | `src/reference.rs` | | a recorded run replayed, and where a host differs | `src/reference.rs` |
| the bundle format, one reader for every host with a filesystem | `src/bundle.rs` | | the bundle format, one reader for every host with a filesystem | `src/bundle.rs` |
@@ -475,11 +475,11 @@ Built as of this document:
| `play`'s host: the pyo3 `Fsm` | `src/py.rs` | | `play`'s host: the pyo3 `Fsm` | `src/py.rs` |
| the robot's program: the loop, the two clocks, the shutdown path | `src/bin/controller.rs` | | the robot's program: the loop, the two clocks, the shutdown path | `src/bin/controller.rs` |
156 tests. Two of them are control groups, because both of these modules replace 162 tests in the generic controller core. Two of them are control groups, because both of these modules replace
something that was previously written into code and would pass every obvious something that was previously written into code and would pass every obvious
assertion while ignoring the file: `the_cascade_is_the_file_s_rather_than_agreeing_with_it` assertion while ignoring the file: `the_cascade_is_the_file_s_rather_than_agreeing_with_it`
moves the tilt rule below the operator's button and requires a tilted robot to moves the tilt rule below the operator's button and requires a tilted robot to
jump, and `the_check_reads_what_training_recorded_rather_than_assuming_it` trains switch modes, and `the_check_reads_what_training_recorded_rather_than_assuming_it` trains
a term as reconstructed and requires simulation to be reported as the divergence. a term as reconstructed and requires simulation to be reported as the divergence.
`control.rs` earned a third test the hard way. Its first `publish` used `control.rs` earned a third test the hard way. Its first `publish` used
@@ -507,8 +507,8 @@ into a `button:<name>` the rules can match. `pump` is compiled against the real
`[[fsm.button]]` names one thing the operator can ask for and which control asks `[[fsm.button]]` names one thing the operator can ask for and which control asks
it: a pad button or a keyboard key, one device per entry, and two entries with it: a pad button or a keyboard key, one device per entry, and two entries with
one name share its latch -- the pad's A and the keyboard's Space are both the one name share its latch -- the pad's A and the keyboard's Space can both drive
jump. It also carries the gesture (`rise`, `fall`, `hold`, `toggle`, or a click the same mode switch. It also carries the gesture (`rise`, `fall`, `hold`, `toggle`, or a click
count `single` … `quintuple` counted inside `[fsm] click_window_ms`), an optional count `single` … `quintuple` counted inside `[fsm] click_window_ms`), an optional
`with` modifier (a pad button, or `ctrl` / `shift` / `alt` for a key), `from` `with` modifier (a pad button, or `ctrl` / `shift` / `alt` for a key), `from`
(the states it may be pressed in) and `leaves` (latches it lets go of). Pad (the states it may be pressed in) and `leaves` (latches it lets go of). Pad
@@ -598,6 +598,6 @@ second shutdown behaviour. None of it can be tested off the board.
## Open ## Open
- **Provenance in the exported contract.** Needs a field per observation term in - **Provenance in the exported contract.** Needs a field per observation term in
kk-rl-mjlab's exporter. Cheap to produce, and the whole value of the divergence `mjrl-lab`'s exporter. Cheap to produce, and the whole value of the divergence
list depends on it. list depends on it.
- **Per-mode command vocabulary**, above. - **Per-mode command vocabulary**, above.
+5 -5
View File
@@ -77,7 +77,7 @@ and one `.app` of it that somebody with none of this repository can use, on any
of the three hosts: of the three hosts:
```bash ```bash
python scripts/deploy.py python scripts/deploy.py --manifest <bundle-id>
``` ```
It runs the cross build above first, every time, so the board's binary in the It runs the cross build above first, every time, so the board's binary in the
@@ -94,7 +94,7 @@ removed rather than left for someone to upload. Then it is held to
For the wasm, a cargo build and wasm-bindgen are what it runs. Run it rather For the wasm, a cargo build and wasm-bindgen are what it runs. Run it rather
than them: it reads the commit **after** looking at the tree, suffixes it `-dirty` than them: it reads the commit **after** looking at the tree, suffixes it `-dirty`
when the controller's source has uncommitted changes -- the crate, and every file when the controller's source has uncommitted changes -- the crate, and every file
outside it the build reads, each task's hook among them (`SOURCES` in the script) outside it the build reads (`SOURCES` in the script)
-- and holds the wasm-bindgen CLI -- and holds the wasm-bindgen CLI
against the version the crate compiles with. The hand procedure lasted one day against the version the crate compiles with. The hand procedure lasted one day
before it recorded a commit whose source would have built a different controller before it recorded a commit whose source would have built a different controller
@@ -165,9 +165,9 @@ the policy `(0, 0)`.
**This is not cosmetic, and the C++ controller does not do it.** The policy is **This is not cosmetic, and the C++ controller does not do it.** The policy is
trained that way — zero magnitude is a value no phase can produce, i.e. an trained that way — zero magnitude is a value no phase can produce, i.e. an
unambiguous "hold still". A free-running unit-magnitude clock was measured during unambiguous "hold still". A free-running unit-magnitude clock was measured during
training to make the robot step in place while commanded to stand: roll-rate training to make the robot step in place while commanded to stand, with roll-rate
autocorrelation peaked at the clock frequency, and 5.17 of 6 feet were on the autocorrelation peaking at the clock frequency instead of holding all supports on
ground. the ground.
The failure is invisible to every dimension check: gated or not, `gait_phase` is The failure is invisible to every dimension check: gated or not, `gait_phase` is
2 wide and the observation is the same length. Only the values differ, and only 2 wide and the observation is the same length. Only the values differ, and only
+2 -2
View File
@@ -32,8 +32,8 @@ not free to float:
- `deploy/convert/requirements.txt` pins `rknn-toolkit2==2.3.2`, and a `.rknn` - `deploy/convert/requirements.txt` pins `rknn-toolkit2==2.3.2`, and a `.rknn`
does not load under a `librknnrt` older than the toolkit that produced it; does not load under a `librknnrt` older than the toolkit that produced it;
- the board carries `librknnrt` 2.3.2 (`deploy/README.md`, *Verified against the - the board carries `librknnrt` 2.3.2, and
board*), and `.claude/skills/deploy/scripts/check_board.py` checks it. `.claude/skills/deploy/scripts/check_board.py` checks it.
Moving to another release means changing all three together, and the two sha256 Moving to another release means changing all three together, and the two sha256
values in `fetch.sh` with them. values in `fetch.sh` with them.
+21 -15
View File
@@ -215,17 +215,18 @@ If this environment ever had them, uninstall first (this does not remove their d
pip uninstall -y mjlab rsl-rl-lib pip uninstall -y mjlab rsl-rl-lib
``` ```
### 2.1 The controller's toolchain: Rust ### 2.1 The legacy controller's toolchain: Rust
The controller (`deploy/fsm`) is Rust, one crate on three hosts. `scripts/deploy.py` builds two of The legacy controller (`deploy/fsm`) is Rust, one crate on three hosts. `scripts/deploy.py` builds
them on this machine with cargo — the browser's wasm and `play --app`'s extension — and two of them on this machine with cargo — the browser's wasm and the legacy `play --app` extension — and
cross-builds the board's binary and the Windows extension in Docker, which brings its own cross-builds the board's binary and the Windows extension in Docker, which brings its own
toolchain. **Every row of section 0's decision table needs this subsection**; it does not branch toolchain. Native platform `.app` bundles (`mjrl-robot-app/1`) run in pure Python without this
on the GPU. toolchain; install this subsection when building or testing legacy `kk-policy-bundle/1` browser,
board, or extension targets.
> ⚠️ **Without cargo the test suite does not fail, it skips.** `tests/test_fsm_extension.py` and > ⚠️ **Without cargo the legacy controller tests do not fail, they skip.** `tests/test_fsm_extension.py` and
> `tests/test_deploy_sources.py` skip when there is no cargo, so `pytest tests/` is green on a > `tests/test_deploy_sources.py` skip when there is no cargo, so `pytest tests/` is green on a
> machine that has never built the controller. > machine that has never built the legacy controller.
Four pieces. `detect.py` prints only the ones this machine lacks: Four pieces. `detect.py` prints only the ones this machine lacks:
@@ -307,7 +308,7 @@ export PATH=$CYCLONEDDS_HOME/bin:$PATH
``` ```
bindgen finds libclang in Xcode's command-line tools. Measured on an M3 Max (Darwin 25.5, bindgen finds libclang in Xcode's command-line tools. Measured on an M3 Max (Darwin 25.5,
cargo 1.95.0) on 2026-10-08: the build takes about two minutes, gate F lists 195 tests, and cargo 1.95.0): the build takes about two minutes, gate F lists 162 tests, and
`cargo test --lib` in `deploy/fsm` passes all of them. A test binary built before `cargo test --lib` in `deploy/fsm` passes all of them. A test binary built before
`CYCLONEDDS_HOME` was exported carries no rpath and aborts with `CYCLONEDDS_HOME` was exported carries no rpath and aborts with
`Library not loaded: @rpath/libddsc.11.dylib`; rebuild it (`cargo clean -p mjrl-fsm`) rather `Library not loaded: @rpath/libddsc.11.dylib`; rebuild it (`cargo clean -p mjrl-fsm`) rather
@@ -394,9 +395,11 @@ A `ModuleNotFoundError` here means `pip install -e .` was not run or did not suc
python scripts/train.py --list python scripts/train.py --list
``` ```
Expected: every `tasks/<robot_id>/robot_spec.py` appears by robot ID. A fresh Expected: every `tasks/<robot_id>/robot_spec.py` appears by robot ID (on a fresh
checkout reports an empty registry. This command loads no simulation checkout: `g1_example`, `go1_example`, `multipod_example`, and
dependencies. Check the editable install and literal robot specs if it fails. `wheeled_biped_example`), followed by the built-in scenes. This command loads no
simulation dependencies. Check the editable install and literal robot specs if
it fails.
### Gate E — The Rust toolchain builds the controller's host targets ### Gate E — The Rust toolchain builds the controller's host targets
@@ -420,7 +423,7 @@ a new machine also downloads them.
cargo test --locked --lib --manifest-path deploy/fsm/Cargo.toml -- --list cargo test --locked --lib --manifest-path deploy/fsm/Cargo.toml -- --list
``` ```
Expected: a list of lines ending in `: test` (179 of them on 2026-09-29). `--list` runs the test Expected: a list of lines ending in `: test` (162 in the generic controller core). `--list` runs the test
binary without running a test, so it proves `libddsc` is found at load time — which a binary without running a test, so it proves `libddsc` is found at load time — which a
`cargo check` never would — and a failing crate test cannot pass itself off as an environment `cargo check` never would — and a failing crate test cannot pass itself off as an environment
fault. 9 s cold on the same machine. A checkout without Rockchip's NPU header fails here, in fault. 9 s cold on the same machine. A checkout without Rockchip's NPU header fails here, in
@@ -516,9 +519,12 @@ wandb also works, but tensorboard is less trouble.)
infers defaults from the `mjData` of a resting pose, and a moving robot has many more contacts infers defaults from the `mjData` of a resting pose, and a moving robot has many more contacts
than a resting one. than a resting one.
Inspect the model's contact geometry and measure contact load. A capacity change **Remedy**: pass `--warp-max-constraints N` and/or `--warp-max-contacts N` on the command line
to the shared simulator recipe requires an explicit template revision and (for example, `g1_example` uses `--warp-max-constraints 300`). Warp runs record these capacities in
updated lock validation. `warp-allocation.json` beside their checkpoints for resume, replay, and export. Also inspect the
model's collision geometry (`onboard.py build-mjcf` or `tools/hull_collision.py`) if contact load is
unreasonably high. A default capacity change inside the shared simulator recipe requires an explicit
template revision and updated lock validation.
### `"cuda" device requested but this build of Warp does not support CUDA` ### `"cuda" device requested but this build of Warp does not support CUDA`
+20 -15
View File
@@ -1,9 +1,9 @@
<!-- tracks: AGENT_SETUP.md @ sha256:62621d9b01a77c30 --> <!-- tracks: AGENT_SETUP.md @ sha256:076262f3d4d73ae1 -->
# 环境搭建说明(写给 AI agent) # 环境搭建说明(写给 AI agent)
本文档写给**在一台全新机器上把 mjrl-lab 跑起来的 AI agent**。 本文档写给**在一台全新机器上把 mjrl-lab 跑起来的 AI agent**。
人类读者请从 [`../README.md`](../README.md) 开始。 人类读者请从 [`../README.zh.md`](../README.zh.md) 开始。
## 机械的部分由两个脚本完成 ## 机械的部分由两个脚本完成
@@ -203,15 +203,15 @@ pip install -e .
pip uninstall -y mjlab rsl-rl-lib pip uninstall -y mjlab rsl-rl-lib
``` ```
### 2.1 控制器的工具链:Rust ### 2.1 旧版控制器的工具链:Rust
控制器(`deploy/fsm`)是 Rust 写的,一个 crate 跑在三种宿主上。`scripts/deploy.py` 在本机用 旧版控制器(`deploy/fsm`)是 Rust 写的,一个 crate 跑在三种宿主上。`scripts/deploy.py` 在本机用
cargo 构建其中两种 —— 浏览器的 wasm 和 `play --app` 的扩展 —— 板端二进制和 Windows 扩展则在 cargo 构建其中两种 —— 浏览器的 wasm 和旧版 `play --app` 的扩展 —— 板端二进制和 Windows 扩展则在
Docker 里交叉编译,镜像自带工具链。**第 0 节决策表的每一行都需要本小节**;它不按有没有 GPU Docker 里交叉编译,镜像自带工具链。原生平台 `.app` 应用(`mjrl-robot-app/1`)使用纯 Python 运行,
分叉。 不需要此工具链;仅当需要构建或测试旧版 `kk-policy-bundle/1` 的浏览器、板端或扩展目标时才需安装本小节。
> ⚠️ **没有 cargo 时测试集不会失败,而是跳过。** 没有 cargo,`tests/test_fsm_extension.py` 和 > ⚠️ **没有 cargo 时旧版控制器测试不会失败,而是跳过。** 没有 cargo,`tests/test_fsm_extension.py` 和
> `tests/test_deploy_sources.py` 会 skip,于是在一台从没构建过控制器的机器上, > `tests/test_deploy_sources.py` 会 skip,于是在一台从没构建过旧版控制器的机器上,
> `pytest tests/` 也是绿的。 > `pytest tests/` 也是绿的。
一共四样。`detect.py` 只打印这台机器缺的那几样: 一共四样。`detect.py` 只打印这台机器缺的那几样:
@@ -290,8 +290,8 @@ export CYCLONEDDS_HOME=$HOME/.local/opt/cyclonedds-11.0.1
export PATH=$CYCLONEDDS_HOME/bin:$PATH export PATH=$CYCLONEDDS_HOME/bin:$PATH
``` ```
bindgen 从 Xcode 命令行工具里找 libclang。2026-10-08 在一台 M3 Max(Darwin 25.5,cargo bindgen 从 Xcode 命令行工具里找 libclang。在一台 M3 Max(Darwin 25.5,cargo
1.95.0)上实测:构建约两分钟,gate F 列出 195 个测试,`deploy/fsm` 里 `cargo test --lib` 全部 1.95.0)上实测:构建约两分钟,gate F 列出 162 个测试,`deploy/fsm` 里 `cargo test --lib` 全部
通过。在 `export CYCLONEDDS_HOME` 之前构建出来的测试二进制没有 rpath,会以 通过。在 `export CYCLONEDDS_HOME` 之前构建出来的测试二进制没有 rpath,会以
`Library not loaded: @rpath/libddsc.11.dylib` 中止;重新构建它(`cargo clean -p mjrl-fsm`), `Library not loaded: @rpath/libddsc.11.dylib` 中止;重新构建它(`cargo clean -p mjrl-fsm`),
不必重装 CycloneDDS。 不必重装 CycloneDDS。
@@ -373,8 +373,9 @@ python -c "import mjlab, rsl_rl, os; print(os.path.dirname(mjlab.__file__)); pri
python scripts/train.py --list python scripts/train.py --list
``` ```
预期:每个 `tasks/<robot_id>/robot_spec.py` 按机器人 ID 列出。新检出报告空注册表。 预期:每个 `tasks/<robot_id>/robot_spec.py` 按机器人 ID 列出(新检出包含
该命令无需加载仿真依赖。失败时检查可编辑安装和机器人规格数据。 `g1_example`、`go1_example`、`multipod_example` 和 `wheeled_biped_example`),
随后列出内置场景。该命令无需加载仿真依赖。失败时检查可编辑安装和机器人规格数据。
### Gate E —— Rust 工具链能构建控制器的宿主目标 ### Gate E —— Rust 工具链能构建控制器的宿主目标
@@ -397,7 +398,7 @@ wasm-bindgen --version
cargo test --locked --lib --manifest-path deploy/fsm/Cargo.toml -- --list cargo test --locked --lib --manifest-path deploy/fsm/Cargo.toml -- --list
``` ```
预期:一串以 `: test` 结尾的行(2026-09-29 时是 179 行)。`--list` 会运行测试二进制但不执行 预期:一串以 `: test` 结尾的行(通用控制器核心包含 162 个测试)。`--list` 会运行测试二进制但不执行
任何测试,所以它能证明加载时找得到 `libddsc` —— 这是 `cargo check` 永远证明不了的 —— 同时 任何测试,所以它能证明加载时找得到 `libddsc` —— 这是 `cargo check` 永远证明不了的 —— 同时
crate 自己的测试失败也没法冒充成环境故障。同一台机器上冷构建 9 s。缺 Rockchip NPU 头文件的 crate 自己的测试失败也没法冒充成环境故障。同一台机器上冷构建 9 s。缺 Rockchip NPU 头文件的
checkout 会在这里、在 `build.rs` 中失败;解决办法是 `fetch.sh`(2.2 节)。 checkout 会在这里、在 `build.rs` 中失败;解决办法是 `fetch.sh`(2.2 节)。
@@ -485,7 +486,11 @@ tensorboard 省事。)
`njmax` / `nconmax` 是每个 world 上约束行数和接触数的上限。mujoco_warp 从静止姿态的 `njmax` / `nconmax` 是每个 world 上约束行数和接触数的上限。mujoco_warp 从静止姿态的
`mjData` 推断默认值,而运动中的机器人接触数比静止时多得多。 `mjData` 推断默认值,而运动中的机器人接触数比静止时多得多。
检查碰撞几何并测量接触负载。若需调整共享仿真容量,应明确修订模板并重新验证锁定规则。 **补救**:在命令行传入 `--warp-max-constraints N` 和/或 `--warp-max-contacts N`(例如
`g1_example` 使用 `--warp-max-constraints 300`)。Warp 训练会在检查点旁的
`warp-allocation.json` 中保存该容量供续训、回放和导出使用。若接触负载过高,也应检查碰撞几何
(`onboard.py build-mjcf` 或 `tools/hull_collision.py`)。若需调整共享仿真配方的默认容量,
应明确修订模板并重新验证锁定规则。
### `"cuda" device requested but this build of Warp does not support CUDA` ### `"cuda" device requested but this build of Warp does not support CUDA`
+1 -1
View File
@@ -16,7 +16,7 @@ platform. Use [Agent setup](AGENT_SETUP.md) to establish the environment and
| Extend the platform | [Contributing](../CONTRIBUTING.md) | | Extend the platform | [Contributing](../CONTRIBUTING.md) |
The checkout includes calibrated Go1, G1, six-legged and wheeled-biped examples, The checkout includes calibrated Go1, G1, six-legged and wheeled-biped examples,
covering all four locked families. G1 also has a separate compliant-gain variant. covering all four locked families.
Their asset READMEs distinguish execution checks, measured Their asset READMEs distinguish execution checks, measured
learning and accepted policies; registration alone is not a performance or learning and accepted policies; registration alone is not a performance or
hardware qualification. Add another robot with the onboarding tools to give it hardware qualification. Add another robot with the onboarding tools to give it
+2 -3
View File
@@ -1,6 +1,6 @@
# 项目指南 # 项目指南
<!-- tracks: PROJECT_GUIDE.md @ sha256:ed077c5edd6cf510 --> <!-- tracks: PROJECT_GUIDE.md @ sha256:1db03214fd026c6f -->
接入资产或策略时先读[接入流程](WORKFLOWS.md)。用[环境准备](AGENT_SETUP.zh.md) 接入资产或策略时先读[接入流程](WORKFLOWS.md)。用[环境准备](AGENT_SETUP.zh.md)
建立环境,用[命令手册](USAGE.zh.md)查询命令和配置。 建立环境,用[命令手册](USAGE.zh.md)查询命令和配置。
@@ -12,12 +12,11 @@
| 配置键盘或手柄 | [操作控制](CONTROLS.zh.md) | | 配置键盘或手柄 | [操作控制](CONTROLS.zh.md) |
| 训练和测量足式策略 | [教程](TUTORIAL.zh.md) | | 训练和测量足式策略 | [教程](TUTORIAL.zh.md) |
| 在 Colab GPU 上训练 | [Colab](COLAB.zh.md) | | 在 Colab GPU 上训练 | [Colab](COLAB.zh.md) |
| 打包原生应用或检查旧版部署包 | [部署指南](../deploy/README.md)与[包格式](../deploy/BUNDLE.md) | | 打包原生应用或检查旧版部署包 | [部署指南](../deploy/README.zh.md)与[包格式](../deploy/BUNDLE.md) |
| 理解双后端与模板锁定 | [平台设计](DESIGN.md)与[上游依赖](VENDOR.md) | | 理解双后端与模板锁定 | [平台设计](DESIGN.md)与[上游依赖](VENDOR.md) |
| 扩展平台 | [贡献指南](../CONTRIBUTING.md) | | 扩展平台 | [贡献指南](../CONTRIBUTING.md) |
本仓库包含经过标定的 Go1、G1、六足和轮足双足样例,覆盖四个锁定模板。 本仓库包含经过标定的 Go1、G1、六足和轮足双足样例,覆盖四个锁定模板。
G1 另有一个独立的柔顺增益变体。
各资产的 README 区分执行检查、实际学习效果与验收通过的策略;注册本身不代表 各资产的 README 区分执行检查、实际学习效果与验收通过的策略;注册本身不代表
性能达标或硬件认证。用接入工具为新机器人生成任务 ID,再运行 性能达标或硬件认证。用接入工具为新机器人生成任务 ID,再运行
`python scripts/train.py --list` 查看本地注册项。 `python scripts/train.py --list` 查看本地注册项。
+2 -1
View File
@@ -14,7 +14,8 @@ instructions.
third-party notices. The legacy Rockchip runtime has separate provenance third-party notices. The legacy Rockchip runtime has separate provenance
and terms described in its [runtime notes](../deploy/fsm/vendor/rknpu2/README.md). and terms described in its [runtime notes](../deploy/fsm/vendor/rknpu2/README.md).
- Inspect tracked configuration, generated packages, and archives for private - Inspect tracked configuration, generated packages, and archives for private
content. Shared defaults are in `.env`. Keep `.env.local` out of the snapshot. content. Shared option keys are documented in `.env.example`. Keep `.env` and
`.env.local` out of the snapshot.
- Choose the commit identity, confirm the target remote and branch, and - Choose the commit identity, confirm the target remote and branch, and
review changes already present there before publishing. review changes already present there before publishing.
- Keep release downloads and provenance tied to actual artifacts. Record - Keep release downloads and provenance tied to actual artifacts. Record
+3 -4
View File
@@ -39,10 +39,9 @@ on 2026-11-04. All training runs started for this snapshot have finished.
Bundling fingerprints inputs, rejects missing gates, and reruns the packaged Bundling fingerprints inputs, rejects missing gates, and reruns the packaged
response before publication. The reader uses its own trusted schema. response before publication. The reader uses its own trusted schema.
- Original exclusive robot assets/tasks were removed after shared mechanisms were - Original exclusive robot assets/tasks were removed after shared mechanisms were
extracted. Historical ignored exports were initially preserved, then removed extracted. Historical ignored exports under `out/` were removed during
during workspace cleanup: `out/pre_platform_exports_20261104/` and workspace cleanup, while training logs, failure reports and user applications
`out/bundle_example/jumper/`. Training logs, failure reports and other user were retained. Scene dimensions are explicit nominal parameters.
applications were retained. Scene dimensions are explicit nominal parameters.
## Measured evidence ## Measured evidence
+2 -2
View File
@@ -92,7 +92,7 @@ python scripts/play.py --task my_robot --checkpoint <model_N.pt> --headless \
--evaluation-out evaluation.json --evaluation-out evaluation.json
``` ```
报告检查点、后端、环境数、迭代数、命令、观测噪声、仿真时长、跟踪误差与重置。 报告检查点、后端、环境数、迭代数、命令、观测噪声、仿真时长、跟踪误差与重置。仅当评测包含与无噪声回放的对比时,才额外使用干净观测回放进行比较。
## 导出到原生仿真 ## 导出到原生仿真
@@ -112,4 +112,4 @@ python scripts/onboard.py verify --model out/native_policy/robot.xml \
使用通过的报告及其对应导出文件构建原生应用。详见 使用通过的报告及其对应导出文件构建原生应用。详见
[控制器设置](CONTROLLER_SETUP.md#native-hybrid-policy-export)和 [控制器设置](CONTROLLER_SETUP.md#native-hybrid-policy-export)和
[部署指南](../deploy/README.md)。 [部署指南](../deploy/README.zh.md)。
+3 -3
View File
@@ -197,9 +197,9 @@ The legacy target flags build the separate Rust bundle format.
## Defaults ## Defaults
Precedence is command line, shell environment, `.env.local`, `.env`, then the Precedence is command line, shell environment, `.env.local`, `.env`, then the
argument default. A blank task means a task is required on task entry points. argument default. Copy `.env.example` to `.env` to set local defaults. A blank
A blank model selects the robot's registered model. The committed defaults task means a task is required on task entry points. A blank model selects the
are: robot's registered model. The effective defaults are:
```dotenv ```dotenv
MJRL_TASK= MJRL_TASK=
+27 -9
View File
@@ -1,6 +1,6 @@
# 命令手册 # 命令手册
<!-- tracks: USAGE.md @ sha256:5d4ada2976459092 --> <!-- tracks: USAGE.md @ sha256:3f15279c7bd4459d -->
用 Python 3.10–3.13 建立环境并执行 `python -m pip install -e ".[dev]"`。 用 Python 3.10–3.13 建立环境并执行 `python -m pip install -e ".[dev]"`。
平台配置见[环境准备](AGENT_SETUP.zh.md)。可编辑安装负责连接两个包根目录。 平台配置见[环境准备](AGENT_SETUP.zh.md)。可编辑安装负责连接两个包根目录。
@@ -73,12 +73,29 @@ extraction = extract_policy_metadata(
`penalized_contact_geoms` 和 `termination_contact_geoms`。模型及控制路径 `penalized_contact_geoms` 和 `termination_contact_geoms`。模型及控制路径
相对输入 JSON 解析。标定报告须对应实际 XML 和编译依赖。 相对输入 JSON 解析。标定报告须对应实际 XML 和编译依赖。
也可提供完整的已验证规格。完整字段包括 `base_body`、`base_height`、 不传 `--calibration` 时,可根据已验证的模型参数提供完整 `RobotSpec`,格式示例如下:
`foot_geoms` 或 `foot_bodies`,以及 `position_joints`。每个位置关节提供
`name`、`kp`、`kd`、`effort_limit`、`action_scale`、`home`, ```json
可选 `armature`。站立根高度是 `base_height`,各关节默认位置是 `home`。 {
支撑物体需要直属的命名碰撞几何。双足和轮足双足至少两个支撑,四足至少四个, "robot_id": "sample_biped",
多足至少五个。轮足双足还需至少两个不限位转动关节,设置 `kp: 0`、 "family": "biped",
"model_path": "assets/sample_biped/robot.xml",
"base_body": "base",
"base_height": 0.32,
"foot_geoms": ["left_foot", "right_foot"],
"penalized_contact_geoms": ["left_shin", "right_shin"],
"termination_contact_geoms": ["torso"],
"position_joints": [
{"name": "left_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1},
{"name": "right_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1}
]
}
```
请使用针对该机器人标定的数值。站立根高度是 `base_height`,各关节默认位置是 `home`,
可选 `armature` 为该关节的附加转动惯量。提供 `foot_geoms` 或 `foot_bodies`;
每个支撑刚体需要直属的命名碰撞几何。双足和轮足双足至少两个支撑,四足至少四个,
多足至少五个。轮足双足还需在 `velocity_joints` 中提供至少两个不限位转动关节,设置 `kp: 0`、
正 `kd`、力矩上限和轮速动作尺度。 正 `kd`、力矩上限和轮速动作尺度。
仅生成 `tasks/<robot_id>/robot_spec.py`,任务 ID 等于机器人 ID。 仅生成 `tasks/<robot_id>/robot_spec.py`,任务 ID 等于机器人 ID。
@@ -148,8 +165,9 @@ python scripts/play.py --app <output-parent>/<robot_id>.app --headless --steps 1
## 默认值 ## 默认值
优先级从高到低为命令行、环境变量、`.env.local`、`.env`、参数默认。 优先级从高到低为命令行、环境变量、`.env.local`、`.env`、参数默认。可将
空任务要求显式指定,空模型选择已注册模型。 `.env.example` 复制为 `.env` 自定义本地默认值。空任务要求显式指定,空模型选择
已注册模型。有效默认值为:
```dotenv ```dotenv
MJRL_TASK= MJRL_TASK=
+5 -7
View File
@@ -85,7 +85,7 @@ include = ["tasks*", "scenes*", "controller*", "mjrl*", "mjlab*", "rsl_rl*"]
# never hit it, which is exactly what makes it easy to ship. # never hit it, which is exactly what makes it easy to ship.
[tool.setuptools.package-data] [tool.setuptools.package-data]
scenes = ["assets/*/*.png"] scenes = ["assets/*/*.png"]
tasks = ["templates/**/*.json", "templates/**/AGENTS.md"] tasks = ["templates/**/AGENTS.md"]
# The gamepad dictionary is data, read at run time by `controller.vocabulary` # The gamepad dictionary is data, read at run time by `controller.vocabulary`
# and at compile time by `deploy/fsm`. Same reason as the scene textures: a # and at compile time by `deploy/fsm`. Same reason as the scene textures: a
# wheel with the module and not the file fails on first use, not on build. # wheel with the module and not the file fails on first use, not on build.
@@ -118,13 +118,11 @@ select = ["E4", "E7", "E9", "F"]
# A notebook cell imports where it first needs a name, after the form fields # A notebook cell imports where it first needs a name, after the form fields
# Colab reads off the top of the cell; ruff 0.16 lints notebooks by default. # Colab reads off the top of the cell; ruff 0.16 lints notebooks by default.
"notebooks/*.ipynb" = ["E402"] "notebooks/*.ipynb" = ["E402"]
# One-off checks and asset tools are written dense -- several statements to a # One-off checks are written dense -- several statements to a line, an import
# line, an import where it is first needed -- on purpose: each is read once, # where it is first needed -- on purpose: each is read once, beside the
# beside the measurement it produced. Only the layout is exempt; a dead import # measurement it produced. Only the layout is exempt; a dead import or an empty
# or an empty f-string is still a finding there. # f-string is still a finding there.
"tools/checks/*" = ["E401", "E402", "E701", "E702"] "tools/checks/*" = ["E401", "E402", "E701", "E702"]
"assets/*/tools/*" = ["E401", "E402", "E701", "E702"]
"tasks/*/tools/*" = ["E701"]
[tool.pytest.ini_options] [tool.pytest.ini_options]
testpaths = ["tests"] testpaths = ["tests"]
+4 -5
View File
@@ -1,7 +1,6 @@
# Asset Zoo # Asset Zoo
| Robot | Image | | Robot | Description |
|-------|-------| |-------|-------------|
| **Unitree G1** | <img src="../../../docs/source/_static/content/g1.png" width="200" height="150" alt="Unitree G1 Humanoid"> | | **Unitree G1** | Unitree G1 Humanoid (`rl/mjlab/asset_zoo/robots/unitree_g1`) |
| **Unitree Go1** | <img src="../../../docs/source/_static/content/go1.png" width="200" height="150" alt="Unitree Go1 Quadruped"> | | **Unitree Go1** | Unitree Go1 Quadruped (`rl/mjlab/asset_zoo/robots/unitree_go1`) |
| **i2rt YAM** | <img src="../../../docs/source/_static/content/yam.png" width="200" height="150" alt="i2rt YAM Robot Arm"> |
-2
View File
@@ -1,5 +1,3 @@
# Terrains # Terrains
Procedurally generate terrains using primitive geometries and heightfields. Procedurally generate terrains using primitive geometries and heightfields.
<img src="../../../docs/source/_static/content/rough_terrain.png" alt="Rough Terrain">
+1 -1
View File
@@ -50,7 +50,7 @@ from dataclasses import dataclass
from pathlib import Path from pathlib import Path
from typing import Any from typing import Any
from mjrl.viewer.keys import ViewerKeys as ViewerKeys from mjrl.viewer.keys import ViewerKeys
try: try:
import tomllib import tomllib
+1 -1
View File
@@ -950,7 +950,7 @@ class NativeSimulation:
**Putting each environment's control and warm start back costs** one **Putting each environment's control and warm start back costs** one
`mj_setState` and two small copies per environment, under the GIL. Measured `mj_setState` and two small copies per environment, under the GIL. Measured
on the i9-14900KF (2026-09-26), example_robot.tripod on 8 threads, medians of 5 on the i9-14900KF (2026-09-26), a 6-legged locomotion task on 8 threads, medians of 5
runs interleaved with the code before it, before -> after: runs interleaved with the code before it, before -> after:
| envs | `sim.step` ms | `env.step` ms | this function ms | | envs | `sim.step` ms | `env.step` ms | this function ms |
+9 -30
View File
@@ -31,8 +31,8 @@ __all__ = [
def load_command_script(spec: str): def load_command_script(spec: str):
"""`FILE[:NAME]` -> the callable `NAME` (default `script`) defined in `FILE`. """`FILE[:NAME]` -> the callable `NAME` (default `script`) defined in `FILE`.
The file is loaded by path, not imported by name: a clip's script lives next The file is loaded by path, not imported by name, so standalone evaluation
to whatever draws the clip (`tools/readme_media.py`), which is not a package. or video-capture scripts outside the package tree can be passed directly.
""" """
path, sep, name = spec.rpartition(":") path, sep, name = spec.rpartition(":")
if not sep or not name.isidentifier(): if not sep or not name.isidentifier():
@@ -55,15 +55,10 @@ def script_commands(env, script) -> list[str]:
"""Have command terms hold what `script` says, from each term's own `compute` on. """Have command terms hold what `script` says, from each term's own `compute` on.
`script(t)` returns `{term name: values}` for `t` seconds since this was `script(t)` returns `{term name: values}` for `t` seconds since this was
installed; it is written into each named term **after** the term's own installed; it is written into each named velocity command term (`vel_command_b`,
`compute`, which is where the operator writes -- so a pad that is plugged in three values) **after** the term's own `compute`, which is where the operator
and nudged does not drive a scripted term, and the term's own bookkeeping writes -- so a pad that is plugged in and nudged does not drive a scripted
(metrics, resample timers, the posture term's walking band) still runs. term, and the term's own bookkeeping (metrics, resample timers) still runs.
Two kinds of term are understood: a velocity command (`vel_command_b`,
three values) and a posture command (`posture_command`, four). A posture's
height may be NaN, the term's own
neutral height, or `(height, share)`, that share of the way there from it.
""" """
import torch import torch
@@ -79,8 +74,8 @@ def script_commands(env, script) -> list[str]:
term = env.command_manager.get_term(name) term = env.command_manager.get_term(name)
except KeyError: except KeyError:
raise ValueError(f"the task has no command term {name!r} to script") from None raise ValueError(f"the task has no command term {name!r} to script") from None
if not hasattr(term, "posture_command") and not hasattr(term, "vel_command_b"): if not hasattr(term, "vel_command_b"):
raise ValueError(f"command term {name!r} is neither a velocity nor a posture " raise ValueError(f"command term {name!r} is not a velocity "
"command; a script cannot drive it") "command; a script cannot drive it")
_install(term, name, script, env, origin, step_dt, torch) _install(term, name, script, env, origin, step_dt, torch)
return names return names
@@ -93,18 +88,6 @@ def _install(term, name, script, env, origin, step_dt, torch) -> None:
compute(dt, env_ids) compute(dt, env_ids)
t = (env.common_step_counter - origin) * step_dt t = (env.common_step_counter - origin) * step_dt
values = list(script(t)[name]) values = list(script(t)[name])
if hasattr(term, "posture_command"):
rest = term.cfg.neutral_height
height = values[3]
if isinstance(height, tuple):
values[3] = rest + (height[0] - rest) * height[1]
elif math.isnan(height):
values[3] = rest
term.posture_command[:] = torch.tensor(
values, device=term.device, dtype=torch.float32
)
term.hold_to_band()
return
columns = term.command.shape[1] columns = term.command.shape[1]
if len(values) != columns: if len(values) != columns:
raise ValueError(f"a script of {len(values)} values for {name!r}, a command of " raise ValueError(f"a script of {len(values)} values for {name!r}, a command of "
@@ -140,8 +123,7 @@ def configure_velocity_replay(env_cfg, training_cfg, checkpoint: dict,
if ladder is not None: if ladder is not None:
params = ladder.params or {} params = ladder.params or {}
fractions, ceilings = params.get("fractions"), params.get("ceilings") fractions, ceilings = params.get("fractions"), params.get("ceilings")
levels, angles = params.get("levels"), params.get("ang_levels") level_count = len(fractions) if fractions else 0
level_count = len(fractions) if fractions else len(levels or ())
infos = checkpoint.get("infos") or {} infos = checkpoint.get("infos") or {}
curriculum = infos.get("curriculum") or {} curriculum = infos.get("curriculum") or {}
saved = curriculum.get("command") or {} saved = curriculum.get("command") or {}
@@ -150,9 +132,6 @@ def configure_velocity_replay(env_cfg, training_cfg, checkpoint: dict,
raise ValueError("checkpoint has no valid saved command curriculum level") raise ValueError("checkpoint has no valid saved command curriculum level")
if fractions and ceilings and len(ceilings) == 3: if fractions and ceilings and len(ceilings) == 3:
x, y, yaw = (float(value) * float(fractions[level]) for value in ceilings) x, y, yaw = (float(value) * float(fractions[level]) for value in ceilings)
elif levels and angles and len(levels) == len(angles):
x = y = float(levels[level])
yaw = float(angles[level])
else: else:
raise ValueError("unsupported command curriculum: no valid command range ladder") raise ValueError("unsupported command curriculum: no valid command range ladder")
if not all(math.isfinite(value) for value in (x, y, yaw)) or x <= 0 or y < 0 or yaw <= 0: if not all(math.isfinite(value) for value in (x, y, yaw)) or x <= 0 or y < 0 or yaw <= 0:
+5 -5
View File
@@ -14,8 +14,8 @@ file runs during `import scenes`, and `--list` has to stay usable on a machine
without the simulation dependencies. `registry.load` imports the module. without the simulation dependencies. `registry.load` imports the module.
`--scene` also takes a **path** to an imported `kk-scene-package/1` or `/2` -- `--scene` also takes a **path** to an imported `kk-scene-package/1` or `/2` --
a directory, a `.zip` or a `.map` that scene-generator, kingkong_design's map a directory, a `.zip` or a `.map` written by an external scene generator or this
library or this repository's own `scenes/tools/export_web_scene.py` wrote. repository's own `scenes/tools/export_web_scene.py`.
`scripts/play.py` accepts one and `scripts/train.py` refuses it; `scripts/play.py` accepts one and `scripts/train.py` refuses it;
`scenes/package.py` says why. `scenes/package.py` says why.
@@ -129,9 +129,9 @@ register(
description="**changes the ground**: generated slopes, stairs and rough surface", description="**changes the ground**: generated slopes, stairs and rough surface",
tags=("terrain",), tags=("terrain",),
# A 10 x 7 grid of difficulty tiles with a flat control column, sized from # A 10 x 7 grid of difficulty tiles with a flat control column, sized from
# this robot's foot-lift height. An instrument for the curriculum to move # explicit nominal terrain parameters. An instrument for the curriculum to
# a robot through, not a place. Stairs worth walking on for fun would be a # move a robot through, not a place. Stairs worth walking on for fun would
# new scene, not this one with its levels shipped. # be a new scene, not this one with its levels shipped.
use="training", use="training",
) )
+1 -1
View File
@@ -29,7 +29,7 @@ The sky is a **cube map** rather than a builtin gradient, because a builtin one
runs from zenith to horizon and nothing else -- it cannot be warm on one side of runs from zenith to horizon and nothing else -- it cannot be warm on one side of
the compass and cold on the other, which is most of what makes a low sun read as the compass and cold on the other, which is most of what makes a low sun read as
a low sun rather than as an orange filter over the whole world. The six faces are a low sun rather than as an orange filter over the whole world. The six faces are
generated by `assets/scenes/beach/tools/make_skybox.py`, which draws the generated by `tools/make_skybox.py`, which draws the
sun's disc into them as well, so the sun is where the light says it is rather sun's disc into them as well, so the sun is where the light says it is rather
than merely implied. That file holds the sun direction and **it has to stay the than merely implied. That file holds the sun direction and **it has to stay the
negation of the light's `dir` below**: disagreeing puts the bright part of the sky negation of the light's `dir` below**: disagreeing puts the bright part of the sky
+9 -10
View File
@@ -5,11 +5,11 @@ another simulator can import, this one reads one somebody else wrote. The format
is the same in both directions, which is the point -- a room exported by is the same in both directions, which is the point -- a room exported by
scene-generator and a pitch exported from here are the same kind of file. scene-generator and a pitch exported from here are the same kind of file.
python scripts/play.py --task example_robot.flat --scene out/bedroom.scene python scripts/play.py --task go1_example --scene out/bedroom.scene
python scripts/play.py --task example_robot.flat --scene out/bedroom.scene.zip python scripts/play.py --task go1_example --scene out/bedroom.scene.zip
python scripts/play.py --task example_robot.flat --scene library/maps/bedroom.map python scripts/play.py --task go1_example --scene library/maps/bedroom.map
`/2` is what kingkong_design's map library is written in: the `/1` world, plus `/2` is what the map library format is written in: the `/1` world, plus
the robot the map was authored around (`robot/`) and a thumbnail (`preview/`). the robot the map was authored around (`robot/`) and a thumbnail (`preview/`).
Both are verified like every other file and neither is loaded -- the robot here Both are verified like every other file and neither is loaded -- the robot here
is the task's own, the one the policy was trained on -- and `spawn` becomes is the task's own, the one the policy was trained on -- and `spawn` becomes
@@ -56,7 +56,7 @@ heading in **degrees** -- while the robot here starts where its task puts it, at
the environment origin facing +X. So the world is attached in a frame that moves the environment origin facing +X. So the world is attached in a frame that moves
the spawn point to the origin and turns its heading onto +X, and the robot's the spawn point to the origin and turns its heading onto +X, and the robot's
initial state is left alone. Ignoring `spawn` is not a small offset: measured on initial state is left alone. Ignoring `spawn` is not a small offset: measured on
kingkong_design's 13 maps (c655914), 6 put it away from the origin, and a robot at 13 reference maps (c655914), 6 put it away from the origin, and a robot at
the origin instead stands in a shelf (shelf-maze: 0.82 m of shelf within 0.25 m the origin instead stands in a shelf (shelf-maze: 0.82 m of shelf within 0.25 m
of it), on a 0.7 m ramp (switchback-slopes) or in bedroom furniture (0.45 m). of it), on a 0.7 m ramp (switchback-slopes) or in bedroom furniture (0.45 m).
@@ -70,8 +70,7 @@ and shelf-maze (-0.03 m, 60%) are buried the same way.
It is not enough to delete the task's plane. Every robot task's It is not enough to delete the task's plane. Every robot task's
`feet_ground_contact` sensor counts contacts with the **body** named `terrain`, `feet_ground_contact` sensor counts contacts with the **body** named `terrain`,
so a foot on anything that lives elsewhere reads as a foot in the air -- and so a foot on anything that lives elsewhere reads as a foot in the air. So every
`example_robot.ref_free_jump` decides take-off and landing from that sensor. So every
geom of the package that collides and does not move -- the ground, and equally geom of the package that collides and does not move -- the ground, and equally
a start platform, a bridge deck, a ramp or a table top -- is rebuilt inside that a start platform, a bridge deck, a ramp or a table top -- is rebuilt inside that
body (`_Terrain`), the ground under the name `terrain` so that everything that body (`_Terrain`), the ground under the name `terrain` so that everything that
@@ -96,7 +95,7 @@ from .registry import Scene
__all__ = ["PackageError", "ScenePackage", "is_package_path", "load_package", "read_package"] __all__ = ["PackageError", "ScenePackage", "is_package_path", "load_package", "read_package"]
#: The versions this importer reads. An unknown one is refused rather than read #: The versions this importer reads. An unknown one is refused rather than read
#: as the nearest known one: kingkong_design's contract says a consumer that #: as the nearest known one: the package contract says a consumer that
#: does not know a version must reject it. #: does not know a version must reject it.
SCHEMAS = ("kk-scene-package/1", "kk-scene-package/2") SCHEMAS = ("kk-scene-package/1", "kk-scene-package/2")
MANIFEST = "scene-package.json" MANIFEST = "scene-package.json"
@@ -109,7 +108,7 @@ SUFFIX = ".map"
#: collide on base names, and MuJoCo's asset lookup falls back to the base name. #: collide on base names, and MuJoCo's asset lookup falls back to the base name.
PLATFORM_DIR = "platforms/" PLATFORM_DIR = "platforms/"
#: What `/2` adds beside the world, kept out of the shared section for the same #: What `/2` adds beside the world, kept out of the shared section for the same
#: reason as `PLATFORM_DIR`: every map in kingkong_design's library carries both #: reason as `PLATFORM_DIR`: every `/2` map carries both
#: `preview/preview.png` and `robot/preview/preview.png`, and the robot's meshes #: `preview/preview.png` and `robot/preview/preview.png`, and the robot's meshes
#: are free to share a base name with the world's. Only for `/2`, where the #: are free to share a base name with the world's. Only for `/2`, where the
#: names mean this -- in a `/1` package `robot/` would be an ordinary directory. #: names mean this -- in a `/1` package `robot/` would be an ordinary directory.
@@ -762,7 +761,7 @@ def _entities(package: ScenePackage) -> dict[str, Any]:
"""The props that are their own file, as mjlab entities. """The props that are their own file, as mjlab entities.
A prop carrying a `file` is the exporter saying it belongs **beside a robot** A prop carrying a `file` is the exporter saying it belongs **beside a robot**
rather than in the room: kk-rl-mjlab writes its football that way because it rather than in the room: `mjrl-lab` writes its football that way because it
places one per environment at that environment's origin. Rebuilding it as an places one per environment at that environment's origin. Rebuilding it as an
entity is what makes the round trip a round trip -- exported from here, entity is what makes the round trip a round trip -- exported from here,
imported back, and placed the same way. imported back, and placed the same way.
+1 -2
View File
@@ -199,8 +199,7 @@ def scene(*, foot_bodies=()) -> Scene:
variable, and if it also changed the lighting then "the robot walks variable, and if it also changed the lighting then "the robot walks
differently here" would have two candidate explanations and no way to differently here" would have two candidate explanations and no way to
separate them by looking. Sharing the look makes `--scene soft` against no separate them by looking. Sharing the look makes `--scene soft` against no
scene at all a one-variable comparison, in the same way `example_robot.flat` is a scene at all a clean one-variable comparison.
one-variable control for two of the gait tasks.
The consequence to keep in mind: **the two are indistinguishable in a The consequence to keep in mind: **the two are indistinguishable in a
screenshot.** A frame from this scene and a frame from `default` differ only screenshot.** A frame from this scene and a frame from `default` differ only
+8 -11
View File
@@ -213,11 +213,10 @@ FEATURES = "web"
#: #:
#: **Not only the crate's directory, either.** This was `Cargo.toml`, #: **Not only the crate's directory, either.** This was `Cargo.toml`,
#: `Cargo.lock` and `src/` until 2026-09-28, and the controller was also built #: `Cargo.lock` and `src/` until 2026-09-28, and the controller was also built
#: from files outside them: `build.rs`, which compiles in every task's deploy #: from files outside them: `build.rs`, which compiles in optional task deploy
#: hook -- so a commit that changed only `tasks/example_robot/deploy/lib.rs` #: hooks (`tasks/**/deploy/lib.rs`), the dictionary `src/vocabulary.rs`
#: shipped a different arm under the previous commit's name, and an uncommitted #: includes, the IDL the board's bus is generated from, and the NPU header
#: one without `-dirty` -- the dictionary `src/vocabulary.rs` includes, the IDL #: `vendor/` holds.
#: the board's bus is generated from, and the NPU header `vendor/` holds.
#: `tests/test_bundle.py` holds this list to what rustc and `build.rs` actually #: `tests/test_bundle.py` holds this list to what rustc and `build.rs` actually
#: read. #: read.
SOURCES = ( SOURCES = (
@@ -963,9 +962,8 @@ def write_reference(out: Path, extension: Path | None,
# The mode the cascade runs with nobody touching anything -- the one these # The mode the cascade runs with nobody touching anything -- the one these
# frames converge on and infer in -- rather than the first mode by name, # frames converge on and infer in -- rather than the first mode by name,
# whose home may be another policy's entirely: `robot`'s `claw_left` sorts # whose home pose may belong to another policy entirely, so the frames
# first and carries an arm 1.6 rad from the walking stance, so the frames # would converge on a pose the warm start never reaches.
# converged on a pose the warm start never reaches and not one inferred.
import tomllib import tomllib
cfg = tomllib.loads((out / "controller.toml").read_text("utf-8")).get("fsm", {}) cfg = tomllib.loads((out / "controller.toml").read_text("utf-8")).get("fsm", {})
@@ -1507,8 +1505,7 @@ def assemble(out: Path, modes: dict[str, Path], fsm_path: Path | None, meta: dic
if name.endswith(f"/{BOARD_BINARY}"): if name.endswith(f"/{BOARD_BINARY}"):
(out / name).chmod(0o755) (out / name).chmod(0o755)
# One copy of a model per export directory. `claw_left` and `claw_right` # One copy of a model per export directory when two modes share an export.
# are one export carried on two sides, and shipped them twice.
stored: dict[Path, dict[str, str]] = {} stored: dict[Path, dict[str, str]] = {}
listed: dict[str, dict] = {} listed: dict[str, dict] = {}
unconverted: list[str] = [] unconverted: list[str] = []
@@ -2074,7 +2071,7 @@ def validate_app(out: Path) -> None:
#: be held against the one shipped last week. #: be held against the one shipped last week.
ZIP_EPOCH = (1980, 1, 1, 0, 0, 0) ZIP_EPOCH = (1980, 1, 1, 0, 0, 0)
#: What a bundle's archive is called: `robot/` travels as `example_robot.app`. #: What a bundle's archive is called: `<bundle_id>/` travels as `<bundle_id>.app`.
#: #:
#: The bytes are an ordinary zip, and any zip reader opens one. The name says #: The bytes are an ordinary zip, and any zip reader opens one. The name says
#: what the file is rather than how it is packed, as `.jar` does for a zip of #: what the file is rather than how it is packed, as `.jar` does for a zip of
+11 -12
View File
@@ -11,10 +11,10 @@ choices for both. The backend comes from `--backend` / `--device`, or is
auto-detected, exactly as in train. auto-detected, exactly as in train.
The environment is built in **replay mode** (`play=True`): external disturbances The environment is built in **replay mode** (`play=True`): external disturbances
are off and episodes run on rather than timing out (the one-shot jumps keep are off and episodes run on rather than timing out, so what you see is the
theirs, so a replay loops whole attempts), so what you see is the policy rather policy rather than the randomisation. Observation noise is the exception:
than the randomisation. Observation noise is the exception: `--obs-noise`, on by `--obs-noise`, on by default, puts training's back, because a clean replay
default, puts training's back, because a clean replay flatters the policy. flatters the policy.
A replay is **one environment** unless `--num_envs` or `MJRL_PLAY_NUM_ENVS` says A replay is **one environment** unless `--num_envs` or `MJRL_PLAY_NUM_ENVS` says
otherwise. `MJRL_NUM_ENVS` is training's batch size, and play does not read it. otherwise. `MJRL_NUM_ENVS` is training's batch size, and play does not read it.
@@ -43,14 +43,13 @@ without a display needs ``MUJOCO_GL=egl`` set before Python starts):
python scripts/play.py --checkpoint <path>/model_N.pt --headless \ python scripts/play.py --checkpoint <path>/model_N.pt --headless \
--steps 500 --video replay.mp4 --video-fps 30 --steps 500 --video replay.mp4 --video-fps 30
**It is the one MP4 recorder** (`mjrl/viewer/video.py`): the README clips, the **It is the one MP4 recorder** (`mjrl/viewer/video.py`): evaluation clips and
dance export and the Colab notebook all run this command rather than drawing for the Colab notebook all run this command rather than drawing for themselves. The
themselves. The camera is placed from the robot's first frame (`--video-azimuth`, camera is placed from the robot's first frame (`--video-azimuth`,
`--video-elevation`, `--no-video-follow`), `--stop-on-done` records one attempt `--video-elevation`, `--no-video-follow`), `--stop-on-done` stops when an
of a one-shot motion rather than looping it, and `--command-script` hands the episode terminates, and `--command-script` hands the command terms a script of
command terms a script of time where the README clips need a walk that starts and time -- written where the operator writes, so a connected pad does not drive a
a posture that changes -- written where the operator writes, so the pad does not scripted term.
drive a scripted term.
""" """
from __future__ import annotations from __future__ import annotations
+1 -2
View File
@@ -13,8 +13,7 @@ from pathlib import Path
#: The repository root. This file lives in `tasks/`, hence one level up. #: The repository root. This file lives in `tasks/`, hence one level up.
REPO_ROOT: Path = Path(__file__).resolve().parents[1] REPO_ROOT: Path = Path(__file__).resolve().parents[1]
#: The model asset root. One subdirectory per asset, each with its own `tools/` #: The model asset root. One subdirectory per robot asset.
#: for generation and calibration scripts.
ASSETS_DIR: Path = REPO_ROOT / "assets" ASSETS_DIR: Path = REPO_ROOT / "assets"
#: The training log root directory name. Relative to the **current working #: The training log root directory name. Relative to the **current working
+2 -2
View File
@@ -283,12 +283,12 @@ def test_usage_doc_matches_the_code() -> None:
for name in ("def register(", "def load_env_cfg(", "def load_agent_cfg("): for name in ("def register(", "def load_env_cfg(", "def load_agent_cfg("):
assert name in registry, f"{name}, mentioned in USAGE, is not in the registry" assert name in registry, f"{name}, mentioned in USAGE, is not in the registry"
# The .env keys in the manual must match the repository's .env # The .env keys in the manual must match the repository's .env.example
import re import re
doc_keys = set(re.findall(r"^(MJRL_[A-Z_]+)=", usage, re.M)) doc_keys = set(re.findall(r"^(MJRL_[A-Z_]+)=", usage, re.M))
env_keys = set( env_keys = set(
re.findall(r"^(MJRL_[A-Z_]+)=", (REPO / ".env").read_text(encoding="utf-8"), re.M) re.findall(r"^(MJRL_[A-Z_]+)=", (REPO / ".env.example").read_text(encoding="utf-8"), re.M)
) )
assert doc_keys == env_keys, ( assert doc_keys == env_keys, (
f"USAGE and .env keys disagree.\nExtra in the document: " f"USAGE and .env keys disagree.\nExtra in the document: "
+1 -1
View File
@@ -220,7 +220,7 @@ def velocity_replay_configs(monkeypatch):
) )
training = SimpleNamespace(commands={"twist": command}, curriculum={ training = SimpleNamespace(commands={"twist": command}, curriculum={
"command": SimpleNamespace(params={ "command": SimpleNamespace(params={
"levels": (.25, .35, .5, .5), "ang_levels": (.3, .5, .75, .75), "fractions": (.5, .7, 1.0, 1.0), "ceilings": (.5, .5, .6),
}), }),
}) })
replay = SimpleNamespace(commands={"twist": copy.deepcopy(command)}) replay = SimpleNamespace(commands={"twist": copy.deepcopy(command)})
+1 -1
View File
@@ -222,7 +222,7 @@ def test_scene_selection_is_wired_to_the_cli_and_env() -> None:
cli = (REPO / "scripts" / "_cli.py").read_text(encoding="utf-8") cli = (REPO / "scripts" / "_cli.py").read_text(encoding="utf-8")
assert '_env("MJRL_SCENE")' in cli assert '_env("MJRL_SCENE")' in cli
assert "def apply_scene(" in cli assert "def apply_scene(" in cli
assert "MJRL_SCENE=" in (REPO / ".env").read_text(encoding="utf-8") assert "MJRL_SCENE=" in (REPO / ".env.example").read_text(encoding="utf-8")
# Only where it can do something. export.py writes an ONNX file and a # Only where it can do something. export.py writes an ONNX file and a
# contract, and nothing a scene changes reaches either; it took --scene from # contract, and nothing a scene changes reaches either; it took --scene from
+1 -1
View File
@@ -497,7 +497,7 @@ def test_strip_visual_config_is_wired() -> None:
cli = read(REPO / "scripts" / "_cli.py") cli = read(REPO / "scripts" / "_cli.py")
assert "MJRL_STRIP_VISUAL" in cli assert "MJRL_STRIP_VISUAL" in cli
assert "strip_visual=" in cli, "the resolve() call does not pass it" assert "strip_visual=" in cli, "the resolve() call does not pass it"
env_keys = (REPO / ".env").read_text(encoding="utf-8") env_keys = (REPO / ".env.example").read_text(encoding="utf-8")
assert "MJRL_STRIP_VISUAL=" in env_keys assert "MJRL_STRIP_VISUAL=" in env_keys
+1 -1
View File
@@ -118,7 +118,7 @@ def test_an_ancient_card_is_referred_upward_rather_than_guessed() -> None:
def test_the_repo_is_found_by_content_not_by_name() -> None: def test_the_repo_is_found_by_content_not_by_name() -> None:
"""The checkout is routinely named something else. """The checkout is routinely named something else.
`kk-rl-mjlab` on the training machine, a hashed path inside `.claude/ `mjrl-lab` on the training machine, or a hashed path inside `.claude/
worktrees/` here. Matching on the directory name would fail on exactly the worktrees/` here. Matching on the directory name would fail on exactly the
machines this is needed for. machines this is needed for.
""" """
+1 -1
View File
@@ -398,7 +398,7 @@ def test_config_is_actually_wired() -> None:
# to contain `_env(`, so the looser check passed either way.) # to contain `_env(`, so the looser check passed either way.)
assert '_bool_env("MJRL_TENSORBOARD"' in cli assert '_bool_env("MJRL_TENSORBOARD"' in cli
assert '_int_env("MJRL_TB_PORT"' in cli assert '_int_env("MJRL_TB_PORT"' in cli
env = (REPO / ".env").read_text(encoding="utf-8") env = (REPO / ".env.example").read_text(encoding="utf-8")
assert "MJRL_TENSORBOARD=" in env and "MJRL_TB_PORT=" in env assert "MJRL_TENSORBOARD=" in env and "MJRL_TB_PORT=" in env
train = (REPO / "scripts" / "train.py").read_text(encoding="utf-8") train = (REPO / "scripts" / "train.py").read_text(encoding="utf-8")
+2 -2
View File
@@ -7,9 +7,9 @@
A scene that generates cube textures declares them in a module-level A scene that generates cube textures declares them in a module-level
`CUBEMAPS = {prefix: colour_fn}` beside its `scene()` factory, where each `CUBEMAPS = {prefix: colour_fn}` beside its `scene()` factory, where each
`colour_fn(dirs) -> rgb` is a function of direction; this writes the six faces of `colour_fn(dirs) -> rgb` is a function of direction; this writes the six faces of
each into `assets/scenes/<id>/`. The convention is that the skybox is called each into `scenes/assets/<id>/`. The convention is that the skybox is called
`sky`; a football's panels are just another function of direction. Colours are code and live with the scene; the PNGs are `sky`; a football's panels are just another function of direction. Colours are code and live with the scene; the PNGs are
data and live under `assets/`, which is the same split as models. data and live under `scenes/assets/`, which is the same split as models.
Re-run it after changing a sky's colours, or the scene will keep loading the Re-run it after changing a sky's colours, or the scene will keep loading the
faces that were written last time -- they are committed, not built on demand. faces that were written last time -- they are committed, not built on demand.