XInput 协议完全解析：从 Windows 手柄 API 到 16 字节 BLE HID 报文

import ctypes

class XINPUT_GAMEPAD(ctypes.Structure):
    _fields_ = [
        ("wButtons",      ctypes.c_ushort),
        ("bLeftTrigger",  ctypes.c_ubyte),
        ("bRightTrigger", ctypes.c_ubyte),
        ("sThumbLX",      ctypes.c_short),
        ("sThumbLY",      ctypes.c_short),
        ("sThumbRX",      ctypes.c_short),
        ("sThumbRY",      ctypes.c_short),
    ]

class XINPUT_STATE(ctypes.Structure):
    _fields_ = [
        ("dwPacketNumber", ctypes.c_ulong),   # 每次状态变化 +1
        ("Gamepad",        XINPUT_GAMEPAD),
    ]

def load_xinput():
    for name in ("XInput1_4.dll", "XInput1_3.dll", "XInput9_1_0.dll"):
        try:
            return ctypes.WinDLL(name)
        except OSError:
            continue
    raise SystemExit("No XInput DLL found")

XINPUT = load_xinput()
GET_STATE = XINPUT.XInputGetState
GET_STATE.restype = ctypes.c_ulong          # ERROR_SUCCESS = 0
GET_STATE.argtypes = [ctypes.c_ulong, ctypes.POINTER(XINPUT_STATE)]

def find_controller():
    state = XINPUT_STATE()
    for i in range(4):
        if GET_STATE(i, ctypes.byref(state)) == 0:
            return i
    return None

# XInput 常量
XINPUT_GAMEPAD_DPAD_UP, XINPUT_GAMEPAD_DPAD_DOWN = 0x0001, 0x0002
XINPUT_GAMEPAD_DPAD_LEFT, XINPUT_GAMEPAD_DPAD_RIGHT = 0x0004, 0x0008
XINPUT_GAMEPAD_START, XINPUT_GAMEPAD_BACK = 0x0010, 0x0020
XINPUT_GAMEPAD_LEFT_THUMB, XINPUT_GAMEPAD_RIGHT_THUMB = 0x0040, 0x0080
XINPUT_GAMEPAD_LEFT_SHOULDER, XINPUT_GAMEPAD_RIGHT_SHOULDER = 0x0100, 0x0200
XINPUT_GAMEPAD_GUIDE = 0x0400
XINPUT_GAMEPAD_A, XINPUT_GAMEPAD_B = 0x1000, 0x2000
XINPUT_GAMEPAD_X, XINPUT_GAMEPAD_Y = 0x4000, 0x8000

def xinput_to_protocol(g):
    """XInput 状态 -> 16 字节 Xbox BLE HID 报文 (小端)"""
    lx, ly, rx, ry = (g.sThumbLX & 0xFFFF, g.sThumbLY & 0xFFFF,
                      g.sThumbRX & 0xFFFF, g.sThumbRY & 0xFFFF)
    lt = min(1023, g.bLeftTrigger * 4)
    rt = min(1023, g.bRightTrigger * 4)
    w = g.wButtons
    up, down = w & XINPUT_GAMEPAD_DPAD_UP, w & XINPUT_GAMEPAD_DPAD_DOWN
    left, right = w & XINPUT_GAMEPAD_DPAD_LEFT, w & XINPUT_GAMEPAD_DPAD_RIGHT
    if up and right:   hat = 2
    elif right and down: hat = 4
    elif down and left:  hat = 6
    elif left and up:    hat = 8
    elif up:    hat = 1
    elif right: hat = 3
    elif down:  hat = 5
    elif left:  hat = 7
    else:       hat = 0
    b13 = ((w & XINPUT_GAMEPAD_A) and 0x01) | ((w & XINPUT_GAMEPAD_B) and 0x02) \
        | ((w & XINPUT_GAMEPAD_X) and 0x08) | ((w & XINPUT_GAMEPAD_Y) and 0x10) \
        | ((w & XINPUT_GAMEPAD_LEFT_SHOULDER) and 0x40) \
        | ((w & XINPUT_GAMEPAD_RIGHT_SHOULDER) and 0x80)
    b14 = ((w & XINPUT_GAMEPAD_BACK) and 0x04) | ((w & XINPUT_GAMEPAD_START) and 0x08) \
        | ((w & XINPUT_GAMEPAD_GUIDE) and 0x10) \
        | ((w & XINPUT_GAMEPAD_LEFT_THUMB) and 0x20) \
        | ((w & XINPUT_GAMEPAD_RIGHT_THUMB) and 0x40)
    return bytes([lx & 0xFF, lx >> 8, ly & 0xFF, ly >> 8,
                  rx & 0xFF, rx >> 8, ry & 0xFF, ry >> 8,
                  lt & 0xFF, lt >> 8, rt & 0xFF, rt >> 8,
                  hat, b13, b14, 0x00])

