"""Read a task's `controls.yaml`, the operator-control specification. **The specification is the source of truth and this is the only reader.** The signs, the splits and the bindings live in the file; `mjrl.tasks.operator` drives `replay from what this returns, `scripts/export.py` embeds it in the deployment contract, and `deploy/fsm/src/operator.rs` drives the robot and the browser from that. Programs that must agree about which way is forward agree by reading one file rather than by people reading each other's docstrings. Everything here fails loudly, for the reason `load_servo_curve` gives about the motor spec: every quiet alternative is worse than a stopped import. A missing axis, a sign left out, a `sign: 0`, a binding naming a key that does not exist -- each would otherwise become a default, and a default sign is a robot that walks the wrong way while the screen looks entirely normal. ## What the file says `command` is a list, one entry per command term an operator drives -- one for a velocity-tracking task and one more if the policy takes posture input. **The pad and the keyboard are two paths**, each bound straight to what it does, and neither names a control of the other (2026-09-29): * **The pad** binds a stick or a trigger to a command axis, with a sign. A stick can carry more than one axis: a binding may take part of its travel (`travel: [0.0, 0.5]`), hand it on to the next one (`[0.0, 0.5, 0.5, 0.75]` climbs over the first half and falls back to zero by three quarters), sit on a layer a button brings in (`shifted: true`), or be one of several controls summed into one axis (a list). The loader refuses two bindings that would climb over the same part of the same stick, which is the one way this could go quietly wrong. * **The keyboard** binds keystrokes to one direction of an axis -- `"+"` is the axis's own positive direction, as its `positive:` words it, so the keyboard has no signs: there is no stick for a sign to be relative to. A keystroke is a key (`key_j`), a modifier on its own (`shift`), or a modifier held with a key (`shift+key_j`), which is a different keystroke from the key alone: J and Shift + J are two things and never both (`controller/vocabulary.py`). A key held pushes its direction further the longer it is held, full after `full_after_s`, and let go it is back at rest. An axis a task deliberately leaves off the keyboard says why (`unbound:`). Until 2026-09-29 the keyboard was a *virtual pad*: a key held moved one of the pad's controls, read through the pad's own mapping. That made the two devices agree by construction, and it made a keyboard that could not lay itself out for hands: a key could only be a stick, so J could not turn while Shift + J twisted, and Shift, Alt and Ctrl could not hold an arm out. The layout Control-agent 3.1 asks for needs both, so the keyboard became a path of its own, and agreement is the file's: both paths name the same axes, and `load_controls` refuses a command axis either one leaves out without saying. * **An axis may move rather than be placed** (`integrate_s`), on the pad. A deflection is then a speed -- full deflection carries the axis from its rest to either end of its range in that many seconds -- and let go it stays where it is. A body-height command is one use. `devices.gamepad.reset` names the button whose tap puts every such axis back at its rest. The keyboard places it as it places every other axis: a key held pushes it towards its end and it is back at rest when let go. * **A task may keep controls for itself.** The top-level `task:` names controls no command reads and what the task does with each. Each device binds every one of them: the pad one control each (an axis for an `amount`, a d-pad direction for a `press`), the keyboard one or more keystrokes. The task's own code answers them by name, in replay a term of its own (`Operator.task_control`) and on the robot its deploy hook (`deploy/fsm/src/hook.rs`). """ from __future__ import annotations import hashlib import itertools import math from dataclasses import dataclass from pathlib import Path from typing import Any import yaml # The control dictionary: what a pad and a keyboard can say. Read, never # repeated -- see `_AXES` below. from controller import vocabulary as _vocabulary __all__ = [ "CENTRE", "SCHEMA", "Axis", "Binding", "Command", "Controls", "KeyAxis", "TaskControl", "controller_contract", "key_name", "load_controls", "stroke_name", ] #: The schema this reader implements, and the contract block it writes is #: `operator_controller/`. SCHEMA = 2 #: The scaling rule this repository implements. A file asking for another one is #: refused rather than run under this one. _SCALING_RULE = "full_deflection_is_range_edge" #: The gamepad vocabulary, read from the dictionary rather than repeated. #: #: `controller/vocabulary.json` is the list and #: `python -m controller --vocabulary` prints it. This module only decides which #: of those words a task's controls file may use and what happens when it does #: -- the meanings, which is the part that belongs to a task. #: #: There is no list here on purpose. There were three for a day: this one, #: `deploy/fsm/src/vocabulary.rs`, and a prose block in a deploy manifest. _AXES = _vocabulary.axes() _BUTTONS = frozenset(_vocabulary.buttons()) #: Axis name -> the attribute a `controller` state object carries. A case #: change and nothing else: `controller/xbox.py` reports the dictionary's names #: now, and this is only Python's habit of lowercase attributes. _STICK_FIELD = {name: name.lower() for name in _AXES} #: Which of the dictionary's axes are sticks (-1..1) and which are triggers #: (0..1). Read from the ranges the dictionary gives, not from the names. _BIPOLAR = frozenset(a["name"] for a in _vocabulary.load()["axes"] if a["range"][0] < 0) #: The four d-pad directions: where a task's `press` control goes on the pad. #: A rocker is held or not, which is what a `press` reads, and the ten buttons #: stay the bundle's for switching modes and the operator's for letting go. _DPAD = frozenset(b["name"] for b in _vocabulary.load()["dpad"]) #: The notched keyboard's other half, retired on 2026-09-27: one key letting go #: of every stick and trigger at once, needed while a key left its control where #: the last press put it. A key let up is back at rest and the release lets go #: of everything, so it did nothing either did not. Named only to refuse a file #: that still has it. CENTRE = "centre" #: The gestures a `shift` implements: `hold`, the layer in for as long as the #: button is held, and `toggle`, in from one click to the next. `rise` and #: `fall` are one tick long, which a layer cannot be. _SHIFT_GESTURES = ("hold", "toggle") #: The keyboard scheme: keystrokes bound to what they do. See the module #: docstring. _KEYBOARD_SCHEME = "keys" #: What a task control is: `amount`, 0 to 1 as far as it is held -- a trigger, #: or a key's ramp -- and `press`, 1 while it is held and 0 otherwise. _TASK_KINDS = ("amount", "press") @dataclass(frozen=True) class Axis: name: str unit: str positive: str #: The command config field holding where a centred stick puts this axis. #: `None` is zero. A height is the case that needs it -- zero is a #: body on the floor, and the range it would be clamped to is not where the #: robot stands. rest: str | None = None #: Seconds full deflection takes to carry the axis from its rest to either #: end of its range: the controls move it rather than place it, and let go #: it stays where it is. `None` is an axis a control places, as a stick's #: position places a walking speed. integrate_s: float | None = None @dataclass(frozen=True) class Command: """One command term an operator drives. The file has a list of these.""" #: The command term's key in `cfg.commands`. term: str feeds: str frame: str axes: tuple[Axis, ...] scaling: dict[str, Any] @dataclass(frozen=True) class Binding: """One pad control's share of one command axis.""" #: A dictionary axis: `Lx` `Ly` `Rx` `Ry` `LT` `RT`. source: str sign: float #: The part of the control's travel this binding takes, as fractions of #: full deflection. `(0.0, 0.5)` reaches full at half travel and holds #: there; `(0.5, 1.0)` is silent until half travel and then climbs. Two #: more, `(0.0, 0.5, 0.5, 0.75)`, are where it falls back: full until the #: third, zero from the fourth on -- a binding that gives the control up to #: the one climbing over the same stretch. travel: tuple[float, ...] = (0.0, 1.0) #: Live only while the `shift` button has the other layer in -- held, or #: toggled, as `shift_gesture` says. A source that has a shifted binding #: drives **only** that binding while shifted; every other source is #: unaffected. shifted: bool = False @dataclass(frozen=True) class KeyAxis: """One command axis on the keyboard: the keystrokes pushing it each way, or why none do.""" #: Keystrokes towards the axis's own positive direction, as its `positive:` #: words it, and away from it. Both empty exactly when `unbound` says why. plus: tuple[str, ...] = () minus: tuple[str, ...] = () unbound: str | None = None @dataclass(frozen=True) class TaskControl: """A control the task answers itself, by name: no command reads it.""" name: str #: `amount` (0..1, as far as it is held) or `press` (1 while held). kind: str #: What the task does with it, in the file's words. does: str @dataclass(frozen=True) class Controls: """The specification, parsed: the commands, one operator for all of them.""" commands: tuple[Command, ...] #: The pad: command axis name -> the controls that drive it, summed. bindings: dict[str, tuple[Binding, ...]] #: The button that brings the shifted layer in, or `None` for a file with none. shift: str | None release_button: str #: Seconds a key is held for its direction to reach full deflection, or a #: task's `amount` to reach 1. It climbs linearly until then and is back at #: rest when the key comes up. full_after_s: float #: The keyboard: command axis name -> its keystrokes, every axis present. key_axes: dict[str, KeyAxis] #: Keystrokes that let go of everything, as the pad's release button does. key_release: tuple[str, ...] #: The controls the task keeps for itself, by name, in the file's order. #: Empty for most tasks. task: dict[str, TaskControl] #: Task control -> the one pad control it is on. pad_task: dict[str, str] #: Task control -> the keystrokes it is on. key_task: dict[str, tuple[str, ...]] keyboard: dict[str, Any] gamepad: dict[str, Any] source_sha256: str source: Path #: How the shift brings its layer in: `hold`, for as long as it is held, #: or `toggle`, from one click to the next. `None` with no shift. shift_gesture: str | None = None #: The button whose tap puts every integrating axis back at its rest, or #: `None`. A tap is the button pressed and let go with no stick it could #: have been reaching for moved in between. reset: str | None = None def command(self, term: str) -> Command: for c in self.commands: if c.term == term: return c raise KeyError( f"{self.source}: describes the commands {[c.term for c in self.commands]}, " f"not {term!r}. A term driven from a file that does not describe it " "would take its bindings from nowhere." ) @property def sources(self) -> frozenset[str]: """Every pad axis some command binding reads.""" return frozenset(b.source for bs in self.bindings.values() for b in bs) @property def integrating(self) -> dict[str, float]: """Axis name -> `integrate_s`, for every axis the controls move rather than place.""" return {a.name: a.integrate_s for c in self.commands for a in c.axes if a.integrate_s is not None} @property def keystrokes(self) -> tuple[str, ...]: """Every keystroke the keyboard block binds, once each, in file order.""" strokes = [s for k in self.key_axes.values() for s in (*k.plus, *k.minus)] strokes += self.key_release strokes += [s for ss in self.key_task.values() for s in ss] return tuple(dict.fromkeys(strokes)) class _StrictLoader(yaml.SafeLoader): """`yaml.safe_load`, except that a key written twice is an error. PyYAML keeps the last of two equal keys and says nothing, so an axis written twice in the keyboard's `axes` is one binding silently gone -- the keyboard then cannot do something and nothing points at the line that took it away. """ def _mapping_without_duplicates(loader: yaml.SafeLoader, node: yaml.MappingNode) -> dict: seen: set[Any] = set() for key_node, _value in node.value: key = loader.construct_object(key_node) if key in seen: raise ValueError( f"line {key_node.start_mark.line + 1}: {key!r} is written twice. YAML " "keeps the last one and drops the other without a word." ) seen.add(key) return loader.construct_mapping(node, deep=True) _StrictLoader.add_constructor( yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _mapping_without_duplicates ) def _require(doc: Any, path: str, where: Path) -> Any: node = doc for part in path.split("."): if not isinstance(node, dict) or part not in node: raise ValueError(f"{where}: missing {path}") node = node[part] if node is None: raise ValueError(f"{where}: {path} is null; it has to be decided, not defaulted") return node def load_controls(path: Path) -> Controls: """Parse a task's `controls.yaml`. See the module docstring.""" if not path.exists(): raise FileNotFoundError( f"{path} not found. It holds how an operator's input becomes the " "command the policy observes, and neither play nor the exporter can " "proceed without it." ) raw = path.read_bytes() try: doc = yaml.load(raw.decode("utf-8"), Loader=_StrictLoader) # a SafeLoader subclass except ValueError as exc: raise ValueError(f"{path}: {exc}") from None version = _require(doc, "schema_version", path) if version != SCHEMA: raise ValueError( f"{path}: schema_version is {version!r}; this reader implements {SCHEMA}. " "Schema 1 was retired -- regenerate the file with " ".claude/skills/controls/scripts/write_controls.py." ) return _parse(doc, raw, path) def _check_button(name: Any, what: str, path: Path) -> None: # A button name is a contract, not a convention: `view` is on the pad and # the robot's service does not send it, so binding it works on a bench and # does nothing on the robot. if name not in _BUTTONS: extra = (" `view` is on the pad but the service does not publish it." if name == "view" else "") raise ValueError( f"{path}: {what} is {name!r}, which the robot's gamepad service " f"does not publish. It publishes {sorted(_BUTTONS)}.{extra}" ) def _check_stroke(stroke: Any, where: str, path: Path) -> tuple[str | None, str]: """A keystroke, or a refusal naming where it was written.""" if not isinstance(stroke, str): raise ValueError(f"{path}: {where} has {stroke!r}, which is not a keystroke") try: return _vocabulary.keystroke(stroke) except ValueError as exc: raise ValueError( f"{path}: {where}: {exc}\n" f" python -m controller --vocabulary\n" f" (A key it lacks is added there, with what it also does in " f"MuJoCo's viewer: the viewer calls the user callback in addition to its " f"own shortcuts, so most keys do two things at once.)" ) from None def _positive_seconds(value: Any) -> bool: return (not isinstance(value, bool) and isinstance(value, (int, float)) and 0 < value < math.inf) def _travel_is_ordered(travel: list) -> bool: """`0 <= from < to <= 1`, and with a fall `to <= back < off <= 1`. A climb or a fall of zero length would be a step, which a stick's travel cannot hold still on; the hold between them may be zero, and is, where one binding's fall starts as the next one's climb does.""" a, z, *fall = travel if not 0.0 <= a < z <= 1.0: return False return not fall or z <= fall[0] < fall[1] <= 1.0 def _field(node: Any, key: str, at: str, path: Path) -> Any: """`_require` for a node inside a list, so the message says which entry.""" if not isinstance(node, dict) or key not in node: raise ValueError(f"{path}: missing {at}.{key}") if node[key] is None: raise ValueError(f"{path}: {at}.{key} is null; it has to be decided, not defaulted") return node[key] def _parse(doc: dict, raw: bytes, path: Path) -> Controls: """Every check here is a control that would drive nothing, drive two things, or be out of one device's reach, without anything raising.""" commands = _parse_commands(doc, path) names = [a.name for c in commands for a in c.axes] task = _parse_task(doc, path) gamepad = _require(doc, "devices.gamepad", path) bindings, shift, gesture, release, reset = _parse_pad(gamepad, commands, path) pad_task = _parse_pad_task(gamepad, task, bindings, {release, shift, reset}, path) keyboard = _require(doc, "devices.keyboard", path) full, key_axes, key_release, key_task = _parse_keyboard(keyboard, names, task, path) return Controls( commands=commands, bindings=bindings, shift=shift, release_button=release, full_after_s=float(full), key_axes=key_axes, key_release=key_release, task=task, pad_task=pad_task, key_task=key_task, keyboard=keyboard, gamepad=gamepad, source_sha256=hashlib.sha256(raw).hexdigest(), source=path, shift_gesture=gesture if shift is not None else None, reset=reset, ) def _parse_commands(doc: dict, path: Path) -> tuple[Command, ...]: listed = _require(doc, "command", path) if not isinstance(listed, list) or not listed: raise ValueError( f"{path}: `command` is a list of the commands an operator " f"drives, one entry per command term; got {type(listed).__name__}" ) commands = [] for i, entry in enumerate(listed): at = f"command[{i}]" axes = [] for j, a in enumerate(_field(entry, "axes", at, path)): where = f"{at}.axes[{j}]" integrate = a.get("integrate_s") if isinstance(a, dict) else None if isinstance(a, dict) and "integrate_s" in a and not _positive_seconds(integrate): raise ValueError( f"{path}: {where}.integrate_s is {integrate!r}; it is the seconds full " "deflection takes to carry the axis from its rest to either end of its " "range, a positive number. Leave it out for an axis a control places." ) axes.append(Axis( name=_field(a, "name", where, path), unit=_field(a, "unit", where, path), positive=_field(a, "positive", where, path), rest=a.get("rest"), integrate_s=float(integrate) if integrate is not None else None, )) if not axes: raise ValueError(f"{path}: {at} names no axes") scaling = _field(entry, "scaling", at, path) if scaling.get("rule") != _SCALING_RULE: raise ValueError( f"{path}: {at}.scaling.rule is {scaling.get('rule')!r}; this repository " f"implements {_SCALING_RULE!r}. Add the rule rather than running the wrong one." ) commands.append(Command( term=_field(entry, "term", at, path), feeds=_field(entry, "feeds", at, path), frame=_field(entry, "frame", at, path), axes=tuple(axes), scaling=scaling, )) terms = [c.term for c in commands] if len(set(terms)) != len(terms): raise ValueError(f"{path}: a command term is listed twice: {terms}") # Bindings are keyed by axis name, so a name two commands share would be one # binding driving both. names = [a.name for c in commands for a in c.axes] if len(set(names)) != len(names): raise ValueError(f"{path}: an axis name is used twice across the commands: {names}") return tuple(commands) def _parse_task(doc: dict, path: Path) -> dict[str, TaskControl]: """The top-level `task:`, the controls the task answers itself.""" declared = doc.get("task") if declared is None: if "task" in doc: raise ValueError(f"{path}: task is null; leave it out for a task that keeps none") return {} if not isinstance(declared, dict) or not all(isinstance(n, str) for n in declared): raise ValueError( f"{path}: task is a {type(declared).__name__}; it maps each control the task " "answers itself to its `kind` and what it `does`" ) task = {} for name, entry in declared.items(): kind = _field(entry, "kind", f"task.{name}", path) if kind not in _TASK_KINDS: raise ValueError( f"{path}: task.{name}.kind is {kind!r}; a task control is `amount` (0 to " "1, as far as it is held) or `press` (1 while it is held)" ) does = entry.get("does") if not isinstance(does, str) or not does.strip(): raise ValueError(f"{path}: the task keeps {name} and does not say what it does") task[name] = TaskControl(name, kind, does) return task def _parse_pad(gamepad: dict, commands: tuple[Command, ...], path: Path): """The pad's command bindings, its shift, its release and its reset.""" names = [a.name for c in commands for a in c.axes] for field in ("scheme", "layout", "axes", "deadzone", "release_button"): _require(gamepad, field, path) if gamepad["scheme"] != "absolute": raise ValueError( f"{path}: gamepad scheme is {gamepad['scheme']!r}. This file implements " "`absolute` only: a stick's position is the command. An axis the controls " "should move rather than place says `integrate_s` on the axis, for both " "devices at once." ) release = gamepad["release_button"] _check_button(release, "release_button", path) shift = gesture = None if "shift" in gamepad: declared = gamepad["shift"] shift = _field(declared, "button", "devices.gamepad.shift", path) _check_button(shift, "shift.button", path) gesture = _field(declared, "gesture", "devices.gamepad.shift", path) if gesture not in _vocabulary.gestures(): raise ValueError( f"{path}: shift.gesture is {gesture!r}; the dictionary's gestures are " f"{list(_vocabulary.gestures())}" ) if gesture not in _SHIFT_GESTURES: raise ValueError( f"{path}: shift.gesture is {gesture!r}; a shift is " f"{' or '.join(map(repr, _SHIFT_GESTURES))}. " "A one-tick gesture brings a layer in for one tick." ) if shift == release: raise ValueError( f"{path}: {shift} is both the shift and the release button. One " "press would hand the command back and change what a stick means." ) bound = gamepad["axes"] stray = sorted(set(bound) - set(names)) if stray: raise ValueError( f"{path}: gamepad.axes names {stray}, which no command has. A typo " f"here is a stick that drives nothing. The axes are {names}" ) bindings: dict[str, tuple[Binding, ...]] = {} for name in names: entry = bound.get(name) if not entry: raise ValueError(f"{path}: no control drives {name}; every command axis needs one") parts = [] for part in entry if isinstance(entry, list) else [entry]: if not isinstance(part, dict) or "source" not in part: raise ValueError(f"{path}: {name} has a binding with no source: {part!r}") source = part["source"] if source not in _STICK_FIELD: raise ValueError( f"{path}: {name} names {source!r}, which the robot's gamepad " f"service does not publish. It publishes {list(_AXES)}" ) sign = part.get("sign") if sign not in (1, -1): # Not clamped to a default: a sign is the one value here whose # wrong answer looks exactly like the right one. raise ValueError(f"{path}: {name} has sign {sign!r}; it must be 1 or -1") travel = part.get("travel", [0.0, 1.0]) if ( not isinstance(travel, list) or len(travel) not in (2, 4) or not all(isinstance(t, (int, float)) for t in travel) or not _travel_is_ordered(travel) ): raise ValueError( f"{path}: {name} has travel {travel!r}; it is [from, to] with " "0 <= from < to <= 1, or [from, to, back, off] with " "0 <= from < to <= back < off <= 1, as fractions of full deflection" ) shifted = part.get("shifted", False) if type(shifted) is not bool: raise ValueError(f"{path}: {name} has shifted {shifted!r}; it is true or false") if shifted and shift is None: raise ValueError( f"{path}: {name} is on the shifted layer and the file declares no " "shift button, so nothing can ever reach it" ) parts.append(Binding(source, float(sign), tuple(float(t) for t in travel), shifted)) bindings[name] = tuple(parts) # No two bindings may climb over the same stretch of the same control in the # same layer: one deflection would then move two axes, and each binding # alone looks correct. A binding's fall is not a claim -- it is the one # stretch where a deflection may move two axes, because it is how the # binding gives the control up to the next one. claims: dict[tuple[str, bool], list[tuple[float, float, str]]] = {} for name, parts in bindings.items(): for b in parts: claims.setdefault((b.source, b.shifted), []).append((*b.travel[:2], name)) for (source, layer), spans in claims.items(): spans.sort() for (_a0, b0, n0), (a1, b1, n1) in itertools.pairwise(spans): if a1 < b0: raise ValueError( f"{path}: {n0} and {n1} both take {source} from {a1:g} to " f"{min(b0, b1):g} of its travel{' on the shifted layer' if layer else ''}. " "One deflection would move both; give them separate travel." ) if shift is not None and not any(b.shifted for parts in bindings.values() for b in parts): raise ValueError(f"{path}: {shift} is declared as the shift and no binding is shifted") # The reset: a tap puts every integrating axis back at its rest. With no # such axis it would be a button that does nothing, bound; on the release # button it would be a second meaning for one press. It may be the shift -- # a hold can change height and a tap can put it back # to standing, told apart by whether the stick moved. reset = gamepad.get("reset") if reset is not None or "reset" in gamepad: _check_button(reset, "reset", path) if reset == release: raise ValueError( f"{path}: {reset} is both the reset and the release button. The release " "already puts every integrating axis back at its rest; a reset on it " "is the same press read twice." ) if not any(a.integrate_s is not None for c in commands for a in c.axes): raise ValueError( f"{path}: gamepad.reset is {reset}, and no axis has `integrate_s`. It " "puts an integrating axis back at its rest; with none, it is a button " "that does nothing and looks bound." ) return bindings, shift, gesture, release, reset def _parse_pad_task( gamepad: dict, task: dict[str, TaskControl], bindings: dict[str, tuple[Binding, ...]], reserved: set, path: Path, ) -> dict[str, str]: """`gamepad.task`: every task control on one pad control of its kind.""" pad_task = _task_block(gamepad, "gamepad", task, path) commanded = {b.source for parts in bindings.values() for b in parts} owner: dict[str, str] = {} for name, control in pad_task.items(): kind = task[name].kind if kind == "press" and control not in _DPAD: raise ValueError( f"{path}: gamepad.task.{name} is {control!r}; a `press` goes on a d-pad " f"direction ({sorted(_DPAD)}) -- the buttons are the bundle's mode " "switches and the operator's release" ) if kind == "amount" and control not in _STICK_FIELD: raise ValueError( f"{path}: gamepad.task.{name} is {control!r}; an `amount` goes on an axis " f"the robot's gamepad service publishes, a trigger or a stick ({list(_AXES)})" ) if control in commanded: raise ValueError( f"{path}: {control} is both the task's ({name}) and a command's; one " "deflection would do both" ) if control in reserved: raise ValueError( f"{path}: {control} is the task's ({name}) and the release, the shift or " "the reset button; one press would do both" ) if control in owner: raise ValueError( f"{path}: {control} is on two task controls, {owner[control]} and {name}; " "the task could not tell them apart" ) owner[control] = name return pad_task def _task_block(device: dict, which: str, task: dict[str, TaskControl], path: Path) -> dict: """A device's `task:`, naming exactly the controls the top-level `task:` does.""" block = device.get("task") if block is None: block = {} if not isinstance(block, dict): raise ValueError( f"{path}: {which}.task is a {type(block).__name__}; it maps each control the " "top-level `task:` declares to where it is on this device" ) stray = sorted(set(block) - set(task)) if stray: raise ValueError( f"{path}: {which}.task names {stray}, which the top-level `task:` does not " f"declare ({sorted(task) or 'nothing'}). A task control is declared once, with " "its kind and what it does, and bound on each device by that name." ) missing = [n for n in task if n not in block] if missing: raise ValueError( f"{path}: {which}.task leaves out {missing}. Each device has to be able to " "reach every control the task keeps on its own." ) return dict(block) def _parse_keyboard(keyboard: dict, names: list[str], task: dict[str, TaskControl], path: Path): """The keyboard: keystrokes on axis directions, the release and the task's controls. Every command axis appears, bound or said to be unbound.""" if not isinstance(keyboard, dict): raise ValueError(f"{path}: devices.keyboard is a {type(keyboard).__name__}") if "step" in keyboard: raise ValueError( f"{path}: the keyboard has a `step`, the notched keyboard retired on " "2026-09-26 -- one press, a tenth of the travel, kept until pressed back. A " "key now pushes its direction for as long as it is held and is back at rest " "when it comes up: write `full_after_s`, the seconds held to full deflection." ) if CENTRE in keyboard: raise ValueError( f"{path}: the keyboard has `{CENTRE}`, retired on 2026-09-27 with the notched " "keyboard it served: a key let up is back at rest, and the release lets go " "of everything. Delete it." ) for field in ("scheme", "full_after_s", "axes", "release"): _require(keyboard, field, path) if keyboard["scheme"] != _KEYBOARD_SCHEME: raise ValueError( f"{path}: keyboard scheme is {keyboard['scheme']!r}. This file implements " f"`{_KEYBOARD_SCHEME}`: each keystroke bound to one direction of an axis, " "the release, or a task control." ) full = keyboard["full_after_s"] if not _positive_seconds(full): raise ValueError( f"{path}: keyboard full_after_s is {full!r}; it is the seconds a key is held " "for its direction to reach full deflection, a positive number" ) # One keystroke, one thing: an axis direction or the release. The task's # auxiliary controls may share one with each other. Two tools # both close on Space, and a mode reads only its own side's -- but not with # an axis or the release, or one key would do both. owner: dict[str, str] = {} parsed: dict[str, tuple[str | None, str]] = {} def claim(stroke: Any, what: str, where: str, exclusive: bool = True) -> str: parsed[stroke] = _check_stroke(stroke, where, path) if stroke in owner and (exclusive or not owner[stroke].startswith("task ")): raise ValueError( f"{path}: {stroke} is on {owner[stroke]} and on {what}. One keystroke " "would do both; give each its own." ) if exclusive: owner[stroke] = what else: owner.setdefault(stroke, what) return stroke def strokes(listed: Any, where: str) -> list: if not isinstance(listed, list) or not listed: raise ValueError( f"{path}: {where} is {listed!r}; it is a non-empty list of keystrokes" ) return listed declared = keyboard["axes"] if not isinstance(declared, dict): raise ValueError( f"{path}: keyboard.axes is a {type(declared).__name__}; it maps every command " "axis to its keystrokes" ) stray = sorted(set(declared) - set(names)) if stray: raise ValueError( f"{path}: keyboard.axes names {stray}, which no command has. A typo here is " f"a key that drives nothing. The axes are {names}" ) key_axes: dict[str, KeyAxis] = {} for name in names: if name not in declared: raise ValueError( f"{path}: keyboard.axes leaves out {name}. Every command axis is on the " "keyboard or says why not (`unbound: `): an axis quietly missing is " "a keyboard that cannot do something the pad can, and nothing says so." ) entry = declared[name] if isinstance(entry, dict) and set(entry) == {"unbound"}: why = entry["unbound"] if not isinstance(why, str) or not why.strip(): raise ValueError( f"{path}: keyboard.axes.{name} is unbound and does not say why" ) key_axes[name] = KeyAxis(unbound=why) continue if not isinstance(entry, dict) or set(entry) != {"+", "-"}: raise ValueError( f"{path}: keyboard.axes.{name} is {entry!r}; it is {{\"+\": [...], \"-\": " "[...]}, the keystrokes towards the axis's positive direction and away " "from it, or {unbound: }" ) plus = [claim(s, f"{name} +", f"keyboard.axes.{name}.+") for s in strokes(entry["+"], f"keyboard.axes.{name}.+")] minus = [claim(s, f"{name} -", f"keyboard.axes.{name}.-") for s in strokes(entry["-"], f"keyboard.axes.{name}.-")] key_axes[name] = KeyAxis(plus=tuple(plus), minus=tuple(minus)) release = tuple(claim(s, "the release", "keyboard.release") for s in strokes(keyboard["release"], "keyboard.release")) key_task = {} for name, listed in _task_block(keyboard, "keyboard", task, path).items(): where = f"keyboard.task.{name}" seen = [claim(s, f"task {name}", where, exclusive=False) for s in strokes(listed, where)] if len(set(seen)) != len(seen): raise ValueError(f"{path}: {where} lists a keystroke twice: {seen}") key_task[name] = tuple(seen) # A modifier held on its own that also modifies a key: holding it for the # one would do the other while the hand reaches for the key. A key that is # one of the modifier's own keys (`key_left_shift`) held alone is the same. modifiers = _vocabulary.modifiers() chords = {m for m, _k in parsed.values() if m is not None} alone = {k for m, k in parsed.values() if m is None and k in modifiers} alone |= {m for m, keys in modifiers.items() for _m, k in parsed.values() if _m is None and k in keys} both = sorted(chords & alone) if both: raise ValueError( f"{path}: {', '.join(both)} is bound on its own and also modifies a key " f"({', '.join(s for s, (m, _k) in parsed.items() if m in both)}). Holding it " "for the one would do it while reaching for the other." ) return full, key_axes, release, key_task def controller_contract(controls: Controls, env_cfg: Any) -> dict[str, Any]: """The specification, shaped for an exported policy's contract. A transcription of the file rather than a description of the code: what a consumer receives is what `play` read. `source_sha256` is carried so it can say which revision, and a runner that wants to diff two bundles has a key to do it with. `deploy/fsm/src/operator.rs` reads it, as `operator_controller/2`; the name is the schema's, and the version is the file's, so a reader built for anything else refuses it by name. `task` is the file's top-level `task:`, kind and words, and `{}` for a task that keeps none: the controller refuses a hook reading a name it does not declare. Each device's own `task:` stays in its block, verbatim. Args: env_cfg: the **environment** config, whose command terms hold the values the file names by field -- `rest: neutral_height` becomes the number. A consumer on the robot has no config to look a field up in, so the block carries the number, and the name beside it for a reader who wants to know where it came from. Required: a rest left as a name is a height the robot would read as zero, which is a body on the floor. Called at export rather than when the config is built, because a task adds its other command terms after `velocity_env_cfg` returns -- `velocity_env_cfg` attaches this as a callable, the way a reference contract is attached. """ commands = [] for c in controls.commands: term_cfg = (getattr(env_cfg, "commands", None) or {}).get(c.term) axes = [] for i, a in enumerate(c.axes): entry = {"name": a.name, "index": i, "unit": a.unit, "positive": a.positive, "range_from": f"command_ranges.{c.term}.{a.name}"} if a.rest: if term_cfg is None or not hasattr(term_cfg, a.rest): raise ValueError( f"{controls.source}: {c.term}.{a.name} rests at `{a.rest}`, and the " f"environment config has no command term {c.term!r} carrying it. " "The block needs the number: a robot has no config to look it up in." ) entry["rest"] = float(getattr(term_cfg, a.rest)) entry["rest_from"] = a.rest if a.integrate_s is not None: entry["integrate_s"] = float(a.integrate_s) axes.append(entry) entry = {"term": c.term, "feeds": c.feeds, "frame": c.frame, "axes": axes, "scaling": dict(c.scaling)} entry.update(_command_shape(controls, c, term_cfg)) commands.append(entry) return { "schema": f"operator_controller/{SCHEMA}", "source": { "file": controls.source.name, "sha256": controls.source_sha256, "note": "Parsed from the specification play reads. Comments and provenance " "live in the source file.", }, "command": commands, "task": {t.name: {"kind": t.kind, "does": t.does} for t in controls.task.values()}, "devices": { "gamepad": dict(controls.gamepad), "keyboard": dict(controls.keyboard), }, } def _command_shape(controls: Controls, c: Command, term_cfg: Any) -> dict[str, Any]: """What happens to a command between the stick and the policy, if anything. Two things a command term can carry, and a consumer on the robot has no config to find either in, so the block carries the numbers: * **`bands`** -- a narrower band some axes are held to while the velocity command walks. `command_ranges.` is the standing band, the widest the command goes and what a full stick reaches; at or above `standing_below`, the norm of the velocity command's `[vx, vy, wz]`, each axis named in `moving` is clamped to it. Read off the term's `moving` and `stand_threshold`: a half-range or a `(low, high)` pair per axis. * **`max_rate`** -- how fast the command may move, in its own units per second, because the policy was trained on a command that ramps. Absent is a command that steps, which is what every other term does. A term that carries neither gets neither, and the block is what it was. A `moving` without a threshold, or naming an axis the file does not, raises: a band nobody can apply is a clamp the robot silently skips. """ out: dict[str, Any] = {} moving = getattr(term_cfg, "moving", None) if moving is not None: threshold = getattr(term_cfg, "stand_threshold", None) velocity = getattr(term_cfg, "velocity_command", None) or getattr( term_cfg, "velocity_command_name", None ) if threshold is None or velocity is None: raise ValueError( f"{controls.source}: {c.term} has a moving band and no " "`stand_threshold` / velocity command to decide when it applies" ) names = {a.name for a in c.axes} band = {} for name, value in vars(moving).items(): if name.startswith("_"): continue if name not in names: raise ValueError( f"{controls.source}: {c.term}'s moving band names {name!r}, " f"which is not one of the file's axes {sorted(names)}" ) if isinstance(value, (int, float)) and not isinstance(value, bool): band[name] = [-float(value), float(value)] else: low, high = value band[name] = [float(low), float(high)] out["bands"] = {"standing_below": float(threshold), "velocity_term": str(velocity), "moving": band} max_rate = getattr(term_cfg, "max_rate", None) if max_rate is not None: out["max_rate"] = float(max_rate) return out def key_name(code: int) -> str: """A GLFW keycode as something a person can read off a banner. A dictionary key is shown by its own name less the `key_` prefix -- `W`, `KP8` for `keypad_8` -- and anything else falls back to the number, which is what a handler would need to remap it. """ for name, codes in _vocabulary.key_codes().items(): if codes["glfw"] == code: if name.startswith("keypad_"): return "KP" + name[len("keypad_"):] return name.removeprefix("key_").upper() return str(code) def stroke_name(stroke: str) -> str: """A keystroke as a banner shows it: `Shift+J`, `Ctrl`, `SPACE`, `KP1`.""" modifier, key = _vocabulary.keystroke(stroke) shown = (key.capitalize() if key in _vocabulary.modifiers() else key_name(_vocabulary.key_codes()[key]["glfw"])) return f"{modifier.capitalize()}+{shown}" if modifier else shown