SignalRGB plugin streaming live colours to both stick rings through the 2.4 GHz dongle (uncommitted config writes, nothing saved), plus a Python CLI. Protocol from a disassembly of 8BitDoAdvance.dll. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
154 lines
5.1 KiB
Python
154 lines
5.1 KiB
Python
"""8BitDo Ultimate 2 Wireless (2.4 GHz dongle, USB 2DC8:310B) config access without the vendor app.
|
|
|
|
Protocol from 8BitDoAdvance.dll (8BitDo Ultimate Software V2 1.30), disassembled.
|
|
Vendor HID interface (usage page 0xFF7A): output report 0x81, input report 0x02, 64 bytes.
|
|
|
|
request [0x81, 0x04, u16 cmd, u16 arg, u32 len, u32 total, u32 offset, data...]
|
|
reply [0x02, 0x04, u16 0x0004, u16 cmd, u32 len, u32 total, u32 offset, data...]
|
|
|
|
cmd 1 = write config bytes (max 45 per packet), cmd 2 = read config bytes,
|
|
cmd 6 arg 0x123 = sent after a write (commit), cmd 0x40 = select lighting theme.
|
|
The config record is 0x638 (1592) bytes.
|
|
"""
|
|
import struct, sys, time
|
|
import hid
|
|
|
|
VID, PID = 0x2DC8, 0x310B
|
|
RECORD_LEN = 0x638
|
|
CHUNK = 45
|
|
|
|
|
|
class U2:
|
|
def __init__(self):
|
|
paths = [d["path"] for d in hid.enumerate(VID, PID) if d["usage_page"] == 0xFF7A]
|
|
if not paths:
|
|
raise SystemExit("8BitDo Ultimate 2 dongle not found (controller on and connected?)")
|
|
self.h = hid.device()
|
|
self.h.open_path(paths[0])
|
|
self.drain()
|
|
|
|
def drain(self):
|
|
self.h.set_nonblocking(1)
|
|
while self.h.read(64):
|
|
pass
|
|
self.h.set_nonblocking(0)
|
|
|
|
def send(self, cmd, arg=0, ln=0, total=0, off=0, data=b""):
|
|
pkt = bytes([0x81, 0x04]) + struct.pack("<HHIII", cmd, arg, ln, total, off) + bytes(data)
|
|
self.h.write(pkt + bytes(64 - len(pkt)))
|
|
|
|
def reply(self, cmd, timeout=500):
|
|
end = time.time() + timeout / 1000
|
|
while time.time() < end:
|
|
r = bytes(self.h.read(64, timeout))
|
|
if len(r) >= 18 and r[0] == 2 and r[1] == 4:
|
|
w0, c, ln, total, off = struct.unpack_from("<HHIII", r, 2)
|
|
if w0 == 4 and c == cmd:
|
|
return ln, off, r[18:18 + ln]
|
|
return None
|
|
|
|
def read_record(self):
|
|
out = bytearray()
|
|
while len(out) < RECORD_LEN:
|
|
n = min(CHUNK, RECORD_LEN - len(out))
|
|
for _ in range(5):
|
|
self.send(2, 0, n, RECORD_LEN, len(out))
|
|
r = self.reply(2)
|
|
if r and r[1] == len(out):
|
|
out += r[2]
|
|
break
|
|
else:
|
|
raise IOError(f"read failed at offset {len(out)}")
|
|
return out
|
|
|
|
|
|
def crc16(d):
|
|
c = 0xFFFF
|
|
for x in d:
|
|
c ^= x
|
|
for _ in range(8):
|
|
c = (c >> 1) ^ 0xA001 if c & 1 else c >> 1
|
|
return c
|
|
|
|
|
|
SINGLE_OFFSET = 0x50C # + slot * 100: u32 flag, then 24 x u32 0x00RRGGBB
|
|
THEME_CUSTOM = 4
|
|
|
|
|
|
def write_bytes(u, off, data):
|
|
pos = 0
|
|
while pos < len(data):
|
|
ch = bytes(data[pos:pos + CHUNK])
|
|
u.send(1, 0, len(ch) | (crc16(ch) << 16), RECORD_LEN, off + pos, ch)
|
|
r = u.reply(1)
|
|
if not r or r[1] != off + pos:
|
|
raise IOError(f"write not acknowledged at 0x{off + pos:x}")
|
|
pos += len(ch)
|
|
|
|
|
|
def write_colors(u, colors, slot=0, commit=False):
|
|
"""colors: 24 (r, g, b) tuples."""
|
|
data = b"".join(struct.pack("<I", (r << 16) | (g << 8) | b) for r, g, b in colors)
|
|
write_bytes(u, SINGLE_OFFSET + slot * 100 + 4, data)
|
|
if commit:
|
|
u.send(6, 0x123)
|
|
u.reply(6, 2000)
|
|
|
|
|
|
def set_theme(u, theme):
|
|
u.send(0x40, theme)
|
|
u.reply(0x40, 1500)
|
|
|
|
|
|
def get_theme(u):
|
|
u.send(0x41)
|
|
r = u.reply(0x41)
|
|
return r[2][0] if r else None
|
|
|
|
|
|
def parse_color(s):
|
|
s = s.lstrip("#")
|
|
return tuple(int(s[i:i + 2], 16) for i in (0, 2, 4))
|
|
|
|
|
|
def main():
|
|
import argparse
|
|
ap = argparse.ArgumentParser(description="8BitDo Ultimate 2 (2.4 GHz dongle) lighting")
|
|
sub = ap.add_subparsers(dest="cmd", required=True)
|
|
sp = sub.add_parser("live", help="set colours now (not saved; lost when the controller sleeps)")
|
|
sp.add_argument("colors", nargs="+", help="RRGGBB: one for both rings, or two: left right")
|
|
sp = sub.add_parser("save", help="set colours and save them to the controller")
|
|
sp.add_argument("colors", nargs="+")
|
|
sp = sub.add_parser("theme", help="show or set the lighting theme (2 dynamic, 3 hotwheel, 4 custom, 5 off)")
|
|
sp.add_argument("number", nargs="?", type=int)
|
|
sub.add_parser("backup").add_argument("file")
|
|
sub.add_parser("restore").add_argument("file")
|
|
args = ap.parse_args()
|
|
u = U2()
|
|
|
|
if args.cmd in ("live", "save"):
|
|
cols = [parse_color(c) for c in args.colors]
|
|
left, right = (cols[0], cols[0]) if len(cols) == 1 else cols[:2]
|
|
if get_theme(u) != THEME_CUSTOM:
|
|
set_theme(u, THEME_CUSTOM)
|
|
write_colors(u, [left] * 12 + [right] * 12, commit=args.cmd == "save")
|
|
elif args.cmd == "theme":
|
|
if args.number is None:
|
|
print("theme:", get_theme(u))
|
|
else:
|
|
set_theme(u, args.number)
|
|
elif args.cmd == "backup":
|
|
open(args.file, "wb").write(u.read_record())
|
|
print("saved", args.file)
|
|
elif args.cmd == "restore":
|
|
rec = open(args.file, "rb").read()
|
|
assert len(rec) == RECORD_LEN
|
|
write_bytes(u, 0, rec)
|
|
u.send(6, 0x123)
|
|
u.reply(6, 2000)
|
|
print("restored; re-select your theme with 'theme N' if needed")
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|