From 5ba124b086abd570b2bf6da700cecf11f3859b2a Mon Sep 17 00:00:00 2001 From: Fabio Scaccabarozzi Date: Sun, 19 Oct 2025 18:32:35 +0100 Subject: [PATCH] Add documentation about unknown command 4 --- FEATURE_CAPABILITIES.md | 18 ++++++++++++++++++ Headset_protocol.md | 22 ++++++++++++++++++++++ src/devices/cloud_ii_wireless.rs | 9 +++++++++ 3 files changed, 49 insertions(+) diff --git a/FEATURE_CAPABILITIES.md b/FEATURE_CAPABILITIES.md index 26bcd16..1bb63bf 100644 --- a/FEATURE_CAPABILITIES.md +++ b/FEATURE_CAPABILITIES.md @@ -87,3 +87,21 @@ Connected: true - 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. diff --git a/Headset_protocol.md b/Headset_protocol.md index 2afb83a..5e881a0 100644 --- a/Headset_protocol.md +++ b/Headset_protocol.md @@ -53,6 +53,7 @@ Byte Value Description | 1 | 0x01 | Get Connection Status | Query wireless connection status | | 2 | 0x02 | Get Battery Level | Query current battery percentage | | 3 | 0x03 | Get Charging Status | Query charging state | +| 4 | 0x04 | Unknown/Unused | Undocumented notification (ignored) | | 8 | 0x08 | Mute Status (Response) | Microphone mute status (in responses) | | 9 | 0x09 | Initialization | Sent during device initialization | | 17 | 0x11 | Get Firmware Version | Query firmware version (4 bytes) | @@ -97,6 +98,27 @@ Response: [0B 00 BB 03 ...] - `0x02` = Fully charged - `0x03` = Charge error +#### Command 4 - Undocumented/Unused Notification + +``` +Response: [0B 00 BB 04 ...] +``` + +- **Purpose:** Unknown - Not handled by official HyperX NGenuity2 software +- **Note:** This command appears sporadically as an asynchronous notification from the headset +- **Not user-initiated:** This is an unsolicited notification from the device, not sent by the host +- **Official behavior:** The official NGenuity2 software logs but does not process this command +- **Implementation:** HyperHeadset logs the data when received for debugging purposes +- **Trigger conditions:** Unknown - does NOT trigger on charging cable connect/disconnect or battery level changes +- **Data format:** Unknown - bytes [4-8] are logged for analysis +- **Recommendation:** Safe to ignore - likely a spurious firmware notification or leftover from other headset models + +**Investigation notes:** + +- Command 4 exists in Cloud Flight S firmware for button press handling, but Cloud II Wireless has no such buttons +- Neither Cloud II Wireless nor Cloud II Wireless DTS firmware handles this command +- May be a firmware artifact or unused notification channel + #### Set Auto Power Off (Cmd 24) ``` diff --git a/src/devices/cloud_ii_wireless.rs b/src/devices/cloud_ii_wireless.rs index a32d547..418e1b8 100644 --- a/src/devices/cloud_ii_wireless.rs +++ b/src/devices/cloud_ii_wireless.rs @@ -228,6 +228,15 @@ impl Device for CloudIIWireless { Duration::from_secs(minutes as u64 * 60), )]) } + 4 => { + // Command 4: Charge limit or battery management + // This may be sent asynchronously when charging state changes + println!( + "Charge limit/battery management response (cmd 4): data={:?}", + &response[4..8] + ); + None + } 9 | 29 => { // Commands 9 and 29 are seen during initialization but purpose unclear println!("Initialization response (cmd {})", response[3]);