HyperHeadset/FEATURE_CAPABILITIES.md

HyperX Headset Feature Capabilities

This document summarizes which features can be controlled vs only monitored for each headset model.

Cloud II Wireless (Non-DTS)

Writable Features (Can be SET via HID commands)

• ✅ Auto Power Off - Can set automatic shutdown timer (0-30 minutes)
• ✅ Sidetone - Can enable/disable sidetone (on/off only, no volume control)

Read-Only Features (Can only monitor, not control)

• ❌ Microphone Mute - Hardware button only, cannot be controlled via HID
• ❌ Surround Sound (7.1) - Controlled via Windows DTS APO or physical button, not HID
• ❌ Battery Level - Read-only status
• ❌ Charging Status - Read-only status
• ❌ Connection Status - Read-only status
• ❌ Firmware Version - Read-only information

Cloud II Wireless DTS

Writable Features

• ✅ Auto Power Off
• ✅ Sidetone - With volume control (0-100)
• ✅ Surround Sound - Via Windows DTS APO system calls (not direct HID)

Read-Only Features

• ❌ Microphone Mute - Hardware button only
• ❌ Battery Level
• ❌ Charging Status
• ❌ Connection Status

Cloud III Wireless

Writable Features

• ✅ Auto Power Off
• ✅ Sidetone - With volume control (0-100)
• ✅ Microphone Mute - Can be controlled programmatically
• ✅ Voice Prompt - Can enable/disable voice prompts
• ✅ Playback Mute (Silent Mode) - Can mute headphone output

Read-Only Features

• ❌ Surround Sound - Not supported via HID
• ❌ Battery Level
• ❌ Charging Status
• ❌ Connection Status
• ❌ Product Color

CLI Error Handling

The CLI application now provides clear error messages when attempting to use unsupported features:

# Example: Trying to control surround sound on Cloud II Wireless
$ ./hyper_headset_cli --surround_sound true
ERROR: Surround sound control is not supported on this device
       Use the physical headset button or Windows audio settings to toggle surround sound.

# Example: Trying to mute on Cloud II Wireless
$ ./hyper_headset_cli --mute true
ERROR: Microphone mute control is not supported on this device (hardware button only)

Tray Application UI

The system tray application now displays "(read-only)" markers next to features that cannot be controlled:

Battery level:            92%
Charging status:          Not charging
Muted:                    false (read-only)
Automatic shutdown after: 20min
Side tone:                false
Surround sound:           true (read-only)
Connected:                true

Implementation Details

• Feature capabilities are checked once during device initialization via init_capabilities()
• Capability flags are stored in DeviceState structure
• CLI flags for unsupported features are hidden in the help menu
• CLI exits with error code 1 when attempting to use unsupported features
• Tray UI shows read-only markers based on device capabilities

Protocol Notes

Undocumented Commands

Command 4 (Cloud II Wireless): An undocumented HID command that occasionally appears as an asynchronous notification from the headset. This command is not handled by the official HyperX NGenuity2 software, which simply logs it to debug traces.

• Appearance: Sporadic, trigger conditions unknown
• Official behavior: Ignored by NGenuity2
• HyperHeadset behavior: Logged for debugging purposes
• Investigation findings:
  • Does NOT trigger on charging cable connect/disconnect
  • Does NOT trigger on battery level changes
  • Not related to any user-controllable feature
  • May be firmware artifact from Cloud Flight S (which uses cmd 4 for button presses)
  • Cloud II Wireless and Cloud II Wireless DTS both ignore this command

This is documented for transparency but can be safely ignored during normal operation.