Files
UniversalTrain-ai/controller/xbox.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

249 lines
9.4 KiB
Python

"""The Xbox pad's evdev codes, and normalising them into a `GamepadState`.
The codes are the Linux `xpad` / `xone` drivers', which is what an Xbox controller
presents over both USB and Bluetooth on a modern kernel. They are kernel
constants, not invented here; the names are `linux/input-event-codes.h`.
## Sign conventions are the kernel's, not the robot's
evdev reports **`ABS_Y` positive when the stick is pushed down**, which is
backwards from every intuition about forward. It is left exactly as the kernel
gives it here, and flipped where the meaning is assigned, in the task. Correcting
it in this file would be a robot opinion smuggled into a device driver: a task
mapping the stick to something else, a camera or a gait frequency, would inherit
a flip that only makes sense for velocity.
## There are two Xbox layouts, and the pad has to be asked which
USB through `xpad` and Bluetooth through `hid-generic` do **not** agree, and the
disagreement is not cosmetic -- it puts the right stick where the other one keeps
a trigger:
axis USB (xpad) Bluetooth (hid-generic)
ABS_X, ABS_Y left stick left stick
ABS_Z, ABS_RZ triggers **right stick**
ABS_RX, ABS_RY right stick absent
ABS_GAS, ABS_BRAKE absent triggers
Measured on an Xbox Wireless Controller over Bluetooth here: `ABS_X ABS_Y ABS_Z
ABS_RZ ABS_GAS ABS_BRAKE ABS_HAT0X ABS_HAT0Y`, with the sticks 0..65535 and the
triggers 0..1023. There is no `ABS_RX` on that device at all. Assuming the USB
layout would have read pushing the right stick as squeezing the left trigger --
which is not a crash, just a control that does the wrong thing.
`layout_of` picks between the two by **which axes the device actually reports**,
which is evidence from the device rather than a table of models and firmware
revisions that would need extending every time someone brings a different pad.
## Ranges come from the device
Sticks are -32768..32767 on one of those layouts and 0..65535 on the other, and
triggers are 0..1023 or 0..255. `normalise` is given the ranges read from
`EVIOCGABS` and uses them, so nothing here assumes a model -- the unsigned sticks
above work out because the midpoint is computed rather than assumed to be zero.
The dead zone is the driver's own `flat` for the same reason: a pad that reports
its own slop knows better than a constant would.
"""
from __future__ import annotations
from dataclasses import dataclass, field
__all__ = ["ABS_AXES", "BUTTONS", "GamepadState", "normalise"]
EV_KEY = 0x01
EV_ABS = 0x03
# ── Axes (EV_ABS) ────────────────────────────────────────────────────────
ABS_X = 0x00 # left stick, right positive (both layouts)
ABS_Y = 0x01 # left stick, **down positive** (both layouts)
ABS_Z = 0x02 # USB: left trigger | Bluetooth: right stick X
ABS_RX = 0x03 # USB: right stick X | Bluetooth: absent
ABS_RY = 0x04 # USB: right stick Y | Bluetooth: absent
ABS_RZ = 0x05 # USB: right trigger | Bluetooth: right stick Y
ABS_GAS = 0x09 # Bluetooth: right trigger
ABS_BRAKE = 0x0A # Bluetooth: left trigger
ABS_HAT0X = 0x10 # d-pad, -1 / 0 / +1 (both layouts)
ABS_HAT0Y = 0x11
#: Every axis worth asking the device about, across both layouts. `device.py`
#: queries one range per entry and simply skips the ones the pad does not have,
#: which is also how `layout_of` learns which layout it is looking at.
ABS_AXES = (
ABS_X, ABS_Y, ABS_Z, ABS_RX, ABS_RY, ABS_RZ,
ABS_GAS, ABS_BRAKE, ABS_HAT0X, ABS_HAT0Y,
)
@dataclass(frozen=True)
class Layout:
"""Which code carries which control on this particular pad."""
name: str
rx: int
ry: int
lt: int
rt: int
#: xpad over USB: the right stick is RX/RY and the triggers are the Z pair.
USB_LAYOUT = Layout("usb", rx=ABS_RX, ry=ABS_RY, lt=ABS_Z, rt=ABS_RZ)
#: hid-generic over Bluetooth: the Z pair *is* the right stick, and the triggers
#: moved to the pedal codes.
BLUETOOTH_LAYOUT = Layout("bluetooth", rx=ABS_Z, ry=ABS_RZ, lt=ABS_BRAKE, rt=ABS_GAS)
def layout_of(axes) -> Layout:
"""Pick a layout from the axes the device reports.
`ABS_RX` is the discriminator because it exists on exactly one of the two.
Falling back to USB when neither is conclusive keeps an unknown pad working as
before rather than reading its sticks as triggers.
"""
if ABS_RX in axes and ABS_RY in axes:
return USB_LAYOUT
if ABS_GAS in axes or ABS_BRAKE in axes:
return BLUETOOTH_LAYOUT
return USB_LAYOUT
# ── Buttons (EV_KEY) ─────────────────────────────────────────────────────
BTN_SOUTH = 0x130 # A
BTN_EAST = 0x131 # B
BTN_WEST = 0x134 # X -- note the codes are not in ABXY order
BTN_NORTH = 0x133 # Y
BTN_TL = 0x136 # left bumper
BTN_TR = 0x137 # right bumper
BTN_SELECT = 0x13A # view
BTN_START = 0x13B # menu
BTN_MODE = 0x13C # the Xbox button
BTN_THUMBL = 0x13D
BTN_THUMBR = 0x13E
#: Button code -> the name the **dictionary** gives it.
#:
#: This package's job is to align a pad to those names and stop there; what any
#: of them means belongs to whoever is driving, which is a task. So these are
#: not our own spelling any more -- they are `controller/vocabulary.json`'s, the
#: same names the robot's own pad service publishes and the same ones a
#: `[[fsm.button]]` or a `controls.yaml` may write.
#:
#: `view` is here and not in the dictionary: this pad reports it and the robot's
#: service deliberately does not. Reported rather than dropped, so `--raw` and a
#: person pressing buttons see the truth; `vocabulary.absent()` is where the
#: asymmetry is written down, and nothing downstream may bind it.
#:
#: **X and Y are unresolved.** The dictionary records it: we read 307 as `Y` and
#: 308 as `X`; the service's table reads them the other way round. One of us is
#: wrong about which physical button it is and pressing it settles it. Left
#: disagreeing rather than quietly picked.
BUTTONS = {
BTN_SOUTH: "A", BTN_EAST: "B", BTN_WEST: "X", BTN_NORTH: "Y",
BTN_TL: "LB", BTN_TR: "RB", BTN_SELECT: "view", BTN_START: "menu",
BTN_MODE: "home", BTN_THUMBL: "L3", BTN_THUMBR: "R3",
}
@dataclass(frozen=True)
class GamepadState:
"""One snapshot. Sticks are -1..1, triggers 0..1, buttons bool.
`ly` and `ry` keep the kernel's sign: **positive is down**.
"""
lx: float = 0.0
ly: float = 0.0
rx: float = 0.0
ry: float = 0.0
lt: float = 0.0
rt: float = 0.0
hat_x: int = 0
hat_y: int = 0
buttons: frozenset[str] = field(default_factory=frozenset)
def __getattr__(self, item: str) -> bool:
"""`state.A` for the buttons, so a caller does not have to remember
whether a name is a field or a set member. The names are the
dictionary's."""
if item in BUTTONS.values():
return item in self.buttons
raise AttributeError(item)
@property
def any_input(self) -> bool:
"""Is the operator touching it? What "taking over" is decided on."""
return (
bool(self.buttons)
or self.hat_x != 0
or self.hat_y != 0
or max(abs(self.lx), abs(self.ly), abs(self.rx), abs(self.ry)) > 0.0
or max(self.lt, self.rt) > 0.0
)
def _axis(
raw: dict[tuple[int, int], int],
ranges: dict[int, tuple[int, int, int]],
code: int,
bipolar: bool,
) -> float:
"""One axis, scaled to -1..1 (bipolar) or 0..1, with the dead zone removed.
The dead zone is **rescaled, not just clipped**: an axis that starts moving at
the edge of the zone should start from zero, not jump to the fraction the zone
occupied. Clipping alone leaves a visible step at the point the stick starts to
bite, which reads as a sticky control.
"""
if code not in ranges:
return 0.0
value = raw.get((EV_ABS, code))
if value is None:
return 0.0
lo, hi, flat = ranges[code]
if bipolar:
mid = (lo + hi) / 2.0
span = (hi - lo) / 2.0
if span <= 0:
return 0.0
x = (value - mid) / span
dead = flat / span if span else 0.0
if abs(x) <= dead:
return 0.0
x = (abs(x) - dead) / (1.0 - dead) * (1.0 if x > 0 else -1.0)
return max(-1.0, min(1.0, x))
span = hi - lo
if span <= 0:
return 0.0
x = (value - lo) / span
dead = flat / span
if x <= dead:
return 0.0
return max(0.0, min(1.0, (x - dead) / (1.0 - dead)))
def normalise(
raw: dict[tuple[int, int], int], ranges: dict[int, tuple[int, int, int]]
) -> GamepadState:
"""Raw evdev values plus the device's own ranges -> a `GamepadState`.
The layout is decided from `ranges`, which holds exactly the axes the device
answered `EVIOCGABS` for. See `layout_of`.
"""
pressed = frozenset(
name for code, name in BUTTONS.items() if raw.get((EV_KEY, code), 0)
)
layout = layout_of(ranges)
return GamepadState(
lx=_axis(raw, ranges, ABS_X, True),
ly=_axis(raw, ranges, ABS_Y, True),
rx=_axis(raw, ranges, layout.rx, True),
ry=_axis(raw, ranges, layout.ry, True),
lt=_axis(raw, ranges, layout.lt, False),
rt=_axis(raw, ranges, layout.rt, False),
hat_x=int(raw.get((EV_ABS, ABS_HAT0X), 0)),
hat_y=int(raw.get((EV_ABS, ABS_HAT0Y), 0)),
buttons=pressed,
)