commit 25f3e31b8ff64385e27954c0bcb0c46ad8d714c8 Author: MangaValk Date: Thu Nov 19 15:39:04 2026 +0100 Mad Catz R.A.T. 8+ lighting control without the vendor software SignalRGB plugin streaming live colours through a firmware LED command (no storage writes), plus a Python CLI for live and stored profile colours. Protocol from the vendor app and a disassembly of firmware v18. Co-Authored-By: Claude Opus 5.5 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5f70406 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +firmware/ +profile_backup*.json +__pycache__/ diff --git a/MadCatz_RAT8Plus.js b/MadCatz_RAT8Plus.js new file mode 100644 index 0000000..ac101e8 --- /dev/null +++ b/MadCatz_RAT8Plus.js @@ -0,0 +1,189 @@ +// Mad Catz R.A.T. 8+ (USB 12CF:0C05), no vendor software needed. +// Live colours use a firmware command the vendor app never sends (found by disassembling +// firmware v18): [12, 0xC4, 3, 4, 1, zone, R, G, B] writes straight to the LED driver, +// with no storage writes, so it can run at full frame rate. The first such command pauses +// the mouse's own effect; [12, 0xC4, 3, 3, 3] hands the LEDs back to it. +// Profile commands (from the vendor app, RAT8P.dll) are only used for "Save to mouse". +export function Name() { return "Mad Catz R.A.T. 8+"; } +export function VendorId() { return 0x12CF; } +export function ProductId() { return 0x0C05; } +export function Publisher() { return "Custom"; } +export function Size() { return [3, 3]; } +export function DefaultPosition() { return [240, 120]; } +export function DefaultScale() { return 8.0; } +export function DeviceType() { return "mouse"; } +export function Validate(endpoint) { return endpoint.interface === 1; } +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 mouse shows when SignalRGB closes. 'Save last colours' stores them in the active profile (one storage write), so they survive replugging", type:"combobox", values:["Mouse's own lighting", "Shutdown Color", "Save last colours to mouse"], default:"Mouse's own lighting"}, + {property:"shutdownColor", group:"lighting", label:"Shutdown Color", min:"0", max:"360", type:"color", default:"#000000"}, + ]; +} + +// Zones: 0 = under the scroll wheel, 1 = palm logo, 2 = DPI button +const vLedNames = ["Scroll Wheel", "DPI Button", "Palm Logo"]; +const vLedPositions = [[1, 0], [1, 1], [1, 2]]; +const vZoneForLed = [0, 2, 1]; + +const FEAT_LEN = 2053; +const PROFILE_LEN = 733; +const LED_OFFSET = 160; +const LED_ZONE_LEN = 191; +const SLOT_CHECK_MS = 3000; +const RESEND_MS = 1000; // resend unchanged colours this often, in case the mouse reset them + +let sent = [null, null, null]; +let lastSend = 0; +let slot = -1; +let lastSlotCheck = 0; + +export function LedNames() { return vLedNames; } +export function LedPositions() { return vLedPositions; } + +export function Initialize() { + device.set_endpoint(1, 0x004B, 0x0008, 0x0003); + device.setName("Mad Catz R.A.T. 8+"); + device.setControllableLeds(vLedNames, vLedPositions); + slot = readActiveSlot(); +} + +export function Render() { + const now = Date.now(); + + // A profile switch on the mouse reloads its own lighting; release and retake + // control so the firmware pauses its effect again + if (now - lastSlotCheck > SLOT_CHECK_MS) { + lastSlotCheck = now; + const s = readActiveSlot(); + if (s >= 0 && s !== slot) { + slot = s; + releaseLeds(); + sent = [null, null, null]; + } + } + + const colors = currentColors(); + const resend = now - lastSend > RESEND_MS; + + for (let z = 0; z < 3; z++) { + if (resend || !sameColor(colors[z], sent[z])) { + setZone(z, colors[z]); + } + } + + if (resend) { lastSend = now; } +} + +export function Shutdown(SystemSuspending) { + if (shutdownMode === "Shutdown Color") { + const c = hexToRgb(shutdownColor); + for (let z = 0; z < 3; z++) { setZone(z, c); } + return; + } + + if (shutdownMode === "Save last colours to mouse" && sent[0]) { + saveToProfile(sent); + } + + releaseLeds(); +} + +function setZone(zone, c) { + device.send_report([12, 0xC4, 3, 4, 1, zone, c[0], c[1], c[2]], FEAT_LEN); + sent[zone] = c; +} + +function releaseLeds() { + device.send_report([12, 0xC4, 3, 3, 3], FEAT_LEN); +} + +function currentColors() { + const out = [null, null, null]; + + for (let i = 0; i < vLedPositions.length; i++) { + const [x, y] = vLedPositions[i]; + out[vZoneForLed[i]] = LightingMode === "Forced" ? hexToRgb(forcedColor) : device.color(x, y); + } + + return out; +} + +function sameColor(a, b) { + return !!a && !!b && a[0] === b[0] && a[1] === b[1] && a[2] === b[2]; +} + +function readActiveSlot() { + device.send_report([12, 0xC4, 22], FEAT_LEN); + + for (let i = 0; i < 10; i++) { + device.pause(10); + const r = device.get_report([12], FEAT_LEN); + if (r[0] === 0xB0 && r[1] === 0xC6) { return r[2]; } + } + + return -1; +} + +// One profile write: read the active profile, put static colours in, write it back +function saveToProfile(colors) { + const s = readActiveSlot(); + if (s < 0) { return; } + + device.send_report([12, 0xC4, 12, s], FEAT_LEN); + let profile = null; + + for (let i = 0; i < 10 && !profile; i++) { + device.pause(50); + const r = device.get_report([5], FEAT_LEN); + if (r[0] === 5 && r[1] === 0xB0 && r[2] === s && r[3] !== 0 && r[3] === checksum(r, 4, 736)) { + profile = r.slice(4, 4 + PROFILE_LEN); + } + } + + if (!profile) { + device.log(`R.A.T. 8+: could not read profile ${s}, colours not saved`); + return; + } + + for (let z = 0; z < 3; z++) { + const o = LED_OFFSET + z * LED_ZONE_LEN; + profile[o] = 1; // static + profile[o + 1] = 255; // brightness + profile[o + 2] = colors[z][0]; + profile[o + 3] = colors[z][1]; + profile[o + 4] = colors[z][2]; + } + + device.send_report([5, 0, s, checksum(profile, 0, PROFILE_LEN)].concat(profile), FEAT_LEN); + + for (let i = 0; i < 25; i++) { + device.pause(20); + const r = device.get_report([12], FEAT_LEN); + if (r[0] === 0xB0 && r[1] === 5 && r[2] === s && r[3] === r[4]) { + device.send_report([12, 0xC4, 0], FEAT_LEN); // reload + return; + } + } + + device.log("R.A.T. 8+: mouse did not confirm the profile write"); +} + +function checksum(data, start, length) { + let sum = 0; + for (let i = start; i < start + length; i++) { sum = (sum + data[i]) & 0xFF; } + return (256 - sum) & 0xFF; +} + +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..984c53d --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +# Mad Catz R.A.T. 8+ lighting without the vendor software + +USB ID 12CF:0C05, firmware 18. Protocol decompiled from the vendor app (`Controllers\RAT8P.dll`). +Details are in the docstring at the top of `rat8.py`. + +- `MadCatz_RAT8Plus.js`: SignalRGB plugin, installed in `Documents\WhirlwindFX\Plugins`. + Restart SignalRGB after changing it. +- `rat8.py`: command-line tool (`pip install hidapi`). +- Run `python rat8.py backup profile_backup.json` before you change anything, so + `restore` can put the mouse back exactly as it was. + +The plugin streams colours live with a firmware command the vendor app never uses +(`[12, C4, 3, 4, 1, zone, R, G, B]`, see "Firmware" below). That command goes straight +to the LED driver with no storage writes, so it doesn't wear anything out. It handles +110+ updates a second. The `static`/`breathe`/`off` commands below change the stored +profile instead (one storage write each), which survives replugging. +Zones: 0 = under the scroll wheel, 1 = palm logo, 2 = DPI button. + +``` +python rat8.py live ff0000 00ff00 0000ff # RAM only, until release/replug +python rat8.py release # back to the stored lighting +python rat8.py info +python rat8.py static 00aaff # all zones +python rat8.py static ff0000 00ff00 0000ff # scroll palm dpi +python rat8.py breathe ff00ff -p 3 +python rat8.py off +python rat8.py restore profile_backup.json +``` + +Close SignalRGB (or disable the plugin) before you use the script, because both share +one reply buffer on the mouse. + +## Firmware + +The firmware isn't in this repo, because it's Mad Catz's code. To get it, decompile +`MADCATZ R8+ Firmware Update Tool.exe` with `ilspycmd -p`. The `Firmware` byte array in +`GAMINGAPP.Properties.Resources.resx` is the whole image: 49,152 bytes, version 18 +(the version the mouse reports). It's unencrypted ARM Cortex-M0 code, loaded at address 0 +(initial SP 0x20002000, so 8 KB RAM; reset handler at 0x86E3), which fits a Sonix +SN32F2-series chip. The addresses below are for that image, disassembled as Thumb with capstone. + +The updater sends `[12, 0xC4, 5, 0, 0]` to put the mouse into update mode, then 24 chunks with +`[10, 0x10, chunk, checksum, 2048 bytes]`. **Never send command 5 by hand.** The mouse would sit +in update mode waiting for an image. The protocol has no command to read flash back. + +Useful addresses: +- `0x319C`: feature-report handler. It dispatches on the prefix byte: C4 goes to 0x2F94, + and C5, DE and DF go to raw/debug handlers. +- `0x2F94`: C4 command switch (jump table at 0x2FA8). 0 reload, 1 reset, 3 live LED, 5 update + mode, 6 calibrate, 7 select profile, 8 version, 12 read profile, 15 raw byte access, 22 active profile. +- `0x2E74`: command 3. The first call pauses the effect engine (0x4ED2) and blanks the LEDs. + Sub 4 sets colours: mode 1 is one zone via 0x6C3C, mode 2 is all zones via 0x6C8C, or off. + Sub 3/3 releases (0x4F1E). +- `0x6B90`: writes to the 9-channel LED driver over bus 0. Register 1 holds the 9 PWM bytes + (3 zones × RGB), and writing register 0x16 latches them. diff --git a/rat8.py b/rat8.py new file mode 100644 index 0000000..eefa157 --- /dev/null +++ b/rat8.py @@ -0,0 +1,206 @@ +"""Mad Catz R.A.T. 8+ (USB 12CF:0C05) lighting control without the vendor software. + +Protocol taken from the vendor's .NET app (Controllers/RAT8P.dll, decompiled). +The vendor channel is interface 1, collection 3 (usage page 0x08). All traffic is +HID feature reports, padded to 2053 bytes: + + report 12 command [12, 0xC4, cmd, args...]; reply via GetFeature(12) = [0xB0, ...] + cmd 0 = reload settings from storage (makes a profile write take effect) + cmd 8 = firmware version -> [B0 55 AA ver] + cmd 12 = read profile slot -> GetFeature(5) + cmd 22 = active profile -> [B0 C6 slot] + report 5 profile [5, 0, slot, checksum, 733 bytes]; ack [B0 05 slot x x] + read reply [5, B0, slot, checksum, 733 bytes] + +LED block: 3 zones of 191 bytes starting at profile offset 160. + zone 0 = under the scroll wheel, zone 1 = palm logo, zone 2 = DPI button + static: [1, brightness, R, G, B] + breathe: [2, 0,0,0,0, period_s lo, hi, 0,0,0,0, 1, brightness, R, G, B] + +Every profile write goes to the mouse's own storage (~160 ms), so don't stream +colours that way: it wears the flash. + +Live control (found by disassembling firmware v18, not used by the vendor app): + [12, C4, 3, 4, 1, zone, R, G, B] set zone 0-2 straight on the LED driver, RAM only. + The first one pauses the mouse's own effect. + [12, C4, 3, 4, 2, 1, R, G, B] set all zones + [12, C4, 3, 3, 3] release: back to the stored profile lighting +""" +import argparse, json, sys, time +import hid + +VID, PID = 0x12CF, 0x0C05 +FEAT_LEN = 2053 +PROFILE_LEN = 733 +LED_OFFSET = 160 +LED_ZONE_LEN = 191 +ZONES = {"scroll": 0, "palm": 1, "dpi": 2} + + +def checksum(data): + return (256 - (sum(data) & 0xFF)) & 0xFF + + +class Rat8: + def __init__(self): + paths = [d["path"] for d in hid.enumerate(VID, PID) if d["usage_page"] == 0x08] + if not paths: + raise SystemExit("R.A.T. 8+ vendor interface not found (is the mouse plugged in?)") + self.h = hid.device() + self.h.open_path(paths[0]) + + def set_feature(self, data): + if self.h.send_feature_report(bytes(data) + bytes(FEAT_LEN - len(data))) < 0: + raise IOError("SetFeature failed") + + def get_feature(self, rid): + return bytes(self.h.get_feature_report(rid, FEAT_LEN)) + + def cmd(self, *args): + self.set_feature([12, 0xC4, *args]) + + def _wait(self, rid, ok, tries=20, delay=0.05): + for _ in range(tries): + r = self.get_feature(rid) + if ok(r): + return r + time.sleep(delay) + return None + + def firmware(self): + self.cmd(8); time.sleep(0.05) + r = self._wait(12, lambda r: r[:3] == b"\xb0\x55\xaa") + return r[3] if r else None + + def active_slot(self): + self.cmd(22); time.sleep(0.05) + r = self._wait(12, lambda r: r[0] == 0xB0 and r[1] == 0xC6) + if not r: + raise IOError("could not read the active profile") + return r[2] + + def read_profile(self, slot): + self.cmd(12, slot); time.sleep(0.1) + r = self._wait(5, lambda r: r[0] == 5 and r[1] == 0xB0 and r[2] == slot + and r[3] != 0 and r[3] == checksum(r[4:4 + 736]), tries=10, delay=0.1) + if not r: + raise IOError(f"could not read profile {slot}") + return bytearray(r[4:4 + PROFILE_LEN]) + + def write_profile(self, slot, data): + assert len(data) == PROFILE_LEN + self.set_feature([5, 0, slot, checksum(data), *data]) + r = self._wait(12, lambda r: r[0] == 0xB0 and r[1] == 5 and r[2] == slot and r[3] == r[4], + tries=25, delay=0.02) + if not r: + raise IOError(f"mouse did not confirm the write to profile {slot}") + + def reload(self): + self.cmd(0) + + +def set_zone(p, zone, block): + """Write block into a zone; None entries keep the byte already there (as the vendor app does).""" + o = LED_OFFSET + zone * LED_ZONE_LEN + for i, v in enumerate(block): + if v is not None: + p[o + i] = v + + +def static_block(rgb, brightness): + return [1, brightness, *rgb] + + +def breathe_block(rgb, brightness, period): + K = None + return [2, K, K, K, K, period & 0xFF, period >> 8, K, K, K, K, 1, brightness, *rgb] + + +def parse_color(s): + s = s.lstrip("#") + if len(s) != 6: + raise argparse.ArgumentTypeError(f"bad colour {s!r}, use RRGGBB") + return tuple(int(s[i:i + 2], 16) for i in (0, 2, 4)) + + +def zone_colors(args): + """Return {zone_index: rgb}; one colour means all zones.""" + cols = args.colors + if len(cols) == 1: + return {z: cols[0] for z in range(3)} + if len(cols) == 3: + return {ZONES["scroll"]: cols[0], ZONES["palm"]: cols[1], ZONES["dpi"]: cols[2]} + raise SystemExit("give 1 colour (all zones) or 3 colours (scroll palm dpi)") + + +def apply(m, args, build): + slots = range(4) if args.all_slots else [m.active_slot()] + for slot in slots: + p = m.read_profile(slot) + for zone, rgb in zone_colors(args).items(): + set_zone(p, zone, build(rgb)) + m.write_profile(slot, p) + print(f"profile {slot}: written") + m.reload() + + +def main(): + ap = argparse.ArgumentParser(description="Mad Catz R.A.T. 8+ lighting control") + sub = ap.add_subparsers(dest="cmd", required=True) + sub.add_parser("info", help="firmware, active profile and current LED settings") + + for name, hlp in (("static", "solid colours"), ("breathe", "breathing effect")): + sp = sub.add_parser(name, help=hlp) + sp.add_argument("colors", nargs="+", type=parse_color, + help="RRGGBB, either one for all zones or three: scroll palm dpi") + sp.add_argument("-b", "--brightness", type=int, default=255) + sp.add_argument("--all-slots", action="store_true", help="write all 4 profiles, not just the active one") + if name == "breathe": + sp.add_argument("-p", "--period", type=int, default=3, help="seconds per breath") + + sp = sub.add_parser("live", help="set colours live (RAM only, no storage write; lost on replug)") + sp.add_argument("colors", nargs="+", type=parse_color, help="RRGGBB, one or three: scroll palm dpi") + sub.add_parser("release", help="hand the LEDs back to the mouse's own stored lighting") + + sp = sub.add_parser("off", help="turn all LEDs off") + sp.add_argument("--all-slots", action="store_true") + sub.add_parser("backup", help="save all 4 profiles to a JSON file").add_argument("file") + sub.add_parser("restore", help="write profiles back from a backup file").add_argument("file") + + args = ap.parse_args() + m = Rat8() + + if args.cmd == "info": + slot = m.active_slot() + print("firmware:", m.firmware(), " active profile:", slot) + p = m.read_profile(slot) + for name, z in ZONES.items(): + o = LED_OFFSET + z * LED_ZONE_LEN + print(f" {name:6} {p[o:o + 16].hex(' ')}") + elif args.cmd == "static": + apply(m, args, lambda rgb: static_block(rgb, args.brightness)) + elif args.cmd == "breathe": + apply(m, args, lambda rgb: breathe_block(rgb, args.brightness, args.period)) + elif args.cmd == "live": + for zone, rgb in zone_colors(args).items(): + m.cmd(3, 4, 1, zone, *rgb) + elif args.cmd == "release": + m.cmd(3, 3, 3) + elif args.cmd == "off": + args.colors = [(0, 0, 0)] + apply(m, args, lambda rgb: static_block(rgb, 0)) + elif args.cmd == "backup": + data = {str(s): m.read_profile(s).hex() for s in range(4)} + json.dump(data, open(args.file, "w"), indent=1) + print("saved", args.file) + elif args.cmd == "restore": + data = json.load(open(args.file)) + for s, hx in data.items(): + if hx: + m.write_profile(int(s), bytearray.fromhex(hx)) + print(f"profile {s}: restored") + m.reload() + + +if __name__ == "__main__": + main()