uchroma

Appearance

Razer USB HID Protocol Reference ​

Comprehensive documentation of the Razer Chroma USB HID protocol, compiled from reverse engineering efforts by the OpenRazer project, razercfg, and community research.

Vendor ID: 0x1532 (Razer Inc.)

1. Report Structure ​

All Razer Chroma devices communicate via 90-byte USB HID feature reports.

Request Format (PC → Device) ​

OffsetSizeFieldDescription
01StatusAlways 0x00 for requests
11Transaction IDDevice-specific routing ID
2-32Remaining PacketsBig-endian, for multi-packet transfers
41Protocol TypeAlways 0x00
51Data SizeNumber of argument bytes
61Command ClassCategory of command
71Command IDSpecific command within class
8-8780ArgumentsCommand parameters
881CRCXOR checksum of bytes 1-86
891ReservedAlways 0x00

Response Format (Device → PC) ​

Same structure, but with status codes in byte 0:

StatusNameDescription
0x00UNKNOWNPending/unprocessed
0x01BUSYRetry needed
0x02OKSuccess
0x03FAILCommand failed
0x04TIMEOUTNo response
0x05UNSUPPORTEDCommand not supported

CRC Calculation ​

python
def calculate_crc(report: bytes) -> int:
    crc = 0
    for i in range(1, 87):  # Bytes 1-86 inclusive
        crc ^= report[i]
    return crc

Note: Some devices (Blade 2021+) return CRC=0x00 on success—validation should be skipped for OK responses.

2. Transaction IDs ​

The transaction ID determines device routing and varies by hardware generation:

Transaction IDDevice GenerationExamples
0xFFLegacy/StandardMost keyboards, original mice
0x3FExtended ProtocolNaga Hex V2, DeathAdder Elite, Mamba Wireless
0x1FModern (2021+)Blade 2021+, Basilisk Ultimate, Viper V3 Pro
0x9FWireless KeyboardsBlackWidow V3 Pro (wireless), DeathStalker V2 Pro (wireless)
0x80Custom Frame DataSome laptops (lid logo)
0x08Special CaseNaga X

uchroma Quirks Mapping ​

python
class Quirks(IntEnum):
    TRANSACTION_CODE_3F = 1
    EXTENDED_FX_CMDS = 2
    TRANSACTION_CODE_1F = 9
    CUSTOM_FRAME_80 = 5

3. Command Classes ​

Class 0x00 — Device Info & Control ​

IDNameSizeDescription
0x04SET_DEVICE_MODE2Set driver mode (0x00=normal, 0x03=driver)
0x05SET_POLLING_RATE1Set polling rate
0x40SET_POLLING_RATE_V2varExtended polling rate (HyperPolling)
0x41PAIRING_STEP3Wireless pairing initiation
0x42UNPAIR2Wireless unpairing
0x46PAIRING_SCAN1Start pairing scan
0x81GET_FIRMWARE2Query firmware version
0x82GET_SERIAL22Query serial number
0x84GET_DEVICE_MODE2Query current mode
0x85GET_POLLING_RATE1Query polling rate
0xBFGET_PAIRED_DEVICES31Query paired device list
0xC0GET_POLLING_RATE_V2varQuery extended polling
0xC5GET_PAIRED_STATUSvarQuery paired device status

Class 0x02 — Key Remapping ​

IDNameSizeDescription
0x0DSET_KEY_REMAPvarKey remapping (non-analog keyboards)
0x12SET_KEY_REMAP_ANALOGvarKey remapping (analog keyboards)

Class 0x03 — Standard LED/Effects ​

IDNameSizeDescription
0x00SET_LED_STATE3Enable/disable LED
0x01SET_LED_COLOR5Set LED color (RGB)
0x02SET_LED_MODE3Set LED effect mode
0x03SET_LED_BRIGHTNESS3Set brightness level
0x0ASET_EFFECTvarApply lighting effect
0x0BSET_FRAME_DATA_MATRIXvarCustom frame (multi-row)
0x0CSET_FRAME_DATA_SINGLEvarCustom frame (single row)
0x10SET_DOCK_CHARGE_EFFECT1Dock charging LED
0x80GET_LED_STATE3Query LED state
0x81GET_LED_COLOR5Query LED color
0x82GET_LED_MODE3Query LED mode
0x83GET_LED_BRIGHTNESS3Query brightness

