# Bragi Protocol — Reverse-Engineered Documentation

This document describes the Corsair Bragi HID protocol used by newer Corsair
wireless devices (HS80 RGB Wireless, HS65, Virtuoso SE, etc.). Reverse-engineered
from USB traces and protocol analysis.

## Overview

Bragi communicates via HID Feature Reports on **Interface 3** of the USB receiver.
Each packet is 65 bytes (1 byte Report ID + 64 bytes data).

## Packet Format

### Request (Host → Device)

```
Byte 0: 0x00       — HID Report ID
Byte 1: 0x02       — Protocol marker (always 0x02)
Byte 2: Endpoint   — 0x08 = Receiver, 0x09 = Headset (via Receiver)
Byte 3: Command    — 0x01 = SET, 0x02 = GET
Byte 4: Property   — Property ID (see below)
Byte 5+: Data      — For SET: the values to write
Rest: 0x00-padded to 65 bytes
```

### Response (Device → Host)

```
Byte 0: 0x01       — Report type (always 0x01, NOT 0x02 like the request marker)
Byte 1: Endpoint   — 0x00 = Receiver, 0x01 = Headset (different IDs than request!)
                      On error: 0xF0/0xF1 = Error/Not Supported
Byte 2: Command    — Echo: 0x01 = SET, 0x02 = GET
Byte 3: Status     — 0x00 = OK
Byte 4+: Data      — Property value (typically uint16 Little-Endian in bytes 4-5)
```

**Note:** The response format differs from the request format:
- Byte 0 is `0x01` (not `0x02` like the request marker)
- Endpoint IDs are `0x00`/`0x01` (not `0x08`/`0x09` like in the request)

**Error detection:** Byte 1 == 0xF0 or 0xF1 indicates that the property is not
supported or the request was invalid.

## Endpoints

| ID   | Name     | Description                     |
|------|----------|---------------------------------|
| 0x08 | Receiver | The USB dongle itself           |
| 0x09 | Headset  | The connected wireless device   |

## Commands

| ID   | Name | Description           |
|------|------|-----------------------|
| 0x01 | SET  | Set a property value  |
| 0x02 | GET  | Read a property value |

## Properties

| ID   | Name              | Type    | Description                                   |
|------|-------------------|---------|-----------------------------------------------|
| 0x01 | Polling Rate      | uint16  | Polling rate in Hz                             |
| 0x02 | Brightness        | uint16  | LED brightness (0-1000)                        |
| 0x03 | Mode              | uint8   | 0x01 = Hardware, 0x02 = Software               |
| 0x09 | Sidetone          | uint16  | Sidetone level                                 |
| 0x0F | Battery Level     | uint16  | Battery in per-mille (0-1000, /10 = percent)  |
| 0x10 | Battery Status    | uint8   | Charging/discharging status (see below)        |
| 0x11 | Vendor ID         | uint16  | USB Vendor ID                                  |
| 0x12 | Product ID        | uint16  | USB Product ID                                 |
| 0x13 | App Firmware      | uint16  | Application firmware version                   |
| 0x14 | Build Firmware    | uint16  | Build firmware version                         |
| 0x15 | Radio App FW      | uint16  | Radio application firmware                     |
| 0x16 | Radio Build FW    | uint16  | Radio build firmware                           |

## Battery Status Values

Empirically determined on the HS80 RGB Wireless.
Differs from ckb-next sources where values are mapped differently.

| Value | Meaning       |
|-------|---------------|
| 0x00  | Offline       |
| 0x01  | Charging      |
| 0x02  | Discharging   |
| 0x03  | Low           |
| 0x04  | Fully charged |

## Initialization Sequence

The device must be switched to software mode before properties can be read.
Full sequence:

### Phase 1: Initialize Receiver

1. **Wake-up:** `GET App Firmware` to Receiver (0x08)
   - Wakes the receiver and confirms communication
2. **Software mode:** `SET Mode = 0x02` to Receiver (0x08)
   - Switches receiver to software mode
3. **Heartbeat:** `GET Product ID` to Receiver (0x08)
   - Confirms receiver responds in software mode

### Phase 2: Initialize Headset

4. **Software mode:** `SET Mode = 0x02` to Headset (0x09)
   - Switches headset to software mode (via receiver)
5. **Flush:** Clear HID buffer (non-blocking reads until empty)
6. **Heartbeat:** `GET Product ID` to Headset (0x09)
   - Confirms headset is reachable and responding
   - No response = headset powered off / not connected

### Cleanup

After all queries, both devices **must** be switched back to hardware mode:

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

**Important:** Without cleanup the device stays in software mode and may not
behave normally (e.g. no automatic power-off).

## Value Extraction

For uint16 values: Little-Endian from response bytes 4 and 5:
```
value = response[4] | (response[5] << 8)
```

For battery: value is in per-mille (0-1000), divide by 10 for percent.

## USB Identification

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

Other Bragi devices use the same protocol with different Product IDs.