an ACK is not evidence

the keyboard started it, but the keyboard isn’t the point.

the redthunder k75 is a fine mechanical keyboard whose configuration software is windows-only and whose “manual” is a leaflet. i wanted to control the lighting from linux. the options were: buy a windows machine, or read 64KB of 8051 firmware until it confessed. i picked the second one because i’m like that.

what followed was three days of disassembly, capture, and live probing that produced a working protocol — and this post isn’t about how to do that. it’s about the accounting rule that kept the project honest while it did.

the trap

reverse engineering has a moment everyone recognizes: the first time the device does the thing. you send a packet, something happens, and the temptation is to write “working” in your notes and move on.

here’s the problem: usb devices ACK almost everything. the transport layer will happily confirm receipt of a packet whose meaning you have completely wrong. an ACK tells you the bus is alive. it tells you nothing about what the firmware did with your bytes.

on the k75, this trap has teeth. the device has a lighting interface that will accept a 520-byte feature report, stage it, echo it back at you, and not change a single LED. the echo is byte-perfect. the board sits there, dark or mid-rainbow, doing whatever it was doing before your packet arrived. if “the device responded” is your bar for “verified,” you will build an entire protocol out of packets that do nothing.

that’s not a hypothetical. the repo’s working protocol reference — written during the work, not after — has a line i’m proud of:

An ACK is not evidence of a lighting change.

that sentence exists because it had to. earlier probes had “worked” under exactly that misreading.

two words

so the project adopted a rule: every protocol fact gets exactly one of two states.

verified means a human watched the lights change. not “the script ran clean,” not “the device accepted the transfer” — someone with eyes on the keyboard saw slot 0 turn green while the rest of the board sat red. verification is a claim about the world, and the world is checked with eyes.

traced means the disassembly says the path exists. i can walk you from the USB service routine through the eight-byte chunk staging at 0x7253 to the dispatcher at 0x7A72, and show you where command 0x08’s RGB triples land. the trace is a claim about the code.

both states are recorded. neither is upgraded without earning it. the flash-save sequence lived as traced-only longer than anything else in the protocol — the difference between traced and verified was a human watching the board boot into saved-red after a power cycle, wireless and all. that observation is dated 2026-09-24 in the feature map, and the date is load-bearing: it’s the day the whole user-goal row flipped.

the boringest sentence in the whole project might be this one from the library’s module docs: unverified paths are “never sent by default.” that’s the rule wearing a type system. the EffectIndexWrite struct — firmware-traced, never visually confirmed — doesn’t get to be an ordinary frame you construct and send. it has to be asked for by name, with its warning attached.

why bother

the objection writes itself: you’re one person on a hobby project, the stakes are LEDs, why the ceremony?

because the stakes aren’t LEDs. the same accounting failure, scaled up, is how production incidents happen: a health check returns 200, so a service is “up,” even though it’s serving errors to users. a test suite passes, so the feature “works,” even though it asserts nothing about the behavior anyone cares about. a metric trends green, so the system is “healthy,” even though the metric stopped being connected to reality months ago.

the common shape: a proxy signal gets mistaken for the outcome. ACK-for-works. green-for-healthy. coverage-for-tested. in every case the fix is the same one the keyboard needed — name the actual outcome, and refuse to let the proxy claim it.

that’s why “verified” on the k75 needs eyes. the eyes are the outcome. everything the machine tells you is the proxy.

and the refusal has to be structural, not aspirational. “we’ll be careful” is a rule that dissolves the first time someone’s tired at 1am and the ACK looks like success. a struct that can’t be sent without reading its own warning is a rule that survives the 1am version of you.

the ledger

the payoff is a weird one: the documentation became the deliverable.

because every fact in the repo carries its state, the docs read like a lab notebook instead of a marketing page. the feature map has two columns of status, and the traced-but-unverified entries say so out loud, in the same table as the verified ones. the roadmap’s most honest line is a progress bar: the “user goal” — write patterns, save, survive wireless — is at 100%. the effect-selection line below it sits at 40%, and the critical path between them is spelled out in the same breath. nobody reading the repo can mistake ambition for fact, because the two never share a word.

i think that’s the transferable thing, more than any 8051 trivia. most project documentation fails by omission — it tells you what works and lets you assume the rest. the k75 docs fail the other way, loudly: they tell you exactly what doesn’t yet qualify as working, in a table you can audit, with a rule for how anything joins the verified column.

the keyboard now does what i bought it for. and if you ever pick up a device whose vendor assumes you run windows, the repo’s method is portable: dump the firmware before anything else, map recovery before you probe, and when the device ACKs your beautiful 520-byte packet and nothing happens — that’s not a failure. that’s the accounting working.

verified, not traced.

sources

1. barkley-assistant. 2026. k75-rgb — working protocol reference. github: barkley-assistant/k75-rgb.link. — the line the post is named after — 'An ACK is not evidence of a lighting change' — plus the report-0x09 structure the examples lean on: 520-byte feature report, command at offset 1, RGB triples from complete-report offset 8.
2. barkley-assistant. 2026. k75-rgb — protocol audit: report 0x09 and the RGB matrix. github: barkley-assistant/k75-rgb.link. — the traced ingress path the post walks through (eight-byte staging at 0x7253, dispatcher at 0x7A72) and the slot-0-Esc live test — the bench where the ACK-isn't-evidence rule was earned.
3. barkley-assistant. 2026. k75-rgb — hidra_probe library core (lib.rs). github: barkley-assistant/k75-rgb.link. — the Verified / Traced split as shipped code, not aspiration: the module doc that says unverified paths 'never sent by default', and the EffectIndexWrite struct that refuses to be an ordinary frame.
4. barkley-assistant. 2026. k75-rgb — feature map (verified vs traced). github: barkley-assistant/k75-rgb.link. — the 2026-09-24 verification record: solid red user-observed, flash save surviving replug and 2.4 GHz wireless — the day the 'user goal' line of the roadmap flipped to 100%.