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:
mangavalkandClaude Opus 5.5 committed 2026-11-19 15:56:11 +01:00
commit af72cce13a
4 files changed
+351

No files matched your search

+2
View File
@@ -0,0 +1,2 @@
config_backup*.bin
__pycache__/
+153
View File
@@ -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)];
}
+43
View File
@@ -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.
+153
View File
@@ -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()