144 lines
5.6 KiB
Python
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
|