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:
commit
25f3e31b8f
4 files changed
+453
No files matched your search
@@ -0,0 +1,3 @@
|
||||
firmware/
|
||||
profile_backup*.json
|
||||
__pycache__/
|
||||
@@ -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)];
|
||||
}
|
||||
@@ -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.
|
||||
@@ -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()
|
||||
Reference in new issue
Block a user