Files
chenlin c32df70326
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
release: v0.1 generic robot training and application platform
2026-11-05 11:05:01 +08:00

529 lines
20 KiB
Python

"""Drive the current browser controller with a deterministic legacy bundle.
Build the same wasm and glue that a page loads, then exercise raw controls,
both ways of starting a recording, and the ONNX-backed reference vectors.
"""
from __future__ import annotations
import json
import os
import shutil
import subprocess
import sys
from pathlib import Path
import pytest
REPO = Path(__file__).resolve().parents[1]
LOADER = Path(__file__).parent / "web" / "load_bundle.mjs"
# Run the real builder in its own process. Isolate its staging area and
# optional cross-build paths from whatever the user keeps under out/.
_BUILD = """
import importlib.util
from pathlib import Path
import sys
script, root, *args = sys.argv[1:]
spec = importlib.util.spec_from_file_location("deploy_for_web", script)
deploy = importlib.util.module_from_spec(spec)
spec.loader.exec_module(deploy)
deploy.STAGING = Path(root) / "wasm-stage"
deploy.CROSS_BUILT = Path(root) / "no-board-runtime"
deploy.PLAY_CROSS_BUILDS = {}
sys.argv = [script, *args]
raise SystemExit(deploy.main())
"""
_FSM = """
[fsm]
initial_state = "walk"
warm_start_ref = "walk"
safe_state = "safe"
tilt_limit = 3.15
state_timeout_ms = 200
command_timeout_ms = 3600000
mode_switch_ramp_s = 0.0
pose_reach_tol = 0.10
warm_start_duration_s = 0.0
ramp_kp = 0.15
ramp_kd = 0.01
[[fsm.button]]
name = "guided"
pad = "A"
on = "toggle"
from = ["walk"]
[[fsm.button]]
name = "guided"
key = "keypad_2"
on = "toggle"
from = ["walk"]
[[fsm.button]]
name = "start_motion"
pad = "LB"
on = "fall"
event = true
from = ["guided"]
[[fsm.button]]
name = "entry"
pad = "dpad_right"
with = "menu"
on = "toggle"
from = ["walk"]
[[fsm.button]]
name = "entry"
key = "keypad_1"
with = "ctrl"
on = "toggle"
from = ["walk"]
[[fsm.state]]
name = "safe"
hold_current = true
kd = 0.01
[[fsm.state]]
name = "walk"
model = "walk.onnx"
[[fsm.state]]
name = "guided"
model = "guided.onnx"
[[fsm.state]]
name = "entry"
model = "entry.onnx"
[[fsm.rule]]
when = "feedback_stale"
enter = "safe"
[[fsm.rule]]
when = "in_state:safe"
enter = "@initial"
[[fsm.rule]]
when = "button:guided"
enter = "guided"
[[fsm.rule]]
when = "button:entry"
enter = "entry"
[[fsm.rule]]
when = "always"
enter = "walk"
"""
def _write_export(source: Path, target: Path, mode: str) -> None:
from controller.controls import controller_contract, load_controls
shutil.copytree(source, target)
path = target / "layout.json"
layout = json.loads(path.read_text("utf-8"))
home = layout["default_joint_pos"]
wire = layout["wire_joint_order"]
layout["joint_limits"] = {name: [home[name] - 1, home[name] + 1] for name in wire}
if mode == "walk":
controls = Path(__file__).parent / "fixtures/controls/velocity.yaml"
layout["controller"] = controller_contract(load_controls(controls), None)
else:
# Replace one three-channel term without changing the fixture ONNX's
# input width. The phase and the two observed joints' preview both
# affect the graph's output.
terms = layout["observation"]["terms"]
index = next(i for i, term in enumerate(terms) if term["name"] == "base_ang_vel")
terms[index : index + 1] = [
{"name": "jump_phase", "dim": 1},
{"name": "ref_future", "dim": 2},
]
trajectory = f"{mode}.trajectory.json"
layout["reference"] = {
"file": trajectory,
"residual_action": False,
"rec_hz": 50,
"duration": 1.6,
"span": 1.6,
"lookahead_s": [0.04],
"n_frames": 81,
**({"starts_on_entry": True} if mode == "entry" else {"go_event": "start_motion"}),
}
frames = [
[home[name] + (i / 800) * (-1) ** j for j, name in enumerate(wire)] for i in range(81)
]
(target / trajectory).write_text(
json.dumps({"joint_order": wire, "q": frames}), encoding="utf-8"
)
path.write_text(json.dumps(layout), encoding="utf-8")
@pytest.fixture(scope="module")
def loaded(tmp_path_factory, legacy_export) -> dict:
if shutil.which("node") is None:
pytest.skip("no Node.js on this machine")
cargo_bin = Path(os.environ.get("CARGO_HOME") or (Path.home() / ".cargo")) / "bin"
for name in ("cargo", "rustup", "wasm-bindgen"):
if shutil.which(name) is None and not (cargo_bin / name).is_file():
pytest.skip(f"{name} is required to build the browser runtime")
rustup = shutil.which("rustup") or str(cargo_bin / "rustup")
installed = subprocess.run(
[rustup, "target", "list", "--installed"],
capture_output=True,
text=True,
check=True,
timeout=30,
)
if "wasm32-unknown-unknown" not in installed.stdout.splitlines():
pytest.skip("Rust wasm32-unknown-unknown target is required")
root = tmp_path_factory.mktemp("current_web_bundle")
fsm = root / "controller.toml"
fsm.write_text(_FSM, encoding="utf-8")
modes = []
for mode in ("walk", "guided", "entry"):
export = root / mode
_write_export(legacy_export, export, mode)
modes.append(f"--mode={mode}={export}")
destination = root / "app"
build = subprocess.run(
[
sys.executable,
"-c",
_BUILD,
str(REPO / "scripts/deploy.py"),
str(root),
"--bundle",
str(destination),
"--fsm",
str(fsm),
"--allow-incomplete",
*modes,
],
cwd=REPO,
capture_output=True,
text=True,
check=False,
timeout=300,
)
assert build.returncode == 0, build.stdout + build.stderr
result = subprocess.run(
["node", str(LOADER), str(destination / "bundle")],
capture_output=True,
text=True,
check=False,
timeout=60,
)
assert result.returncode == 0 and result.stdout, result.stdout + result.stderr
loaded = json.loads(result.stdout)
assert loaded["ok"], loaded.get("error")
return loaded
def test_the_bundle_a_page_would_fetch_actually_builds(loaded: dict) -> None:
"""Construction, with the trajectories a reference-guided mode needs.
The failure this pins is not subtle once you look -- it is a thrown error on
the first line a page runs. It survived because nothing ran that line.
"""
assert loaded["ok"], loaded.get("error")
assert loaded["modes"], "a bundle with no modes is not a bundle"
def test_a_recorded_motion_travels_with_the_bundle(loaded: dict) -> None:
"""Whichever modes declare a recording got one.
Reading this from the contracts rather than naming `jump` and `dance`: the
point is that the set the bundle *declares* and the set the page *supplies*
are the same set, whatever they contain.
"""
assert set(loaded["withTrajectory"]) == {"guided", "entry"}
assert set(loaded["withTrajectory"]) <= set(loaded["modes"])
def test_driving_it_produces_inferences_and_a_target(loaded: dict) -> None:
"""Built is not running. Four seconds of ticks, and it has to ask.
A controller that constructs and then never asks for an inference is the
other half of the same silence: the page renders, the robot stands, and
nothing says why.
"""
assert loaded["infers"] > 0, "four seconds of ticks and it never asked to infer"
assert loaded["inferredModes"], loaded
assert loaded["mode"] in loaded["modes"]
assert len(loaded["positions"]) == loaded["joints"], (
f"{len(loaded['positions'])} targets for {loaded['joints']} joints -- the "
f"publish side would be misaligned from wherever they stopped matching"
)
assert loaded["positions"] != pytest.approx(loaded["home"]), (
"the inference result never changed a joint target"
)
def test_this_host_computes_what_the_others_did(loaded: dict) -> None:
"""The reference vectors, replayed here.
This is the whole reason a bundle carries `reference.json`: the three hosts
run the same source and must produce the same numbers, and agreement is
measured rather than assumed. `observation` and `target` are maxima over
every frame, so anything above rounding is a real difference.
"""
r = loaded["reference"]
assert r["frames"] > 0 and r["inferences"] > 0, r
assert not r["modeMismatches"], r["modeMismatches"]
assert r["observation"] < 1e-6, f"observation differs by {r['observation']}"
assert r["target"] < 1e-6, f"target differs by {r['target']}"
assert not r["divergent"], (
f"terms this host sources differently than the one that recorded: {r['divergent']}"
)
def test_the_contract_maps_the_stick_not_the_page(loaded: dict) -> None:
"""Raw sticks in, a command out, and the contract is what turned one into
the other.
A page used to do this itself -- read the pad, apply the sign, scale by the
range, hand over a finished command. Two implementations of one contract,
and they drifted: the browser's table still spelled the axes
`left_stick_y` long after the dictionary had closed on `Ly`, which is a
bundle refused for naming a stick the way its own exporter names it.
So the host now pushes what the Gamepad API reports and nothing else. What
this pins is the part with no second chance: **the sign**. Pushing a stick
forward is `Ly = -1` in evdev's convention, and if that arrives as backwards
the robot drives away from the operator while every screen looks correct.
"""
pad = loaded.get("pad")
assert pad, loaded
lin_x = pad["axes"].get("lin_vel_x")
assert lin_x, f"the contract binds no stick to lin_vel_x: {pad['axes']}"
assert lin_x["source"] == "Ly", (
f"lin_vel_x is driven by {lin_x['source']!r}; this test reasons about `Ly`"
)
centred, forward, back = pad["centred"], pad["forward"], pad["back"]
assert centred[0] == 0.0, f"a centred stick asked for {centred[0]}"
# evdev reports a stick pushed **forward** as negative, and the contract
# carries sign -1, so `Ly = -1` has to come out positive.
assert forward[0] > 0, (
f"stick forward (Ly=-1) asked for {forward[0]}, which is backwards. "
f"Nothing downstream can catch this; a hand on the pad can"
)
assert back[0] < 0, f"stick back (Ly=+1) asked for {back[0]}"
assert forward[0] == pytest.approx(-back[0], rel=1e-6), (
f"the two ends are not symmetric: {forward[0]} vs {back[0]}"
)
# Full deflection is the edge of the range the policy trained on, not an
# absolute speed -- so it can never be asked for something off-distribution.
assert 0 < forward[0] <= 5.0, f"full stick asked for {forward[0]} m/s"
def test_a_go_event_actually_starts_the_motion(loaded: dict) -> None:
"""The button that fires a recorded motion, pressed on this host.
`rise` and `fall` are one frame wide and are derived from the change since
the last observation, so two observers do not see them twice -- the second
destroys them. This host had two: `padFrame` latched the buttons and then
`tick` latched them again, found no edge, and handed the controller an empty
set. A `toggle` survived, because a toggle is remembered rather than
re-derived, so entering the mode worked perfectly and the `go` never fired.
Nothing reported it. The mode was entered, the policy inferred every tick,
the panel said `jump`, and the robot stood still with `jump_phase` at 0 for
the whole length of a motion nobody could start. What separates the two is
the motion's own clock, which is what this reads.
"""
go = loaded.get("go")
assert go, loaded
assert go["phasesBeforeGo"] <= 1, (
f"the motion clock was already moving before the `go`: "
f"{go['phasesBeforeGo']} distinct phases in {go['mode']}"
)
assert go["phasesAfterGo"] > 10, (
f"{go['button']} on {go['on']} did not start {go['mode']}: its clock took "
f"{go['phasesAfterGo']} distinct value(s) over three seconds. The mode is "
f"entered and inferring either way, so nothing else here would notice"
)
def test_entering_a_motion_that_starts_on_entry_starts_it(loaded: dict) -> None:
"""The recorded motion whose mode is the whole of asking for it, entered on
this host and nothing else pressed.
The entry binding alone must start the phase clock and the mode must
hand control back when the recording ends. Before the press the entry
mode must stay inactive.
"""
entry = loaded.get("entry")
assert entry, loaded
assert entry["phasesBefore"] == 0, (
f"{entry['mode']} ran before anything reached it: {entry['phasesBefore']} phases"
)
assert entry["phasesDuring"] > 10, (
f"entering {entry['mode']} on {entry['enter']} did not start it: its clock took "
f"{entry['phasesDuring']} distinct value(s) over {entry['windowS']:.1f} s"
)
assert entry["modeAfter"] != entry["mode"], (
f"{entry['mode']} ({entry['durationS']:.2f} s) was still running "
f"{entry['windowS']:.1f} s after it was entered: the recording ended and "
f"nothing handed the robot back"
)
def test_a_key_switch_changes_modes_as_a_page_presses_it(loaded: dict) -> None:
"""The keyboard's own switches, pressed as a page presses them.
The keys a page is handed are browser codes, and a key the dictionary
names under another code, or one the host does not count as bound, is a
key that does nothing on a page that looks right -- and a page that does
not `preventDefault` it scrolls instead. So each keyboard switch that may
be pressed in the mode the robot starts in is pressed by its code, modifier
first, and the mode read back. The control group is a chord's key without
its modifier (1 without Ctrl), which must not reach the chord's mode.
"""
pressed = loaded.get("keyboard")
assert pressed, loaded
for p in pressed:
assert all(p["codes"]), f"{p['keys']} have no browser code: {p}"
assert all(p["bound"]), f"{p['codes']} were not reported as bound: {p}"
assert p["modeAfter"] == p["mode"], (
f"{' + '.join(p['codes'])} left the robot in {p['modeAfter']!r}, not {p['mode']!r}"
)
if p["with"]:
assert p["alone"] != p["mode"], (
f"{p['codes'][-1]} without {p['codes'][0]} switched to {p['alone']!r}: "
f"the modifier is not being read"
)
def test_a_pad_button_switches_modes_in_a_browser_d_pad_included(loaded: dict) -> None:
"""Every mode switch the bundle binds to the pad, pressed through `setPad`
the way `BUNDLE_README.md` tells a page to call it -- the d-pad's directions
by their names. `setPad` used to know only the ten buttons, so `menu` and
right, the dance, could not be made from a pad in a browser, and the
`false` it returned read as "nothing binds this". The control group is the
chord's button without its modifier, which must switch nothing.
"""
pressed = loaded.get("padSwitch")
assert pressed, loaded
assert any(b.startswith("dpad_") for p in pressed for b in p["buttons"]), (
"no switch on the d-pad: this test has lost the case it was written for"
)
for p in pressed:
assert all(p["bound"]), f"{p['buttons']} were not reported as bound: {p}"
assert p["modeAfter"] == p["mode"], (
f"{' + '.join(p['buttons'])} left the robot in {p['modeAfter']!r}, not {p['mode']!r}"
)
if p["alone"] is not None:
assert p["alone"] != p["mode"], (
f"{p['buttons'][-1]} alone switched to {p['alone']!r}, the chord's mode"
)
def test_the_pad_a_page_draws_is_the_pad_the_controller_reads(loaded: dict) -> None:
"""`padGuide()`, the drawing, against `inputs().keys`, what is bound.
A page draws the pad and the keyboard from the guide -- two lists since
2026-09-29, a key never drawn on a pad control. A key bound and missing
from the drawing works with nothing to say so; a key drawn and not bound
is a label on a key that does nothing -- and the page would not
`preventDefault` it, so an arrow would scroll the page instead. So the two
are held to one set, and every key switch pressed above is drawn with the
mode it enters. The control group is the whole pad being there, used or
not, which a guide listing only what it binds would fail.
"""
guide = loaded.get("guide")
assert guide is not None and "keyboard" in guide, loaded
controls = {c["control"]: c for c in guide["controls"]}
drawn = sorted(
{code for k in guide["keyboard"] for code in (*k["codes"]["key"], *k["codes"]["modifier"])}
)
assert drawn == loaded["boundCodes"], (
f"drawn and not bound: {sorted(set(drawn) - set(loaded['boundCodes']))}; "
f"bound and not drawn: {sorted(set(loaded['boundCodes']) - set(drawn))}"
)
assert {
"A",
"B",
"X",
"Y",
"LB",
"RB",
"Lx",
"Ly",
"Rx",
"Ry",
"LT",
"RT",
"dpad_up",
"dpad_down",
"dpad_left",
"dpad_right",
"menu",
} <= set(controls)
assert all("keys" not in c for c in guide["controls"]), "a key is drawn on the pad again"
strokes = {k["stroke"]: k for k in guide["keyboard"]}
for p in loaded.get("keyboard") or []:
stroke = f"{p['with']}+{p['key']}" if p["with"] else p["key"]
assert stroke in strokes, f"{stroke} switches into {p['mode']} and is not drawn"
assert any(s["enters"] == p["mode"] for s in strokes[stroke]["switches"]), (
f"{stroke} switches into {p['mode']} and the drawing does not say so"
)
def test_a_key_held_is_the_bundles_pad_pushed_and_a_stop_lets_go(loaded: dict) -> None:
"""The keyboard and the page's Stop, through the controller a page loads.
Three silences this pins. A page hands over `KeyboardEvent.code`s and the
wasm's own dictionary decides which are keys: a code that is not translated
is a key that does nothing, on a page that looks right. A key let up that
keeps driving is a robot walking on after the hand has left the keyboard.
And a Stop that does not reach a key still held stops nothing, with every
screen saying it has.
The control group is the pad: the key held past `full_after_s` must be what
the full stick asks for, exactly, and held half that must be half of it --
which is what makes the key's number mean something rather than merely
non-zero.
"""
keys = loaded.get("keys")
assert keys, loaded
inputs = keys["inputs"]
assert inputs["rawInput"] is True
assert inputs["controls"], "the operator gave no account of its own bindings"
assert keys["forwardKey"], (
f"nothing binds `key_w`, so there is no key to press: {inputs['keys']}"
)
assert keys["fullAfterS"], "the bundle's keyboard carries no `full_after_s`"
assert keys["bound"] is True, "the controller says it binds no such key"
assert keys["unbound"] is False, "a key nothing binds was reported as bound"
full = loaded["pad"]["forward"][0]
# Read at the last inference before the half second, a few milliseconds short.
assert keys["half"][0] == pytest.approx(full / 2, rel=0.02), (
f"held {keys['fullAfterS'] / 2} s the key asked for {keys['half'][0]}, the "
f"full stick for {full}: a key's hold is not its share of the travel"
)
assert keys["held"][0] == pytest.approx(full, rel=1e-5), (
f"held past {keys['fullAfterS']} s, with the browser's auto-repeat, the key "
f"asked for {keys['held'][0]}, not the full stick's {full}"
)
assert keys["letUp"][0] == 0.0, (
f"let up, the key still asks for {keys['letUp'][0]}: the stick did not centre"
)
assert keys["letGo"] is True, "letGo found no operator to let go"
assert keys["released"][0] == 0.0, (
f"after letGo, with the key still down, the command is {keys['released'][0]}: "
f"a Stop button would stop nothing"
)