From af72cce13ad185b84f494d65c2b12bbdd604b543 Mon Sep 17 00:00:00 2001 From: MangaValk Date: Thu, 19 Nov 2026 15:56:11 +0100 Subject: [PATCH] 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 --- .gitignore | 2 + 8BitDo_Ultimate2.js | 153 ++++++++++++++++++++++++++++++++++++++++++++ README.md | 43 +++++++++++++ u2.py | 153 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 351 insertions(+) create mode 100644 .gitignore create mode 100644 8BitDo_Ultimate2.js create mode 100644 README.md create mode 100644 u2.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..993b8d5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +config_backup*.bin +__pycache__/ diff --git a/8BitDo_Ultimate2.js b/8BitDo_Ultimate2.js new file mode 100644 index 0000000..6f406ac --- /dev/null +++ b/8BitDo_Ultimate2.js @@ -0,0 +1,153 @@ +// 8BitDo Ultimate 2 Wireless through its 2.4 GHz dongle (USB 2DC8:310B). +// Protocol from 8BitDoAdvance.dll (Ultimate Software V2 1.30), disassembled: +// out report 0x81: [0x81, 0x04, u16 cmd, u16 arg, u32 len | crc16 << 16, u32 total, u32 offset, data] +// in report 0x02: [0x02, 0x04, u16 4, u16 cmd, ...] +// cmd 1 writes the config buffer. Without the commit command (cmd 6) it only changes the +// live lighting, so streaming doesn't wear anything. cmd 0x40 selects the lighting theme +// (4 = custom per-LED), cmd 0x41 reads it. LEDs: 0-11 left stick ring, 12-23 right stick +// ring, each starting at the bottom and going clockwise. +export function Name() { return "8BitDo Ultimate 2 Wireless"; } +export function VendorId() { return 0x2DC8; } +export function ProductId() { return 0x310B; } +export function Publisher() { return "Custom"; } +export function Size() { return [20, 13]; } +export function DefaultPosition() { return [180, 140]; } +export function DefaultScale() { return 6.0; } +export function DeviceType() { return "other"; } +export function Validate(endpoint) { return endpoint.interface === 2; } +export function ImageUrl() { return "https://assets.signalrgb.com/devices/default/misc/usb-drive-render.png"; } +/* global +LightingMode:readonly +forcedColor:readonly +shutdownMode:readonly +shutdownColor:readonly +*/ +export function ControllableParameters() { + return [ + {property:"LightingMode", group:"lighting", label:"Lighting Mode", description:"Canvas follows the active effect, Forced uses one fixed colour", type:"combobox", values:["Canvas", "Forced"], default:"Canvas"}, + {property:"forcedColor", group:"lighting", label:"Forced Color", min:"0", max:"360", type:"color", default:"#009bde"}, + {property:"shutdownMode", group:"lighting", label:"On Exit", description:"What the controller shows when SignalRGB closes", type:"combobox", values:["Controller's own lighting", "Shutdown Color"], default:"Controller's own lighting"}, + {property:"shutdownColor", group:"lighting", label:"Shutdown Color", min:"0", max:"360", type:"color", default:"#000000"}, + ]; +} + +const RECORD_LEN = 0x638; +const SINGLE_OFFSET = 0x50C; // profile slot 0: u32 flag, then 24 x u32 0x00RRGGBB +const THEME_CUSTOM = 4; +const CHUNK = 45; + +const vLedNames = []; +const vLedPositions = []; + +for (const [side, cx, cy] of [["Left", 4, 4], ["Right", 15, 8]]) { + for (let k = 0; k < 12; k++) { + const a = (90 + k * 30) * Math.PI / 180; // bottom, then clockwise + vLedNames.push(`${side} Stick ${k + 1}`); + vLedPositions.push([Math.round(cx + 4 * Math.cos(a)), Math.round(cy + 4 * Math.sin(a))]); + } +} + +let originalTheme = -1; +let lastFrame = null; +let lastSend = 0; + +export function LedNames() { return vLedNames; } +export function LedPositions() { return vLedPositions; } + +export function Initialize() { + device.set_endpoint(2, 0x0001, 0xFF7A, 0x0000); + device.setName("8BitDo Ultimate 2"); + device.setControllableLeds(vLedNames, vLedPositions); + + originalTheme = readTheme(); + if (originalTheme !== THEME_CUSTOM) { + setTheme(THEME_CUSTOM); + } +} + +export function Render() { + const colors = vLedPositions.map(([x, y]) => + LightingMode === "Forced" ? hexToRgb(forcedColor) : device.color(x, y)); + + // Skip unchanged frames, but resend once a second in case the controller + // reconnected or woke up with its stored colours + const now = Date.now(); + const key = colors.join(); + if (key === lastFrame && now - lastSend < 1000) { return; } + + sendColors(colors); + lastFrame = key; + lastSend = now; +} + +export function Shutdown(SystemSuspending) { + if (shutdownMode === "Shutdown Color") { + const c = hexToRgb(shutdownColor); + sendColors(vLedPositions.map(() => c)); + return; + } + + // Back to the stored lighting: re-selecting a theme reloads it from storage + if (originalTheme >= 0 && originalTheme !== THEME_CUSTOM) { + setTheme(originalTheme); + } else { + setTheme(THEME_CUSTOM); + } +} + +function sendColors(colors) { + const data = []; + for (const [r, g, b] of colors) { data.push(b, g, r, 0); } // u32 LE 0x00RRGGBB + + for (let pos = 0; pos < data.length; pos += CHUNK) { + const chunk = data.slice(pos, pos + CHUNK); + send(1, 0, chunk.length, crc16(chunk), RECORD_LEN, SINGLE_OFFSET + 4 + pos, chunk); + readReply(1, 50); + } +} + +function setTheme(theme) { + send(0x40, theme, 0, 0, 0, 0, []); + readReply(0x40, 1500); +} + +function readTheme() { + send(0x41, 0, 0, 0, 0, 0, []); + const r = readReply(0x41, 500); + return r ? r[18] : -1; +} + +function send(cmd, arg, len, crc, total, offset, data) { + const pkt = [0x81, 0x04, cmd & 0xFF, cmd >> 8, arg & 0xFF, arg >> 8, + len & 0xFF, len >> 8, crc & 0xFF, crc >> 8] + .concat(u32(total), u32(offset), data); + while (pkt.length < 64) { pkt.push(0); } + device.write(pkt, 64); +} + +function readReply(cmd, timeoutMs) { + const end = Date.now() + timeoutMs; + do { + const r = device.read([0x02], 64, 20); + if (device.getLastReadSize() > 0 && r[0] === 0x02 && r[1] === 0x04 && r[2] === 4 && r[4] === (cmd & 0xFF)) { + return r; + } + } while (Date.now() < end); + return null; +} + +function u32(v) { return [v & 0xFF, (v >> 8) & 0xFF, (v >> 16) & 0xFF, (v >>> 24) & 0xFF]; } + +function crc16(data) { + let c = 0xFFFF; + for (const x of data) { + c ^= x; + for (let i = 0; i < 8; i++) { c = (c & 1) ? (c >>> 1) ^ 0xA001 : c >>> 1; } + } + return c; +} + +function hexToRgb(hex) { + const r = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex); + return [parseInt(r[1], 16), parseInt(r[2], 16), parseInt(r[3], 16)]; +} diff --git a/README.md b/README.md new file mode 100644 index 0000000..2998dc3 --- /dev/null +++ b/README.md @@ -0,0 +1,43 @@ +# 8BitDo Ultimate 2 Wireless lighting without the vendor app + +Through the 2.4 GHz dongle (USB 2DC8:310B). I disassembled the protocol from `8BitDoAdvance.dll`, +which ships with 8BitDo Ultimate Software V2 1.30. + +- `8BitDo_Ultimate2.js`: SignalRGB plugin, installed in `Documents\WhirlwindFX\Plugins`. + Restart SignalRGB after you change it. +- `u2.py`: command-line tool (`pip install hidapi`). + +``` +python u2.py backup config_backup.bin # do this first +python u2.py live ff0000 0000ff # left ring, right ring; not saved +python u2.py save 00aaff # both rings, saved to the controller +python u2.py theme # show theme; "theme 2" sets dynamic again +python u2.py restore config_backup.bin +``` + +## Protocol + +The vendor HID interface is interface 2, usage page 0xFF7A, 64-byte reports. + +``` +out 0x81 [0x81, 0x04, u16 cmd, u16 arg, u32 len | crc16(data) << 16, u32 total, u32 offset, data] +in 0x02 [0x02, 0x04, u16 0x0004, u16 cmd, u32 len, u32 total, u32 offset, data] +``` + +The CRC is CRC-16/MODBUS (init 0xFFFF, poly 0xA001). It's only needed on writes. + +| cmd | meaning | +|---|---| +| 1 | write config bytes (max 45 per packet) into the 0x638-byte config record | +| 2 | read config bytes | +| 6, arg 0x123 | commit: save the config to the controller | +| 0x40, arg n | select lighting theme: 2 dynamic, 3 hotwheel, 4 custom per-LED, 5/6 off | +| 0x41 | read the current theme (first data byte) | + +Custom colours for profile slot 0 sit at record offset 0x50C: a u32 flag (0x20200911), +then 24 × u32 `0x00RRGGBB`. LEDs 0–11 are the left stick ring and 12–23 the right stick ring. +Each ring starts at the bottom and runs clockwise. + +A write without commit changes the lighting straight away, in about 34 ms for all 24 LEDs. +Nothing is saved, so the plugin streams that way and doesn't wear out the controller's storage. +Selecting a theme again reloads the stored lighting. diff --git a/u2.py b/u2.py new file mode 100644 index 0000000..1a597a5 --- /dev/null +++ b/u2.py @@ -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("= 18 and r[0] == 2 and r[1] == 4: + w0, c, ln, total, off = struct.unpack_from("> 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("