# USB HID Commands

The Beyond MCU uses USB HID as its primary PC communication channel. All reports are **64 bytes** long; unused bytes are padded with zeros.

**PC -> HMD:** Feature reports (via `send_feature_report()`)  
**HMD -> PC:** Standard reports (via `read()`)

## Command Reference

### Device Information

| Code | Command | Description |
|------|---------|-------------|
| `*` (0x2A) | SW_VER | Get firmware version string (null-terminated, up to 63 chars) |
| `%` (0x25) | SERIAL_NUM | Get PCBA serial number |
| `&` (0x26) | HMD_SERIAL_NUM | Get HMD assembly serial number |
| `~` (0x7E) | TRACKING_SERIAL | Get tracking module serial number |
| `^` (0x5E) | OLED_ID | Get OLED panel serial (14 bytes). Byte 1: 0=left, 1=right |
| `N` (0x4E) | VXR_FWNAME | Get VXR7200 firmware name (15 bytes) |
| `s` (0x73) | STACK_LEVELS | Get FreeRTOS task stack watermarks (4 bytes per task) |

### Display Control

| Code | Command | Description |
|------|---------|-------------|
| `I` (0x49) | OLED_BRIGHTNESS | Set brightness 0–1023 (16-bit BE) |
| `P` (0x50) | OLED_FLIP | Flip displays vertically (0=normal, 1=flipped) |
| `=` (0x3D) | COLORBARPATTERN | Show colorbar test pattern on OLEDs |
| `d` (0x64) | EDID_SWITCH | Change video modes (0=default, 1=90Hz only, 2=75Hz only) |
| `o` (0x6F) | OLED_COMMAND | Send raw register write to OLED panels |
| `-` (0x2D) | OLED_POWER_DISABLE | Disable OLED power (BS1 only) |
| `+` (0x2B) | OLED_POWER_ENABLE | Enable OLED power (BS1 only) |

### Audio Control

| Code | Command | Description |
|------|---------|-------------|
| `S` (0x53) | STEREO | Set mono (0) or stereo (1) microphone mode |
| `G` (0x47) | GAIN | Set integer mic gain 0–32767 (16-bit BE) |
| `g` (0x67) | FRAC_GAIN | Set fractional mic gain -1.0 to +1.0 (16-bit signed fixed-point BE) |

### Fan Control

| Code | Command | Description |
|------|---------|-------------|
| `F` (0x46) | FAN | Set fan speed 0–100% (takes effect immediately) |
| `f` (0x66) | FAN_DEFERRED | Set fan speed (takes effect when displays turn on) |

### Proximity Sensor

| Code | Command | Description |
|------|---------|-------------|
| `M` (0x4D) | PROX_SETTINGS | Configure all proximity parameters (12 bytes) |
| `p` (0x70) | PROX_DISABLE | Disable proximity (displays forced on) until power cycle |
| `[` (0x5B) | PROX_ENABLE | Re-enable proximity sensor |

### LED

| Code | Command | Description |
|------|---------|-------------|
| `L` (0x4C) | RGB_LED | Set RGB color and animation mode (R, G, B + optional mode byte) |

**RGB_LED detail (v0.3.19):**
```
Byte 0: 'L'
Byte 1: Red   (0–255)
Byte 2: Green (0–255)
Byte 3: Blue  (0–255)
Byte 4: Animation mode (optional, 0 or omitted = color only):
        1 = Static (solid color)
        2 = Breathing (smooth fade in/out)
        3 = Blinking (on/off toggle)
```

### VXR7200 Management

| Code | Command | Description |
|------|---------|-------------|
| `K` (0x4B) | VXR_CHECKSUM | Compute checksum over VXR flash range (addr + length) |
| `T` (0x54) | VXR_TAGS | Get active flash bank bitfield |
| `D` (0x44) | VXR_DELETE | Erase VXR flash (requires "VXRDELETE" safety phrase) |
| `A` (0x41) | VXR_PROGRAM | Program up to 32 bytes to VXR flash |
| `Y` (0x59) | VXR_RESET | Reset VXR7200 |
| `N` (0x4E) | VXR_FWNAME | Get VXR firmware name/version |

### Configuration Flash

| Code | Command | Description |
|------|---------|-------------|
| `U` (0x55) | READ_SIG | Read 32-byte block from user signature (block 0–15) |
| `W` (0x57) | WRITE_SIG | Write 32-byte block to user signature (block 0–15) |
| `V` (0x56) | SAVE_SIG | Commit written signature bytes to permanent Flash |