# verify_xinput_protocol.py
import ctypes, time
from xinput_reader import *   # 上文第 2/6/8 节代码合并为模块

# (XInput 位, 协议字节偏移, 协议位) 对照表
CHECKS = [
    (XINPUT_GAMEPAD_A,              13, 0x01, "A"),
    (XINPUT_GAMEPAD_B,              13, 0x02, "B"),
    (XINPUT_GAMEPAD_X,              13, 0x08, "X"),
    (XINPUT_GAMEPAD_Y,              13, 0x10, "Y"),
    (XINPUT_GAMEPAD_LEFT_SHOULDER,  13, 0x40, "LB"),
    (XINPUT_GAMEPAD_RIGHT_SHOULDER, 13, 0x80, "RB"),
    (XINPUT_GAMEPAD_BACK,           14, 0x04, "View"),
    (XINPUT_GAMEPAD_START,          14, 0x08, "Menu"),
    (XINPUT_GAMEPAD_GUIDE,          14, 0x10, "Xbox"),
    (XINPUT_GAMEPAD_LEFT_THUMB,     14, 0x20, "LS"),
    (XINPUT_GAMEPAD_RIGHT_THUMB,    14, 0x40, "RS"),
]

def main():
    xinput = load_xinput()
    get_ex, guide_ok = load_get_state_ex(xinput)
    idx = find_controller()
    print(f"Controller slot {idx}, Guide support: {guide_ok}")
    print("Press ONE button at a time; Ctrl+C to stop.\n")
    state = XINPUT_STATE()
    while True:
        if get_ex(idx, ctypes.byref(state)) != 0:
            time.sleep(0.05); continue
        g = state.Gamepad
        proto = xinput_to_protocol(g)
        for xbit, off, pbit, name in CHECKS:
            if g.wButtons & xbit:                      # 该键按下
                ok = proto[off] & pbit
                tag = "OK " if ok else "MISMATCH"
                print(f"{tag} {name:5s} wButtons=0x{g.wButtons:04X} "
                      f"-> proto[{off}]&0x{pbit:02X} = {ok}")
        time.sleep(0.01)

if __name__ == "__main__":
    main()

# -*- coding: utf-8 -*-
"""
Xbox 手柄 XInput GUI 验证程序
数据源: XInputGetStateEx ( ordinal 100, 支持 Guide 键 )
用途: 验证 16 字节 BLE HID 协议映射
运行: python xinput_gui.py
"""
import ctypes
import time
import tkinter as tk
from tkinter import ttk

# ---------------- XInput ----------------
XINPUT_GAMEPAD_DPAD_UP = 0x0001
XINPUT_GAMEPAD_DPAD_DOWN = 0x0002
XINPUT_GAMEPAD_DPAD_LEFT = 0x0004
XINPUT_GAMEPAD_DPAD_RIGHT = 0x0008
XINPUT_GAMEPAD_START = 0x0010
XINPUT_GAMEPAD_BACK = 0x0020
XINPUT_GAMEPAD_LEFT_THUMB = 0x0040
XINPUT_GAMEPAD_RIGHT_THUMB = 0x0080
XINPUT_GAMEPAD_LEFT_SHOULDER = 0x0100
XINPUT_GAMEPAD_RIGHT_SHOULDER = 0x0200
XINPUT_GAMEPAD_GUIDE = 0x0400
XINPUT_GAMEPAD_A = 0x1000
XINPUT_GAMEPAD_B = 0x2000
XINPUT_GAMEPAD_X = 0x4000
XINPUT_GAMEPAD_Y = 0x8000

