293 lines
10 KiB
Python
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)
|