Class 0x04 — DPI / Mouse Settings ​

IDNameSizeDescription
0x05SET_DPI_XY7Set X/Y DPI values
0x06SET_DPI_STAGESvarSet DPI stage presets
0x85GET_DPI_XY7Query current DPI
0x86GET_DPI_STAGESvarQuery DPI stages

Class 0x05 — Profile Management ​

IDNameSizeDescription
0x02SET_PROFILEvarSwitch to profile slot
0x03GET_PROFILEvarQuery current profile
0x08WRITE_PROFILE_DATAvarWrite data to profile slot

Profile slot IDs: 0x00=no-store, 0x01=default/white, 0x02=red, 0x03=green, 0x04=blue, 0x05=cyan

Class 0x07 — Power & Battery ​

IDNameSizeDescription
0x01SET_LOW_BATTERY1Set low battery threshold
0x02SET_DOCK_BRIGHTNESS1Set dock LED brightness
0x03SET_IDLE_TIME2Set idle timeout (60-900s)
0x10SET_DONGLE_LED1Set HyperSpeed dongle LED mode
0x80GET_BATTERY_LEVEL2Query battery level (0-255)
0x81GET_LOW_BATTERY1Query low battery threshold
0x82GET_DOCK_BRIGHTNESS1Query dock brightness
0x83GET_IDLE_TIME2Query idle timeout
0x84GET_CHARGING_STATUS2Query charging (0=no, 1=yes)

Class 0x0B — Calibration ​

IDNameSizeDescription
0x03SET_CALIBRATIONvarSurface calibration mode
0x05SET_LIFTOFFvarLift-off distance
0x09START_CALIBRATIONvarBegin calibration
0x0BFINALIZE_CALIBRATIONvarComplete calibration
0x85GET_CALIBRATIONvarQuery calibration data

Class 0x0D — Laptop Fan/Power (EC Control) ​

IDNameSizeDescription
0x02SET_FAN_MODEvarFan control mode
0x82GET_FAN_RPMvarQuery fan speed

Class 0x0F — Extended Matrix Effects ​

IDNameSizeDescription
0x02SET_EFFECT_EXTENDEDvarApply extended effect
0x03SET_FRAME_EXTENDEDvarExtended custom frame
0x04SET_LED_BRIGHTNESS_EXT3Set brightness (extended)
0x80GET_EFFECT_EXTENDEDvarQuery current effect
0x82GET_MATRIX_EFFECTvarQuery matrix state
0x84GET_LED_BRIGHTNESS_EXT3Query brightness (extended)

4. Effects ​

Standard Effects (Class 0x03, ID 0x0A) ​

Effect IDNameArgs
0x00DISABLE—
0x01WAVEdirection (1=right, 2=left)
0x02REACTIVEspeed, R, G, B
0x03BREATHEmode, [colors...]
0x04SPECTRUM—
0x05CUSTOM_FRAMEvarstore
0x06STATICR, G, B
0x0AGRADIENT—
0x0CSWEEPdirection, speed, bg_color, fg_color
0x10HIGHLIGHT—
0x11MORPHmode, speed, color1, color2
0x12FIREmode, speed, color
0x13RIPPLE_SOLIDmode, speed, color
0x14RIPPLEmode, speed, color
0x19STARLIGHTmode, speed, [colors...]

Extended Effects (Class 0x0F, ID 0x02) ​

Used on devices with EXTENDED_FX_CMDS quirk:

Effect IDNameArgs
0x00DISABLE—
0x01STATICR, G, B
0x02BREATHEmode, [colors...]
0x03SPECTRUM—
0x04WAVEdirection
0x05REACTIVEspeed, R, G, B
0x07STARLIGHTmode, speed, [colors...]
0x08CUSTOM_FRAME—