class XINPUT_GAMEPAD(ctypes.Structure):
    _fields_ = [("wButtons", ctypes.c_ushort),
                ("bLeftTrigger", ctypes.c_ubyte),
                ("bRightTrigger", ctypes.c_ubyte),
                ("sThumbLX", ctypes.c_short),
                ("sThumbLY", ctypes.c_short),
                ("sThumbRX", ctypes.c_short),
                ("sThumbRY", ctypes.c_short)]

class XINPUT_STATE(ctypes.Structure):
    _fields_ = [("dwPacketNumber", ctypes.c_ulong),
                ("Gamepad", XINPUT_GAMEPAD)]

def load_xinput():
    for name in ("XInput1_4.dll", "XInput1_3.dll", "XInput9_1_0.dll"):
        try:
            return ctypes.WinDLL(name)
        except OSError:
            continue
    raise SystemExit("No XInput DLL found")

XINPUT = load_xinput()
try:
    GET_STATE = XINPUT[100]          # XInputGetStateEx, 支持 Guide
    GUIDE_OK = True
except (AttributeError, OSError):
    GET_STATE = XINPUT.XInputGetState
    GUIDE_OK = False
GET_STATE.restype = ctypes.c_ulong
GET_STATE.argtypes = [ctypes.c_ulong, ctypes.POINTER(XINPUT_STATE)]

def find_controller():
    state = XINPUT_STATE()
    for i in range(4):
        if GET_STATE(i, ctypes.byref(state)) == 0:
            return i
    return None

# ---------------- 协议映射 (16 字节 BLE HID 报文) ----------------
def xinput_to_protocol(g):
    """XInput 状态 -> 16 字节 BLE HID 报文"""
    lx = g.sThumbLX & 0xFFFF
    ly = g.sThumbLY & 0xFFFF
    rx = g.sThumbRX & 0xFFFF
    ry = g.sThumbRY & 0xFFFF
    lt = min(1023, g.bLeftTrigger * 4)
    rt = min(1023, g.bRightTrigger * 4)
    w = g.wButtons
    up = w & XINPUT_GAMEPAD_DPAD_UP
    down = w & XINPUT_GAMEPAD_DPAD_DOWN
    left = w & XINPUT_GAMEPAD_DPAD_LEFT
    right = w & XINPUT_GAMEPAD_DPAD_RIGHT
    if up and right: hat = 2
    elif right and down: hat = 4
    elif down and left: hat = 6
    elif left and up: hat = 8
    elif up: hat = 1
    elif right: hat = 3
    elif down: hat = 5
    elif left: hat = 7
    else: hat = 0
    b13 = 0
    if w & XINPUT_GAMEPAD_A: b13 |= 0x01
    if w & XINPUT_GAMEPAD_B: b13 |= 0x02
    if w & XINPUT_GAMEPAD_X: b13 |= 0x08
    if w & XINPUT_GAMEPAD_Y: b13 |= 0x10
    if w & XINPUT_GAMEPAD_LEFT_SHOULDER: b13 |= 0x40
    if w & XINPUT_GAMEPAD_RIGHT_SHOULDER: b13 |= 0x80
    b14 = 0
    if w & XINPUT_GAMEPAD_BACK: b14 |= 0x04
    if w & XINPUT_GAMEPAD_START: b14 |= 0x08
    if w & XINPUT_GAMEPAD_GUIDE: b14 |= 0x10
    if w & XINPUT_GAMEPAD_LEFT_THUMB: b14 |= 0x20
    if w & XINPUT_GAMEPAD_RIGHT_THUMB: b14 |= 0x40
    return bytes([lx & 0xFF, lx >> 8, ly & 0xFF, ly >> 8,
                  rx & 0xFF, rx >> 8, ry & 0xFF, ry >> 8,
                  lt & 0xFF, lt >> 8, rt & 0xFF, rt >> 8,
                  hat, b13, b14, 0x00])

