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 <noreply@anthropic.com>
This commit is contained in:
mangavalkandClaude Opus 5.5 committed 2026-11-19 15:39:04 +01:00
commit 25f3e31b8f
4 files changed
+453

No files matched your search

+3
View File
@@ -0,0 +1,3 @@
firmware/
profile_backup*.json
__pycache__/
+189
View File
@@ -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)];
}
+55
View File
@@ -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.
+206
View File
@@ -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()