Development

See the main README for basic compilation instructions.

Also there is now a dev menu available under ./headsetcontrol --dev -- --dev-help use it after the instructions below.

Contributing

We use the WebKit coding style and clang-format to enforce it. You can usually install clang-format via package managers (clang-format or clang-format-9.0).

If both is installed, you can build the project by creating and going into the build folder and then with
cmake -DENABLE_CLANG_FORMAT=1 -DCMAKE_BUILD_TYPE=Debug ..

Use it like this:

• make format will automatically format your code to our specification

When you do a Pull Request (PR), the CI will check the format, and will also check for unnecessary whitespaces (you can also check it yourself with git diff --check HEAD^)

Adding a new device or a feature like battery

Check this wiki entry: https://github.com/Sapd/HeadsetControl/wiki/Development-%E2%80%90-Adding-a-device

If you're done, you can generate a table for updating the README.md using:

./headsetcontrol --readme-helper

Adding an entirely new feature to a device

If this feature is already present generally in HeadsetControl but not in your device (like battery), refer to the article from the section above.

Here is a rough general checklist for adding an entirely new device-feature:

• Add the function prototype with a documentation to device.h and adjust enum capabilities
• Implement it for your device in your device file
• In main.c:
  • Add a new parameter - preferably as long option only (like --mycoolfeature) in int main(int argc, char* argv[])
  • Define a feature in the FeatureRequest featureRequests[] table also in the same function
  • Process/call your feature in static FeatureResult handle_feature
  • Add the new paramter also to print_help
• Add output in output.c/h
  • In output.h adjust the struct HeadsetInfo which is used to convert it into YAML/JSON etc
  • In output.c adjust processFeatureRequests() for a feature which requests data
  • Adjust output_json etc. to include new information in the HeadsetInfo struct
• Adjust the README if needed

Adding a new feature to the HeadsestControl Application itself

It is important to acknowledge this:

• HeadsetControl is written with portability in mind
• HeadsetControl adheres to the Unix principle with simplicity in mind

If your feature can be solved by a script, it should do so instead of in HeadsetControl itself (and preferably hosted as Third Party repository). Also features like (User-)interface etc. should always be made as Third-Party application in its own repository. Refer to the [https://github.com/Sapd/HeadsetControl/wiki/API-%E2%80%90-Building-Applications-on-top-of-HeadsetControl](API guide) here.

Before starting to make one for the main repo, please open up a Issue or Discussion beforehand.

Writing a third party app

Refer to the API docs: https://github.com/Sapd/HeadsetControl/wiki/API-%E2%80%90-Building-Applications-on-top-of-HeadsetControl

Feel free to open a PR to link your app in the README of the main repo.

Windows

Compilation

1. Download and Install MSYS2
2. pacman -Syu
3. Close the msys terminal and start it again
4. pacman -Syu
5. pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-hidapi make git
6. There should be now also a "MSYS2 MinGW 64-bit"-shortcut in your start menu (just use Windows Search), start and use it now
7. git clone the repository
8. mkdir build && cd build
9. cmake -G"MSYS Makefiles" ..
10. make and if wanted make install

You can also call the application then normally via windows-cmd or bat file etc. The application will be statically linked, so you dont need any dependencies when running it.

Problems

Windows needs different endpoints then the UNIX-implementations. They are called Usages and Usage Pages. There could be multiple different endpoints for different packets (like sidetone <-> leds). However the HeadsetControl software only supports one endpoint for each device for now.

You can see the endpoints with headsetcontrol --dev -- --list --device VENDORID:PRODUCTID They will be shown as Usage-Page: 0xff00 Usageid: 0x1 also the Interface number could be relevant.

Also Windows expects the correct amount of bytes for every packet sent by the software. Linux/MacOS is more forgiving and allows ending 0's to be omitted.

"Incorrect function"

The endpoint (usageid / usagepage) is wrong.

"Incorrect parameter"

You probably didn't send the correct amount of bytes.