Paul Contreras

Posted on Jun 8

DPI, Color, and Why "OK" Doesn't Mean It Worked

#discuss #learning #sideprojects #tutorial

Part 3 of a series on building a native Razer mouse controller for macOS.

We have the envelope from part 2. Now the commands that actually do something: DPI and lighting. The DPI one is easy. The color one taught me the most useful lesson in this whole project, which is that the device telling you 0x02 (OK) is not the device telling you it did what you wanted.

Setting DPI

Command class 0x04, id 0x05, data_size 0x07.

The value is the raw DPI, not divided by anything. 800 DPI is 0x0320, split into a high byte and a low byte. The mouse stores X and Y sensitivity separately, so you send the pair twice.

func dpiReport(_ dpi: Int) -> [UInt8] {
    let v = UInt16(dpi)
    var r = [UInt8](repeating: 0, count: 90)
    r[1]  = 0x3F
    r[5]  = 0x07
    r[6]  = 0x04          // class: DPI
    r[7]  = 0x05          // id: set DPI
    r[8]  = 0x00          // stage
    r[9]  = UInt8(v >> 8)   // X high
    r[10] = UInt8(v & 0xFF) // X low
    r[11] = UInt8(v >> 8)   // Y high
    r[12] = UInt8(v & 0xFF) // Y low
    r[88] = r[2...87].reduce(0, ^)
    return r
}

This one is fire-and-forget. You don't need to read a response. Set it, feel the cursor speed change.

Reading DPI Back

There's a matching read command, class 0x04, id 0x85. Same idea, the id just has the high bit set, which is the convention for "get" versions of Razer commands.

I didn't think I needed this until the GUI app shipped and immediately created a bug: every time you opened the app it reset your DPI to 800. The app had a default of 800 and pushed it on connect, stomping whatever you'd actually set.

The fix was to read the device's real DPI on connect instead of forcing a default:

func getDPI() -> Int {
    // send class 0x04 id 0x85, read response
    let resp = request(...)
    return (Int(resp[9]) << 8) | Int(resp[10])
}

The DPI sits in the same byte positions in the response as you'd send it. Read first, then the UI reflects reality instead of overwriting it. Obvious in hindsight. Most of these bugs are.

The Color Command That Lied to Me

This is the part worth reading.

I wanted to set the logo and scroll wheel to a static color. I found a command that looked right, class 0x03, id 0x03, packed in the zone and an RGB triple, sent it. Got 0x02 back. OK. Accepted.

Nothing happened. The LED didn't change.

I checked the CRC. Fine. Checked the transaction ID. Fine. Checked the bytes ten times. The device kept saying 0x02. Accepted, accepted, accepted, and the logo stayed the color it already was.

The problem: 0x03 / 0x03 is not "set color." It's "set LED brightness." I was setting the brightness to a value, the device was happily setting the brightness to that value, and reporting success. It just wasn't a color command at all. I'd been sending a perfectly valid command for the wrong thing.

The real static color command for this device lives in a different family. Class 0x0F, id 0x02, the "extended matrix effect" commands. The layout:

data_size = 0x09
args[0] = 0x01        // varstore
args[1] = led_id      // scroll = 0x01, logo = 0x04
args[2] = 0x01        // effect: static
args[3] = 0x00
args[4] = 0x00
args[5] = 0x01
args[6] = r
args[7] = g
args[8] = b

Sent that. Logo turned green. First time the lighting actually moved.

The lesson stuck with me: a status of 0x02 only tells you the packet was well-formed and the device understood it as a command. It says nothing about whether it was the command you meant. A valid brightness-set and a valid color-set both return 0x02. If you're debugging by status code alone, you can burn an hour sending textbook-correct commands that do the wrong job.

Effects Come for Free

Once you're in the 0x0F / 0x02 family, the other lighting effects are just a different effect byte at args[2]:

Effect	args[2]	data_size
Off	`0x00`	6
Static	`0x01`	9 (+ rgb)
Breathing	`0x02`	9 (+ rgb)
Spectrum	`0x03`	6

Spectrum is the rainbow cycle. You set it once and the mouse firmware animates it on its own, no polling from your app. Breathing pulses a single color. Off goes dark. Same envelope, one byte different. After the static color fight, adding three more effects took about ten minutes.

What's Next

Part 4 leaves the protocol behind and wraps all this in a SwiftUI menu bar app. That sounds like the easy part. It was not. There's a crash that only happens because of a build setting, a permission macOS won't grant without being asked in a specific way, and a color picker that refuses to open. The protocol was more honest than the UI framework.

DEV Community