I wrote this library as a personal hack tool for testing Logitech's HID++ protocol. It also contains tools for configuring complex mouse profiles in persistent or temporary memory.

For simpler profiles, you may prefer to use libratbag.

Documentation for HID++ 1.0 mice, can be found on my G500 repository. Other varied documents (HID++ 1.0 receivers, HID++ 2.0 devices) from Logitech can be found on this Google drive. Peter Wu has some HID++ 2.0 features documentation on his website.

Building requires a C++17 compiler and cmake.

The library can be built with different HID backend (using the HID_BACKEND cmake variable, default is set according the current operating system).

• linux uses Linux hidraw and libudev.
• windows uses Microsoft Windows HID API.

Profile tools use TinyXML2 for parsing and writing profiles.

Use cmake to build the library and tools.

mkdir build
cd build
cmake ..
make

Library and tools can be installed with make install.

For building hidpp with Visual Studio (tested with Visual Studio 2019 16.11.5) a CMakeSettings.json file is included which contains Debug and Release configurations each for the x64 and x86 platforms. By default BUILD_SHARED_LIBS and BUILD_TOOLS are disabled, the former because shared library builds are not currently supported for MSVC (see #19), the latter because it requires extra dependencies.

Building the tools requires installing the getopt dependency first. The easiest way of doing so is by installing this one available through vcpkg:

vcpkg install getopt:x86-windows
vcpkg install getopt:x64-windows

With getopt installed, enable the BUILD_TOOLS variable in the CMake Settings for the desired configurations, regenerate the CMake cache, and then build.

Manually building from a Visual Studio Developer console is also supported:

mkdir build
cd build
cmake -DBUILD_SHARED_LIBS=OFF -DBUILD_TOOLS=OFF ..
# or, with tools support:
cmake -DBUILD_SHARED_LIBS=OFF -DCMAKE_TOOLCHAIN_FILE=<path to vcpkg>\scripts\buildsystems\vcpkg.cmake ..
start hidpp.sln

An alternative is to use CMake's Ninja generator:

cmake -G ninja -DBUILD_SHARED_LIBS=OFF -DBUILD_TOOLS=OFF ..
# or, with tools support:
cmake -G ninja -DBUILD_SHARED_LIBS=OFF -DCMAKE_TOOLCHAIN_FILE=<path to vcpkg>\scripts\buildsystems\vcpkg.cmake ..
ninja

• BUILD_TOOLS (default: ON): build the command line tools alongside the library.
• INSTALL_UDEV_RULES (default: OFF): install an udev rule for adding user access to HID++ devices. This will add a file in /etc/udev/rules.d (not in CMAKE_INSTALL_PREFIX). Run udevadm control --reload and udevadm trigger after the installation for updating udev rules and already present devices.

Most commands use a device path for interacting with the device. For some devices (wireless or older HID++ 1.0 devices), you need to add a device index with the -d or --device in order to access the device instead of the receiver. Use hidpp-list-devices to discover plugged devices and their respective device path and index.

hidpp-check-device *device_path*

This command print the protocol version of the device if it supports HID++. Otherwise it return a non-zero code.

hidpp-list-devices

List every HID++ devices that can be opened (run as root if the device is not visible).

hidpp-list-features *device_path*

List every feature or register available on the device. For HID++ 1.0, register are discovered by trying to read or write them, this command does not try writing unless the -w or --write options are given.

hidpp10-dump-page *device_path* *page*

Dump the content of page page in the HID++ 1.0 device memory in stdout.

hidpp10-write-page *device_path* *page*

Write the content of stdin in page page of the HID++ 1.0 device.

Profiles are stored in XML format, see profile_format.md for details.

hidpp-persistent-profiles *device_path* read [*file*]

Read the persistent profiles from the device and write them in XML format in file or stdout.

hidpp-persistent-profiles *device_path* write [*file*]

Write the persistent profiles from the XML in file or stdin to the device.

Supported devices:

• G9 (experimental, untested)
• G9x, G500, G500s
• G700, G700s (experimental, untested)
• HID++2.0 or later supporting On-board profiles (feature 0x8100) with profile format 1, 2 or 3 (only format 2 was tested with a G502 spectrum, other formats may be incomplete) and macro format 1. Use hidpp20-onboard-profiles-get-description to get the format used by the device.

hidpp10-load-temp-profile *device_path* [*file*]

Write the profile from the XML in file or stdin to the device temporary memory and load it.

hidpp10-active-profile *device_path* current

Get the index of the current profile (or default if the factory default is loaded).

hidpp10-active-profile *device_path* load *index*

Load the profile index from persistent memory.

hidpp10-active-profile *device_path* load-default

Load the factory default profile.

hidpp10-active-profile *device_path* load-address *page* [*offset*]

Load the profile at the given address (default value for offset is 0).

hidpp10-active-profile reload

Reload the current profile from persistent memory (useful to get back to the last profile after hidpp10-load-temp-profile).

hidpp-mouse-resolution *device_path* get

Get the current resolution from the mouse.

hidpp-mouse-resolution *device_path* set *x_dpi* [*y_dpi*]

Set the current resolution for the mouse. If only one resolution is given, both axes use x_dpi. Some mice do not support per-axis resolution.

hidpp-mouse-resolution *device_path* info

Print informations about supported resolutions.

Supported devices: G5, G9, G9x, G500, G500x, G700, G700s, HID++2.0 or later devices with “Adjustable DPI” feature (0x2201).

hidpp10-raw-command *device_path* *command* read|write short|long [*parameters*...]

Used for raw interaction with HID++ 1.0 register command. Parameters are hexadecimal and default are zeroes.

hidpp20-call-function *device_path* *feature_index* *function* [*parameters*...]

Call the low-level function given by feature_index and function. Parameters are hexadecimal and default are zeroes.