Writing the full 512-byte config requires 16 WRITE_SIG commands (one per 32-byte block), followed by one SAVE_SIG command.

### System Control

| Code | Command | Description |
|------|---------|-------------|
| `B` (0x42) | BOOTLOADER | Restart into bootloader mode (no reply) |
| `C` (0x43) | RESET | Reset MCU (no reply) |
| `R` (0x52) | RATE | Set periodic report interval in ms (16-bit BE, min 10) |
| `Z` (0x5A) | USAGE_TIMER_GET | Get usage timer (0=power on, 1=left display, 2=longest, 3=right display) |
| `z` (0x7A) | USAGE_TIMER_SET | Set usage timer value |
| `J` (0x4A) | HW_TEST | Run hardware self-test (see sub-commands below) |
| `@` (0x40) | FATP_MODE | Enter factory test video modes |

### Eye-Tracking FPGA (BS2 only)

| Code | Command | Description |
|------|---------|-------------|
| `e` (0x65) | FPGA_COMMANDS | FPGA control: Reset (R), Reconfig (B), I2C Write (I), I2C Read (i) |

### Debug / Crash Triggers

All require the string "CRASHNOW" in bytes 1–8 as a safety measure:

| Code | Command | Description |
|------|---------|-------------|
| `,` (0x2C) | HARDFAULT | Trigger a hard fault |
| `.` (0x2E) | UNUSED_IRQ | Trigger an unused interrupt |
| `>` (0x3E) | STACK_OVERFLOW | Cause a FreeRTOS stack overflow |

## HW_TEST Sub-Commands

Sent as byte 1 of the `J` command. Reply byte 1: 0=fail, 1=pass.

| Code | Test | What It Checks |
|------|------|----------------|
| `H` | USB Hub | I2C connection to USB hub chips |
| `L` | RGB LED | I2C connection to LED driver |
| `S` | USB-C Switch | I2C connection to crossbar switch |
| `V` | VXR7200 | I2C connection to display SoC |
| `P` | Proximity | I2C connection to TMD2635 |
| `O` | OLED | I2C connection + ID readback from OLED panels |
| `F` | Fan | Verifies fan spins when commanded |

## Response Codes

| Code | Meaning |
|------|---------|
| `$` (0x24) | Success |
| `E` (0x45) | Error (byte 1 = error code) |
| `#` (0x23) | Periodic data report |

For information-request commands, the reply code matches the request code.

### Error Codes

| Value | Description |
|-------|-------------|
| 0 | Success |
| 1 | Invalid_Arg |
| 2 | Unsupported |
| 3 | Unknown_Error |
| 4 | Busy_Error |
| 6 | Timeout_Error |

## Periodic Telemetry Report

Sent automatically at the configured rate. 24-byte payload prefixed with `$`:

| Bytes | Type | Content |
|-------|------|---------|
| 0 | char | `$` report identifier |
| 1 | uint8 | Length (always 24) |
| 2–3 | uint16 BE | Fan speed |
| 4–5 | uint16 BE | Proximity distance (raw) |
| 6–7 | uint16 BE | CC1 pin ADC value |
| 8–9 | uint16 BE | CC2 pin ADC value |
| 10–13 | float | Board temperature (Kelvin) |
| 14–17 | float | Left display temperature (Celsius) |
| 18–21 | float | Right display temperature (Celsius) |
| 22–23 | uint16 BE | Display brightness (added v0.3.1) |
| 24–25 | uint16 | Display status bitfield (added v0.3.1) |

### Display Status Bitfield Detail

| Bits | Field |
|------|-------|
| 0 | Displays on |
| 1 | Proximity on (user detected) |
| 2 | Proximity 5-min timer expired |
| 3 | DSC enabled |
| 4–7 | Video mode enum (0=Unknown, 1=2544@75, 2=2544@72, 3=1920@90, 4=1920@60, 5=2560@30, 6=2544@60, 7=Colorbar) |
| 8–11 | DP link rate (0=Unknown, 1=RBR, 2=HBR, 3=HBR2, 4=HBR3) |
| 12–15 | DP lane count |

**Source files:** `src/usbhid_interface.c/h`  
**Full specification:** `docs/HID_Commands.md`