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

144 lines
5.6 KiB
Python

"""Game controllers, as their own axis.
A fourth thing alongside the framework, the tasks and the scenes, and separate for
the same reason a scene is: **it knows nothing about robots.** Nothing here has an
opinion about what a stick means. It reports that the left stick is at (0.4, -0.9)
and that A is down; deciding that this is 0.2 m/s forward belongs to the task, in
`mjrl.tasks.operator` or the native controller, the same way a key's meaning does.
controller/ this package: find a pad, read it, name it
vocabulary.json what a pad can say -- the dictionary, and the only
copy of that list anywhere
mjrl/tasks/operator.py training command semantics from controls.yaml
deploy/fsm/ the same dictionary, for the robot and the browser
scripts/ replay forwards input to the selected controller
`python -m controller --vocabulary` prints the dictionary. Three programs read
it and none of them writes it: this package, a task validating its
`controls.yaml`, and the deployed controller refusing a `[[fsm.button]]`.
## What it is for
`play.py` samples random velocity commands. That is right for seeing a policy
across its training distribution and useless for "walk it into the corner and see
what happens". The keyboard already covers that (`mjrl.viewer.keys` plus a task's
teleop term); a stick covers it better, because walking is a continuous thing and
a key press is not.
## Using it
import controller
pad = controller.open() # None if nothing is plugged in
if pad is not None:
s = pad.state() # a snapshot; never blocks
print(s.lx, s.ly, s.a)
`open()` returns None rather than raising when there is no pad, because "no
controller today" is the normal case and not an error. It *does* print why when
there is a device it cannot use -- a pad that is plugged in but unreadable is a
problem to be told about, and the cause is almost always permissions rather than
anything to do with this code.
## Permissions, which is where this actually fails on Linux
`/dev/input/event*` is `crw-rw---- root input`, so reading it needs membership of
the `input` group:
sudo usermod -aG input "$USER" # then log out and back in
Until that is done a paired, working, blinking controller reads as absent. This
package says so explicitly rather than looking like it simply found nothing --
`describe()` reports what it saw and why each candidate was rejected.
## A new top-level package needs the editable install refreshed
`pip install -e .` writes a **strict name-to-path table**, not a path entry, so a
package added after the install is invisible to anything that does not happen to
be run from the repository root. The symptom is confusing: `python -c "import
controller"` works (the current directory is on `sys.path`) while
`python scripts/play.py` raises `ModuleNotFoundError`, because a script's
`sys.path[0]` is `scripts/`. `pip install -e .` again, once, fixes it -- the same
thing was true of `scenes` when it arrived.
## Platform
Linux through evdev (`device.py`), Windows through XInput (`xinput.py`), both with
no dependency beyond the standard library. The Windows reader presents each
reading as the evdev table Linux's `xpad` driver would have produced, so both
end in the same `xbox.normalise` and a stick means the same number on either.
macOS exposes nothing equivalent without a package, and adding one for a
convenience feature is the wrong trade; `open()` returns None there, `describe()`
says it is the platform, and everything that uses it carries on without a pad.
"""
from __future__ import annotations
import sys
from . import device, xinput
from .device import Gamepad, GamepadState, PadInfo
from .xinput import XInputPad
__all__ = [
"Gamepad", "GamepadState", "XInputPad", "available", "describe", "find_pads", "open",
]
def _backend():
"""The module that reads pads on this platform, or None where nothing does."""
if sys.platform == "linux":
return device
if sys.platform == "win32":
return xinput
return None
def find_pads(readable_only: bool = False) -> list[PadInfo]:
"""Every pad this platform's reader can see, in a stable order."""
backend = _backend()
return backend.find_pads(readable_only) if backend is not None else []
def describe() -> str:
"""What was found and, for anything rejected, why. For diagnosing "the pad is
connected but nothing happens", which is otherwise indistinguishable from
"no pad"."""
backend = _backend()
if backend is None:
return (
f"pads are read on Linux (evdev) and Windows (XInput), not on "
f"{sys.platform}; the keyboard drives."
)
return backend.describe()
def available() -> bool:
"""Is there a controller this process can actually read?
Cheap: it stats the device nodes and checks readability (on Windows, asks each
XInput slot once), and never opens a reader thread. Safe to call while building
a config.
"""
return bool(find_pads(readable_only=True))
def open(name: str | None = None) -> Gamepad | XInputPad | None:
"""Open the first usable controller, or None.
Args:
name: substring of the device name to require, for a machine with more
than one pad. None takes the first.
"""
backend = _backend()
if backend is None:
return None
pads = backend.find_pads(readable_only=True)
if name is not None:
pads = [p for p in pads if name.lower() in p.name.lower()]
if not pads:
return None
pad = (XInputPad if backend is xinput else Gamepad)(pads[0])
pad.start()
return pad