8BitDo Ultimate 2 lighting control without the vendor app
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>
This commit is contained in:
commit
af72cce13a
4 files changed
+351
No files matched your search
@@ -0,0 +1,153 @@
|
||||
"""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()
|
||||
Reference in new issue
Block a user