From 0547392a56ad0ef21cc6f5266d0ca7a2929e13f2 Mon Sep 17 00:00:00 2001 From: Denis Arnst Date: Thu, 21 Mar 2024 17:21:46 +0100 Subject: [PATCH] Improve README, fix crash, improve test device Also improve issue templates --- .github/ISSUE_TEMPLATE/1_new_device.yaml | 12 ++++++ .github/pull_request_template.md | 8 ++++ README.md | 47 +++++++++++------------- src/devices/headsetcontrol_test.c | 12 +++--- src/main.c | 8 ++-- 5 files changed, 53 insertions(+), 34 deletions(-) create mode 100644 .github/pull_request_template.md diff --git a/.github/ISSUE_TEMPLATE/1_new_device.yaml b/.github/ISSUE_TEMPLATE/1_new_device.yaml index 12e5308..f3b0b9e 100644 --- a/.github/ISSUE_TEMPLATE/1_new_device.yaml +++ b/.github/ISSUE_TEMPLATE/1_new_device.yaml @@ -42,3 +42,15 @@ body: ``` +- type: checkboxes + id: newdevice + attributes: + label: New Device Implementation Checklist + description: Implementing a new device requires specific steps and tools (like WireShark) to capture and analyze device communications. This process typically can only be done by those who have physical access to the device. + options: + - label: I acknowledge that implementing a new device requires direct access to the device and familiarity with capturing and analyzing its communications. I have access to the device and am willing to contribute by capturing necessary data and/or attempting implementation. + required: true + - label: I have already attempted to capture device communications using WireShark or similar tools and am including my findings (successful or not) with this issue to assist in implementation efforts. + required: false + - label: I am seeking guidance on how to begin this process and am willing to collaborate with the community to add support for this device. I understand where to find resources (refer to the WIKI). + required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..e2f71bb --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,8 @@ +### Changes made + +. + +### Checklist + +- [ ] I adjusted the README (if needed) +- [ ] For new features in HeadsetControl: I discussed it beforehand in Issues or Discussions and adhered to the [wiki](https://github.com/Sapd/HeadsetControl/wiki/Development#adding-a-new-feature-to-the-headsestcontrol-application-itself) diff --git a/README.md b/README.md index b922303..54b2f4d 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ talking. This differs from a simple loopback via PulseAudio as you won't have an For non-supported headsets on Linux: There is a chance that you can set the sidetone via AlsaMixer -* *If your Corsair headset is not recognized, see [Adding a corsair device](https://github.com/Sapd/HeadsetControl/wiki/Adding-a-Corsair-device).* HS80 and HS70 wired, RGB Elite, and Virtuso is not supported, but you can change its sidetone in Alsamixer. +* *If your Corsair headset is not recognized - or you have a very similar headset to an existing one, see [Adding a corsair device](https://github.com/Sapd/HeadsetControl/wiki/Adding-a-Corsair-device).* HS80 and HS70 wired, RGB Elite, and Virtuso is not supported, but you can change its sidetone in Alsamixer. For more features or other headsets, the protocol of the respective headset must be analyzed further. This can be done by capturing the USB traffic between the device and the original Windows software and analyzing it with WireShark or USBlyzer. For that, you can also use a virtual machine with USB passthrough. The [wiki](https://github.com/Sapd/HeadsetControl/wiki/Development) provides a tutorial. @@ -86,25 +86,9 @@ RHEL and CentOS also require the epel-repository. `emerge -a app-misc/headsetcontrol` -#### Mac OS X - -Recommendation: Use [Homebrew](https://brew.sh). - -* To automatically compile and install the latest version: -`brew install sapd/headsetcontrol/headsetcontrol --HEAD` -* To manually compile, first install the dependencies: -`brew install hidapi cmake` - -Note: Xcode must be downloaded via the Mac App Store for the compilers. - -#### Windows - -* Binaries are available on the [releases](https://github.com/Sapd/HeadsetControl/releases) page. -* For compilation instructions using MSYS2/MinGW refer to the [wiki](https://github.com/Sapd/HeadsetControl/wiki/Development#windows). - ### Compiling -``` +```bash git clone https://github.com/Sapd/HeadsetControl && cd HeadsetControl mkdir build && cd build cmake .. @@ -115,23 +99,32 @@ To make `headsetcontrol` accessible globally, run: ```bash sudo make install + +# On LINUX, to access without root reboot your computer or run +sudo udevadm control --reload-rules && sudo udevadm trigger ``` -This command installs the binary in a location that is globally accessible via your system's PATH. +This command installs the binary in a location that is globally accessible via your system's PATH. On Linux it also runs `headsetcontrol -u` for generating udev files and stores them in `/etc/udev/rules.d/` (used to allow non-root access) -### Access Without Root (Linux only) +### OS X + +Recommendation: Use [Homebrew](https://brew.sh). -To use the application without root privileges on Linux, udev rules are required. These can be generated with: +* To automatically compile and install the latest version: ```bash -headsetcontrol -u +brew install sapd/headsetcontrol/headsetcontrol --HEAD ``` -Running `sudo make install` will automatically generate and write these rules to /etc/udev/rules.d/. To apply the changes without rebooting, reload udev configuration: +* To manually compile, first install the dependencies: +`brew install hidapi cmake` -```bash -sudo udevadm control --reload-rules && sudo udevadm trigger -``` +Note: Xcode must be downloaded via the Mac App Store for the compilers. + +### Windows + +* Binaries are available on the [releases](https://github.com/Sapd/HeadsetControl/releases) page. +* For compilation instructions using MSYS2/MinGW refer to the [wiki](https://github.com/Sapd/HeadsetControl/wiki/Development#windows). ## Usage @@ -153,6 +146,8 @@ To use headsetcontrol in scripts or other applications, explore: headsetcontrol --output ``` +(and the wiki article about [API development](https://github.com/Sapd/HeadsetControl/wiki/API-%E2%80%90-Building-Applications-on-top-of-HeadsetControl)) + Note: When running the application from the current directory, prefix commands with `./` ### Third Party diff --git a/src/devices/headsetcontrol_test.c b/src/devices/headsetcontrol_test.c index 8e7862f..d6b6462 100644 --- a/src/devices/headsetcontrol_test.c +++ b/src/devices/headsetcontrol_test.c @@ -28,8 +28,8 @@ extern int test_profile; void headsetcontrol_test_init(struct device** device) { - if (test_profile < 0 || test_profile > 6) { - printf("test_profile must be between 0 and 5\n"); + if (test_profile < 0 || test_profile > 10) { + printf("test_profile must be between 0 and 10\n"); abort(); } @@ -42,7 +42,7 @@ void headsetcontrol_test_init(struct device** device) wcsncpy(device_headsetcontrol_test.device_hid_vendorname, L"HeadsetControl", sizeof(device_headsetcontrol_test.device_hid_vendorname) / sizeof(device_headsetcontrol_test.device_hid_vendorname[0])); wcsncpy(device_headsetcontrol_test.device_hid_productname, L"Test device", sizeof(device_headsetcontrol_test.device_hid_productname) / sizeof(device_headsetcontrol_test.device_hid_productname[0])); - if (test_profile != 2) { + if (test_profile != 10) { device_headsetcontrol_test.capabilities = B(CAP_SIDETONE) | B(CAP_BATTERY_STATUS) | B(CAP_NOTIFICATION_SOUND) | B(CAP_LIGHTS) | B(CAP_INACTIVE_TIME) | B(CAP_CHATMIX_STATUS) | B(CAP_VOICE_PROMPTS) | B(CAP_ROTATE_TO_MUTE) | B(CAP_EQUALIZER_PRESET) | B(CAP_EQUALIZER) | B(CAP_MICROPHONE_MUTE_LED_BRIGHTNESS) | B(CAP_MICROPHONE_VOLUME); } else { device_headsetcontrol_test.capabilities = B(CAP_SIDETONE) | B(CAP_LIGHTS) | B(CAP_BATTERY_STATUS); @@ -83,7 +83,7 @@ static BatteryInfo headsetcontrol_test_request_battery(hid_device* device_handle info.level = 42; break; case 1: - info.status = BATTERY_UNAVAILABLE; + info.status = BATTERY_HIDERROR; break; case 2: info.status = BATTERY_CHARGING; @@ -94,7 +94,7 @@ static BatteryInfo headsetcontrol_test_request_battery(hid_device* device_handle info.level = 64; break; case 4: - info.status = BATTERY_HIDERROR; + info.status = BATTERY_UNAVAILABLE; break; case 5: info.status = BATTERY_TIMEOUT; @@ -151,6 +151,8 @@ static int headsetcontrol_test_request_chatmix(hid_device* device_handle) { if (test_profile == 1) { return -1; + } else if (test_profile == 2) { + return -1; } return 42; diff --git a/src/main.c b/src/main.c index e0b02e2..6c1d200 100644 --- a/src/main.c +++ b/src/main.c @@ -454,11 +454,11 @@ void print_help(char* programname, struct device* device_found, bool _show_all) if (show_all || has_capability(device_found->capabilities, CAP_SIDETONE) || has_capability(device_found->capabilities, CAP_BATTERY_STATUS)) { printf("Examples:\n"); - if (has_capability(device_found->capabilities, CAP_BATTERY_STATUS)) + if (show_all || has_capability(device_found->capabilities, CAP_BATTERY_STATUS)) printf(" %s -b\t\tCheck the battery level\n", programname); - if (has_capability(device_found->capabilities, CAP_SIDETONE)) + if (show_all || has_capability(device_found->capabilities, CAP_SIDETONE)) printf(" %s -s 64\tSet sidetone level to 64\n", programname); - if (has_capability(device_found->capabilities, CAP_LIGHTS) && has_capability(device_found->capabilities, CAP_SIDETONE)) + if (show_all || (has_capability(device_found->capabilities, CAP_LIGHTS) && has_capability(device_found->capabilities, CAP_SIDETONE))) printf(" %s -l 1 -s 0\tTurn on lights and deactivate sidetone\n", programname); printf("\n"); } @@ -722,6 +722,8 @@ int main(int argc, char* argv[]) } // fall through } else if (strcmp(opts[option_index].name, "readme-helper") == 0) { + // We need to initialize it at this point + init_devices(); print_readmetable(); return 0; } else if (strcmp(opts[option_index].name, "help-all") == 0) {