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,2 @@
|
||||
config_backup*.bin
|
||||
__pycache__/
|
||||
@@ -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)];
|
||||
}
|
||||
@@ -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.
|
||||
@@ -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