Format: [varstore, LED_type, effect_id, ...params]

5. LED Identifiers ​

LED TypeIDCapabilities
SCROLL_WHEEL0x01RGB, brightness
MISC0x02RGB
BATTERY0x03RGB (dock charge color)
LOGO0x04RGB, brightness
BACKLIGHT0x05RGB, brightness, effects
MACRO0x07On/off
GAME0x08On/off
PROFILE_RED0x0EOn/off
PROFILE_GREEN0x0COn/off
PROFILE_BLUE0x0DOn/off
CHARGING0x20On/off
FAST_CHARGING0x21On/off
FULLY_CHARGED0x22On/off

6. Polling Rates ​

Standard Polling Rate Values (Class 0x00, ID 0x05) ​

ValueRate
0x011000 Hz
0x02500 Hz
0x08125 Hz

HyperPolling Values (Class 0x00, ID 0x40) ​

ValueRate
0x024000 Hz (8000 Hz wireless)
0x042000 Hz
0x081000 Hz
0x10500 Hz
0x40125 Hz

Note: HyperPolling dongle sends each rate command twice with transaction IDs 0x00 and 0x01.

7. Custom Frame Protocol ​

Matrix Frame (multi-row keyboards) ​

Command: 0x03, 0x0B

ByteDescription
0Frame ID (usually 0xFF)
1Row index (0-5 for 6-row keyboard)
2Start column
3End column
4+RGB data (3 bytes per LED)

For keyboards wider than 24 columns, split into two commands.

Single Row Frame (mousepads, mice) ​

Command: 0x03, 0x0C

ByteDescription
0Start index
1End index
2+RGB data

8. Headset Protocol (Kraken Family) ​

Kraken headsets use a completely different protocol:

Report Structure ​

  • Output Report ID: 0x04 (37 bytes)
  • Input Report ID: 0x05 (33 bytes)
  • Delay: 25ms between commands

Command Format ​

ByteDescription
0Destination (0x00=read RAM, 0x20=read EEPROM, 0x40=write RAM)
1Length
2-3Address (big-endian)
4+Arguments

Memory Addresses ​

Rainie (Kraken 7.1 v1):

  • LED Mode: 0x1008
  • Breathing Color: 0x15DE

Kylie (Kraken V2/Ultimate):

  • LED Mode: 0x172D
  • Breathing 1: 0x1741
  • Breathing 2: 0x1745
  • Breathing 3: 0x174D

Effect Bits (single byte) ​

BitEffect
0LED On
1Breathe Single
2Spectrum
3Sync
4Breathe Double
5Breathe Triple

9. Inter-Command Timing ​

Device TypeDelay
Standard7ms
Headsets (Kraken)25ms
Naga mice35ms
Wireless (retry)100ms

10. Known Quirks ​

Device-Specific Issues ​

QuirkDevicesWorkaround
CRC=0x00 on successBlade 2021+Skip CRC validation on OK status
Extended FX onlySynapse 3 devicesUse class 0x0F instead of 0x03
No firmware effectsNewer mice/keyboardsSoftware-rendered effects only
Battery always 0AA battery miceCheck is_wireless flag
Serial query timeoutWireless (device off)Mark device offline

Multi-Packet Transfers ​

For commands exceeding 80 bytes of arguments:

  1. Set remaining_packets field to count of additional packets
  2. Send packets in sequence
  3. Hardware processes on final packet (remaining_packets=0)

11. Reverse Engineering Methodology ​

Setup ​

  1. VirtualBox with Windows VM
  2. Razer Synapse installed
  3. USB passthrough to VM
  4. Wireshark with usbmon kernel module

Capture Commands ​

bash
sudo modprobe usbmon
sudo setfacl -m u:$USER:r /dev/usbmon*
wireshark -k -i usbmon0

Filter ​

usb.idVendor == 0x1532 && usb.transfer_type == 0x02

Look for "Leftover Capture Data" field containing protocol bytes.

12. Sources ​

Released under the LGPL-3.0 License.

Copyright © 2017-present Stefanie Jane