Files
UniversalTrain-ai/controller/device.py
T
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

293 lines
10 KiB
Python

"""Finding and reading a Linux evdev gamepad, with no dependencies.
## Why evdev and not joydev
`/dev/input/js*` is simpler to parse, and on this machine it does not exist: the
`joydev` module is not loaded, while `event*` is always there. evdev is also the
one that carries the axis ranges, so a trigger that reports 0..1023 on one pad and
0..255 on another normalises correctly without a table of models.
## The wire format
An evdev event is `struct input_event`: a `timeval` then type, code and value.
On 64-bit Linux that is `llHHi`, 24 bytes, which is asserted at import rather
than assumed -- a wrong size here would not raise, it would silently decode
garbage as button presses.
Ranges come from the `EVIOCGABS` ioctl, one per axis, read once at open. The ioctl
numbers are built with the same arithmetic as the kernel's `_IOR` macro rather
than pasted as magic constants, so the derivation is visible.
"""
from __future__ import annotations
import array
import glob
import os
import select
import struct
import sys
import threading
from dataclasses import dataclass, field
try:
import fcntl
except ImportError: # Windows. There is no evdev to read there and no ioctl
# to read it with; pads there go through `xinput.py`, and nothing in this
# module is called. The import still happens, so it must not take the whole
# package down with it: the tasks import `controller` for its vocabulary, and
# that is on the path of every training run.
fcntl = None
from .xbox import ABS_AXES, GamepadState, normalise
__all__ = ["Gamepad", "GamepadState", "PadInfo", "describe", "find_pads"]
#: `struct input_event` on 64-bit Linux: struct timeval (two longs), then
#: __u16 type, __u16 code, __s32 value.
_EVENT_FORMAT = "llHHi"
_EVENT_SIZE = struct.calcsize(_EVENT_FORMAT)
# Asserted rather than assumed, because a wrong size here would not raise -- it
# would decode the stream misaligned and report button presses that never
# happened. **Only on Linux, which is what the 24 bytes describe**: Windows'
# C `long` is 4 bytes, so the same format measures 16 there and would fail an
# assertion about a layout that platform never uses.
if sys.platform == "linux":
assert _EVENT_SIZE == 24, (
f"struct input_event is {_EVENT_SIZE} bytes here, not 24. Decoding would "
f"silently produce nonsense rather than fail, so this is checked."
)
EV_KEY = 0x01
EV_ABS = 0x03
def _ioc(direction: int, type_: int, nr: int, size: int) -> int:
"""The kernel's `_IOC` macro. dir 2 is `_IOC_READ`."""
return (direction << 30) | (size << 16) | (type_ << 8) | nr
def _eviocgname(length: int) -> int:
return _ioc(2, ord("E"), 0x06, length)
def _eviocgabs(axis: int) -> int:
#: `struct input_absinfo` is six __s32: value, min, max, fuzz, flat, resolution.
return _ioc(2, ord("E"), 0x40 + axis, 24)
@dataclass
class PadInfo:
"""A candidate device and what was decided about it."""
path: str
name: str
readable: bool
reason: str = ""
def _read_name(fd: int) -> str:
buf = array.array("B", b"\x00" * 256)
try:
fcntl.ioctl(fd, _eviocgname(256), buf)
except OSError:
return ""
return bytes(buf).split(b"\x00", 1)[0].decode("utf-8", "replace")
def _read_ranges(fd: int) -> dict[int, tuple[int, int, int]]:
"""Per-axis (min, max, flat) from EVIOCGABS. `flat` is the driver's own idea
of the dead zone, which is better than a number invented here."""
ranges: dict[int, tuple[int, int, int]] = {}
for axis in ABS_AXES:
buf = array.array("i", [0] * 6)
try:
fcntl.ioctl(fd, _eviocgabs(axis), buf)
except OSError:
continue # the pad does not have this axis
_value, lo, hi, _fuzz, flat, _res = buf
if hi > lo:
ranges[axis] = (lo, hi, flat)
return ranges
#: Buttons whose presence marks a device as something to be played with, from
#: udev's own `input_id` rule.
BTN_JOYSTICK = 0x120
BTN_GAMEPAD = 0x130
def _bitmap(path: str) -> set[int]:
"""Parse a sysfs capability bitmap into the set of bits it has.
The kernel prints these as space-separated 64-bit hex words, **most
significant first**, so the last word is bits 0-63. Reading them left to
right, which is the obvious way, gets every bit index wrong.
"""
try:
with open(path) as f:
words = f.read().split()
except OSError:
return set()
bits: set[int] = set()
for i, word in enumerate(reversed(words)):
value = int(word, 16)
base = i * 64
while value:
low = value & -value
bits.add(base + low.bit_length() - 1)
value ^= low
return bits
def find_pads(readable_only: bool = False) -> list[PadInfo]:
"""Every gamepad-looking device, in a stable order.
Discovery is through `/sys/class/input/event*`, applying udev's own rule --
the device has absolute axes and at least one gamepad or joystick button.
**Not through `/dev/input/by-id/*-event-joystick`**, which is what this did
first and which silently finds nothing over Bluetooth: those symlinks are
generated from USB and serial identifiers, and a Bluetooth pad has neither.
Measured here, an Xbox Wireless Controller paired over Bluetooth appears as
`/dev/input/event17` with no `by-id` entry at all, so a working, connected
controller read as absent.
sysfs also answers without opening anything, so a pad the process cannot read
is still *found*, and can be reported as a permissions problem rather than as
nothing at all.
"""
pads: list[PadInfo] = []
for sysdir in sorted(
glob.glob("/sys/class/input/event*"),
key=lambda p: int(os.path.basename(p)[5:] or 0),
):
device = os.path.join(sysdir, "device")
caps = os.path.join(device, "capabilities")
ev = _bitmap(os.path.join(caps, "ev"))
keys = _bitmap(os.path.join(caps, "key"))
if EV_ABS not in ev:
continue
if not (BTN_GAMEPAD in keys or BTN_JOYSTICK in keys):
continue
path = os.path.join("/dev/input", os.path.basename(sysdir))
try:
with open(os.path.join(device, "name")) as f:
name = f.read().strip()
except OSError:
name = os.path.basename(path)
try:
fd = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
except PermissionError:
pads.append(
PadInfo(path, name, False,
"permission denied -- add yourself to the 'input' group "
"(sudo usermod -aG input \"$USER\", then log out and back "
"in), or log in on the seat so logind grants the ACL")
)
continue
except OSError as exc:
pads.append(PadInfo(path, name, False, str(exc)))
continue
try:
pads.append(PadInfo(path, _read_name(fd) or name, True))
finally:
os.close(fd)
if readable_only:
return [p for p in pads if p.readable]
return pads
def describe() -> str:
"""What was found and, for anything rejected, why. `controller.describe()` is
the entry point; this is its Linux half."""
pads = find_pads()
if not pads:
return (
"no input device has both absolute axes and a gamepad button. "
"Nothing is paired, or it connected as something other than a pad."
)
lines = []
for p in pads:
state = "usable" if p.readable else f"unusable: {p.reason}"
lines.append(f" {p.path} {p.name} -- {state}")
return "\n".join(lines)
@dataclass
class Gamepad:
"""A pad being read on a background thread.
The reader thread only ever writes raw integers into `_raw`; normalisation
happens in `state()`, on the caller's thread. That keeps the axis ranges and
the dead zone out of the hot path and, more usefully, means a caller polling
at 50 Hz sees a consistent snapshot rather than a half-updated one.
"""
info: PadInfo
_raw: dict[tuple[int, int], int] = field(default_factory=dict)
_ranges: dict[int, tuple[int, int, int]] = field(default_factory=dict)
_fd: int = -1
_thread: threading.Thread | None = None
_stop: threading.Event = field(default_factory=threading.Event)
@property
def name(self) -> str:
return self.info.name
def start(self) -> None:
self._fd = os.open(self.info.path, os.O_RDONLY | os.O_NONBLOCK)
self._ranges = _read_ranges(self._fd)
self._thread = threading.Thread(
target=self._run, name="gamepad", daemon=True
)
self._thread.start()
def close(self) -> None:
self._stop.set()
if self._thread is not None:
self._thread.join(timeout=1.0)
if self._fd >= 0:
os.close(self._fd)
self._fd = -1
def _run(self) -> None:
"""Poll rather than block on read, so `close()` is not left waiting for a
stick that nobody is touching."""
while not self._stop.is_set():
ready, _, _ = select.select([self._fd], [], [], 0.1)
if not ready:
continue
try:
data = os.read(self._fd, _EVENT_SIZE * 64)
except OSError:
# The pad went away mid-read: unplugged, or Bluetooth dropped.
# Leave the last state in place and stop; state() keeps working
# and `connected` goes False.
break
for i in range(0, len(data) - _EVENT_SIZE + 1, _EVENT_SIZE):
_s, _us, etype, code, value = struct.unpack_from(
_EVENT_FORMAT, data, i
)
if etype in (EV_KEY, EV_ABS):
self._raw[(etype, code)] = value
self._stop.set()
@property
def connected(self) -> bool:
return self._thread is not None and self._thread.is_alive()
def state(self) -> GamepadState:
"""A normalised snapshot. Never blocks and never raises."""
return normalise(dict(self._raw), self._ranges)
def raw(self) -> dict[tuple[int, int], int]:
"""Everything seen so far, unnormalised, as `{(type, code): value}`.
For working out a pad whose mapping does not match `xbox.py` -- press the
button, see which code moved.
"""
return dict(self._raw)