corsairctl/docs/bragi-protocol.md

Bragi-Protokoll — Reverse-Engineerte Dokumentation

Dieses Dokument beschreibt das Corsair Bragi HID-Protokoll, wie es von neueren Corsair-Wireless-Geräten (HS80 RGB Wireless, etc.) verwendet wird. Reverse-Engineered aus USB-Traces und den Python-Probes in ~/Projects/hs80-battery/.

Übersicht

Bragi kommuniziert über HID Feature Reports auf Interface 3 des USB-Receivers. Jedes Paket ist 65 Bytes (1 Byte Report ID + 64 Bytes Daten).

Paketformat

Request (Host → Gerät)

Byte 0: 0x00       — HID Report ID
Byte 1: 0x02       — Protokoll-Marker (immer 0x02)
Byte 2: Endpoint   — 0x08 = Receiver, 0x09 = Headset (via Receiver)
Byte 3: Command    — 0x01 = SET, 0x02 = GET
Byte 4: Property   — Property-ID (siehe unten)
Byte 5+: Daten     — Bei SET: die zu setzenden Werte
Rest: 0x00-gepaddet auf 65 Bytes

Response (Gerät → Host)

Byte 0: 0x02       — Protokoll-Marker
Byte 1: Status     — 0x00 = OK, 0xF0/0xF1 = Error/Not Supported
Byte 2: Endpoint   — Echo des Request-Endpoints
Byte 3: Command    — Echo des Request-Commands
Byte 4+: Daten     — Property-Wert (typisch uint16 Little-Endian in Bytes 4-5)

Fehler-Erkennung: Byte 1 == 0xF0 oder 0xF1 bedeutet, dass die Property nicht unterstützt wird oder der Request ungültig war.

Endpoints

ID	Name	Beschreibung
0x08	Receiver	Der USB-Dongle selbst
0x09	Headset	Das verbundene Wireless-Gerät

Commands

ID	Name	Beschreibung
0x01	SET	Property-Wert setzen
0x02	GET	Property-Wert lesen

Properties

ID	Name	Typ	Beschreibung
0x01	Polling Rate	uint16	Polling-Rate in Hz
0x02	Brightness	uint16	LED-Helligkeit (0-1000)
0x03	Mode	uint8	0x01 = Hardware, 0x02 = Software
0x09	Sidetone	uint16	Sidetone-Level
0x0F	Battery Level	uint16	Batterie in Promille (0-1000, /10 = Prozent)
0x10	Battery Status	uint8	Lade-/Entladestatus (siehe unten)
0x11	Vendor ID	uint16	USB Vendor ID
0x12	Product ID	uint16	USB Product ID
0x13	App Firmware	uint16	Applikations-Firmware-Version
0x14	Build Firmware	uint16	Build-Firmware-Version
0x15	Radio App FW	uint16	Radio-Applikations-Firmware
0x16	Radio Build FW	uint16	Radio-Build-Firmware

Battery Status Werte

Wert	Bedeutung
0x00	Offline
0x01	Entladen
0x02	Niedrig
0x03	Laden
0x04	Laden
0x05	Voll geladen

Initialisierungssequenz

Das Gerät muss in den Software-Modus versetzt werden, bevor Properties gelesen werden können. Die vollständige Sequenz:

Phase 1: Receiver initialisieren

1. Wake-Up: GET App Firmware an Receiver (0x08)
   • Weckt den Receiver auf und bestätigt Kommunikation
2. Software-Modus: SET Mode = 0x02 an Receiver (0x08)
   • Schaltet Receiver in Software-Modus
3. Heartbeat: GET Product ID an Receiver (0x08)
   • Bestätigt dass Receiver im Software-Modus antwortet

Phase 2: Headset initialisieren

4. Software-Modus: SET Mode = 0x02 an Headset (0x09)
   • Schaltet Headset in Software-Modus (via Receiver)
5. Flush: HID-Puffer leeren (nonblocking reads bis leer)
6. Heartbeat: GET Product ID an Headset (0x09)
   • Bestätigt dass Headset erreichbar ist und antwortet
   • Keine Antwort = Headset ausgeschaltet/nicht verbunden

Cleanup

Nach allen Abfragen müssen beide Geräte zurück in den Hardware-Modus:

7. SET Mode = 0x01 an Headset (0x09)
8. SET Mode = 0x01 an Receiver (0x08)

Wichtig: Ohne Cleanup bleibt das Gerät im Software-Modus und verhält sich möglicherweise nicht normal (z.B. keine automatische Abschaltung).

Wert-Extraktion

Für uint16-Werte: Little-Endian aus Response-Bytes 4 und 5:

value = response[4] | (response[5] << 8)

Für Batterie: Wert ist in Promille (0-1000), Division durch 10 ergibt Prozent.

USB-Identifikation

• Vendor ID: 0x1B1C (Corsair)
• Product ID: 0x0A6B (HS80 RGB Wireless)
• Interface: 3 (HID Control Interface)

Andere Bragi-Geräte verwenden dasselbe Protokoll mit unterschiedlichen Product IDs.