diff --git a/ACKNOWLEDGEMENTS b/ACKNOWLEDGEMENTS new file mode 100644 index 0000000..5d9cae4 --- /dev/null +++ b/ACKNOWLEDGEMENTS @@ -0,0 +1,51 @@ +ksni: (https://crates.io/crates/ksni) + + + +thiserror: +MIT License + +Copyright (c) [year] [fullname] + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + + + +hidapi: +MIT License + +Copyright (c) [year] [fullname] + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/Cargo.toml b/Cargo.toml index c4b4a02..0822423 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "hyper_x_cloud_ii_wireless" -version = "0.1.0" +version = "1.0.0" edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html diff --git a/README.md b/README.md index 1c05a3e..ec91c38 100644 --- a/README.md +++ b/README.md @@ -1 +1,95 @@ -# HyperXCloudIIWireless \ No newline at end of file +# HyperXCloudIIWireless +A CLI and tray application to monitor HyperX Cloud II Wireless headset battery level. + +tray_app + +## Compatibility +The CLI application is compatible with both Linux and MacOS operating systems. However, the tray application is only functional on Linux. Although it was only tested on Manjaro/KDE, it should also work on other distribution and desktop environments. + +Currently, only the HyperX Cloud II Wireless is supported. + +## Prerequisites + +### Hidraw + +Make sure you have hidraw installed on your system. + +Debian/Ubuntu: + +`sudo apt install libhidapi-hidraw0` + +Arch: + +`sudo pacman -S hidapi` + +MacOS: + +`brew install hidapi` + +### Other Dependencies + +These dependencies are probably already installed. + +Debian/Ubuntu: + +`sudo apt install libdbus-1-dev libusb-1.0-0-dev libudev-dev` + +Arch: + +`sudo pacman -S dbus libusb` + +MacOS: + +`brew install libusb` + +### Udev (Linux only) + +Create a new file in /etc/udev/rules.d/99-hyperx-cloud-II.rules with the following content inside: + +``` +SUBSYSTEMS=="usb", ATTRS{idProduct}=="018b", ATTRS{idVendor}=="03f0", MODE="0666" +SUBSYSTEMS=="usb", ATTRS{idProduct}=="1718", ATTRS{idVendor}=="0951", MODE="0666" + +KERNEL=="hidraw*", ATTRS{idProduct}=="018b", ATTRS{idVendor}=="03f0", MODE="0666" +KERNEL=="hidraw*", ATTRS{idProduct}=="1718", ATTRS{idVendor}=="0951", MODE="0666" +``` + +Once created, replug the wireless dongle. + +## Building + +To only build the cli_app on MacOS, use: +`cargo build --release --bin cli_app` + +To build both applications on Linux, use: +`cargo build --release` + +You can also download a compiled version from [releases](https://github.com/LennardKittner/HyperXCloudIIWireless/releases). + +## Usage + +`cli_app` without any arguments will print the current battery level. + +`hyper_x_cloud_ii_wireless` without any arguments will start the tray application. Once it's open, hover over the headset icon in the system tray to view details like the battery level. To exit, right-click on the icon. + +## Limitations +The battery level is checked regularly, but information about muting or charging the headset is only recorded when those events occur. + +## Contributing / TODOs +- [ ] Menu bar app for MacOS. +- [ ] Actively configure the headset. +- [ ] Query device state instead of only relying on events. + +You can contribute code or monitor packets using Wireshark from the HyperX app on Windows. + +### How to use Wireshark to capture packets + +This [guide](https://github.com/liquidctl/liquidctl/blob/main/docs/developer/capturing-usb-traffic.md) is very helpful. +In my case, the filter `usb.idVendor == 0x03f0 && usb.idProduct == 0x018b` only showed on request. +I then only listened to the port on which this request was sent, e.g., `(usb.src == "3.5.0") || (usb.dst =="3.5.0")`. +If you have an older headset, you may have to use a different vendor and product ID `usb.idVendor == 0x0951 && usb.idProduct == 0x1718`. +Once you have set the filters, you can perform various actions and review the packets transmitted to and from the headset. + +## Acknowledgments + +This project was inspired by X-cloud-flight](https://github.com/kondinskisX-cloud-flight). \ No newline at end of file diff --git a/screenshots/tray_app.png b/screenshots/tray_app.png new file mode 100644 index 0000000..2b817c2 Binary files /dev/null and b/screenshots/tray_app.png differ