# 按键灯用 XInput 的 wButtons 位判断
LAMPS13 = [("A", XINPUT_GAMEPAD_A), ("B", XINPUT_GAMEPAD_B),
           ("X", XINPUT_GAMEPAD_X), ("Y", XINPUT_GAMEPAD_Y),
           ("LB", XINPUT_GAMEPAD_LEFT_SHOULDER), ("RB", XINPUT_GAMEPAD_RIGHT_SHOULDER)]
LAMPS14 = [("View", XINPUT_GAMEPAD_BACK), ("Menu", XINPUT_GAMEPAD_START),
           ("Xbox", XINPUT_GAMEPAD_GUIDE),
           ("LS", XINPUT_GAMEPAD_LEFT_THUMB), ("RS", XINPUT_GAMEPAD_RIGHT_THUMB)]
# 下方为 16 字节协议视图的位掩码
MASK13 = [("A", 0x01), ("B", 0x02), ("X", 0x08), ("Y", 0x10), ("LB", 0x40), ("RB", 0x80)]
HAT = {0: "中位", 1: "上", 2: "右上", 3: "右", 4: "右下", 5: "下",
       6: "左下", 7: "左", 8: "左上"}

class App:
    def __init__(self, root):
        self.root = root
        root.title("Xbox 手柄协议验证 (XInput)")
        self.state = XINPUT_STATE()
        self.idx = find_controller()
        self.guide_ok = GUIDE_OK

        top = tk.Frame(root)
        top.pack(fill="x", padx=8, pady=6)
        self.conn = tk.Label(top, anchor="w", font=("Microsoft YaHei", 10, "bold"))
        self.conn.pack(side="left")
        tk.Label(top, fg="gray", anchor="e",
                 text=f"Guide键: {'支持' if GUIDE_OK else '不支持(旧DLL)'}    轮询: ~100Hz").pack(side="right")

        btnf = ttk.LabelFrame(root, text="按键", padding=6)
        btnf.pack(fill="x", padx=8, pady=4)
        self.lamps = {}
        for i, n in enumerate([x for x, _ in LAMPS13 + LAMPS14] + ["Share"]):
            lamp = tk.Label(btnf, text=n, width=6, relief="groove", bg="#e8e8e8", fg="#333")
            lamp.grid(row=i // 8, column=i % 8, padx=3, pady=3, sticky="nsew")
            self.lamps[n] = lamp

        midf = ttk.Frame(root)
        midf.pack(fill="both", expand=True, padx=8, pady=4)
        self.sticks = {}
        for j, name in enumerate(("左摇杆", "右摇杆")):
            f = ttk.LabelFrame(midf, text=name, padding=2)
            f.grid(row=0, column=j, padx=6, sticky="nsew")
            cv = tk.Canvas(f, width=170, height=170, bg="white")
            cv.pack()
            cv.create_line(10, 85, 160, 85, fill="#ccc")
            cv.create_line(85, 10, 85, 160, fill="#ccc")
            self.sticks[name] = (cv, cv.create_oval(0, 0, 0, 0, fill="red", outline="darkred"))
        trigf = ttk.LabelFrame(midf, text="扳机 0~255", padding=6)
        trigf.grid(row=0, column=2, padx=6, sticky="nsew")
        self.trigs = {}
        for j, name in enumerate(("LT", "RT")):
            ttk.Label(trigf, text=name).grid(row=0, column=j)
            cv = tk.Canvas(trigf, width=50, height=170, bg="white")
            cv.grid(row=1, column=j, padx=4)
            self.trigs[name] = (cv, cv.create_rectangle(5, 170, 45, 170, fill="#2a7f2a"),
                                cv.create_text(25, 12, text="0"))
        midf.columnconfigure((0, 1, 2), weight=1)

        self.dp_lbl = tk.Label(root, text="十字键: --", anchor="w", font=("Microsoft YaHei", 10))
        self.dp_lbl.pack(fill="x", padx=8, pady=2)

        proff = ttk.LabelFrame(root, text="协议视图 — 16 字节 BLE HID 报文", padding=6)
        proff.pack(fill="x", padx=8, pady=(4, 8))
        self.proto_hex = tk.Label(proff, font=("Consolas", 12), anchor="w")
        self.proto_hex.pack(fill="x")
        self.proto_detail = tk.Label(proff, font=("Consolas", 9), anchor="w", fg="#444")
        self.proto_detail.pack(fill="x")

        self.last = None
        self.rate = 0
        self.t0 = time.time()
        self.frames = 0
        self.root.after(8, self.poll)

    def poll(self):
        if GET_STATE(self.idx if self.idx is not None else 0, ctypes.byref(self.state)) == 0:
            g = self.state.Gamepad
            self.render(g)
            self.frames += 1
        else:
            self.conn.config(text="未连接手柄", fg="#c22")
        dt = time.time() - self.t0
        if dt >= 1:
            self.rate = self.frames / dt
            self.frames = 0
            self.t0 = time.time()
        self.root.after(8, self.poll)

    def render(self, g):
        w = g.wButtons
        for n, _ in LAMPS13 + LAMPS14:
            self.lamps[n].config(bg="#e8e8e8", fg="#333")
        self.lamps["Share"].config(bg="#e8e8e8", fg="#333")
        for n, m in LAMPS13:
            if w & m:
                self.lamps[n].config(bg="#d22", fg="white")
        for n, m in LAMPS14:
            if w & m:
                self.lamps[n].config(bg="#d22", fg="white")

        for (name, x, y) in (("左摇杆", g.sThumbLX, -g.sThumbLY),
                             ("右摇杆", g.sThumbRX, -g.sThumbRY)):
            cv, dot = self.sticks[name]
            cx, cy = 87, 87
            cv.coords(dot, cx + x / 32768 * 75 - 6, cy + y / 32768 * 75 - 6,
                      cx + x / 32768 * 75 + 6, cy + y / 32768 * 75 + 6)

        for tname, val in (("LT", g.bLeftTrigger), ("RT", g.bRightTrigger)):
            cv, bar, txt = self.trigs[tname]
            h = int(val / 255 * 160)
            cv.coords(bar, 5, 170 - h, 45, 170)
            cv.itemconfig(txt, text=str(val))

        hat = 0
        up = w & XINPUT_GAMEPAD_DPAD_UP; down = w & XINPUT_GAMEPAD_DPAD_DOWN
        left = w & XINPUT_GAMEPAD_DPAD_LEFT; right = w & XINPUT_GAMEPAD_DPAD_RIGHT
        if up and right: hat = 2
        elif right and down: hat = 4
        elif down and left: hat = 6
        elif left and up: hat = 8
        elif up: hat = 1
        elif right: hat = 3
        elif down: hat = 5
        elif left: hat = 7
        self.dp_lbl.config(text=f"十字键帽子值: {hat}  {HAT[hat]}    "
                                f"L3={bool(w & XINPUT_GAMEPAD_LEFT_THUMB)} "
                                f"R3={bool(w & XINPUT_GAMEPAD_RIGHT_THUMB)}")

        proto = xinput_to_protocol(g)
        self.proto_hex.config(text=" ".join(f"{b:02X}" for b in proto))
        lx = int.from_bytes(proto[0:2], "little"); ly = int.from_bytes(proto[2:4], "little")
        rx = int.from_bytes(proto[4:6], "little"); ry = int.from_bytes(proto[6:8], "little")
        lt = int.from_bytes(proto[8:10], "little"); rt = int.from_bytes(proto[10:12], "little")
        self.proto_detail.config(
            text=f"LX={lx:5d} LY={ly:5d} RX={rx:5d} RY={ry:5d}  "
                 f"(中值0x8000)   LT={lt:4d} RT={rt:4d}  (10bit, 中值0)   "
                 f"[12]hat={proto[12]}  [13]btn=0x{proto[13]:02X}  "
                 f"[14]sys=0x{proto[14]:02X}  [15]share=0x{proto[15]:02X}")
        self.conn.config(text=f"手柄已连接 (slot {self.idx})   帧率: {self.rate:.0f} 帧/秒   包号: {self.state.dwPacketNumber}",
                         fg="#1a1")

if __name__ == "__main__":
    root = tk.Tk()
    App(root)
    root.mainloop()

你将编写读取 Xbox 手柄并转换为标准 16 字节 BLE HID 报文的 Python 代码。
严格遵守以下协议规范：

【数据源层：XInput】
- 通过 ctypes 调用 XInput1_4.dll；必须优先尝试 ordinal 100 (XInputGetStateEx)
  以获得 Guide 键支持，失败时回退 XInputGetState。
- 结构体 XINPUT_STATE = { dwPacketNumber: c_ulong; Gamepad: XINPUT_GAMEPAD }；
  XINPUT_GAMEPAD = { wButtons: c_ushort; bLeftTrigger: c_ubyte; bRightTrigger: c_ubyte;
  sThumbLX/sThumbLY/sThumbRX/sThumbRY: c_short }。
- XInputGetState 返回 0 表示成功，1167 表示手柄未连接。
- 轮询间隔 5~10ms；dwPacketNumber 用于检测状态变化。

【wButtons 位掩码 (XInput 编码，勿与协议编码混淆)】
DPAD_UP=0x0001 DPAD_DOWN=0x0002 DPAD_LEFT=0x0004 DPAD_RIGHT=0x0008
START=0x0010 BACK=0x0020 LS=0x0040 RS=0x0080 LB=0x0100 RB=0x0200
GUIDE=0x0400 A=0x1000 B=0x2000 X=0x4000 Y=0x8000

【输出层：16 字节 BLE HID 报文，全部小端序】
byte[0:2]  左摇杆X  u16 LE，中值 0x8000：直接 value & 0xFFFF
byte[2:4]  左摇杆Y  u16 LE（Y 向上为正）
byte[4:6]  右摇杆X  u16 LE
byte[6:8]  右摇杆Y  u16 LE
byte[8:10]  左扳机 u16 LE，10 位 0~1023 = min(1023, bLeftTrigger * 4)
byte[10:12] 右扳机 同上
byte[12]  十字键帽子值: 0=中 1=上 2=右上 3=右 4=右下 5=下 6=左下 7=左 8=左上
          (两方向同按时取对应枚举，如 上+右=2)
byte[13]  动作键: A=0x01 B=0x02 X=0x08 Y=0x10 LB=0x40 RB=0x80 (可按位或)
byte[14]  系统键: View(Back)=0x04 Menu(Start)=0x08 Xbox(Guide)=0x10 LS=0x20 RS=0x40
byte[15]  保留，Share=0x01；XInput 读不到 Share，恒填 0x00

【已知硬件实测偏置】
- 静止时 sThumbLY/sThumbRY 常为 -256，转换后 byte 为 FF FF 而非 00 80，
  属正常固件量化误差；输出前应应用死区：
  XINPUT_GAMEPAD_LEFT_THUMB_DEADZONE=7849, RIGHT=8689,
  XINPUT_GAMEPAD_TRIGGER_THRESHOLD=30。

【代码要求】
1. 单文件、仅依赖 ctypes 与标准库；
2. 提供 load_xinput()/find_controller()/xinput_to_protocol(g) 三个函数；
3. xinput_to_protocol 输入为 XINPUT_GAMEPAD，返回 16 字节 bytes；
4. 不做 GUI；异常时返回 None 并打印错误码。